keymem

The associative memory layer for LLM agents — recall by association, not just similarity.

Most agent memory is a vector store. It surfaces what sounds like your query — and misses everything your query is connected to.

keymem stores memories in a key graph instead. A search for "Newton" can still reach "strawberries" — Newton → apple → fruit → strawberry. The path lives in the graph, not in embedding space. It runs locally as an MCP server, so any MCP-compatible agent gets human-like associative recall with no external database.

Works with: Claude Desktop · Claude Code · any MCP-compatible LLM agent

---

Why associative memory?

Vector-store memory retrieves by embedding similarity. That works until the thing you need isn't similar to the words you typed:

Query: "Newton"
Similarity search finds: "Newton discovered gravity"  ✅
Similarity search misses: "user likes strawberries"   ❌

A person makes the leap anyway — Newton reminds them of the apple, apples are fruit, they like strawberries. keymem makes that same leap because the path exists in the key graph: Newton → apple memory → fruit key → strawberry memory. No embedding distance connects "Newton" and "strawberry"; a chain of shared keys does.

This is the core idea: memories are not islands ranked by distance. They are nodes in an N:M key/value graph that an agent can walk.

---

How it works

Key Space (concepts)         Value Space (memories)
[apple]   ────────┬─────────→      ↑ same memory
[gravity] ────────┘
                  │
[apple]   ────────┼─────────→ "apples are red fruit"
[fruit]   ──────┬─┘
[red]     ──────┤
                │
[fruit]   ──────┼─────────→ "user likes strawberries"
[strawberry]────┘

Memories live in a Value Space, reached through a separate Key Space — one memory reachable via many keys, one key leading to many memories.

recall("Newton") returns matching key clusters such as [Newton] and [apple] plus one passive Top-1 memory under the strongest key. That memory carries matched_key, validity, and connected_keys, so the agent can answer immediately or continue through read_key(fruit).

The default MCP flow remains Key → Memory → Key, but its first Key → Memory hop is completed in one call. Only one memory enters context automatically; later hops remain deliberate.

The animation at the top shows this on a real store: three recall() calls walk from a profile key to a verification philosophy, loading three memories (~2.4k tokens). The branches the agent skipped are still one call away, and auto-expanding the same 12-memory hub would have cost ~8k tokens. The graph knows the roads; the agent decides the steps. Source: docs/demo/chain-walk.html.

---

Quick Start

