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 con