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

• 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.
• 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 helped, against your own log. Ours is published — one store, one user, 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

The rest is 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.