bettermemory 3.31.1

Memory you can verify — a trust layer between an AI coding agent and its own past: per-hit staleness verdicts, claim-level use attribution, measured effectiveness, episodic run-state. MCP-native, local-first, MIT, no cloud.

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.

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 38,009 bytes, which is 4.84x claude-mem's whole default surface (7,845 B); 28,604 of ours is names and descriptions, measured 2026-07-26 at 3.29.0 (bench/toolcost). CI caps the descriptions; a trim landed after that run, so a re-measure comes in lower.
• 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:

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.)
3. bettermemory doctor — exit 0 means correctly wired; every failed check prints a one-line fix.
4. 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.