Skip to content

buildingjoshbetter/TrueMemory

TrueMemory

The memory your AI should have had from the start.

English 简体中文 हिन्दी Español Français العربية বাংলা Português Русский 日本語 한국어 Deutsch Bahasa Indonesia Tiếng Việt Türkçe Italiano ไทย Polski Українська Nederlands

Stars Installs CI PyPI License arXiv

LoCoMo LongMemEval BEAM-1M

Why · Quick Start · Compare · Tiers · Benchmarks · API · Docs · FAQ

TrueMemory terminal demo


Why TrueMemory

It finds signal in the noise. Your AI sees thousands of messages. TrueMemory figures out which ones actually matter and throws away the rest. No manual tagging, no prompt engineering. It just knows.

It gets sharper over time. It's not a static database. It's a living memory that grows with you. It resolves contradictions when you change your mind, updates stale facts, and consolidates what it knows. The longer you use it, the better it gets.

It works without you thinking about it. TrueMemory automatically captures memories from your conversations and automatically injects the right ones into your next session. You never have to store or search for anything manually. It just happens.

It's 100% local. One SQLite file on your machine. Nothing leaves your device. No cloud, no API keys needed. Your data is yours.

Without TrueMemory: "What framework are we using?" Asked for the 12th time this week. Your agent starts every session with amnesia. It doesn't know your name, your stack, or anything you told it yesterday.

With TrueMemory: Your agent already knows you use FastAPI, prefer Pydantic v2, and that your auth middleware lives in src/auth/. It remembers your corrections, your preferences, and your decisions. Across every session, forever.


How TrueMemory Compares

System LoCoMo LongMemEval Local-first Auto-capture License
TrueMemory Pro 93.0% 92.0% AGPL-3.0
TrueMemory Base 87.7% 84.1% AGPL-3.0
Mem0 61.4% Partial Apache-2.0
Supermemory 65.4% Cloud API
MemOS 75.8% Apache-2.0
ReadAgent 79.5% Research

All benchmarks independently reproducible. Scripts included in benchmarks/.


Quick Start

For Claude Code / Claude CLI / Cursor / Codex CLI / Gemini CLI

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

Installs everything in an isolated environment. Downloads ~1.5GB of AI models. No data leaves your machine. No sudo required.

New to the terminal? Click here for step-by-step instructions.
  1. Open a terminal: Mac: Cmd + Space, type Terminal. Linux: Ctrl + Alt + T. Windows: open PowerShell.
  2. Paste the command above and press Enter.
  3. Wait 3-5 minutes for models to download.
  4. Quit your AI tool completely and reopen it (Mac: Cmd+Q).
  5. Type "Set up TrueMemory" and pick a tier.

Windows (PowerShell):

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

That's it. TrueMemory remembers your conversations automatically from here.

For developers (Python library)

pip install truememory
from truememory import Memory

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

Tiers

Same architecture, three tiers. All included in a single install. Switch anytime by saying "switch to Pro" or "switch to Base."

Edge Base Pro
LoCoMo 89.6% 92.0% 93.0%
LongMemEval 92.0%
BEAM-1M 76.6% (SOTA)
Embedding model 8 MB lightweight 600 MB high-accuracy 600 MB high-accuracy
Reranker 22M params 149M params 149M params
HyDE search ✅ (requires LLM API key)
Runs on Any machine, CPU only 4 GB+ RAM 4 GB+ RAM + API key

Edge works everywhere. Base is the strongest fully-offline tier. Pro adds AI-powered query expansion for the highest scores.


Benchmarks

Benchmark Leaderboard

Tested across three major benchmarks with all systems sharing the same answer model (GPT-4.1-mini), judge (GPT-4o-mini, 3x majority vote), and scoring pipeline.

