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:

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

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