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

<p align="center">
  <em>Bo nho ma AI cua ban le ra phai co tu dau.</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="#tai-sao-chon-truememory">Tai sao</a> · <a href="#bat-dau-nhanh">Bat dau nhanh</a> · <a href="#so-sanh-truememory">So sanh</a> · <a href="#cac-goi">Cac goi</a> · <a href="#benchmark">Benchmark</a> · <a href="#python-api">API</a> · <a href="#tai-lieu">Tai lieu</a> · <a href="#faq">FAQ</a>
</p>

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

---

## Tai sao chon TrueMemory

**No tim ra tin hieu giua nhieu nhieu.** AI cua ban nhin thay hang ngan tin nhan. TrueMemory xac dinh tin nhan nao thuc su quan trong, va loai bo phan con lai. Khong can gan the thu cong, khong can prompt engineering. No don gian la biet.

**No ngay cang sac ben theo thoi gian.** Day khong phai la co so du lieu tinh. Day la bo nho song dong lon len cung ban. No giai quyet mau thuan khi ban doi y, cap nhat su kien loi thoi, va tong hop nhung gi no biet. Ban dung cang lau, no cang tot.

**No hoat dong ma ban khong can suy nghi ve no.** TrueMemory tu dong ghi lai ky uc tu cac cuoc hoi thoai cua ban va tu dong dua nhung ky uc phu hop vao phien lam viec tiep theo. Ban khong bao gio phai luu tru hay tim kiem thu cong. Moi thu dien ra tu nhien.

**100% cuc bo.** Mot file SQLite tren may cua ban. Khong co gi roi khoi thiet bi cua ban. Khong cloud, khong can khoa API. Du lieu cua ban la cua ban.

> **Khong co TrueMemory:** "Chung ta dang dung framework gi?" Da hoi lan thu 12 trong tuan nay. Agent cua ban bat dau moi phien voi chung mat tri nho. No khong biet ten ban, stack cua ban, hay bat cu dieu gi ban da noi hom qua.
>
> **Voi TrueMemory:** Agent cua ban da biet ban dung FastAPI, thich Pydantic v2, va middleware auth cua ban nam o `src/auth/`. No nho cac chinh sua, so thich va quyet dinh cua ban. Qua moi phien, mai mai.

---

## So sanh TrueMemory

| He thong | LoCoMo | LongMemEval | Uu tien cuc bo | Tu dong ghi | Giay phep |
|----------|--------|-------------|:-----------:|:------------:|-----------|
| **TrueMemory Pro** | **93.0%** | **92.0%** | ✅ | ✅ | AGPL-3.0 |
| **TrueMemory Base** | **87.7%** | **84.1%** | ✅ | ✅ | AGPL-3.0 |
| Mem0 | 61.4% | — | Mot phan | ❌ | Apache-2.0 |
| Supermemory | 65.4% | — | ❌ | ❌ | Cloud API |
| MemOS | 75.8% | — | ✅ | ❌ | Apache-2.0 |
| ReadAgent | 79.5% | — | ❌ | ❌ | Research |

> Tat ca benchmark co the tai tao doc lap. Cac script co trong [`benchmarks/`](../benchmarks/).

---

## Bat dau nhanh

### Cho Claude Code / Claude CLI / Cursor / Codex CLI / Gemini CLI

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

> Cai dat moi thu trong moi truong co lap. Tai xuong ~1,5 GB mo hinh AI. Khong co du lieu nao roi khoi may ban. Khong can sudo.

<details><summary>Moi dung terminal? Nhan vao day de xem huong dan tung buoc.</summary>

1. **Mo terminal:** Mac: `Cmd + Space`, go `Terminal`. Linux: `Ctrl + Alt + T`. Windows: mo PowerShell.
2. **Dan lenh o tren** va nhan Enter.
3. **Doi 3-5 phut** de tai mo hinh.
4. **Tat hoan toan cong cu AI** va mo lai (Mac: `Cmd+Q`).
5. **Go "Set up TrueMemory"** va chon goi.

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

</details>

Vay thoi. TrueMemory se tu dong ghi nho cac cuoc hoi thoai cua ban tu bay gio.

