io.github.donggyun112/keymem

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. The synchronous hook waits up to 9 seconds for /inject (set KEYMEM_HOOK_TIMEOUT_MS to tune it); local embedding and reranking can add several seconds to prompts that trigger recall.

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 = 10

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. It mandates 3 blind recall() calls before the first reply — appropriate when there's no hook surfacing anything passively. If you do wire up a UserPromptSubmit-equivalent push path yourself, set KEYMEM_HOOK_INSTALLED=true so the prompt reacts to what was surfaced instead of blind-guessing on top of it (this is set automatically by the plugin's .mcp.json).

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) — Kiwi BM25 over keys and content + key embeddings + 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:

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:

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.

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 checks which facts the question needs. It can use the preview when those facts are present; otherwise it follows a connected key for a missing fact with read_key(key_id, missing_fact_query) or recalls that fact directly. It stops when the evidence is complete or no promising path remains. 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.

Associative Recall Engine (library API, used internally by recallInject)

MemoryGraph.recall() is a one-call ranked retrieval path used by recallInject() and available to library callers. It combines two candidate paths with Reciprocal Rank Fusion (RRF_K = 60):

• Kiwi BM25: lexical search over memory keys and content, using the official kiwi-nlp WASM tokenizer in Node. Korean morphology is tokenized locally; no Python process is required.
• Key matching: query embeddings match concept keys; exact names and aliases provide literal entry points. Key links lead to candidate memories.

Memory bodies have no embeddings. Cross-encoder reranking remains enabled and scores query–content pairs directly. Graph expansion, depth, and confirmation freshness still affect ranking. The default MCP recall tool uses explicit key navigation, so agents can drive later hops deliberately.

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. recall()/recallInject() retain 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.

recall() algorithm (hybrid, configurable 1–5 hops; default 2; used internally by recallInject()):

1. Tokenize the query and memory keys/content with Kiwi, then retrieve BM25 candidates.
2. Match concept keys with query embeddings and literal name/alias matches, then follow their memory links.
3. Fuse lexical and key-path ranks with RRF (RRF_K = 60).
4. Apply depth and confirmation freshness, and expand through shared keys and explicit related_to links for the configured hops.
5. Rerank candidates with the cross-encoder and return ranked results. Matched-link reinforcement and explored-link decay retain their existing behavior.

Storage and duplicate handling

Only keys retain embedding vectors. Existing memory-body vectors are ignored on load and omitted after the next successful save; key vectors, memory text, links, and history are retained. Back up the store before upgrading if you need to reopen it with an older release.

Duplicate detection compares normalized memory text exactly, within the existing namespace and active-memory rules. Paraphrases are separate records. Automatic confirmation requires normalized utterance and body text to match exactly. New memories do not gain links or contradiction flags from body-vector similarity; supply keys and explicit relationships, and use correct for changed facts. Existing explicit links and recorded contradictions remain readable.

Key similarity thresholds

Embedding thresholds apply to keys, not memory bodies. getThresholdProfile() in src/embedding.ts supplies model-specific defaults; use KEYMEM_KEY_RECALL, KEYMEM_KEY_MERGE, KEYMEM_KEY_AUTOLINK (auto-key alias promotion), and KEYMEM_SHORT_KEY_MERGE to tune key routing and canonicalization. An uncalibrated model falls back to the BGE profile with a warning.

Legacy body-cosine settings (KEYMEM_CONTENT_RECALL, KEYMEM_CONTENT_RECALL_SHORT, KEYMEM_MEMORY_DEDUP, KEYMEM_CONTRADICTION, KEYMEM_MIN_SCORE, KEYMEM_GATE_Z, and KEYMEM_KEY_GATE) no longer control memory retrieval or writes. BM25 scores, key cosine scores, RRF ranks, and cross-encoder scores are different scales; do not reuse an old body-cosine threshold as a lexical relevance threshold.

For cross-language recall, retain multilingual keys and aliases (for example 딸기 and strawberry). Lexical body search alone does not translate queries.

---

MCP Tools

The tool set contains 10 tools:

TTL-expired memories and key/memory/link counts are no longer agent-facing tools: the daemon sweeps expired memories itself (once at startup, then every KEYMEM_CLEANUP_INTERVAL_MS; the stdio path sweeps once at startup), and the key/memory/link stats are already passively injected into SERVER_INSTRUCTIONS on every turn — a separate memory_stats() call was pure duplication.

Scores carry score_kind. Key recall exposes key_relevance from key cosine or bounded lexical relevance. content_relevance is bounded BM25 (s / (1 + s)), not cosine. read_key uses within_key_rank, with cross-encoder relevance when available and bounded lexical relevance otherwise. Direct recall uses rrf_fused_rank; RRF rank_score is a rank-fusion value, not a similarity probability.

A system prompt template is also available via the memory_system_prompt MCP prompt — include it to instruct the agent to recall silently, use diverse keys, and never mention the memory system to users.

---

Local embedding models

