keymem is an MCP server that gives LLM agents associative long-term memory: save durable facts, recall them by related keys, and navigate a key/memory graph.
Recall related memories — recall() returns ranked key clusters plus a passive Top-1 memory with validity, matched key, and connected keys.
Navigate the key graph — browse_keys() and read_key() explore concepts and list memory handles; read_memory() reads full content and exposes connected keys for further hops.
Save durable facts — remember() and remember_batch() store memories with atomic keys, key types, namespaces, TTL, decay profiles, and related-to links.
Correct and delete — correct() performs versioned updates, forget() permanently removes wrong memories, and dismiss() weakens a bad key-to-memory association.
Maintain freshness — confirm_memory() refreshes validity only with explicit evidence; memories track decay profiles, age, and verification status.
Utility operations — related() finds neighbors, list_memories() lists stored facts, cleanup_expired() removes TTL-expired entries, and memory_stats() reports graph counts.
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
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.
Related MCP server: MahoRAGa
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.
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 withnpm i -g keymem. Do not add it to your app withnpm i keymemas a dependency: it bundlesopenai,zod, and the MCP SDK, so inside an existing project it just duplicates those trees (and can clash with your app'szod/openaiversions). Thenpm i keymemline 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 keymemAdd 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. OmitLOCAL_EMBEDDING_MODELfor 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.
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@keymemCodex CLI:
codex plugin marketplace add donggyun112/keymem
codex plugin add keymem@keymemCodex 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.
# 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# 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-shimUse 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 = 5Codex 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).
git clone https://github.com/donggyun112/keymem
cd keymem
pnpm installCreate .env:
OPENAI_API_KEY=your-openai-api-key
OPENAI_EMBEDDING_MODEL=text-embedding-3-smallOr use local embeddings (no API key required):
EMBEDDING_BACKEND=local
LOCAL_EMBEDDING_MODEL=fast-multilingual-e5-large # default; best fit for Korean/multilingual keyspnpm dev
# or:
pnpm build
pnpm startRequirements:
Node.js 20+
pnpm for local development
OpenAI API key for OpenAI embeddings, or fastembed for local embeddings
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).
Every memory has a depth score 0.0 → 1.0, but retrieval and confirmation are separate:
Stage | Depth | Behavior |
Shallow |
| Little explicit confirmation; minimal ranking boost. |
Medium |
| Repeatedly confirmed; moderate ranking boost. |
Deep |
| 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 |
| 7 days | Fast-changing state such as temporary plans or availability |
| 90 days | General facts; the default |
| 365 days | Slowly changing facts |
| 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.
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 |
| Embedding similarity ≥ threshold (0.28 OpenAI / 0.60 local) | Topics, categories, attributes |
| Exact match only | Person names |
| 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.
"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.
Add key "파이썬" → finds existing "Python" (similarity 0.87 > threshold 0.85)
→ reuses existing key instead of creating duplicatePrevents key space fragmentation. The same concept across languages or phrasing stays unified.
The default MCP API crosses from Key Space to one Value while preserving explicit graph navigation:
recall(query, context) returns ranked key clusters and the Top-1 memory under the strongest key. The raw context ranks memories within that key.
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.
The agent can use relevant content immediately or follow a connected key with read_key(key_id). Later memories are not automatically injected.
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.
recallInject)MemoryGraph.recall() is a one-call ranked retrieval path, not exposed as its own MCP tool — recallInject() (the auto-injection hook in daemon.ts) is its production caller, and it's available directly if you use keymem as a library. 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). The default MCP recall tool uses explicit key navigation (above) instead of this engine, so agents drive expansion deliberately rather than collapsing the graph into one search call.
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.
│ 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:
Embed the query and match canonical key concepts plus exact aliases.
Return key clusters with memory_count, is_hub, and specificity; do not return memory content.
Rank a selected key's memory handles by link weight, depth, and confirmation freshness in read_key().
Return full content and adjacent key clusters from read_memory(); reinforce the traversed edge only when via_key_id is supplied.
Repeat read_key(next_key_id) to walk the graph deliberately.
recall() algorithm (hybrid, configurable 1–5 hops; default 2; used internally by recallInject()):
Three retrieval signals run in parallel, then get fused and expanded:
BM25 (sparse): lexical search over memory content (MiniSearch, fuzzy 0.2 + prefix). Keep top 50.
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.
Dense Path B (content): compare query embedding directly against memory content embeddings (cosine ≥ threshold).
RRF fusion: merge the BM25 and dense rank lists via score += 1 / (RRF_K + rank + 1) (RRF_K = 60).
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.
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.
Hebbian update: reinforce matched-key links of returned memories (+0.1), decay explored-but-unreturned links (−0.005).
Return ranked results with hop field (1 = direct, 2+ = associative distance).
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 |
| per-model (e.g. | Absolute cosine floor for |
|
| Opt-in distribution gate for |
| per-model (e.g. | Contradiction-band lower bound. Memory pairs whose cosine similarity falls in |
|
| Auto-key self-healing: learn missing search terms from real usage. Set |
|
| Routing-confirmed selections of a |
|
| 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. |
|
| Max learned aliases promoted per key. |
|
| Seconds before a never-hit learned alias is pruned by the daemon's automatic TTL sweep (30 days). |
|
| How often the daemon sweeps expired memories/aliases on its own. The stdio path sweeps once at startup instead (no long-running loop to schedule against). |
|
| Half-life in days for |
|
| Half-life in days for the default |
|
| Half-life in days for |
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.
Distribution gate parameters:
gateZ — set via KEYMEM_GATE_Z, or pass min_z directly if you call recall() as a library.
0 disables the gate (default for bge-m3, bge, openai, minilm — where min_score already works).
Both gates compose (AND): a result must clear both min_score and gateZ to be returned.
A literal name/proper-noun key match (e.g. querying a stored name-typed key exactly) is always a definite anchor and bypasses the distribution gate.
GATE_MIN_POPULATION = 8: the gate is skipped when fewer than 8 memories exist (too few samples for a reliable distribution), so early-session recall is unaffected. The gate's background population is namespace-filtered and excludes superseded/expired memories, so recall scoped to a sparse namespace may fall below this threshold and skip the gate entirely.
Known e5 limitation: the optional gate keys off maxContentSim (content cosine only). A relevant fuzzy-key hit with a flat content distribution may be rejected; literal key matches bypass the gate.
An uncalibrated LOCAL_EMBEDDING_MODEL falls back to the BGE profile and logs a warning so the miscalibration is never silent.
Multilingual note: cross-lingual content matching has a same-language bias (a Korean query scores Korean memories higher regardless of meaning). The reliable cross-lingual path is the key graph — tag memories with keys in multiple languages (e.g.
["딸기", "strawberry"]) so recall hits the key exactly instead of relying on biased content similarity.
The tool set contains 10 tools:
Tool | Description |
| Return ranked keys plus one passive Top-1 memory with |
| Browse a namespace's active key vocabulary, hubs first, when recall has no entry hit. |
| List ranked memory IDs and metadata connected to one key. Pass the original query for relevance ordering; supports pagination for hubs. |
| Read full memory content, connected keys, and |
| Refresh freshness and deepen a current memory after explicit user evidence, an authoritative source, or direct observation. A read alone is not evidence. |
| Save memory with key concepts, optional TTL, and a |
| Versioned update. The immediate predecessor is preserved but inactive; omitted TTL/profile inherit from it. |
| Negative feedback: the fact is fine, this key should not have surfaced it. Weakens that one edge (floored, never severed) and cancels its pending alias learning |
| Permanently delete |
| Save multiple memories; each item accepts |
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 cosine-like key_relevance; read_key exposes content_relevance plus a within-key rank score; injected/direct memories expose relevance_score separately from their small RRF rank_score. Compare thresholds only within the same score kind.
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.
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_PATHalready 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. fastembed pads every input to 512 tokens, so a 4-token query cost as much as a full page — 199ms and a 9.6-core burst on every recall. Tokenizing to the actual length is 23x less CPU (15ms) at identical retrieval quality:
npm run bench(92%/97%/0.93), the ablation grid, andreal-evalover a 3018-vector live store all score the same, case for case. Pooling is unchanged (CLS + L2), but unpadded vectors sit ~0.98 cosine from padded ones, so the embedding fingerprint islocal:bge-m3+nopadand an existing graph re-embeds itself once on first load after upgrading (agraph.json.bak.local_bge-m3backup is written first). Other model families still use fastembed.
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) suitsbge-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.
Recommended for multilingual / cross-lingual use:
bge-m3. It separates unrelated queries more reliably and performs substantially better than e5 on the project's Korean↔English fixtures. For the optional direct-mode not-found gate, bge-m3's absolutemin_scorereaches ≈96% on the gate fixture; e5 requires corpus-specific tuning.
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 and memory 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-largeandbge-m3are both 1024-d); a dimension check alone would miss that swap and silently corrupt every similarity. Disable withKEYMEM_AUTO_MIGRATE=false. Re-embedding via OpenAI incurs one-time API cost proportional to your memory 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=truefor 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.
All data is local. No external database required.
~/.keymem/
└── graph.json # canonical keys, aliases, memories, weighted linksSet 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:
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.
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).
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.
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.
Cross-lingual content bias — with multilingual e5, raw content similarity favors same-language memories regardless of meaning. Tag memories with multilingual keys so the key graph (not biased content cosine) carries cross-lingual recall.
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.
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/dirscenarios.ts and robustness.ts exercise the real local embedding backend (direct/associative/cross-lingual recall, versioning, depth growth, dedup, TTL, Hebbian learning, namespace isolation). They double as a recalibration harness when tuning thresholds for a new model.
FAISS/ChromaDB for scale
Coding agent profile (different key strategies for code context)
Memory export/import
Multi-user support
donggyun112 — github.com/donggyun112
Repository: donggyun112/keymem · Issues & PRs welcome.
MIT © donggyun112
Browse the vocabulary of one namespace when recall has no hit or you need an entry point. Returns active key clusters with hubs first, then by linked-memory count. This is index metadata only; continue with read_key(key_id, query, namespace) and read_memory(memory_id, via_key_id, namespace).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| hubs_only | No | ||
| namespace | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose meaningful behavior: results are active key clusters ordered hubs-first then by linked-memory count, and it is index metadata only, not memory content. It omits pagination behavior, default limits, and what occurs for an unknown/empty namespace, which keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with purpose, then return shape, then next steps. Nothing is redundant and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description must stand alone; it orients the agent well on intent and follow-up calls but leaves parameter behavior (paging, hubs_only) unexplained for a four-parameter tool. Adequate for choosing the tool, incomplete for invoking it precisely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it never explains limit, offset, hubs_only, or the namespace argument. The phrase 'hubs first' hints at the hubs concept but does not clarify the hubs_only flag or paging semantics, leaving all four parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (browse) and resource (the vocabulary / key clusters of one namespace), and contrasts it with recall by describing itself as the fallback entry point. An agent can distinguish it from recall, read_key and read_memory without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit triggering condition: use it when recall returns no hit or you need an entry point, naming recall as the alternative it complements. It also routes the agent forward with read_key(key_id, query, namespace) and read_memory(memory_id, via_key_id, namespace), so the workflow position is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Confirm that a memory is still current using explicit present evidence. Never call this merely because read_memory returned the content. Use only after a current user assertion, an authoritative current source, or direct observation. Refreshes validity but does not change content or key links. A strong restatement passed as recall's context is already auto-confirmed there (check memories[0].auto_confirmed) — this tool is for evidence recall can't see: read_memory results, authoritative sources, or direct observation.
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | ||
| evidence | Yes | ||
| memory_id | Yes | ||
| namespace | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and discloses the key side effect: 'Refreshes validity but does not change content or key links.' It also warns about auto-confirmation, preventing subtle misuse. It does not discuss idempotence or error behavior, but the main behavioral impact is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four dense, purposeful sentences: action, negative guidance, side effects, and the recall exception are all front-loaded without filler. The only mild complexity is the implementation-specific `memories[0].auto_confirmed` reference, but it is relevant and clearly tied to when not to use the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description supplies enough guidance for tool selection and invocation: what counts as evidence, when not to call, and what the tool does and does not change. It falls short of fully complete because the semantics of `source` and `namespace` are not addressed, and no return behavior is mentioned despite there being no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are absent, and the description compensates for the evidence parameter by translating its enum into practical terms: 'current user assertion, authoritative source, or direct observation.' However, the `source` object and `namespace` parameter remain unexplained, so the agent still has to infer their meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Confirm that a memory is still current') tied to explicit evidence, and immediately distinguishes the tool from read_memory and recall's auto-confirmation path. An agent can tell exactly what this tool does and how it differs from its siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use and when-not-to-use guidance: never after a read_memory result alone, and only after a current user assertion, authoritative source, or direct observation. It also names the alternative flow (recall with a strong restatement auto-confirms), so the agent has a clear decision rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update outdated information. Use when user corrects you or info changes (e.g. moved cities, changed job). Old version is preserved but weakened — never lost. Omit keys to keep the same search terms. Omit decay_profile and ttl_seconds to preserve the predecessor's policies; provide either to replace that policy. related_to links the updated memory to other memory IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| keys | No | ||
| source | No | ||
| content | Yes | ||
| key_types | No | ||
| memory_id | Yes | ||
| related_to | No | ||
| ttl_seconds | No | ||
| decay_profile | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers meaningful behavior: the old version is 'preserved but weakened — never lost,' establishes a non-destructive update pattern, and explains the defaulting semantics of omitted fields. It omits return format and any auth/permission behavior, but the core mutation semantics are well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded, leading with purpose then immediately covering behavior and parameter defaults in tight sentences. Every clause carries information, though it reads as a run-on paragraph rather than separated concerns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter mutation tool with no annotations or output schema, it covers the essential behaviors (predecessor preservation, field defaults) an agent needs. Gaps remain around the undocumented source/key_types params and the response shape, but the critical decision-relevant behavior is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 8 parameters, so the description must compensate. It explains the non-obvious semantics of keys, decay_profile, ttl_seconds, and related_to, but leaves source, key_types, content, and memory_id undocumented, so roughly half the parameters remain unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('Update outdated information') and the examples ('moved cities, changed job') make the corrective-update intent concrete. It does not, however, explicitly differentiate itself from siblings like remember/confirm_memory, leaving that distinction to the reader.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a clear trigger condition ('Use when user corrects you or info changes') with illustrative examples, which is solid context for selection. It stops short of naming when-not-to-use or the alternative tools (e.g. remember for new facts, forget for removal).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tell keymem a recalled memory was surfaced by the WRONG key — the fact may be fine, it just should not have come up for this query. Pass the memory_id and the key_id it arrived under (recall returns both). Weakens that one key->memory link so the pairing ranks lower next time, and cancels any pending alias learning for it. The memory itself, its other keys, and its content are untouched, and the link is floored rather than severed, so nothing becomes unreachable. Use correct() when the fact changed and forget() when it is simply wrong.
| Name | Required | Description | Default |
|---|---|---|---|
| key_id | Yes | The key the memory was recalled under. | |
| memory_id | Yes | ||
| namespace | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly: it discloses that only one key->memory link is weakened, that ranking is lowered next time, that pending alias learning is cancelled, that the memory/other keys/content are untouched, and that the link is floored rather than severed so nothing becomes unreachable. That is unusually complete disclosure of effect and reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Although multi-sentence, it is front-loaded with the core purpose and each sentence adds a distinct, non-redundant fact (what changes, what does not, how to choose between siblings). No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation-style tool with no annotations and no output schema, the description covers effect, reversibility, and sibling disambiguation well. The only gap is the unexplained namespace parameter, which is a minor omission given how much else is disclosed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, so the description must compensate. It adds real meaning for memory_id and key_id, including the helpful hint that recall returns both, but the third parameter (namespace) is undocumented in both the description and the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource and a precise scope: 'Tell keymem a recalled memory was surfaced by the WRONG key.' It immediately clarifies the semantics (fact may be fine, just wrong pairing), which distinguishes it sharply from the correct() and forget() siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly routes the agent: 'Use correct() when the fact changed and forget() when it is simply wrong,' and separately distinguishes the case where 'the fact may be fine, it just should not have come up for this query.' Both when-to-use and alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a memory. Only use for completely wrong information. For outdated info, use correct() instead — it preserves history.
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It states 'permanently delete' indicating destructive action, but does not mention side effects, irreversibility, or authorization requirements. Adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no unnecessary words, front-loaded with the key action. Highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and no output schema, the description covers purpose and usage guidance well. Lacks detail on parameter format or behavior, but overall sufficient for an agent to understand its role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and there is one parameter (memory_id). The description does not explain the parameter, but the name is self-explanatory. Baseline is 3 for a single parameter; no additional value from description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a memory permanently and is for wrong information. It distinguishes from correct(), but does not explicitly mention that it takes a memory_id parameter, which is inferred from context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (completely wrong information) and when not to (outdated info), and recommends an alternative tool (correct()). Provides clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the memories stored under one key (concept), ranked. Returns the canonical key, its aliases, and hub metadata plus ranked memory IDs, metadata, and validity — never memory content. Always pass the original focused query and active namespace when known: handles are then ranked by content relevance, which is essential for hubs. Each memory's score is content_relevance × link_weight × depth_factor × freshness_factor when query is passed (link_weight × depth_factor × freshness_factor otherwise); content_relevance is a cosine, comparable to recall's key relevance — both only meaningful within this one key's ranking. Call read_memory(memory_id, via_key_id=key_id, namespace) on the selected handle to inspect the fact and reinforce the path; reading does not confirm that its content is current. Use limit/offset to page without flooding context.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| key_id | Yes | ||
| offset | No | ||
| namespace | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the return payload (canonical key, aliases, hub metadata, ranked IDs, metadata, validity), explicitly states it never returns memory content, explains the scoring formula and its semantics, and warns that reading does not confirm current content. This is unusually thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized: it opens with purpose and return summary, then usage guidance, then scoring formula, then a pointer to the next step, then pagination. Every sentence adds value, though the scoring formula section could be trimmed without losing critical meaning. The structure front-loads the key facts.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and five parameters, the description covers the return shape, ranking logic, caveats about content freshness, and pagination. It also provides cross-tool guidance (read_memory) that completes the workflow. No critical operational detail appears missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain all parameters. It covers key_id implicitly (the key), query and namespace (with their effect on ranking), and limit/offset for pagination. It also clarifies how query changes the scoring, which is essential for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List'), the resource ('memories stored under one key'), and the ranking behavior. It distinguishes itself from siblings by explicitly noting it never returns memory content and pointing to read_memory for that purpose, and it contrasts with recall's key relevance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises always passing the original focused query and active namespace, explains why (essential for hubs), and explicitly directs the agent to call read_memory on a selected handle. It implies when to use this tool (to list and rank) versus read_memory (to inspect content) but does not explicitly enumerate exclusions or alternative conditions beyond that.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the full content and validity of one stored memory (selected via read_key). Returns the memory and all connected key clusters so exploration can continue Key → Memory → Key. Pass via_key_id from the selected key: the read records access and only that traversed edge is Hebbian-reinforced. Reading does not change content depth or confirm that the content is current.
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes | ||
| namespace | No | ||
| via_key_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses that reading records access, that only the traversed edge is Hebbian-reinforced, and that reading neither changes content depth nor confirms the content is current. These are non-obvious side effects and non-effects that an agent could not infer from the name or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then the traversal workflow, then the side-effect caveats. Sentences are dense but each adds information; slightly long but no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description does describe the return ('the memory and all connected key clusters'), which is the key missing piece. It omits explanation of the namespace parameter, leaving one gap for a 3-param tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It richly explains via_key_id and its reinforcement behavior, but memory_id (the required param) and namespace are left entirely undocumented in both schema and description, so it only partially covers the semantics gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read the full content and validity of one stored memory') and immediately clarifies the input selector ('selected via read_key'), which distinguishes it from the read_key sibling. An agent knows this fetches a memory object, not a key.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent to obtain the id from read_key and pass via_key_id from the selected key, giving a clear workflow context (Key → Memory → Key). It does not state explicit when-not-to-use conditions or name alternative retrieval tools like recall or related, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search long-term memory for what is already known about the user, project, or topic — call this before your first reply and whenever the topic shifts. Always pass the active namespace when known. Returns {status, query, namespace, keys, memories}: ranked key clusters plus one passive Top-1 memory selected under the top key. The memory includes validity, matched_key, and connected_keys, each with a relevance score (cosine of that key to your query/context, sorted high→low). recall answers a question: check whether the Top-1 memory actually answers it. If it only points elsewhere, is partial, or the highest-relevance connected key is not the one you arrived by, take one more hop — read_key(that key_id, query, namespace) then read_memory — and stop as soon as the answer is complete. Each hop is one call; the store never fans out for you. Passive recall never reinforces links or changes access, depth, aliases, or confirmation — except: when context is a strong restatement of the returned memory, it is auto-confirmed (memories[0].auto_confirmed: true) without a separate confirm_memory call. An empty result includes empty keys/memories and nearest_keys.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| top_k | No | ||
| context | No | The raw user utterance or sentence this lookup serves. Keep query as short noun keywords; pass the sentence here — it drives content matching, which measures higher on sentence-shaped cues. | |
| explain | No | When true, also return namespace_memory_count; status distinguishes found, no_match, and empty_namespace. | |
| max_chars | No | Truncate the returned memory's content to this length. | |
| namespace | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the side-effect burden. It states passive recall never reinforces links or changes access/depth/aliases/confirmation, except for the auto-confirm case, and clarifies there is no fan-out — each hop is one call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loaded: purpose and timing first, then return shape and hop behavior. Every sentence carries operational information; the length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers return shape, memory fields, relevance ordering, empty-result shape, and auto-confirmation, which is substantial for a tool with no output schema. It omits only minor detail such as the meaning of nearest_keys and explicit status values outside explain mode.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%, so prose must compensate. The description adds meaning for query (short noun keywords), context (raw sentence that drives matching), and namespace (always pass when known), but top_k is left to inference and explain/max_chars are only covered by schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Search long-term memory') and immediately scopes it to known user/project/topic knowledge. It also distinguishes recall from sibling read_key/read_memory by framing it as the first-pass retrieval that answers a question.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to call before the first reply and whenever the topic shifts, and to pass the active namespace when known. It also gives concrete hop logic: if the Top-1 memory doesn't answer, call read_key then read_memory and stop when complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
MANDATORY END-OF-TURN GATE: before replying, save every durable fact newly revealed this turn (names, preferences, decisions, corrections, project facts, goals). A durable fact left unsaved is a bug; save silently in the same turn. Save nothing only after consciously confirming that nothing durable appeared. Before writing, recall() the topic in the same namespace and reuse returned canonical concepts or aliases. Use 3-6 diverse ATOMIC concept keys of 1-2 words each, never memory-specific phrases (use 'Nexora' and 'portfolio', not 'Nexora portfolio'); 3+-word keys are flagged in hints.phrase_keys and are measurably 91% unreachable singletons. CROSS-LINGUAL: register both language forms together (for example '포트폴리오' and 'portfolio'). Shared broad keys become navigable hubs. namespace groups memories by project/context; ttl_seconds sets expiry; decay_profile selects transient, standard (the default), stable, or permanent confirmation freshness; related_to adds explicit memory links; source attaches provenance and is auto-stamped with the server session, a timestamp, and — when a host agent (Claude Code, Codex) transcript is active — host_session/host_agent/host_turn. The response may include hints.near_keys (existing concepts your keys nearly duplicate — prefer reusing those concepts) and hints.language_note (add the missing-language variants).
| Name | Required | Description | Default |
|---|---|---|---|
| keys | Yes | ||
| source | No | ||
| content | Yes | ||
| key_types | No | ||
| namespace | No | ||
| related_to | No | ||
| ttl_seconds | No | ||
| decay_profile | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the burden of behavioral disclosure. It clearly states the tool is a write operation that modifies memory, and it explains the side effects: unsaved durable facts are bugs, keys become hubs, and hints may return near-duplicate keys. It also documents decay_profile semantics and source auto-stamping. However, it does not explain what the response contains beyond hints, whether the call is idempotent, or whether there are any rate limits or confirmation behaviors (e.g., confirm_memory). A 3 is fair — it covers the core mutation behavior but not all consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with the mandatory gate, but it is quite long — roughly 170 words — and mixes policy (what to save), style guidance (key naming rules), parameter semantics, and hint-handling instructions in one block. Every sentence adds information, but the structure is a single wall of text with no paragraph breaks, which makes it harder to scan. The urgency tone ('MANDATORY', 'bug') is justified but adds noise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, high-stakes memory-write tool with 8 parameters, no annotations, and no output schema, the description covers the essential behavioral contract: when to call, what to save, how to structure keys, how to handle cross-lingual facts, and what hints may come back. It is somewhat incomplete in that it does not explain key_types at all, does not describe the success/failure response body, and assumes the agent knows what 'canonical concepts' means from recall's description. Still, it provides far more operational context than most tool definitions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for all 8 parameters. It explains keys (atomic, 1-2 words, diverse), content (durable facts), namespace (groups memories by project/context), ttl_seconds (sets expiry), decay_profile (transient/standard/stable/permanent), related_to (explicit memory links), and source (provenance, auto-stamped). Only key_types is not explicitly explained, and it is an optional advanced field. This is strong compensation despite one gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a memory-save operation with a mandatory end-of-turn gate, specifying that durable facts must be saved silently before replying. It distinguishes itself from recall/read_memory/browse_keys by focusing on writing new facts, and from remember_batch by describing single-turn single-item saving. However, it never explicitly says 'saves facts to memory' in a simple verb+resource form — the purpose is conveyed through instructions rather than a direct statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: before every reply, save every durable fact newly revealed, and save nothing only after consciously confirming nothing durable appeared. It differentiates from remember_batch by framing this as the per-turn single-item save path, and it tells the agent to recall() the same namespace and reuse canonical concepts — an explicit integration with sibling tools. This is strong operational guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
MANDATORY END-OF-TURN GATE: when a turn reveals multiple durable facts, save them silently before replying. A durable fact left unsaved is a bug. Recall each topic first, reuse canonical concept-level keys (ATOMIC, 1-2 words each — never phrases), and register cross-lingual forms together. Each item: {content, keys, key_types?, namespace?, ttl_seconds?, decay_profile?, related_to?}; decay_profile defaults to standard. Returns saved IDs and is more efficient than multiple remember() calls.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations the description carries the full burden, and it does disclose useful traits: the save is silent, it returns saved IDs, and decay_profile defaults to standard. It omits failure modes, permission/auth needs, and key-collision behavior, leaving meaningful gaps for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the mandate, then moves to key guidance and the field signature. The emphatic 'A durable fact left unsaved is a bug' is arguably padding, but the rest of the sentences each carry actionable content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, it covers purpose, trigger, alternatives, item fields, and the return value (saved IDs). Only the semantics of a few item fields are missing, which is minor given the rest of the coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It enumerates the item fields and adds genuine guidance for 'keys' (atomic, 1-2 words, never phrases; register cross-lingual forms together) and the decay_profile default, but leaves 'source', 'key_types', and 'ttl_seconds' unexplained and just restates the rest of the schema signature.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (save multiple durable facts silently at end of turn) and explicitly differentiates from the sibling 'remember' by calling this 'more efficient than multiple remember() calls'. The core purpose is clear, though the heavy prescriptive framing partially buries it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger ('when a turn reveals multiple durable facts') and names the alternative ('more efficient than multiple remember() calls'), plus a prerequisite ('Recall each topic first'). It never states the converse exclusion (single fact → use remember), so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.30.0cleanup_expiredlist_memoriesmemory_statsrecall7 fields changedInput schema / properties / injectRemoved value: -{
- "type": "boolean"
-}Input schema / properties / inject_explore_shallowRemoved value: -{
- "type": "boolean"
-}Input schema / properties / inject_max_charsRemoved value: -{
- "type": "number"
-}Input schema / properties / inject_min_rel_scoreRemoved value: -{
- "type": "number"
-}Input schema / properties / inject_prefer_depthRemoved value: -{
- "type": "boolean"
-}Input schema / properties / inject_top_kRemoved value: -{
- "type": "number"
-}Input schema / properties / max_charsAdded value: +{
+ "description": "Truncate the returned memory's content to this length.",
+ "type": "number"
+}relatedv0.29.0browse_keysconfirm_memorycorrect2 fields changedInput schema / properties / decay_profileAdded value: +{
+ "enum": [
+ "transient",
+ "standard",
+ "stable",
+ "permanent"
+ ],
+ "type": "string"
+}Input schema / properties / ttl_secondsAdded value: +{
+ "type": "number"
+}dismissread_keyread_memoryrecall2 fields changedInput schema / properties / contextAdded value: +{
+ "description": "The raw user utterance or sentence this lookup serves. Keep query as short noun keywords; pass the sentence here — it drives content matching, which measures higher on sentence-shaped cues.",
+ "type": "string"
+}Input schema / properties / explainAdded value: +{
+ "description": "When true, also return namespace_memory_count; status distinguishes found, no_match, and empty_namespace.",
+ "type": "boolean"
+}rememberremember_batch1 field changedInput schema / properties / items / items / properties / decay_profileAdded value: +{
+ "enum": [
+ "transient",
+ "standard",
+ "stable",
+ "permanent"
+ ],
+ "type": "string"
+}v0.17.1read_keyread_memoryrecall2 fields changedInput schema / properties / inject_max_charsAdded value: +{
+ "type": "number"
+}Input schema / properties / inject_min_rel_scoreAdded value: +{
+ "type": "number"
+}rememberv0.14.10get_conversationv0.14.8cleanup_expiredcorrectforgetget_conversationlist_memoriesmemory_statsread_keyread_memoryrecallrelatedrememberremember_batchScored across 10 tools
Each tool maps to a distinct operation: retrieval (browse_keys/read_key/read_memory/recall), writing (remember/remember_batch), updating (correct/confirm_memory), and deleting/decaying (forget/dismiss). The only close pair, remember vs remember_batch, is clearly separated by single vs multiple facts. Correct, forget, and dismiss are carefully differentiated with usage guidance.
The toolkit uses imperative lowercase verbs throughout, with many verb_noun compounds like read_key, read_memory, browse_keys, and confirm_memory. However, several tools are standalone verbs without objects (recall, correct, dismiss, forget, remember), creating a slight inconsistency in naming shape.
Ten tools is a well-scoped size for a memory server covering search, browsing, reading, writing, updating, and forgetting. Each tool has a clear role, and there is no redundant surface area. The batch variant of remember is justified by efficiency and does not feel like filler.
The core lifecycle is covered: recall/read for retrieval, remember/remember_batch for creation, correct/confirm_memory for updates, and forget for deletion, plus dismiss for link-level correction. Minor gaps exist around namespace enumeration and explicit alias/history management, but agents can complete normal workflows without dead ends.
Graph memory for AI agents: entities, cause-effect links, cross-session recall, time travel.
Shared long-term memory for AI agents: save and recall context as a searchable knowledge graph.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Persistent memory and knowledge graph for AI assistants — keyword + vector + graph search.
