Imagine This Scenario

You just spent an hour with an AI coding agent setting up JWT authentication for your app. You worked through the middleware, wrote tests, chose a library. Everything works.

Next day, you open a new session and ask: “Add rate limiting to the API.”

The agent says: “Sure! First, let me look at your project structure...”

It has no idea you already set up auth. No idea you chose jose over jsonwebtoken for Edge compatibility. No idea your tests cover token validation. You have to explain everything again.

What agentmemory Does

agentmemory is a persistent memory system for AI coding agents. It runs silently in the background and remembers what your agent does across sessions.

Why It Matters: The Numbers

One Command, Full Memory

# Start the memory server
npx @agentmemory/agentmemory

# In another terminal, see it work
npx @agentmemory/agentmemory demo

# Open the real-time viewer
open http://localhost:3113
            

Check Your Understanding

Six Components, One Mission

Think of agentmemory as a modular system where each component has a clear role. Here are the six characters you need to know:

A Day in the Life: The Cast Talks

Watch how the six components collaborate when your AI agent edits a file:

How They Connect

The Secret Sauce: iii Engine

The iii engine is what makes agentmemory work without any external dependencies. It provides three building blocks:

// Every capability is an iii function
import { registerWorker } from "iii-sdk";

const sdk = registerWorker("ws://localhost:49134");
await sdk.connect();

sdk.registerFunction("mem::observe",
  async (data) => {
    // privacy filter, dedup, compress, index
    return { stored: true };
  }
);
            

Where Everything Lives

Check Your Understanding

Five Stages of Memory Creation

Think of it like a factory pipeline. Raw tool calls enter one end, and structured, searchable memories come out the other. Let us trace the journey:

Watch It Flow

Click through each step to see how data moves through the pipeline:

Stage 2: The Privacy Filter

Before anything gets stored, a privacy filter scrubs sensitive data. This is your first line of defense — your API keys never reach the memory store.

const SECRET_PATTERNS = [
  /Bearer\s+[A-Za-z0-9._\-+/=]{20,}/gi,
  /sk-ant-[A-Za-z0-9\-_]{20,}/g,
  /gh[pus]_[A-Za-z0-9]{36,}/g,
  /AKIA[0-9A-Z]{16}/g,
  /eyJ[A-Za-z0-9_-]{10,}\.../g,
];

export function stripPrivateData(input: string) {
  let result = input
    .replace(PRIVATE_TAG_RE, "[REDACTED]");
  for (const pattern of SECRET_PATTERNS) {
    result = result.replace(pattern, "[REDACTED_SECRET]");
  }
  return result;
}
            

Stage 3: Deduplication

AI agents often repeat the same action multiple times — running the same test, reading the same file. The content-addressable dedup system prevents storing the same observation twice:

computeHash(sessionId, toolName, toolInput) {
  const input = typeof toolInput === "string"
    ? toolInput.slice(0, 500)
    : JSON.stringify(toolInput).slice(0, 500);
  const raw = `${sessionId}:${toolName}:${input}`;
  return createHash("sha256")
    .update(raw).digest("hex");
}
            

Stage 4: Compression (Zero LLM)

By default, agentmemory uses synthetic compression — pure heuristics that extract structure from tool calls without spending a single token on an LLM. It is like having a smart filing clerk who knows that grep means “searching” and bash means “running a command.”

function inferType(toolName: string): ObservationType {
  const n = toolName.replace(/([a-z])([A-Z])/g, "$1_$2")
    .toLowerCase();
  if (["grep","search","glob"].some(hasWord))
    return "search";
  if (["edit","update","patch"].some(hasWord))
    return "file_edit";
  if (["bash","shell","exec"].some(hasWord))
    return "command_run";
}
            

Spot the Issue

Here is a simplified version of the hook that captures tool usage. There is a subtle timing issue — can you find it?

Check Your Understanding

The Search Problem

Last week you fixed an N+1 query problem in your codebase. Today you search for “database performance optimization.”

A simple keyword search would never find “N+1 query fix” — the words do not match. But agentmemory finds it. How?

The answer: three search engines running simultaneously, each looking at the query from a different angle, then fused together into one ranked result.

Three Engines, One Query

The Magic: Reciprocal Rank Fusion

Each engine returns a ranked list. But how do you merge three different rankings into one? The answer is Reciprocal Rank Fusion (RRF).

const RRF_K = 60;

// Each engine produces a ranked list
const bm25Results = this.bm25.search(query, limit * 2);
const vectorResults = this.vector
  .search(queryEmbedding, limit * 2);

// Merge: score = weight * 1/(K + rank)
combined = w_bm25 * (1/(60 + bm25Rank))
       + w_vector * (1/(60 + vectorRank))
       + w_graph * (1/(60 + graphRank));
            

What Happens When an Engine Is Missing?

Not everyone has an embedding provider configured. Not everyone enables the knowledge graph. The system adapts automatically:

The default weights are: BM25 = 0.4, Vector = 0.6, Graph = 0.3. But these are configurable:

The Complete Search Journey

When your AI agent starts a new session and asks agentmemory for context, here is what happens behind the scenes:

The Embedding Options

Vector search needs an embedding model. agentmemory supports six providers, and auto-detects which one to use:

Check Your Understanding

Why Your Brain Forgets Things (On Purpose)

Your brain does not store everything forever — that would be overwhelming. Instead, it has a system:

• During the day, you form short-term memories — what you had for lunch, what your coworker said.
• While you sleep, your brain consolidates those memories — extracting the important parts and filing them into long-term storage.
• Memories you rarely access fade over time (the Ebbinghaus forgetting curve).
• Memories you use frequently get strengthened — they become easier to recall.

agentmemory implements this exact pattern in code. Four tiers, automatic consolidation, exponential decay, and importance-based eviction.

The 4-Tier Memory Model

The Consolidation Pipeline

Consolidation is the “sleep” phase — it happens periodically, not on every observation. The pipeline in src/functions/consolidation-pipeline.ts runs through each tier:

// Exponential decay applied to memories
strength *= 0.9 ** number_of_decay_periods;

// Decay period: configurable, default 30 days
// Floor at 0.1 — never fully zero
if (strength < 0.1) strength = 0.1;
            

The Retention Score

Not all memories are created equal. A retention score determines each memory's fate:

score = salience * exp(-lambda * days)
      + sigma * reinforcementBoost

// Salience weights by memory type:
architecture = 0.9  // structural decisions
bug          = 0.7  // bugs and fixes
pattern      = 0.8  // recurring patterns
preference   = 0.85 // user preferences

// Tier classification:
hot    >= 0.7   // always keep
warm   >= 0.4   // keep but watch
cold   >= 0.15  // candidate for eviction
evict  < 0.15   // remove on next sweep
            

Three Ways to Forget

Auto-forget runs every 60 minutes with three strategies:

The Complete Lifecycle

Putting it all together — from capture to eventual forgetting:

Final Check