donggyun112/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*:
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
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.
Claude Desktop
Add to claude_desktop_config.json:
**OpenAI embeddings:**
**Local embeddings (no API key required) — bge-m3 recommended:**
> 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:**
**Codex CLI:**
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)
Codex CLI (manual)
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:
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.