keymem is an MCP server (a CLI), not a library. Run it with npx -y keymem (recommended — always the latest) or install the command globally with npm i -g keymem. Do not add it to your app with npm i keymem as a dependency: it bundles openai, zod, and the MCP SDK, so inside an existing project it just duplicates those trees (and can clash with your app's zod/ openai versions). The npm i keymem line npm shows on the package page is for libraries — it doesn't apply here.

# Optional global install (npx needs none). This puts a `keymem` command on PATH that
# MCP clients can spawn. Run bare, it starts a stdio MCP server and waits for a client —
# so point your MCP config at `keymem` (or just use `npx -y keymem` as shown below).
npm i -g keymem

Claude Desktop

Add to claude_desktop_config.json:

OpenAI embeddings:

{
  "mcpServers": {
    "keymem": {
      "command": "npx",
      "args": ["-y", "keymem"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

Local embeddings (no API key required) — bge-m3 recommended:

{
  "mcpServers": {
    "keymem": {
      "command": "npx",
      "args": ["-y", "keymem"],
      "env": {
        "EMBEDDING_BACKEND": "local",
        "LOCAL_EMBEDDING_MODEL": "bge-m3"
      }
    }
  }
}

bge-m3 (multilingual, recommended) auto-downloads ~570MB on first run, then caches. Omit LOCAL_EMBEDDING_MODEL for the lighter default (fast-multilingual-e5-large). Cross-encoder reranking is part of the core recall path and downloads a second model on first use; set "KEYMEM_RERANK": "false" only to disable it.

Plugin (recommended — Claude Code & Codex)

The repo is also a plugin marketplace, so one install wires up everything: the MCP server (daemon-backed shim), the UserPromptSubmit hook that passively surfaces related memories on every prompt, and the keymem skill carrying the recall/remember protocol.

Claude Code:

/plugin marketplace add donggyun112/keymem
/plugin install keymem@keymem

Codex CLI:

codex plugin marketplace add donggyun112/keymem
codex plugin add keymem@keymem

Codex prompts once to trust the hook; approve it or the push path stays silent. The plugin defaults to local bge-m3 embeddings (auto-downloads ~570MB on first run, no API key). For OpenAI embeddings, use the manual setup below instead — plugin MCP servers only see the env they declare.

Claude Code (manual)

# OpenAI embeddings
claude mcp add keymem -e OPENAI_API_KEY=your-key -- npx -y keymem

# Local embeddings (no API key required) — bge-m3 recommended (auto-downloads ~570MB on first run)
claude mcp add keymem -e EMBEDDING_BACKEND=local -e LOCAL_EMBEDDING_MODEL=bge-m3 -- npx -y keymem

Codex CLI (manual)

# OpenAI embeddings
codex mcp add keymem --env OPENAI_API_KEY=your-key -- npx -y -p keymem@latest keymem-shim

# Local embeddings (no API key required)
codex mcp add keymem --env EMBEDDING_BACKEND=local --env LOCAL_EMBEDDING_MODEL=bge-m3 -- npx -y -p keymem@latest keymem-shim

Use the keymem-shim entry point (not bare keymem): it runs the shared daemon the push-path hook talks to. For the hook, add to ~/.codex/config.toml:

[[hooks.UserPromptSubmit]]
[[hooks.UserPromptSubmit.hooks]]
type = "command"
command = "node /absolute/path/to/keymem/hooks/keymem-hook.mjs"
timeout = 5

Codex only forwards the env vars declared in its MCP entry, so pass every KEYMEM_* / SUPER_MEMORY_* override with --env.

That's it — recall and remember work immediately. The agent calls recall before its first reply, navigates with read_key/read_memory, and saves with remember.

For reliable proactive saving in Claude Code, add the following to ~/.claude/CLAUDE.md (MCP prompts are not automatically applied as persistent Claude Code instructions):

## keymem

- Before the first reply and whenever the topic changes, call `recall` silently with short noun-keyword queries.
- Before ending every reply, check whether this turn revealed a durable fact: a name, preference, decision, correction, project fact, or goal.
- If it did, call `remember` or `remember_batch` silently in the same turn with 3-6 diverse keys. A durable fact left unsaved is a bug.
- Use `correct` when existing information changes. Save nothing only when the turn revealed nothing durable.
- Treat `read_memory` as retrieval, not confirmation. Use its `validity.status`: qualify `aging`, and never assert `stale` as current without checking an external source or asking the user.
- Call `confirm_memory` only after an explicit current user assertion, an authoritative current source, or direct observation — never merely because a read succeeded.
- Never mention memory lookup or saving to the user.

In Codex, put the same block in ~/.codex/AGENTS.md. (The plugin install ships this as the keymem skill instead, so you can skip it there.)

For other MCP clients, include the memory_system_prompt MCP prompt in the agent's persistent system instructions.

Manual / Development

git clone https://github.com/donggyun112/keymem
cd keymem
pnpm install

Create .env:

OPENAI_API_KEY=your-openai-api-key
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

Or use local embeddings (no API key required):

EMBEDDING_BACKEND=local
LOCAL_EMBEDDING_MODEL=fast-multilingual-e5-large  # default; best fit for Korean/multilingual keys

pnpm dev
# or:
pnpm build
pnpm start

Requirements:

• Node.js 20+
• pnpm for local development
• OpenAI API key for OpenAI embeddings, or fastembed for local embeddings

---

Features

• N:M key/value graph — memories and the concepts that index them are separate spaces, linked many-to-many. One memory is reachable through many keys; one key leads to many memories.
• Agent-driven Key → Memory → Key navigation — the agent walks the graph deliberately instead of collapsing it into one opaque similarity search.
• Associative multi-hop recall — reach memories no embedding distance would connect, by following chains of shared keys.
• Confirmation-aware freshness — reads learn useful paths without certifying old content; explicit evidence refreshes facts across four decay profiles.
• One-step versioning — a correction retains its immediate predecessor and records what it superseded.
• Key types — concept keys match by similarity; name/proper_noun keys match exactly, so "동건" never matches "뉴턴" just for being short.
• Cross-lingual key merging (IDF) — 파이썬 and Python collapse into one canonical cluster instead of fragmenting the key space.
• Hebbian link learning — the path an agent actually traverses gets reinforced ("fire together, wire together"), so useful associations become easier to reach.
• Hybrid retrieval (optional direct mode) — BM25 + dense + Reciprocal Rank Fusion, with depth/confirmation-freshness modulation and configurable multi-hop expansion.
• Cross-encoder reranking (core default) — bge-reranker-v2-m3 re-scores the passive Top-1 pool and compatibility direct-mode candidates.
• Local-first — all data in a local JSON graph; no external database. OpenAI or fully-local embeddings (auto-downloaded).

Freshness and Depth

Every memory has a depth score 0.0 → 1.0, but retrieval and confirmation are separate:

Stage	Depth	Behavior
Shallow	< 0.3	Little explicit confirmation; minimal ranking boost.
Medium	0.3–0.7	Repeatedly confirmed; moderate ranking boost.
Deep	> 0.7	Strongly confirmed; maximum ranking boost, but still correctable and age-sensitive.

read_memory() increments access metadata and may reinforce the traversed key edge, but it does not change depth, last_confirmed_at, confirmation_count, or freshness. Only confirm_memory(memory_id, evidence) refreshes validity and increases depth +0.05; accepted evidence is an explicit current user assertion, an authoritative current source, or direct observation. A successful read alone is never confirmation.

Freshness decays from last_confirmed_at according to the memory's decay_profile:

Profile	Default half-life	Intended use
transient	7 days	Fast-changing state such as temporary plans or availability
standard	90 days	General facts; the default
stable	365 days	Slowly changing facts
permanent	No decay	Deliberately timeless or immutable facts

Every memory view includes a validity payload with freshness, status (fresh, aging, or stale), age_days, last_confirmed_at, confirmation_count, decay_profile, verification_recommended, and verification_required. fresh means freshness is at least 0.5; aging is at least 0.125 but below 0.5; stale is below 0.125 and must not be asserted as current without verification. Decay is soft: it lowers ranking through 0.2 + 0.8 × freshness and never deletes a memory. TTL remains the only automatic expiry mechanism.

For example, save a temporary plan with remember(..., decay_profile:"transient"); after the user explicitly says it is still current, call confirm_memory(memory_id, evidence:"user"). Do not confirm merely because read_memory returned it.

Key Types

Not all keys should behave the same. Names shouldn't match semantically — "동건" shouldn't match "뉴턴" just because they're both short Korean words.

Type	Matching	Use Case
concept (default)	Embedding similarity ≥ threshold (0.28 OpenAI / 0.60 local)	Topics, categories, attributes
name	Exact match only	Person names
proper_noun	Exact match only	Brands, places

Name/proper_noun keys also get an IDF penalty (×0.5) when they become hub keys connected to many memories, preventing them from polluting unrelated searches.

Versioning (one-step predecessor)

"user lives in Seoul"   (depth: 0.4 → weakened to 0.12, preserved)
        ↑ superseded by
"user moved to Busan"   (depth: 0.0, new)

keymem retains the immediate predecessor instead of overwriting it. The superseded record is excluded from active retrieval regardless of its depth, and the new version becomes current. A later correction prunes the grandparent, so provenance is one step rather than a full-history archive.

Key Merging

Add key "파이썬"  → finds existing "Python" (similarity 0.87 > threshold 0.85)
                 → reuses existing key instead of creating duplicate

Prevents key space fragmentation. The same concept across languages or phrasing stays unified.

Agent-driven Retrieval (default)

The default MCP API crosses from Key Space to one Value while preserving explicit graph navigation:

1. recall(query, context) returns ranked key clusters and the Top-1 memory under the strongest key. The raw context ranks memories within that key.
2. The memory is a passive preview with validity, matched_key, and every connected_keys[].key_id. It does not increment access/depth, reinforce links, learn aliases, or confirm freshness.
3. The agent can use relevant content immediately or follow a connected key with read_key(key_id). Later memories are not automatically injected.
4. read_memory(memory_id, via_key_id) remains the explicit full-read path. It updates access metadata and reinforces only the traversed edge; it does not confirm or deepen the memory.

Semantically merged keys are preserved as aliases on one canonical key cluster (for example Python + 파이썬). The recommended bge-m3 profile enables conservative short-key merging by default; override or disable it with KEYMEM_SHORT_KEY_MERGE. A key linked to at least three active memories is surfaced as a hub with is_hub, memory_count, and specificity metadata rather than being hidden by IDF. Override the hub threshold with KEYMEM_KEY_HUB_MIN_LINKS.

Direct Hybrid Retrieval (optional compatibility mode)

Set KEYMEM_DIRECT_RECALL=true to expose recall_memories(), a one-call memory retrieval path. Three signals run in parallel and are fused with Reciprocal Rank Fusion (RRF_K = 60):

• BM25 (sparse): lexical full-text search over memory content (MiniSearch, fuzzy + prefix). Catches exact terms, names, and rare tokens that embeddings blur.
• Dense Path A (key matching): query embedding → match keys → follow links → memories. Score = keySim × IDF × linkWeight, summed across all matching keys.
• Dense Path B (content matching): query embedding → directly compare against memory content embeddings. Finds memories even when they weren't tagged with the right keys.

Sparse and dense rank lists are merged by RRF, then modulated by depth and confirmation freshness before configurable multi-hop expansion (hops=1–5, default 2). This compatibility tool is hidden by default so agents use explicit key navigation instead of collapsing the graph into one search call.

Hebbian Link Learning

Reading a full memory is a write, not just a read. In the default flow, recall() and read_key() are read-only; read_memory(memory_id, via_key_id) reshapes the selected path:

• The traversed via_key_id → memory_id link is reinforced (+0.1, capped at 3.0).
• A full read increments access metadata but changes neither depth nor last_confirmed_at, so it never refreshes freshness. Freshness continues to decay as elapsed time grows. Evidence-backed confirm_memory() increases depth and refreshes freshness by advancing last_confirmed_at.

Reinforcement is scoped to the key the agent actually traversed — not every key attached to the memory. This is the literal Hebbian rule ("fire together, wire together") and prevents unrelated associations from growing when the memory is reached through a different concept. Weights are clamped to [0.1, 3.0].

Link weights feed back into read_key() ranking, so repeatedly selected paths become easier to reach. Optional recall_memories() retains the previous matched-link reinforcement and explored-link decay behavior.

---

Architecture

│                      Key Space                          │
│   [name] [동건] [programming] [python] [fruit] [red]   │
│      ↓      ↓         ↓           ↓       ↓      ↓     │
│   [vec]  [exact]    [vec]       [vec]   [vec]  [vec]   │
                         │ N:M links
                         ↓
│                     Value Space                         │
│   "user's name is Donggeon"     depth: 0.85  (deep)    │
│   "user likes Python"           depth: 0.30  (medium)  │
│   "user likes strawberries"     depth: 0.05  (shallow) │

Default MCP navigation:

1. Embed the query and match canonical key concepts plus exact aliases.
2. Return key clusters with memory_count, is_hub, and specificity; do not return memory content.
3. Rank a selected key's memory handles by link weight, depth, and confirmation freshness in read_key().
4. Return full content and adjacent key clusters from read_memory(); reinforce the traversed edge only when via_key_id is supplied.
5. Repeat read_key(next_key_id) to walk the graph deliberately.

Optional recall_memories() algorithm (hybrid, configurable 1–5 hops; default 2):

Three retrieval signals run in parallel, then get fused and expanded:

1. BM25 (sparse): lexical search over memory content (MiniSearch, fuzzy 0.2 + prefix). Keep top 50.
2. Dense Path A (keys): embed query → match keys (concept: cosine ≥ threshold; name/proper_noun: substring match → score 1.0) → take top 10 keys → follow links. Score = keySim × IDF × linkWeight, summed across matching keys.
3. Dense Path B (content): compare query embedding directly against memory content embeddings (cosine ≥ threshold).
4. RRF fusion: merge the BM25 and dense rank lists via score += 1 / (RRF_K + rank + 1) (RRF_K = 60).
5. Depth & freshness modulation: score × (0.9 + depth × 0.1) × (0.2 + 0.8 × freshness), using the selected 7/90/365-day half-life or no decay for permanent.
6. Associative expansion (hops, default 2): breadth-first from the directly-matched set — each round follows shared keys (× HOP_DECAY(0.3) × IDF × linkWeight) and explicit related_to links (bidirectional, × HOP_DECAY) to the next frontier. hops=N walks up to N steps, so a memory's hop is its shortest chain distance. Score decays by HOP_DECAY per hop.
7. Hebbian update: reinforce matched-key links of returned memories (+0.1), decay explored-but-unreturned links (−0.005).
8. Return ranked results with hop field (1 = direct, 2+ = associative distance).

Similarity thresholds (calibrated per embedding model)

Embedding backends have very different cosine distributions, so a single threshold set cannot serve all of them. The thresholds below are calibrated per model (getThresholdProfile() in src/embedding.ts):

Threshold	OpenAI	Local BGE (en)	Local e5 (multilingual)
Key recall (query↔key cosine)	0.28	0.60	0.85
Content recall (query↔content cosine)	0.28	0.50	0.80
Key auto-link	0.50	0.60	0.93
Key merge	0.85	0.85	0.97
Memory dedup	0.90	0.90	0.985

Why e5 differs so much: multilingual-e5 packs embeddings into a narrow high-cosine band (~0.86–0.99). Same-word query↔key pairs (asymmetric query:/passage: prefixes) still separate cleanly (~0.89 vs ≤0.82), but key↔key and content↔content do not — distinct facts like "A uses Postgres" and "B uses Mongo" sit at ~0.96, dangerously close to true paraphrases (~0.99). Hence e5's merge/dedup/auto-link thresholds are pushed high to avoid silently collapsing distinct memories.

Drift escape hatch: if you switch models or your data's character drifts, override any threshold without code changes:

KEYMEM_KEY_RECALL=0.82
KEYMEM_MEMORY_DEDUP=0.99
# also: _KEY_MERGE, _KEY_AUTOLINK, _CONTENT_RECALL  (values in [0,1])

Score gate, distribution gate, and contradiction band can also be tuned per deployment:

Env var	Default (profile)	Description
KEYMEM_MIN_SCORE	per-model (e.g. 0.55 for bge-m3)	Absolute cosine floor for optional recall_memories(). Set to 0 to disable.
KEYMEM_GATE_Z	0 by default	Opt-in distribution gate for recall_memories() (robust-z, median/MAD). Values around 2–5 are typical; 0 disables it.
KEYMEM_CONTRADICTION	per-model (e.g. 0.80 for bge-m3)	Contradiction-band lower bound. Memory pairs whose cosine similarity falls in [contradiction, memoryDedup) are flagged as contradictions. read_memory(), related(), and optional recall_memories() expose conflicting IDs.
KEYMEM_AUTOKEY	true	Auto-key self-healing: learn missing search terms from real usage. Set false to disable.
KEYMEM_AUTOKEY_PROMOTE_N	3	Routing-confirmed selections of a (key, query) pair before the query is folded into the key space.
KEYMEM_AUTOKEY_CONFIRM_FLOOR	0.45	Lowest query↔key cosine eligible for routing-confirmation learning. Repeated selections through the same key can teach a below-gate query alias; this confirms routing only, never content freshness. Lower (e.g. 0.40) to catch more borderline paraphrases; set ≥ the recall threshold to disable.
KEYMEM_AUTOKEY_MAX_ALIASES	8	Max learned aliases promoted per key.
KEYMEM_AUTOKEY_PRUNE_AGE	2592000	Seconds before a never-hit learned alias is pruned by cleanup_expired (30 days).
KEYMEM_DECAY_TRANSIENT_DAYS	7	Half-life in days for transient memories. Must be finite and greater than zero.
KEYMEM_DECAY_STANDARD_DAYS	90	Half-life in days for the default standard profile. Must be finite and greater than zero.
KEYMEM_DECAY_STABLE_DAYS	365	Half-life in days for stable memories. Must be finite and greater than zero.

Why e5 gates are opt-in: multilingual-e5's narrow cosine band (~0.86–0.99) makes a static floor unreliable, while held-out tests showed distribution and key-proximity gates can also overfit. Both are disabled by default to avoid hiding real memories. Use bge-m3 for reliable not-found behavior, or calibrate e5 gates on your own corpus.