### Cho nha phat trien (thu vien 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"))
```

---

## Cac goi

Cung kien truc, ba goi. Tat ca duoc bao gom trong mot lan cai dat. Chuyen doi bat ky luc nao bang cach noi "switch to Pro" hoac "switch to Base."

| | Edge | Base | Pro |
|---|------|------|-----|
| **LoCoMo** | 89.6% | 92.0% | **93.0%** |
| **LongMemEval** | — | — | **92.0%** |
| **BEAM-1M** | — | — | **76.6% (SOTA)** |
| **Mo hinh embedding** | 8 MB nhe | 600 MB do chinh xac cao | 600 MB do chinh xac cao |
| **Reranker** | 22M tham so | 149M tham so | 149M tham so |
| **Tim kiem HyDE** | — | — | ✅ (can khoa API LLM) |
| **Chay tren** | Moi may, chi CPU | 4 GB+ RAM | 4 GB+ RAM + khoa API |

**Edge** hoat dong moi noi. **Base** la goi offline manh nhat. **Pro** them mo rong truy van bang AI de dat diem cao nhat.

---

## Benchmark

<p align="center">
  <img src="../assets/charts/leaderboard-bar.png" alt="Bang xep hang Benchmark" width="700" />
</p>

Duoc thu nghiem tren ba benchmark chinh voi tat ca he thong dung chung mo hinh tra loi (GPT-4.1-mini), giam khao (GPT-4o-mini, bieu quyet da so 3x), va pipeline cham diem.

| Benchmark | Kiem tra gi | TrueMemory Pro |
|-----------|------------|:--------------:|
| [LoCoMo](https://github.com/snap-research/locomo) | 1.540 cau hoi tu 10 cuoc hoi thoai | **93.0%** |
| [LongMemEval](https://github.com/xiaowu0162/LongMemEval) | 500 cau hoi da phien | **92.0%** |
| [BEAM-1M](https://github.com/mohammadtavakoli78/BEAM) | 700 cau hoi tai 1M+ token | **76.6% (SOTA)** |
| BEAM-10M | 200 cau hoi tai 10M token | **65.0%** |

### Tu tai tao bat ky ket qua nao

Moi script benchmark la doc lap va chay tren [Modal](https://modal.com).

- **[Script LoCoMo](../benchmarks/locomo/scripts/)** — 8 he thong (TrueMemory, Mem0, Zep, Engram, v.v.)
- **[Ket qua LoCoMo](../benchmarks/locomo/BENCHMARK_RESULTS.md)** — phan tich theo danh muc, do tre, chi phi
- **[Cau hinh Eval LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md)** — mo hinh, prompt, tham so chinh xac
- **[Script LongMemEval](../benchmarks/longmemeval/)** — bien the oracle + strict
- **[Ket qua LongMemEval](../benchmarks/longmemeval/results/)** — 6 lan chay TM Pro + 5 ket qua doi thu
- **[Script BEAM-1M](../benchmarks/beam/bench_truememory_pro_beam1m.py)** — 35 cuoc hoi thoai tai 1M+ token
- **[Script BEAM-10M](../benchmarks/beam/bench_truememory_pro_beam10m.py)** — 10 cuoc hoi thoai tai 10M token
- **[Ket qua BEAM](../benchmarks/beam/)** — 3 lan chay (1M) + 1 lan chay (10M)

Tat ca benchmark dung cung pipeline danh gia. Khong co gi bi an. Chi tiet day du: [LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md) | [LongMemEval](../benchmarks/longmemeval/README.md) | [BEAM](../benchmarks/beam/README.md)

---

## Tuong thich voi

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

Lifecycle hook tu dong ghi lai cac cuoc hoi thoai. Khong can lam thu cong. Ky uc cua ban duoc luu cuc bo trong mot file SQLite duy nhat.

---

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

| Phuong thuc | Mo ta |
|-------------|-------|
| `m.add(content, user_id)` | Luu mot ky uc |
| `m.search(query, user_id)` | Tim kiem (pipeline 6 lop + reranker) |
| `m.search_deep(query, user_id)` | Tim kiem da vong kieu agent |
| `m.get(id)` / `m.get_all(user_id)` | Truy xuat ky uc |
| `m.update(id, content)` / `m.delete(id)` | Sua doi hoac xoa |
| `m.stats()` | Thong ke he thong |

[Tham chieu API day du →](../docs/python-api.md)

---

## Tai lieu

| | |
|---|---|
| [Bat dau](../docs/guides/getting-started.md) | Tu cai dat den ky uc dau tien |
| [Tham chieu Python API](../docs/python-api.md) | Tham chieu day du lop `Memory` |
| [Tham chieu MCP Tool](../docs/mcp-tools.md) | Tat ca 8 MCP tool |
| [Tham chieu CLI](../docs/cli.md) | `truememory-mcp` va `truememory-ingest` |
| [Bien moi truong](../docs/env-vars.md) | Tat ca tuy chon cau hinh `TRUEMEMORY_*` |
| [Kien truc chi tiet](../docs/architecture.md) | Pipeline truy xuat 6 lop, encoding gate |
| [Huong dan chon goi](../docs/guides/tier-selection.md) | Edge vs Base vs Pro |
| [Go loi](../docs/guides/debugging.md) | Log, trace, van de thuong gap |

---

## FAQ

<details><summary><strong>Du lieu cua toi duoc luu o dau? Co gi duoc gui len cloud khong?</strong></summary>

Moi thu deu nam cuc bo tai `~/.truememory/memories.db`. Goi Edge va Base khong thuc hien bat ky cuoc goi nao ra ben ngoai. Pro chi gui van ban truy van tim kiem cua ban den LLM de mo rong truy van. Ky uc cua ban khong bao gio duoc truyen di.
</details>

<details><summary><strong>Toi co can cai Python khong?</strong></summary>

Khong. Trinh cai dat su dung [uv](https://docs.astral.sh/uv/) de quan ly Python 3.12 trong moi truong sandbox. Python he thong cua ban khong bi thay doi.
</details>

<details><summary><strong>Tai sao khong dung context window lon hon?</strong></summary>

Context window thi dat, cham, va trong rong khi bat dau moi phien. TrueMemory cho phep truy hoi tuc thi voi khong token ngu canh, trong duoi 200 ms.
</details>

<details><summary><strong>TrueMemory co thu thap du lieu do luong khong?</strong></summary>

Du lieu do luong su dung an danh (cuoc goi tool, so phien, thong tin nen tang) duoc bat mac dinh. Chung toi **khong bao gio** theo doi noi dung ky uc, truy van, duong dan file, hay khoa API. Tat: `export TRUEMEMORY_TELEMETRY=off`
</details>

---

## Bat dau trong 60 giay

```bash
pip install truememory
```

Cau hoi? [Mo mot Cuoc thao luan](https://github.com/buildingjoshbetter/TrueMemory/discussions). Neu TrueMemory giup ban tiet kiem thoi gian, [hay cho chung toi mot ngoi sao](https://github.com/buildingjoshbetter/TrueMemory)

---

## Cam on cac cong tac vien

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

---

## Nghien cuu

TrueMemory duoc ho tro boi mot bai bao nghien cuu binh duyet ve bo nho agent dua tren truy xuat.

**[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}
}
```