BGE-M3 (recommended, multilingual) — auto-downloaded: set LOCAL_EMBEDDING_MODEL=bge-m3 (aliases: bgem3, baai/bge-m3, fast-bge-m3). On first use the model is fetched automatically if missing — quantized ONNX (~570MB, from onnx-community/bge-m3-ONNX) plus the tokenizer/config (from BAAI/bge-m3) — and cached under ~/.keymem/models/bge-m3. No manual download needed:

EMBEDDING_BACKEND=local
LOCAL_EMBEDDING_MODEL=bge-m3
# optional — point at an existing model dir to skip the download (backward compatible):
# LOCAL_EMBEDDING_MODEL_PATH=/absolute/path/to/model-dir   # dir with model.onnx + tokenizer files
# LOCAL_EMBEDDING_MODEL_FILE=model.onnx                    # optional; default is model.onnx
# optional: KEYMEM_EMBED_THREADS=4                         # ONNX intra-op threads (default: a quarter of the machine, max 6)

First run downloads ~570MB once, then reuses the cache. If LOCAL_EMBEDDING_MODEL_PATH already holds the model it is used as-is with no download (a partial dir is self-healed — only missing files are fetched). Online-API backends (OpenAI) and fastembed built-ins are unaffected.

bge-m3 runs on its own ONNX session, not through fastembed. Inputs use their actual token length. Its vector-space fingerprint is local:bge-m3+nopad; a fingerprint change triggers key-vector migration. Earlier padding/latency and retrieval measurements in BENCHMARKS.md describe the previous body-embedding engine.

Cross-encoder reranking (core): the default recall MCP tool's Top-1 path re-scores the candidate pool under its strongest key with bge-reranker-v2-m3. recall()/recallInject() results are reranked too. The model (~570MB, quantized) auto-downloads on first use and caches under ~/.keymem/models/reranker.

# optional: KEYMEM_RERANK=false              # disable the core reranker
# optional: KEYMEM_RERANK_MODEL_PATH=/dir    # use an existing model directory
# optional: KEYMEM_RERANK_POOL=30            # candidates re-scored (default 30)
# optional: KEYMEM_RERANK_THREADS=4          # ONNX intra-op threads (default: a quarter of the machine, max 6)

On by default. If the model cannot load, recall falls back to fused ranking. Query decomposition remains the caller's responsibility.

Task-conditioned evidence selection: expanded recall stays associative, but comparison-shaped queries are projected at the final evidence boundary so both named entities receive task-relevant support. KeyMem derives the comparison dimension after removing the entity names (for example, nationality or founded), keeps the graph candidate pool and association scores intact, and preserves the original associative winner for reinforcement. This is on by default; disable it with KEYMEM_TASK_EVIDENCE_SELECTION=false.

Reranker not-found gate (KEYMEM_RERANK_MIN_SCORE): in recall()/recallInject(), reject the complete result when the top cross-encoder logit is below this floor.

KEYMEM_RERANK_MIN_SCORE=0   # reject when top rerank logit < 0 (bge-reranker-v2-m3 scale)

⚠️ Caveats. (1) Unset by default — no gate. (2) The logit scale is model-dependent; 0 (≈ sigmoid 0.5) suits bge-reranker-v2-m3 (measured: same-language found ≈ +3.9, not-found ≈ −5 to −6) — recalibrate for other rerankers. (3) Trusted for SAME-LANGUAGE only. Cross-lingual relevance logits run low even when relevant (KR query ↔ EN memory ≈ −5.4), so the gate auto-bypasses on a script mismatch (KR↔Latin) to avoid false-rejecting cross-lingual hits — which means cross-lingual content must be reachable via bilingual keys (["Jiwoo","지우"]), and cross-lingual not-found precision is a known limitation. Leave this off if you can't tag bilingual keys.

Prefix behavior: BGE-M3 does not use passage:/query: prefixes — embeddings are passed through as-is. All other local models (e5, BGE-en, MiniLM) continue to use prefixes unchanged.

Multilingual key embeddings: bge-m3 remains supported. Historical model comparisons do not establish the quality or not-found behavior of the current Kiwi BM25 architecture.

If OPENAI_API_KEY is not set and EMBEDDING_BACKEND is unset, the server automatically uses the local fastembed backend. For English-only use or lower local resource usage, set LOCAL_EMBEDDING_MODEL=fast-bge-base-en-v1.5 or fast-bge-small-en-v1.5.

Switching backends is safe. The graph records an embedding fingerprint (backend + model id) identifying the vector space its embeddings live in. On startup, if the current backend's fingerprint or dimension differs from what is stored, the graph auto-migrates — every key is re-embedded with the new backend while content, links, depth, and access history are preserved (a graph.json.bak.* backup is written first). The fingerprint matters because two models can share a dimension yet produce incompatible vectors (e.g. fast-multilingual-e5-large and bge-m3 are both 1024-d); a dimension check alone would miss that swap and silently corrupt every similarity. Disable with KEYMEM_AUTO_MIGRATE=false. Re-embedding via OpenAI incurs one-time API cost proportional to your key count.

