io.github.0Mattias/bettermemory

An MCP memory server for coding agents. Stored facts get checked against the filesystem and git before the model relies on them, so a memory that has rotted is flagged instead of quoted back at you.

Install

Claude Code — two slash commands, zero config:

/plugin marketplace add 0Mattias/bettermemory
/plugin install bettermemory@bettermemory

Anything else that speaks MCP:

uv tool install bettermemory
bettermemory init --client claude-desktop   # or cursor / cline / claude-code

Restart the client. bettermemory doctor exits 0 when it's wired correctly and prints a one-line fix for anything that isn't.

Try it without installing: uvx bettermemory try writes a memory citing a file, deletes the file, and shows the next search flagging it. Offline, throwaway store.

What it does

• Checks memory before believing it. Every hit carries a staleness verdict: calendar age, whether the paths it cites still exist, and the commits landed since it was last confirmed. Declared claims (path, path::symbol, path::NAME=literal) are re-checked against the working tree; a claim that stops being true blocks the stamp instead of riding along.
• Retrieval is deliberate. Memory is a tool call, not an injection. Write gates bounce transient state, secret-shaped tokens and near-duplicates; claims about you stage for confirmation.
• The code is the model. Search is deterministic lexical ranking — keyword + BM25, fused — over your own vocabulary. No embedding models, no downloads, nothing to warm up, same answer every time.
• Plain files. One markdown file per memory. Greppable, git-syncable, no cloud, no account. The SQLite index beside the files is a derived cache you can delete; bettermemory reindex rebuilds it.
• Rot gets acted on, not accumulated. Episodes journal per-session run-state without polluting durable search; health telemetry and curation tools surface what drifted, what went cold, and what contradicts what.
• Receipts, not adjectives. The claims above are measured by preregistered benchmarks with published artifacts — misses included — in [bench/][bench], and bettermemory eval scores whether memory actually helped against your own log ([ours is published][eval-results]).

For agents

You were likely handed this link with "set this up." On Claude Code, the two plugin commands above are the whole install — skip to step 3. Everywhere else, steps are idempotent and safe to re-run:

1. uv tool install bettermemory — or pipx install bettermemory, or pip install bettermemory into a venv. Python 3.11–3.14.
2. bettermemory init --client claude-code — likewise claude-desktop, cursor, cline. For any other MCP host, plain bettermemory init prints the canonical mcpServers JSON snippet plus known config locations. (Continue needs a hand-written YAML entry — see [docs/clients.md][clients-continue].)
3. bettermemory doctor — exit 0 means correctly wir

... View full README on GitHub