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 / hermes
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, the
commits landed since it was last confirmed, and how the record
entered the store (written here, pulled, or placed by hand).
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 are labelled as inferences, so they stay distinguishable and correctable.
- 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 reindexrebuilds 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 whose frozen result artifacts — misses
included — live in bench/ (
results/*.json, each carrying the declared terms it was scored under), andbettermemory evalscores whether memory actually helped against your own log (ours is published).
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,hermes. 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
Metadata
1 maintainer
Release files for bettermemory 8.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| bettermemory-8.0.0.tar.gz | 13.1 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| bettermemory-8.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 14.3 MB
Release files / bettermemory-8.0.0.tar.gz
| Download URL | bettermemory-8.0.0.tar.gz |
|---|---|
| Size | 13.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8b0b9e2906dfa33501fb30af7cfde84f05b48b9f459020e20202762321121da3
|
|
BLAKE2b-256 checksum How to use checksums |
c7acccfbb062ef4e5d195989655785d639119131d129e278e10ec6638d8a942b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency logRelease files / bettermemory-8.0.0-py3-none-any.whl
| Download URL | bettermemory-8.0.0-py3-none-any.whl |
|---|---|
| Size | 1.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
62935a84505b4f6dc9e71124f049d93b15dfbf377076525b9f4b59eab41b910f
|
|
BLAKE2b-256 checksum How to use checksums |
fdc41398dc4469d73d589c1a3fe6c7f28a33ca3dc5b4bae0eed0f29ec2b8c4c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency log
