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
Restart the client. bettermemory doctor exits 0 when it's wired
correctly and prints a one-line fix for anything that isn't.
Kick the tyres 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
- Every hit carries a staleness verdict — calendar age, the paths it
cites, commits landed since it was last confirmed.
- Nothing is auto-injected; retrieval is a deliberate tool call. The 18
default tools still charge schema every turn: a serialized
tools/list of 33,960 bytes, 27,092 of it names and descriptions,
measured 2026-07-31 at 3.32.0 (bench/toolcost). CI caps
the descriptions. The claude-mem head-to-head in that directory is a
2026-07-26 run whose bettermemory arm predates these cuts, so its
ratio is dated rather than current.
- Write gates: transient state, secret-shaped tokens and near-duplicates
bounce; claims about you stage for confirmation.
- One markdown file per memory. Greppable, git-syncable. Markdown is
canonical; the SQLite index next to it is a derived cache you can
delete. No cloud, no account.
bettermemory eval measures whether memory actually helped, against
your own log. Ours is published — a floor, from one
user's store, caveats and misses included.
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:
uv tool install bettermemory — or pipx install bettermemory,
or pip install bettermemory into a venv. Python 3.11–3.14.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.)bettermemory doctor — exit 0 means correctly wired; every failed
check prints a one-line fix.- Have the user restart the client so the server loads, then confirm
by asking the model "what memory tools do you have?"
Your operating contract — tool signatures, retrieval discipline,
write gates — is docs/api.md; the server's
instructions block delivers the core policy automatically. For the
long-form policy in your system prompt: bettermemory init --with-addendum. Migrating from Claude Code's built-in auto-memory:
bettermemory ingest imports those files once.
Everything else
You shouldn't need it, but it's all written down: mechanics, storage
format, the full tool surface, CLI, configuration and limitations in
internals; per-client setup in clients and
installation; eval methodology in eval;
postmortems in incidents; release history in
CHANGELOG; dev setup and the compatibility contract in
CONTRIBUTING.
MIT licensed — see LICENSE.