Benchmark What it tests TrueMemory Pro
LoCoMo 1,540 questions across 10 conversations 93.0%
LongMemEval 500 multi-session questions 92.0%
BEAM-1M 700 questions at 1M+ tokens 76.6% (SOTA)
BEAM-10M 200 questions at 10M tokens 65.0%

Reproduce any result yourself

Every benchmark script is self-contained and runs on Modal.

All benchmarks use the same eval pipeline. Nothing is hidden. Full details: LoCoMo | LongMemEval | BEAM


Works With

Claude Code · Claude CLI · Cursor · Codex CLI · Gemini CLI · Claude Desktop

Lifecycle hooks capture conversations automatically. No manual work needed. Your memories stay local in a single SQLite file.


Python API

from truememory import Memory

m = Memory()

m.add("Prefers dark mode and TypeScript", user_id="alex")
m.add("Works at Anthropic as a senior engineer", user_id="alex")

results = m.search("What are Alex's preferences?", user_id="alex")
results = m.search_deep("career history?", user_id="alex")  # multi-round, higher accuracy
Method Description
m.add(content, user_id) Store a memory
m.search(query, user_id) Search (6-layer pipeline + reranker)
m.search_deep(query, user_id) Multi-round agentic search
m.get(id) / m.get_all(user_id) Retrieve memories
m.update(id, content) / m.delete(id) Modify or remove
m.stats() System statistics

Full API reference →


Docs

Getting Started Install to first memory
Python API Reference Full Memory class reference
MCP Tool Reference All 8 MCP tools
CLI Reference truememory-mcp and truememory-ingest
Environment Variables All TRUEMEMORY_* config options
Architecture Deep Dive 6-layer retrieval pipeline, encoding gate
Tier Selection Guide Edge vs Base vs Pro
Debugging Logs, traces, common issues

FAQ

Where is my data stored? Is anything sent to the cloud?

Everything lives locally in ~/.truememory/memories.db. Edge and Base tiers make zero external calls. Pro sends only your search query text to an LLM for query expansion. Your memories are never transmitted.

Do I need Python installed?

No. The installer uses uv to manage a sandboxed Python 3.12. Your system Python is never touched.

Why not just use a bigger context window?

Context windows are expensive, slow, and empty at the start of every session. TrueMemory gives instant recall for zero tokens of context, in under 200ms.

Does TrueMemory collect telemetry?

Anonymous usage telemetry (tool calls, session counts, platform info) is on by default. We never track memory content, queries, file paths, or API keys. Opt out: export TRUEMEMORY_TELEMETRY=off


Get Started in 60 Seconds

pip install truememory

Questions? Open a Discussion. If TrueMemory saves you time, give us a ⭐


Thanks to Our Contributors

buildingjoshbetter
buildingjoshbetter
SoilChang
SoilChang
Huntehhh
Huntehhh
mseep-ai
mseep-ai
adityajha2005
adityajha2005
shivamverma1999
shivamverma1999

Research

TrueMemory is backed by a peer-reviewed research paper on retrieval-centered agent memory.

Storage Is Not Memory: A Retrieval-Centered Architecture for Agent Recall (arXiv 2605.04897)

@article{adler2025storage,
  title   = {Storage Is Not Memory: A Retrieval-Centered Architecture for Agent Recall},
  author  = {Sauron Labs},
  journal = {arXiv preprint arXiv:2605.04897},
  year    = {2025},
  url     = {https://arxiv.org/abs/2605.04897}
}

Community

If TrueMemory saves you time, give us a ⭐


License

AGPL-3.0. Free for personal and research use. Commercial use requires a separate license. Contact josh@sauronlabs.ai.


TrueMemory, a sauron company

About

The memory your AI should have had from the start. Automatic capture, automatic recall, 100% local. One SQLite file, zero cloud. Works with Claude Code, Claude CLI, Cursor, Codex CLI, Gemini CLI.

Topics

Resources

License

Contributing

Security policy

Stars

Watchers

Forks

Packages

 
 
 

Contributors

Languages