TrueMemory: local agent memory in one SQLite file for Claude Code, Cursor and Codex CLI

The amnesia problem TrueMemory is aimed at

Every coding agent starts a session with no memory of the last one. You tell Claude Code you use FastAPI and Pydantic v2 on Monday, and on Tuesday it asks again. The README frames this bluntly: "What framework are we using?" asked for the 12th time this week. The fix people usually reach for is pasting context into a prompt or maintaining a CLAUDE.md by hand, which works until the file grows past what anyone will read.

TrueMemory targets that gap with automatic capture and automatic recall. The README states that memories are captured from conversations and injected into the next session without manual tagging or prompt engineering. The intended user is a developer running an agent CLI locally: Claude Code, Claude CLI, Cursor, Codex CLI or Gemini CLI. It is not a general document store and it is not a RAG framework you assemble yourself.

The design constraint that shapes everything else is locality. The README says memories live in one SQLite file on your machine and never leave the device, with anonymous usage telemetry as the stated exception and an environment variable to turn that off. That constraint is why the install downloads models instead of calling an embedding endpoint.

How capture, storage and recall fit together

The dependency list in pyproject.toml is the clearest view of the mechanism. sqlite-vec provides the vector index inside SQLite, so similarity search happens in the same file as the records. model2vec and sentence-transformers supply embeddings, and torch is a hard dependency, which is why the download is measured in gigabytes. mcp[cli] is present because the integration surface is a Model Context Protocol server, which is how the agent CLIs reach the memory store.

The tier table describes the recall pipeline in three strengths. Edge ships an 8 MB embedding model and a 22M-parameter reranker and runs CPU-only on any machine. Base moves to a 600 MB embedding model and a 149M-parameter reranker and wants 4 GB of RAM. Pro keeps the Base models and adds HyDE search, which the README says requires an LLM API key. That is the only tier where anything leaves your machine for a query, and the README is explicit that it is the exception rather than the default.

The README also claims memory is not static: it resolves contradictions, updates stale facts and consolidates. That is a behavioural claim rather than a documented algorithm, and the README does not describe the consolidation policy in the excerpt available. Treat it as a design goal to evaluate against your own conversations, not a guarantee.

One optional piece is declared separately. The clustering extra pulls hdbscan, and the pyproject comment says clustering.py imports it lazily and degrades gracefully when it is absent. So scene clustering is a feature you opt into with an extra, not part of the default install.

Installing TrueMemory and storing your first memory

The README gives a one-line installer for the agent CLIs. It downloads roughly 1.5GB of models, installs into an isolated environment, and needs no sudo. The README tells you to wait three to five minutes, quit your AI tool completely, reopen it, and then type "Set up TrueMemory" and pick a tier.

curl -LsSf https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/install.sh | sh

On Windows the README provides a PowerShell equivalent.

irm https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/install.ps1 | iex

If you would rather use the library directly, the package installs from PyPI and the README shows this example. The add call takes a user_id, and search returns matches scoped to the same id, so the identifier is what separates one person's memories from another's.

from truememory import Memory

m = Memory()
m.add("Prefers dark mode and TypeScript", user_id="alex")
print(m.search("preferences", user_id="alex"))

For contributors, the Makefile defines the working commands: make install runs pip install -e ., make dev installs the dev and all extras, make test runs pytest tests/ -v, and make lint runs ruff check truememory/. The clustering extra is installed on its own with pip install truememory[clustering]. The pyproject file notes that reranker, gpu and agentic are kept as empty aliases so older install commands still resolve.

Where TrueMemory is the wrong tool

The licence is the first hard boundary. pyproject.toml declares AGPL-3.0-only, and the README table repeats AGPL-3.0 for both Base and Pro. If you are embedding a memory layer inside a proprietary product and you cannot meet the network-copyleft obligations that the AGPL imposes, this is not the component to build on. That is a licensing question for your own counsel, not something this article can settle.

