This release is a pre-release and may not be stable for production use.
An MCP memory server for coding agents. Memories are checked against your files and git history on every read, and stale ones come back flagged.
Install
Claude Code, with uv installed:
/plugin marketplace add 0Mattias/bettermemory
/plugin install bettermemory@bettermemory
The plugin adds the server, the memory policy as a skill, and three hooks.
Anything else that speaks MCP:
uv tool install bettermemory
bettermemory init --client claude-desktop # or cursor / cline / claude-code / hermes
Restart the client and ask the model what memory tools it has; nine
tools, memory_search among them, mean the server is wired.
Coming from 8.x: run bettermemory migrate v8 once (uvx bettermemory migrate v8 if you use the plugin). Until then the server refuses to
start beside the old files and says why.
What it does
- Every search hit carries a staleness verdict: its age, whether the
paths it cites still exist, and the commits since it was last
checked. Declared claims (
path,path::symbol,path::NAME=literal,!path) are re-checked against the working tree, andmemory_verifywill not stamp a memory fresh while one of its claims no longer holds. - The store is one SQLite file built from a hash-chained log, each row
signed with a key kept outside the store. A record planted or forged
outside the tool reads
unaccountedon the next search;bettermemory log verifyaudits the whole chain. - Memory reaches the model through tool calls. On Claude Code the hooks add pointers, never bodies: up to eight fresh memories from the repository when a session opens, and up to three matching memories from the project on each prompt.
- Writes pass gates for transient state, secret-shaped tokens and near-duplicates, then a review: the model sees the stored statements the write resembles and answers three questions before anything is written. Claims about you are stored labelled as inferences. No second model is involved.
- Session capture is off by default. With
[capture] stop_checkpoint = trueinconfig.toml, the Stop hook asks the model in the session to save what each 12,000 tokens of conversation established.bettermemory capture reviewlists the batches andcapture undotakes one back. - Search ranks by keyword and BM25, fused, with no embedding model and nothing to download; the same query gets the same ranking.
episodekeeps per-session run-state out of durable search.bettermemory healthreports what drifted, what went cold and what contradicts what.- One local daemon per store, on 127.0.0.1, serves every session and
hook;
bettermemory up,downandstatusmanage it.bettermemory exportwrites the store as JSON or as the 8.x markdown directory. - The benchmarks and their result files, misses included, are in bench/.
For agents
You were likely handed this link with "Install bettermemory". On Claude Code, ask the user to type the two plugin commands above, then go to step 3. Everywhere else, every step is idempotent:
uv tool install bettermemory, orpipx install bettermemory, orpip install bettermemoryinto a venv. Python 3.11 to 3.14.bettermemory init --client claude-code, orclaude-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.)- Have the user restart the client so the server loads, then confirm
by asking the model "what memory tools do you have?": nine tools,
memory_searchamong them (under themcp__bettermemory__prefix on Claude Code).
With an 8.x store, run bettermemory migrate v8 (uvx bettermemory migrate v8 with the plugin) before step 3; until then the server
refuses to start.
Your operating contract (tool signatures, retrieval discipline, write
gates, the write review) 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.
Everything else
Mechanics, storage format, the full tool surface, CLI, configuration and limitations are in internals; per-client setup in clients and installation; eval methodology in eval; the threat model in SECURITY; 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 9.0.0rc1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| bettermemory-9.0.0rc1.tar.gz | 16.5 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| bettermemory-9.0.0rc1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 17.4 MB
Release files / bettermemory-9.0.0rc1.tar.gz
| Download URL | bettermemory-9.0.0rc1.tar.gz |
|---|---|
| Size | 16.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
97938ba02c753fddddc15b1413fdb98f6845d8d1995d180d713b71c81ef44c3d
|
|
BLAKE2b-256 checksum How to use checksums |
0ca46398d22fde0621454f2ae1d91f58491fa77b8d586ad1fd60ead157378bda
|
| 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 Oct 15, 2026.
Transparency logRelease files / bettermemory-9.0.0rc1-py3-none-any.whl
| Download URL | bettermemory-9.0.0rc1-py3-none-any.whl |
|---|---|
| Size | 943.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
556ae006c40e3075e01a6484a226716e8d212b3579d1be183f0342e02b12c10e
|
|
BLAKE2b-256 checksum How to use checksums |
4365f914adcca28adb32bf21c962d32aa2fe0012dd458f92ff70d3258905fcc9
|
| 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 Oct 15, 2026.
Transparency logSecurity for bettermemory 9.0.0rc1
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.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for bettermemory-9.0.0rc1.tar.gz
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 Oct 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