---

## Cong dong

- [Tham gia Discord cua chung toi](https://discord.gg/ZJ74JB2gVW) de duoc ho tro, gop y va cap nhat
- Theo doi [@Building_Josh](https://x.com/Building_Josh) tren X de cap nhat
- Theo doi [@Sauron_Labs](https://x.com/Sauron_Labs) de nhan tin tuc cong ty
- [Mo mot Cuoc thao luan](https://github.com/buildingjoshbetter/TrueMemory/discussions) cho cau hoi hoac y tuong
- Doc bai bao tren [arXiv](https://arxiv.org/abs/2605.04897) · [Google Scholar](https://scholar.google.com/citations?user=YOUR_ID) · [Semantic Scholar](https://www.semanticscholar.org/)
- Truy cap [truememory.net](https://truememory.net) · [sauronlabs.ai](https://sauronlabs.ai)

Neu TrueMemory giup ban tiet kiem thoi gian, [hay cho chung toi mot ngoi sao](https://github.com/buildingjoshbetter/TrueMemory)

---

## Giay phep

[AGPL-3.0](../LICENSE). Mien phi cho su dung ca nhan va nghien cuu. Su dung thuong mai can giay phep rieng. Lien he josh@sauronlabs.ai.

---

<p align="center">
  <em>TrueMemory, mot san pham cua <a href="https://sauronlabs.ai"><strong>sauron</strong></a></em>
</p>