Migrating a pre-fingerprint (legacy) graph across same-dimension models. A graph written before fingerprinting has no recorded vector space, so a same-dimension model swap off it cannot be detected automatically. Set KEYMEM_FORCE_REEMBED=true for one startup to re-embed unconditionally and stamp the fingerprint; remove it afterward (left on, it re-embeds on every start). This is exactly the one-shot needed when moving an existing e5 graph to bge-m3.

---

Data Storage

All data is local. No external database required.

~/.keymem/
└── graph.json              # canonical keys, aliases, memories, weighted links

Set KEYMEM_DATA_DIR to use a different storage directory.

Linking a memory to its source conversation. When you save a memory, keymem stamps the active host session onto its source (host_session / host_agent / host_turn) for provenance. keymem does not expose a tool to read those transcripts back — it only reads them internally to resolve the active session. Locations are auto-detected per OS and honour the agents' env overrides:

• Claude Code — ~/.claude/projects/**/{session_id}.jsonl ($CLAUDE_CONFIG_DIR)
• Codex — ~/.codex/sessions/**/rollout-*-{session_id}.jsonl ($CODEX_HOME)

Access is gated. Because transcripts are local, potentially sensitive history, keymem only reads them to stamp provenance when trusted as the owner's personal local agent — i.e. a recognized host injected its session env (CLAUDE_CODE_SESSION_ID / CODEX_THREAD_ID), or you explicitly opt in with KEYMEM_TRANSCRIPT_ACCESS=true. Otherwise (a plain server, a remote deployment, a non-owner/custom agent) memories are saved without a host link. Set KEYMEM_TRANSCRIPT_ACCESS=false to force-disable even under a host agent.

The active session is found two ways:

1. Deterministic — the host injects its session id into every MCP server it spawns, and keymem reads it directly: Claude Code → CLAUDE_CODE_SESSION_ID, Codex → CODEX_THREAD_ID (which equals the rollout file's session id). The link is exact, with no guessing.
2. Heuristic fallback — for hosts that don't expose a session id (e.g. Claude Desktop), keymem uses the most-recently-modified transcript (with a staleness guard).

---

Benchmarks

Historical measurements of the previous body-embedding engine: on HotpotQA bridge questions (real external multi-hop data, gold labels, no LLM judge — and keys generated blind by independent subagents that never saw the question or answer), the key-graph retrieves both gold supporting paragraphs 63% of the time vs 53% for flat semantic retrieval and 35% for lexical (+10pp / +28pp) — the connected-but-dissimilar case it's built for. (Honest: my own hand-derived keys inflated this to 78/60; on non-multi-hop "comparison" questions the graph slightly hurts; it's retrieval-recall, not answer accuracy.) The read path is also O(1) (read_memory p50 ~45ms → ~0.01ms @ 500 memories). Full methodology and caveats: BENCHMARKS.md. These scores do not validate the current Kiwi BM25 + key-embedding engine; no production quality scores have been established for it.

---

Limitations

• Linear scan — suitable for personal use (~10k memories). FAISS/ChromaDB integration planned for larger scale.
• Later-hop round trips — recall completes the first Key → Memory hop, but following a connected key to another memory still requires read_key → read_memory.
• Hub breadth — broad keys can connect many memories. read_key() paginates hubs; the agent must choose whether to continue paging or follow a more specific adjacent key.
• Agent quality matters — key selection on remember affects retrieval quality. System prompt tuning is important.
• Lexical coverage — Kiwi BM25 does not translate or detect paraphrases by itself. Multilingual keys, key embeddings, and reranking help route and rank candidates, but cannot guarantee missing candidates are recovered.
• Threshold calibration — thresholds are tuned per embedding model. A new/uncalibrated model falls back to the BGE profile (with a warning); recalibrate via the KEYMEM_* env overrides.

---

Testing

pnpm test                        # unit tests (fast, no model download)
tsx test/scenarios.ts            # 21 end-to-end behavioral checks (local e5)
tsx test/robustness.ts           # threshold overrides + Hebbian pollution bounds
tsx test/migration.ts            # backend/dimension switch auto-migration (no brick)
tsx test/nhop.ts                 # N-hop chained traversal (recall hops parameter)
tsx test/depth-noise.ts          # deep-hop noise bounds + relative score floor
tsx test/live-multilingual.ts    # interactive multilingual recall demo

# Manual retriever-quality check (NOT part of pnpm test):
EMBEDDING_BACKEND=local npx tsx test/retriever-quality.live.ts
# For bge-m3: also set LOCAL_EMBEDDING_MODEL=bge-m3 LOCAL_EMBEDDING_MODEL_PATH=/abs/dir

scenarios.ts and robustness.ts exercise the real local embedding backend (direct/associative/cross-lingual recall, versioning, depth growth, dedup, TTL, Hebbian learning, namespace isolation). Key-threshold recalibration and retrieval quality require fresh runs after an engine or model change; historical passing results do not validate this architecture.

---

Roadmap

• [ ] FAISS/ChromaDB for scale
• [ ] Coding agent profile (different key strategies for code context)
• [ ] Memory export/import
• [ ] Multi-user support

---

Author

donggyun112 — github.com/donggyun112

Repository: donggyun112/keymem · Issues & PRs welcome.

License

MIT © donggyun112