Pro is the second boundary. The tier table says HyDE search requires an LLM API key, so the top benchmark numbers depend on a hosted model being reachable. If your reason for choosing TrueMemory was that nothing leaves the machine, Pro quietly contradicts that. Base is the strongest fully offline tier according to the README, and it scores 92.0% on LoCoMo against Pro's 93.0%. That one-point gap is the actual cost of staying offline.

The third boundary is maturity. The package classifiers mark Development Status 4 - Beta, and the release history shows rapid hardening: v0.7.5.0 on 2026-06-08, then v0.7.6.1 and v0.7.6.2 both on 2026-06-11. Three releases in four days around a single hardening theme is normal for a young project and also a signal that interfaces may still move. The repository was last pushed on 2026-09-02, so it is not dormant, but a beta version number is not a stability promise.

Finally, the resource footprint rules out some environments. The installer downloads about 1.5GB, torch is a required dependency, and Base and Pro want at least 4 GB of RAM. On a small CI runner or a locked-down corporate laptop, that is a real obstacle, not a rounding error.

TrueMemory against Mem0 and MemOS

The README's comparison table puts TrueMemory next to Mem0, Supermemory, MemOS and ReadAgent. The differences that matter are not only the scores. Mem0 is Apache-2.0 and listed as partial on local-first with no auto-capture, so the integration work of deciding what to store falls to you. MemOS is Apache-2.0 and local-first but also listed without auto-capture. Supermemory is a cloud API with no local-first column and no auto-capture.

So the real split is between libraries that give you a memory store and a system that decides on its own what to keep. TrueMemory's pitch is the second kind: capture and injection happen without you writing the extraction logic. If you already have a pipeline that decides what is worth remembering, a permissively licensed store like Mem0 may fit better, because you are not paying for capture you will not use and you are not taking on AGPL-3.0.

On scores, the table lists TrueMemory Pro at 93.0% on LoCoMo and TrueMemory Base at 92.0%, against Mem0 at 61.4%, Supermemory at 65.4%, MemOS at 75.8% and ReadAgent at 79.5%. The README states all systems shared the same answer model, judge and scoring pipeline, and that scripts live in benchmarks/ and run on Modal. Those are the project's own numbers and its own harness. The honest position is that they are reproducible in principle and unverified here.

Maintenance, releases and what the licence asks of you

The last push was on 2026-09-02, and the most recent tagged release in the list is v0.7.6.2 from 2026-06-11. That gap is worth noticing: roughly three months of commits without a new tag at the time of writing. It does not mean the project stopped, and the repository is not archived, but if you depend on tagged releases you should check the CHANGELOG.md and the commit history on main rather than assuming the tag stream tracks development.

Upgrade cost is dominated by the model downloads. Because the tiers differ by embedding model size (8 MB on Edge against 600 MB on Base and Pro) and reranker size (22M against 149M parameters), switching tiers is not just a config change. The README says all tiers ship in a single install and you switch by saying "switch to Pro" or "switch to Base", which implies the assets are already present after the initial download. Moving between machines still means paying the download again.

On the licence, AGPL-3.0-only is the declared identifier in pyproject.toml and AGPL-3.0 appears in the README table. The practical consequence people care about is the network clause: if you offer a modified version as a service, the AGPL's source-availability terms are typically triggered. Whether your specific deployment counts is a legal question, and the repository's LICENSE file is where the actual terms live.

Editorial conclusion

Adopt TrueMemory if you want agent memory that stays on disk and you are comfortable with a beta-status Python package and an AGPL-3.0 licence. Skip it if you need a hosted dashboard, a stable 1.0 API, or a permissive licence for a closed product. Before installing, read the tier table and decide whether Base is enough, because Pro is the only tier that requires an LLM API key for HyDE search. Then run the install script and confirm which tier you actually landed on by asking the tool to switch.

Frequently asked questions

Official sources

1. buildingjoshbetter/TrueMemory on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases