<p align="center">
  <img src="../assets/hero-banner-dark.svg" alt="TrueMemory" width="800">
</p>

<p align="center">
  <em>您的 AI 从一开始就应该拥有的记忆。</em>
</p>

<p align="center">
  <a href="../README.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>
  <a href="./README.zh-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>
  <a href="./README.hi.md"><img alt="हिन्दी" src="https://img.shields.io/badge/हिन्दी-d9d9d9"></a>
  <a href="./README.es.md"><img alt="Español" src="https://img.shields.io/badge/Español-d9d9d9"></a>
  <a href="./README.fr.md"><img alt="Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>
  <a href="./README.ar.md"><img alt="العربية" src="https://img.shields.io/badge/العربية-d9d9d9"></a>
  <a href="./README.bn.md"><img alt="বাংলা" src="https://img.shields.io/badge/বাংলা-d9d9d9"></a>
  <a href="./README.pt-BR.md"><img alt="Português" src="https://img.shields.io/badge/Português-d9d9d9"></a>
  <a href="./README.ru.md"><img alt="Русский" src="https://img.shields.io/badge/Русский-d9d9d9"></a>
  <a href="./README.ja.md"><img alt="日本語" src="https://img.shields.io/badge/日本語-d9d9d9"></a>
  <a href="./README.ko.md"><img alt="한국어" src="https://img.shields.io/badge/한국어-d9d9d9"></a>
  <a href="./README.de.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>
  <a href="./README.id.md"><img alt="Bahasa Indonesia" src="https://img.shields.io/badge/Indonesia-d9d9d9"></a>
  <a href="./README.vi.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/Tiếng Việt-d9d9d9"></a>
  <a href="./README.tr.md"><img alt="Türkçe" src="https://img.shields.io/badge/Türkçe-d9d9d9"></a>
  <a href="./README.it.md"><img alt="Italiano" src="https://img.shields.io/badge/Italiano-d9d9d9"></a>
  <a href="./README.th.md"><img alt="ไทย" src="https://img.shields.io/badge/ไทย-d9d9d9"></a>
  <a href="./README.pl.md"><img alt="Polski" src="https://img.shields.io/badge/Polski-d9d9d9"></a>
  <a href="./README.uk.md"><img alt="Українська" src="https://img.shields.io/badge/Українська-d9d9d9"></a>
  <a href="./README.nl.md"><img alt="Nederlands" src="https://img.shields.io/badge/Nederlands-d9d9d9"></a>
</p>

<p align="center">
  <a href="https://github.com/buildingjoshbetter/TrueMemory"><img src="https://img.shields.io/github/stars/buildingjoshbetter/TrueMemory?style=social" alt="Stars"></a>
  <a href="https://pypi.org/project/truememory/"><img src="https://img.shields.io/badge/installs-7.3k+-brightgreen" alt="Installs"></a>
  <a href="https://arxiv.org/abs/2605.04897"><img src="https://img.shields.io/badge/arXiv-2605.04897-b31b1b" alt="arXiv"></a>
  <a href="https://discord.gg/ZJ74JB2gVW"><img src="https://img.shields.io/badge/Discord-Join%20us-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/LoCoMo-93.0%25-blueviolet" alt="LoCoMo">
  <img src="https://img.shields.io/badge/LongMemEval-92.0%25-blue" alt="LongMemEval">
  <img src="https://img.shields.io/badge/BEAM--1M-76.6%25_(SOTA)-orange" alt="BEAM-1M">
</p>

<p align="center">
  <a href="#为什么选择-truememory">为什么</a> · <a href="#快速开始">快速开始</a> · <a href="#truememory-对比">对比</a> · <a href="#版本层级">层级</a> · <a href="#基准测试">基准测试</a> · <a href="#python-api">API</a> · <a href="#文档">文档</a> · <a href="#常见问题">常见问题</a>
</p>

<p align="center">
  <img src="../assets/terminal-demo.svg" alt="TrueMemory 终端演示" width="750">
</p>

---

## 为什么选择 TrueMemory

**它从噪音中找到信号。** 您的 AI 看到数千条消息。TrueMemory 找出哪些真正重要，并丢弃其余的。无需手动标记，无需提示工程。它就是知道。

**它随着时间变得更加敏锐。** 它不是一个静态数据库。它是一个与您一起成长的活记忆，当您改变想法时解决矛盾，更新过时的事实，并整合已知信息。使用时间越长，它就越好。

**它无需您操心就能工作。** TrueMemory 自动从您的对话中捕获记忆，并在下一次会话中自动注入正确的记忆。您无需手动存储或搜索任何东西。一切自然发生。

**它是 100% 本地的。** 您机器上的一个 SQLite 文件。没有任何数据离开您的设备。无需云端，无需 API 密钥。您的数据属于您自己。

> **没有 TrueMemory：** "我们用的是什么框架？"本周第 12 次问了。您的智能体每次会话都从失忆开始。它不知道您的名字、您的技术栈，也不记得昨天您告诉它的任何事情。
>
> **有了 TrueMemory：** 您的智能体已经知道您使用 FastAPI，偏好 Pydantic v2，并且您的认证中间件在 `src/auth/` 目录下。它记住您的纠正、您的偏好和您的决策。跨越每一次会话，永远如此。

---

## TrueMemory 对比

| 系统 | LoCoMo | LongMemEval | 本地优先 | 自动捕获 | 许可证 |
|--------|--------|-------------|:-----------:|:------------:|---------|
| **TrueMemory Pro** | **93.0%** | **92.0%** | ✅ | ✅ | AGPL-3.0 |
| **TrueMemory Base** | **87.7%** | **84.1%** | ✅ | ✅ | AGPL-3.0 |
| Mem0 | 61.4% | — | 部分 | ❌ | Apache-2.0 |
| Supermemory | 65.4% | — | ❌ | ❌ | Cloud API |
| MemOS | 75.8% | — | ✅ | ❌ | Apache-2.0 |
| ReadAgent | 79.5% | — | ❌ | ❌ | Research |

> 所有基准测试均可独立复现。脚本包含在 [`benchmarks/`](../benchmarks/) 中。

---

## 快速开始

### 用于 Claude Code / Claude CLI / Cursor / Codex CLI / Gemini CLI

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

> 在隔离环境中安装一切。下载约 1.5GB 的 AI 模型。没有数据离开您的机器。无需 sudo。

<details><summary>终端新手？点击这里查看分步说明。</summary>

1. **打开终端：** Mac：`Cmd + Space`，输入 `Terminal`。Linux：`Ctrl + Alt + T`。Windows：打开 PowerShell。
2. **粘贴上面的命令** 并按回车。
3. **等待 3-5 分钟** 让模型下载完成。
4. **完全退出您的 AI 工具** 并重新打开（Mac：`Cmd+Q`）。
5. **输入 "Set up TrueMemory"** 并选择一个层级。

**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/install.ps1 | iex
```

</details>

就这样。从现在起 TrueMemory 会自动记住您的对话。

### 面向开发者（Python 库）

```bash
pip install truememory
```

```python
from truememory import Memory

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

---

## 版本层级

相同架构，三个层级。全部包含在一次安装中。随时可以通过说 "switch to Pro" 或 "switch to Base" 来切换。

| | Edge | Base | Pro |
|---|------|------|-----|
| **LoCoMo** | 89.6% | 92.0% | **93.0%** |
| **LongMemEval** | — | — | **92.0%** |
| **BEAM-1M** | — | — | **76.6% (SOTA)** |
| **嵌入模型** | 8 MB 轻量级 | 600 MB 高精度 | 600 MB 高精度 |
| **重排序器** | 22M 参数 | 149M 参数 | 149M 参数 |
| **HyDE 搜索** | — | — | ✅（需要 LLM API 密钥） |
| **运行环境** | 任何机器，仅 CPU | 4 GB+ 内存 | 4 GB+ 内存 + API 密钥 |

**Edge** 适用于所有环境。**Base** 是最强大的完全离线层级。**Pro** 增加了 AI 驱动的查询扩展以获得最高分数。

---

## 基准测试

<p align="center">
  <img src="../assets/charts/leaderboard-bar.png" alt="基准测试排行榜" width="700" />
</p>

在三大基准测试中进行测试，所有系统共享相同的回答模型（GPT-4.1-mini）、评判模型（GPT-4o-mini，3 次多数投票）和评分流程。

| 基准测试 | 测试内容 | TrueMemory Pro |
|-----------|--------------|:--------------:|
| [LoCoMo](https://github.com/snap-research/locomo) | 10 组对话中的 1,540 个问题 | **93.0%** |
| [LongMemEval](https://github.com/xiaowu0162/LongMemEval) | 500 个多会话问题 | **92.0%** |
| [BEAM-1M](https://github.com/mohammadtavakoli78/BEAM) | 1M+ token 下的 700 个问题 | **76.6% (SOTA)** |
| BEAM-10M | 10M token 下的 200 个问题 | **65.0%** |

### 自行复现任何结果

每个基准测试脚本都是独立的，并在 [Modal](https://modal.com) 上运行。

- **[LoCoMo 脚本](../benchmarks/locomo/scripts/)** — 8 个系统（TrueMemory、Mem0、Zep、Engram 等）
- **[LoCoMo 结果](../benchmarks/locomo/BENCHMARK_RESULTS.md)** — 分类细分、延迟、成本
- **[LoCoMo 评估配置](../benchmarks/locomo/EVAL_CONFIG.md)** — 确切的模型、提示和参数
- **[LongMemEval 脚本](../benchmarks/longmemeval/)** — oracle + strict 变体
- **[LongMemEval 结果](../benchmarks/longmemeval/results/)** — 6 次 TM Pro 运行 + 5 个竞品结果
- **[BEAM-1M 脚本](../benchmarks/beam/bench_truememory_pro_beam1m.py)** — 35 组对话，1M+ token
- **[BEAM-10M 脚本](../benchmarks/beam/bench_truememory_pro_beam10m.py)** — 10 组对话，10M token
- **[BEAM 结果](../benchmarks/beam/)** — 3 次运行 (1M) + 1 次运行 (10M)

所有基准测试使用相同的评估流程。没有隐藏内容。完整详情：[LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md) | [LongMemEval](../benchmarks/longmemeval/README.md) | [BEAM](../benchmarks/beam/README.md)

---

## 兼容工具

<p align="center">
  <strong>Claude Code</strong> · <strong>Claude CLI</strong> · <strong>Cursor</strong> · <strong>Codex CLI</strong> · <strong>Gemini CLI</strong> · <strong>Claude Desktop</strong>
</p>

生命周期钩子自动捕获对话。无需手动操作。您的记忆以单个 SQLite 文件的形式保存在本地。

---

## Python API

```python
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
```

| 方法 | 描述 |
|--------|-------------|
| `m.add(content, user_id)` | 存储一条记忆 |
| `m.search(query, user_id)` | 搜索（6 层管道 + 重排序器） |
| `m.search_deep(query, user_id)` | 多轮智能搜索 |
| `m.get(id)` / `m.get_all(user_id)` | 检索记忆 |
| `m.update(id, content)` / `m.delete(id)` | 修改或删除 |
| `m.stats()` | 系统统计信息 |

[完整 API 参考 →](../docs/python-api.md)

---

## 文档

| | |
|---|---|
| [入门指南](../docs/guides/getting-started.md) | 从安装到第一条记忆 |
| [Python API 参考](../docs/python-api.md) | 完整的 `Memory` 类参考 |
| [MCP 工具参考](../docs/mcp-tools.md) | 全部 8 个 MCP 工具 |
| [CLI 参考](../docs/cli.md) | `truememory-mcp` 和 `truememory-ingest` |
| [环境变量](../docs/env-vars.md) | 所有 `TRUEMEMORY_*` 配置选项 |
| [架构深入解析](../docs/architecture.md) | 6 层检索管道、编码门控 |
| [层级选择指南](../docs/guides/tier-selection.md) | Edge vs Base vs Pro |
| [调试](../docs/guides/debugging.md) | 日志、追踪、常见问题 |

---

## 常见问题

<details><summary><strong>我的数据存储在哪里？有任何数据会发送到云端吗？</strong></summary>

所有数据都保存在本地的 `~/.truememory/memories.db` 中。Edge 和 Base 层级不进行任何外部调用。Pro 仅将您的搜索查询文本发送给 LLM 进行查询扩展。您的记忆永远不会被传输。
</details>

<details><summary><strong>我需要安装 Python 吗？</strong></summary>

不需要。安装程序使用 [uv](https://docs.astral.sh/uv/) 管理沙盒化的 Python 3.12。您的系统 Python 不会被触及。
</details>

<details><summary><strong>为什么不直接使用更大的上下文窗口？</strong></summary>

上下文窗口昂贵、缓慢，并且在每次会话开始时都是空的。TrueMemory 以零上下文 token 实现即时召回，延迟不到 200 毫秒。
</details>

<details><summary><strong>TrueMemory 是否收集遥测数据？</strong></summary>

默认开启匿名使用遥测（工具调用、会话计数、平台信息）。我们**绝不**跟踪记忆内容、查询、文件路径或 API 密钥。选择退出：`export TRUEMEMORY_TELEMETRY=off`
</details>

---

## 60 秒快速上手

```bash
pip install truememory
```

有问题？[发起讨论](https://github.com/buildingjoshbetter/TrueMemory/discussions)。如果 TrueMemory 为您节省了时间，[给我们一颗星](https://github.com/buildingjoshbetter/TrueMemory)

---

## 感谢我们的贡献者

<table>
  <tr>
    <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>
    <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>
    <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>
    <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>
    <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>
    <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>
    <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>
    <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>
  </tr>
</table>

---

## 研究

TrueMemory 由一篇关于以检索为中心的智能体记忆的同行评审研究论文支持。

**[Storage Is Not Memory: A Retrieval-Centered Architecture for Agent Recall](https://arxiv.org/abs/2605.04897)** — arXiv 2605.04897

```bibtex
@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}
}
```

---

## 社区

- [加入我们的 Discord](https://discord.gg/ZJ74JB2gVW) 获取帮助、反馈和更新
- 在 X 上关注 [@Building_Josh](https://x.com/Building_Josh) 获取更新
- 关注 [@Sauron_Labs](https://x.com/Sauron_Labs) 获取公司新闻
- [发起讨论](https://github.com/buildingjoshbetter/TrueMemory/discussions) 提问或分享想法
- 在 [arXiv](https://arxiv.org/abs/2605.04897) · [Google Scholar](https://scholar.google.com/citations?user=YOUR_ID) · [Semantic Scholar](https://www.semanticscholar.org/) 上阅读论文
- 访问 [truememory.net](https://truememory.net) · [sauronlabs.ai](https://sauronlabs.ai)

如果 TrueMemory 为您节省了时间，[给我们一颗星](https://github.com/buildingjoshbetter/TrueMemory)

---

## 许可证

[AGPL-3.0](../LICENSE)。个人和研究使用免费。商业使用需要单独的许可证，请联系 josh@sauronlabs.ai。

---

<p align="center">
  <em>TrueMemory，一家 <a href="https://sauronlabs.ai"><strong>sauron</strong></a> 公司</em>
</p>
