Skip to content
Back to search

TrueMemory

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/buildingjoshbetter--truememory/badge.svg)](/listings/buildingjoshbetter--truememory)

HTML

<a href="/listings/buildingjoshbetter--truememory"><img src="/api/listings/buildingjoshbetter--truememory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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.

<details><summary>New to the terminal? Click here for step-by-step instructions.</summary>

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

</details>

That's it. TrueMemory remembers your conversations automatically from here. Need help? [Join our Discord](https://discord.gg/ZJ74JB2gVW).

> If TrueMemory saves you time, [a ⭐ helps other devs find it](https://github.com/buildingjoshbetter/TrueMemory).

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"))

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 313 lines · 3 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="assets/charts/hero-banner.png" alt="TrueMemory" width="800">
  3. </p>
  4. <p align="center">
  5. <a href="https://github.com/buildingjoshbetter/TrueMemory"><img src="https://img.shields.io/github/stars/buildingjoshbetter/TrueMemory?style=social" alt="Stars"></a>
  6. <a href="https://pepy.tech/projects/truememory"><img src="https://img.shields.io/badge/dynamic/json?url=https://pepy.tech/api/v2/projects/truememory&query=$.total_downloads&label=installs&color=39FF14&labelColor=white&style=flat" alt="PyPI Installs"></a>
  7. &nbsp;–&nbsp;
  8. <a href="./i18n/README.zh-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>
  9. <a href="./i18n/README.ru.md"><img alt="Русский" src="https://img.shields.io/badge/Русский-d9d9d9"></a>
  10. &nbsp;–&nbsp;
  11. <a href="https://arxiv.org/abs/2605.04897"><img src="https://img.shields.io/badge/arXiv-2605.04897-b31b1b" alt="arXiv"></a>
  12. <a href="https://discord.gg/ZJ74JB2gVW"><img src="https://img.shields.io/badge/Discord-Join%20us-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
  13. </p>
  14. <p align="center">
  15. <img src="https://img.shields.io/badge/LoCoMo-93.0%25-blueviolet" alt="LoCoMo">
  16. <img src="https://img.shields.io/badge/LongMemEval-92.0%25-blue" alt="LongMemEval">
  17. <img src="https://img.shields.io/badge/BEAM--1M-76.6%25_(SOTA)-orange" alt="BEAM-1M">
  18. </p>
  19. <p align="center">
  20. <a href="#the-problem">Why</a> · <a href="#quick-start">Quick Start</a> · <a href="#how-truememory-compares">Compare</a> · <a href="#tiers">Tiers</a> · <a href="#benchmarks">Benchmarks</a> · <a href="#python-api">API</a> · <a href="#docs">Docs</a> · <a href="#faq">FAQ</a> · <a href="https://discord.gg/ZJ74JB2gVW">Discord</a>
  21. </p>
  22. <p align="center">
  23. <img src="assets/terminal-demo.svg" alt="TrueMemory terminal demo" width="750">
  24. </p>
  25. ---
  26. ## Why TrueMemory
  27. **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.
  28. **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.
  29. **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.
  30. **It's 100% local.** One SQLite file on your machine. Your memories never leave your device. No cloud, no API keys needed. Your data is yours. (Anonymous usage telemetry is the only exception — never memory content — and one env var turns it off. [Details](#faq).)
  31. > **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.
  32. >
  33. > **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.
  34. <p align="center"><a href="https://discord.gg/ZJ74JB2gVW"><strong>Join the Discord</strong></a> to see what others are building with TrueMemory.</p>
  35. ---
  36. ## How TrueMemory Compares
  37. | System | LoCoMo | LongMemEval | Local-first | Auto-capture | License |
  38. |--------|--------|-------------|:-----------:|:------------:|---------|
  39. | **TrueMemory Pro** | **93.0%** | **92.0%** | ✅ | ✅ | AGPL-3.0 |
  40. | **TrueMemory Base** | **92.0%** | **84.1%** | ✅ | ✅ | AGPL-3.0 |
  41. | Mem0 | 61.4% | — | Partial | ❌ | Apache-2.0 |
  42. | Supermemory | 65.4% | — | ❌ | ❌ | Cloud API |
  43. | MemOS | 75.8% | — | ✅ | ❌ | Apache-2.0 |
  44. | ReadAgent | 79.5% | — | ❌ | ❌ | Research |
  45. > All benchmarks independently reproducible. Scripts included in [`benchmarks/`](benchmarks/).
  46. ---
  47. ## Quick Start
  48. ### For Claude Code / Claude CLI / Cursor / Codex CLI / Gemini CLI
  49. ```bash
  50. curl -LsSf https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 70 on GitHub
  51. ```
  52. > Installs everything in an isolated environment. Downloads ~1.5GB of AI models. No data leaves your machine. No sudo required.
  53. <details><summary>New to the terminal? Click here for step-by-step instructions.</summary>
  54. 1. **Open a terminal:** Mac: `Cmd + Space`, type `Terminal`. Linux: `Ctrl + Alt + T`. Windows: open PowerShell.
  55. 2. **Paste the command above** and press Enter.
  56. 3. **Wait 3-5 minutes** for models to download.
  57. 4. **Quit your AI tool completely** and reopen it (Mac: `Cmd+Q`).
  58. 5. **Type "Set up TrueMemory"** and pick a tier.
  59. **Windows (PowerShell):**
  60. ```powershell
  61. irm https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/install.ps1 | iex
  62. ```
  63. </details>
  64. That's it. TrueMemory remembers your conversations automatically from here. Need help? [Join our Discord](https://discord.gg/ZJ74JB2gVW).
  65. > If TrueMemory saves you time, [a ⭐ helps other devs find it](https://github.com/buildingjoshbetter/TrueMemory).
  66. ### For developers (Python library)
  67. ```bash
  68. pip install truememory
  69. ```
  70. ```python
  71. from truememory import Memory
  72. m = Memory()
  73. m.add("Prefers dark mode and TypeScript", user_id="alex")
  74. print(m.search("preferences", user_id="alex"))
  75. ```
  76. ---
  77. ## Tiers
  78. Same architecture, three tiers. All included in a single install. Switch anytime by saying "switch to Pro" or "switch to Base."
  79. | | Edge | Base | Pro |
  80. |---|------|------|-----|
  81. | **LoCoMo** | 89.6% | 92.0% | **93.0%** |
  82. | **LongMemEval** | — | — | **92.0%** |
  83. | **BEAM-1M** | — | — | **76.6% (SOTA)** |
  84. | **Embedding model** | 8 MB lightweight | 600 MB high-accuracy | 600 MB high-accuracy |
  85. | **Reranker** | 22M params | 149M params | 149M params |
  86. | **HyDE search** | — | — | ✅ (requires LLM API key) |
  87. | **Runs on** | Any machine, CPU only | 4 GB+ RAM | 4 GB+ RAM + API key |
  88. **Edge** works everywhere. **Base** is the strongest fully-offline tier. **Pro** adds AI-powered query expansion for the highest scores.
  89. ---
  90. ## Benchmarks
  91. <p align="center">
  92. <img src="assets/charts/leaderboard-bar.png" alt="Benchmark Leaderboard" width="700" />
  93. </p>
  94. 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.
  95. | Benchmark | What it tests | TrueMemory Pro |
  96. |-----------|--------------|:--------------:|
  97. | [LoCoMo](https://github.com/snap-research/locomo) | 1,540 questions across 10 conversations | **93.0%** |
  98. | [LongMemEval](https://github.com/xiaowu0162/LongMemEval) | 500 multi-session questions | **92.0%** |
  99. | [BEAM-1M](https://github.com/mohammadtavakoli78/BEAM) | 700 questions at 1M+ tokens | **76.6% (SOTA)** |
  100. | BEAM-10M | 200 questions at 10M tokens | **65.0%** |
  101. ### Reproduce any result yourself
  102. Every benchmark script is self-contained and runs on [Modal](https://modal.com).
  103. - **[LoCoMo Scripts](benchmarks/locomo/scripts/)** — 8 systems (TrueMemory, Mem0, Zep, Engram, etc.)
  104. - **[LoCoMo Results](benchmarks/locomo/BENCHMARK_RESULTS.md)** — per-category breakdowns, latency, cost
  105. - **[LoCoMo Eval Config](benchmarks/locomo/EVAL_CONFIG.md)** — exact models, prompts, parameters
  106. - **[LongMemEval Scripts](benchmarks/longmemeval/)** — oracle + strict variants
  107. - **[LongMemEval Results](benchmarks/longmemeval/results/)** — 6 TM Pro runs + 5 competitor results
  108. - **[BEAM-1M Script](benchmarks/beam/bench_truememory_pro_beam1m.py)** — 35 conversations at 1M+ tokens
  109. - **[BEAM-10M Script](benchmarks/beam/bench_truememory_pro_beam10m.py)** — 10 conversations at 10M tokens
  110. - **[BEAM Results](benchmarks/beam/)** — 3 runs (1M) + 1 run (10M)
  111. All benchmarks use the same eval pipeline. Nothing is hidden. Full details: [LoCoMo](benchmarks/locomo/EVAL_CONFIG.md) | [LongMemEval](benchmarks/longmemeval/README.md) | [BEAM](benchmarks/beam/README.md)
  112. ---
  113. ## Works With
  114. <p align="center">
  115. <strong>Claude Code</strong> · <strong>Claude CLI</strong> · <strong>Cursor</strong> · <strong>Codex CLI</strong> · <strong>Gemini CLI</strong> · <strong>Claude Desktop</strong>
  116. </p>
  117. Lifecycle hooks capture conversations automatically. No manual work needed. Your memories stay local in a single SQLite file.
  118. ---
  119. ## Python API
  120. ```python
  121. from truememory import Memory
  122. m = Memory()
  123. m.add("Prefers dark mode and TypeScript", user_id="alex")
  124. m.add("Works at Anthropic as a senior engineer", user_id="alex")
  125. m.add("Always sign commits with GPG", directive=True) # directives auto-load every session
  126. results = m.search("What are Alex's preferences?", user_id="alex")
  127. results = m.search_deep("career history?", user_id="alex") # multi-round, higher accuracy
  128. ```
  129. | Method | Description |
  130. |--------|-------------|
  131. | `m.add(content, user_id)` | Store a memory (`directive=True` for standing instructions that auto-load at the start of every session) |
  132. | `m.search(query, user_id)` | Search (6-layer pipeline + reranker) |
  133. | `m.search_deep(query, user_id)` | Multi-round agentic search |
  134. | `m.get(id)` / `m.get_all(user_id)` | Retrieve memories |
  135. | `m.update(id, content)` / `m.delete(id)` | Modify or remove |
  136. | `m.stats()` | System statistics |
  137. [Full API reference →](docs/python-api.md)
  138. ---
  139. ## Docs
  140. | | |
  141. |---|---|
  142. | [Getting Started](docs/guides/getting-started.md) | Install to first memory |
  143. | [Python API Reference](docs/python-api.md) | Full `Memory` class reference |
  144. | [MCP Tool Reference](docs/mcp-tools.md) | All 11 MCP tools |
  145. | [CLI Reference](docs/cli.md) | `truememory-mcp` and `truememory-ingest` |
  146. | [Environment Variables](docs/env-vars.md) | All `TRUEMEMORY_*` config options |
  147. | [Architecture Deep Dive](docs/architecture.md) | 6-layer retrieval pipeline, encoding gate |
  148. | [Tier Selection Guide](docs/guides/tier-selection.md) | Edge vs Base vs Pro |
  149. | [Debugging](docs/guides/debugging.md) | Logs, traces, common issues |
  150. ---
  151. ## FAQ
  152. <details><summary><strong>Where is my data stored? Is anything sent to the cloud?</strong></summary>
  153. 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.
  154. </details>
  155. <details><summary><strong>Do I need Python installed?</strong></summary>
  156. No. The installer uses [uv](https://docs.astral.sh/uv/) to manage a sandboxed Python 3.12. Your system Python is never touched.
  157. </details>
  158. <details><summary><strong>Why not just use a bigger context window?</strong></summary>
  159. 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.
  160. </details>
  161. <details><summary><strong>Does TrueMemory collect telemetry?</strong></summary>
  162. 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`
  163. </details>
  164. ---
  165. ## Get Started in 60 Seconds
  166. For Claude Code, Claude CLI, Cursor, Codex CLI, or Gemini CLI:
  167. ```bash
  168. curl -LsSf https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 242 on GitHub
  169. ```
  170. Using it as a Python library instead? `pip install truememory`
  171. Questions? [Join our Discord](https://discord.gg/ZJ74JB2gVW) or [open a Discussion](https://github.com/buildingjoshbetter/TrueMemory/discussions). If TrueMemory saves you time, [give us a ⭐](https://github.com/buildingjoshbetter/TrueMemory)
  172. ---
  173. ## Thanks to Our Contributors
  174. <table>
  175. <tr>
  176. <td align="center"><a href="https://github.com/buildingjoshbetter"><img src="https://avatars.githubusercontent.com/u/236675935?v=4" width="80" alt="buildingjoshbetter"/><br><sub>buildingjoshbetter</sub></a></td>
  177. <td align="center"><a href="https://github.com/SoilChang"><img src="https://avatars.githubusercontent.com/u/12407044?v=4" width="80" alt="SoilChang"/><br><sub>SoilChang</sub></a></td>
  178. <td align="center"><a href="https://github.com/Huntehhh"><img src="https://avatars.githubusercontent.com/u/66277108?v=4" width="80" alt="Huntehhh"/><br><sub>Huntehhh</sub></a></td>
  179. <td align="center"><a href="https://github.com/mseep-ai"><img src="https://avatars.githubusercontent.com/u/207640208?v=4" width="80" alt="mseep-ai"/><br><sub>mseep-ai</sub></a></td>
  180. <td align="center"><a href="https://github.com/adityajha2005"><img src="https://avatars.githubusercontent.com/u/147301021?v=4" width="80" alt="adityajha2005"/><br><sub>adityajha2005</sub></a></td>
  181. <td align="center"><a href="https://github.com/shivamverma1999"><img src="https://avatars.githubusercontent.com/u/33162868?v=4" width="80" alt="shivamverma1999"/><br><sub>shivamverma1999</sub></a></td>
  182. <td align="center"><a href="https://github.com/Adarsh-031"><img src="https://avatars.githubusercontent.com/u/185399508?v=4" width="80" alt="Adarsh-031"/><br><sub>Adarsh-031</sub></a></td>
  183. <td align="center"><a href="https://github.com/nareshkarthigeyan"><img src="https://avatars.githubusercontent.com/u/130460278?v=4" width="80" alt="nareshkarthigeyan"/><br><sub>nareshkarthigeyan</sub></a></td>
  184. </tr>
  185. </table>
  186. ---
  187. ## Research
  188. TrueMemory is backed by a research paper (arXiv preprint) on retrieval-centered agent memory.
  189. **[Storage Is Not Memory: A Retrieval-Centered Architecture for Agent Recall](https://arxiv.org/abs/2605.04897)** (arXiv 2605.04897)
  190. ```bibtex
  191. @article{sauronlabs2026storage,
  192. title = {Storage Is Not Memory: A Retrieval-Centered Architecture for Agent Recall},
  193. author = {Sauron Labs},
  194. journal = {arXiv preprint arXiv:2605.04897},
  195. year = {2026},
  196. url = {https://arxiv.org/abs/2605.04897}
  197. }
  198. ```
  199. ---
  200. ## Community
  201. - [Join our Discord](https://discord.gg/ZJ74JB2gVW) for help, feedback, and updates
  202. - Follow [@Building_Josh](https://x.com/Building_Josh) on X for updates
  203. - Follow [@Sauron_Labs](https://x.com/Sauron_Labs) for company news
  204. - [Open a Discussion](https://github.com/buildingjoshbetter/TrueMemory/discussions) for questions or ideas
  205. - Read the paper on [arXiv](https://arxiv.org/abs/2605.04897)
  206. - Visit [truememory.net](https://truememory.net) · [sauronlabs.ai](https://sauronlabs.ai)
  207. If TrueMemory saves you time, [give us a ⭐](https://github.com/buildingjoshbetter/TrueMemory)
  208. ---
  209. ## Translations
  210. Read this in: [简体中文](./i18n/README.zh-CN.md) · [हिन्दी](./i18n/README.hi.md) · [Español](./i18n/README.es.md) · [Français](./i18n/README.fr.md) · [العربية](./i18n/README.ar.md) · [বাংলা](./i18n/README.bn.md) · [Português](./i18n/README.pt-BR.md) · [Русский](./i18n/README.ru.md) · [日本語](./i18n/README.ja.md) · [한국어](./i18n/README.ko.md) · [Deutsch](./i18n/README.de.md) · [Bahasa Indonesia](./i18n/README.id.md) · [Tiếng Việt](./i18n/README.vi.md) · [Türkçe](./i18n/README.tr.md) · [Italiano](./i18n/README.it.md) · [ไทย](./i18n/README.th.md) · [Polski](./i18n/README.pl.md) · [Українська](./i18n/README.uk.md) · [Nederlands](./i18n/README.nl.md)
  211. ---
  212. ## License
  213. [AGPL-3.0](LICENSE). Free for personal and research use. Commercial use requires a separate license. Contact josh@sauronlabs.ai.
  214. ---
  215. <p align="center">
  216. <em>TrueMemory, a <a href="https://sauronlabs.ai"><strong>sauron</strong></a> company</em>
  217. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.