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.
- That verdict is measured, not asserted. A preregistered benchmark
(bench/rot) grades the shipped staleness code against git
ground truth on 30 repositories it did not choose — 37,635 claims
(the artifact's
pooled_claims), every prediction filed before the run and the misses published as retractions rather than renegotiated. The claim-level tier reads 94% precision at 1.1 alerts per catch against the file-level signal's 3.4 (artifact); declared claims onmemory_write/memory_verifyare that detector shipped (3.40.0). - Retrieval is a deliberate tool call, with one score-gated exception:
on the rare prompts where the silent-miss probe says memory was
needed (the measured rate lives in docs/eval-results.md),
the recall hook injects the top hit's id + snippet — a
pointer, never a body, so verification still runs through
memory_show([behavior] prompt_recall; off = purely opt-in). A second exception ships default-off:[behavior] standing_tierdelivers the repository's fresh-verifiedambientmemories whole at session start (capped at ~1 KB, truncated only at memory boundaries), because opt-in retrieval cannot serve knowledge whose trigger condition is not knowing you need it — and verification is the admission ticket, so a stale ambient memory is never delivered, only named in an aggregate verify-to-restore line. The 18 default tools still charge schema every turn: a serializedtools/listof 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 evalmeasures 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— orpipx install bettermemory, orpip install bettermemoryinto a venv. Python 3.11–3.14.bettermemory init --client claude-code— likewiseclaude-desktop,cursor,cline. For any other MCP host, plainbettermemory initprints the canonicalmcpServersJSON 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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file bettermemory-4.0.0.tar.gz.
File metadata
- Download URL: bettermemory-4.0.0.tar.gz
- Upload date:
- Size: 3.8 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1f4bcba90a483c9f96007d2000a6aca196e7717b066e9c3aa4b49d586190418f
|
|
| MD5 |
7bfd3a7247642b6611946212d74cf71d
|
|
| BLAKE2b-256 |
93b22fe638543bd6a8330bc066fef4541eac71e5e6cb31bd3fbc68072f3ddf8b
|
Provenance
The following attestation bundles were made for bettermemory-4.0.0.tar.gz:
Publisher:
release.yml on 0Mattias/bettermemory
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
bettermemory-4.0.0.tar.gz -
Subject digest:
1f4bcba90a483c9f96007d2000a6aca196e7717b066e9c3aa4b49d586190418f - Sigstore transparency entry: 2390975236
- Sigstore integration time:
-
Permalink:
0Mattias/bettermemory@2e146d3832c4f3276039a9b224e08d0a11a2c3a7 -
Branch / Tag:
refs/tags/v4.0.0 - Owner: https://github.com/0Mattias
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@2e146d3832c4f3276039a9b224e08d0a11a2c3a7 -
Trigger Event:
push
-
Statement type:
File details
Details for the file bettermemory-4.0.0-py3-none-any.whl.
File metadata
- Download URL: bettermemory-4.0.0-py3-none-any.whl
- Upload date:
- Size: 1.1 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1cc9a88c1385ce34123455ef93c3d4e717d5cf21c088255067d709c0aafdf437
|
|
| MD5 |
bee9589c105d050707fbbd557cd6c34d
|
|
| BLAKE2b-256 |
481453ee4f8b62b4dc65ef4852edb74c89035e83efa8859af726aa0fc4025b53
|
Provenance
The following attestation bundles were made for bettermemory-4.0.0-py3-none-any.whl:
Publisher:
release.yml on 0Mattias/bettermemory
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
bettermemory-4.0.0-py3-none-any.whl -
Subject digest:
1cc9a88c1385ce34123455ef93c3d4e717d5cf21c088255067d709c0aafdf437 - Sigstore transparency entry: 2390975301
- Sigstore integration time:
-
Permalink:
0Mattias/bettermemory@2e146d3832c4f3276039a9b224e08d0a11a2c3a7 -
Branch / Tag:
refs/tags/v4.0.0 - Owner: https://github.com/0Mattias
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@2e146d3832c4f3276039a9b224e08d0a11a2c3a7 -
Trigger Event:
push
-
Statement type:
