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

<p align="center">
  <em>Het geheugen dat je AI vanaf het begin had moeten hebben.</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="#waarom-truememory">Waarom</a> · <a href="#snel-starten">Snel starten</a> · <a href="#hoe-truememory-zich-vergelijkt">Vergelijking</a> · <a href="#niveaus">Niveaus</a> · <a href="#benchmarks">Benchmarks</a> · <a href="#python-api">API</a> · <a href="#documentatie">Documentatie</a> · <a href="#faq">FAQ</a>
</p>

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

---

## Waarom TrueMemory

**Het vindt het signaal in de ruis.** Je AI ziet duizenden berichten. TrueMemory bepaalt welke er echt toe doen en gooit de rest weg. Geen handmatig taggen, geen prompt engineering. Het weet het gewoon.

**Het wordt scherper met de tijd.** Het is geen statische database. Het is een levend geheugen dat met je meegroeit. Het lost tegenstrijdigheden op wanneer je van gedachten verandert, verouderde feiten bijwerkt en consolideert wat het weet. Hoe langer je het gebruikt, hoe beter het wordt.

**Het werkt zonder dat je erover hoeft na te denken.** TrueMemory legt automatisch herinneringen vast uit je gesprekken en injecteert automatisch de juiste in je volgende sessie. Je hoeft nooit handmatig iets op te slaan of te zoeken. Het gebeurt gewoon.

**Het is 100% lokaal.** Een enkel SQLite-bestand op jouw machine. Niets verlaat je apparaat. Geen cloud, geen API-sleutels nodig. Je data is van jou.

> **Zonder TrueMemory:** "Welk framework gebruiken we?" Voor de 12e keer deze week gevraagd. Je agent begint elke sessie met geheugenverlies. Het kent je naam niet, je stack niet, of wat je gisteren verteld hebt.
>
> **Met TrueMemory:** Je agent weet al dat je FastAPI gebruikt, de voorkeur geeft aan Pydantic v2, en dat je auth middleware in `src/auth/` staat. Het onthoudt je correcties, je voorkeuren en je beslissingen. In elke sessie, voor altijd.

---

## Hoe TrueMemory zich vergelijkt

| Systeem | LoCoMo | LongMemEval | Lokaal-eerst | Automatisch vastleggen | Licentie |
|--------|--------|-------------|:-----------:|:------------:|---------|
| **TrueMemory Pro** | **93.0%** | **92.0%** | ✅ | ✅ | AGPL-3.0 |
| **TrueMemory Base** | **87.7%** | **84.1%** | ✅ | ✅ | AGPL-3.0 |
| Mem0 | 61.4% | — | Gedeeltelijk | ❌ | Apache-2.0 |
| Supermemory | 65.4% | — | ❌ | ❌ | Cloud API |
| MemOS | 75.8% | — | ✅ | ❌ | Apache-2.0 |
| ReadAgent | 79.5% | — | ❌ | ❌ | Research |

> Alle benchmarks zijn onafhankelijk reproduceerbaar. Scripts zijn opgenomen in [`benchmarks/`](../benchmarks/).

---

## Snel starten

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

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

> Installeert alles in een geisoleerde omgeving. Downloadt ~1,5 GB aan AI-modellen. Er verlaten geen gegevens je machine. Geen sudo vereist.

<details><summary>Nieuw met de terminal? Klik hier voor stapsgewijze instructies.</summary>

1. **Open een terminal:** Mac: `Cmd + Space`, typ `Terminal`. Linux: `Ctrl + Alt + T`. Windows: open PowerShell.
2. **Plak het bovenstaande commando** en druk op Enter.
3. **Wacht 3-5 minuten** tot de modellen zijn gedownload.
4. **Sluit je AI-tool volledig af** en open het opnieuw (Mac: `Cmd+Q`).
5. **Typ "Set up TrueMemory"** en kies een niveau.

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

</details>

Dat is alles. TrueMemory onthoudt je gesprekken vanaf nu automatisch.

### Voor ontwikkelaars (Python-bibliotheek)

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

---

## Niveaus

Dezelfde architectuur, drie niveaus. Allemaal inbegrepen in een enkele installatie. Schakel op elk moment door te zeggen "switch to Pro" of "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 lichtgewicht | 600 MB hoge nauwkeurigheid | 600 MB hoge nauwkeurigheid |
| **Reranker** | 22M parameters | 149M parameters | 149M parameters |
| **HyDE search** | — | — | ✅ (vereist LLM API-sleutel) |
| **Draait op** | Elke machine, alleen CPU | 4 GB+ RAM | 4 GB+ RAM + API-sleutel |

**Edge** werkt overal. **Base** is het sterkste volledig offline niveau. **Pro** voegt AI-gestuurde queryuitbreiding toe voor de hoogste scores.

---

## Benchmarks

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

Getest op drie grote benchmarks waarbij alle systemen hetzelfde antwoordmodel (GPT-4.1-mini), dezelfde beoordelaar (GPT-4o-mini, 3x meerderheidsstemming) en dezelfde scorepijplijn delen.

| Benchmark | Wat het test | TrueMemory Pro |
|-----------|--------------|:--------------:|
| [LoCoMo](https://github.com/snap-research/locomo) | 1.540 vragen over 10 gesprekken | **93.0%** |
| [LongMemEval](https://github.com/xiaowu0162/LongMemEval) | 500 multi-sessievragen | **92.0%** |
| [BEAM-1M](https://github.com/mohammadtavakoli78/BEAM) | 700 vragen bij 1M+ tokens | **76.6% (SOTA)** |
| BEAM-10M | 200 vragen bij 10M tokens | **65.0%** |

### Reproduceer elk resultaat zelf

Elk benchmarkscript is zelfstandig en draait op [Modal](https://modal.com).

- **[LoCoMo Scripts](../benchmarks/locomo/scripts/)** — 8 systemen (TrueMemory, Mem0, Zep, Engram, etc.)
- **[LoCoMo Resultaten](../benchmarks/locomo/BENCHMARK_RESULTS.md)** — uitsplitsing per categorie, latentie, kosten
- **[LoCoMo Evaluatieconfiguratie](../benchmarks/locomo/EVAL_CONFIG.md)** — exacte modellen, prompts, parameters
- **[LongMemEval Scripts](../benchmarks/longmemeval/)** — oracle + strict varianten
- **[LongMemEval Resultaten](../benchmarks/longmemeval/results/)** — 6 TM Pro-runs + 5 concurrentresultaten
- **[BEAM-1M Script](../benchmarks/beam/bench_truememory_pro_beam1m.py)** — 35 gesprekken bij 1M+ tokens
- **[BEAM-10M Script](../benchmarks/beam/bench_truememory_pro_beam10m.py)** — 10 gesprekken bij 10M tokens
- **[BEAM Resultaten](../benchmarks/beam/)** — 3 runs (1M) + 1 run (10M)

Alle benchmarks gebruiken dezelfde evaluatiepijplijn. Niets is verborgen. Volledige details: [LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md) | [LongMemEval](../benchmarks/longmemeval/README.md) | [BEAM](../benchmarks/beam/README.md)

---

## Werkt met

<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 hooks leggen gesprekken automatisch vast. Geen handmatig werk nodig. Je herinneringen blijven lokaal in een enkel SQLite-bestand.

---

## 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")  # meerdere rondes, hogere nauwkeurigheid
```

| Methode | Beschrijving |
|--------|-------------|
| `m.add(content, user_id)` | Sla een herinnering op |
| `m.search(query, user_id)` | Zoek (6-laagse pijplijn + reranker) |
| `m.search_deep(query, user_id)` | Multi-ronde agentische zoekopdracht |
| `m.get(id)` / `m.get_all(user_id)` | Haal herinneringen op |
| `m.update(id, content)` / `m.delete(id)` | Wijzig of verwijder |
| `m.stats()` | Systeemstatistieken |

[Volledige API-referentie ->](../docs/python-api.md)

---

## Documentatie

| | |
|---|---|
| [Aan de slag](../docs/guides/getting-started.md) | Van installatie tot eerste herinnering |
| [Python API-referentie](../docs/python-api.md) | Volledige `Memory`-klassereferentie |
| [MCP-toolreferentie](../docs/mcp-tools.md) | Alle 8 MCP-tools |
| [CLI-referentie](../docs/cli.md) | `truememory-mcp` en `truememory-ingest` |
| [Omgevingsvariabelen](../docs/env-vars.md) | Alle `TRUEMEMORY_*`-configuratieopties |
| [Architectuur in detail](../docs/architecture.md) | 6-laagse zoekpijplijn, encoding gate |
| [Niveauselectiegids](../docs/guides/tier-selection.md) | Edge vs Base vs Pro |
| [Foutopsporing](../docs/guides/debugging.md) | Logs, traces, veelvoorkomende problemen |

---

## FAQ

<details><summary><strong>Waar worden mijn gegevens opgeslagen? Wordt er iets naar de cloud gestuurd?</strong></summary>

Alles wordt lokaal opgeslagen in `~/.truememory/memories.db`. Edge- en Base-niveaus maken nul externe aanroepen. Pro stuurt alleen je zoekquerytekst naar een LLM voor queryuitbreiding. Je herinneringen worden nooit verzonden.
</details>

<details><summary><strong>Heb ik Python nodig?</strong></summary>

Nee. Het installatieprogramma gebruikt [uv](https://docs.astral.sh/uv/) om een sandboxed Python 3.12 te beheren. Je systeem-Python wordt nooit aangeraakt.
</details>

<details><summary><strong>Waarom niet gewoon een groter contextvenster gebruiken?</strong></summary>

Contextvensters zijn duur, langzaam en leeg aan het begin van elke sessie. TrueMemory biedt directe herinnering voor nul tokens context, in minder dan 200ms.
</details>

<details><summary><strong>Verzamelt TrueMemory telemetrie?</strong></summary>

Anonieme gebruikstelemetrie (toolaanroepen, sessieaantallen, platforminformatie) is standaard ingeschakeld. We volgen **nooit** geheugeninhoud, zoekopdrachten, bestandspaden of API-sleutels. Uitschakelen: `export TRUEMEMORY_TELEMETRY=off`
</details>

---

## Begin in 60 seconden

```bash
pip install truememory
```

Vragen? [Open een discussie](https://github.com/buildingjoshbetter/TrueMemory/discussions). Als TrueMemory je tijd bespaart, [geef ons een ster](https://github.com/buildingjoshbetter/TrueMemory)

---

## Met dank aan onze bijdragers

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

---

## Onderzoek

TrueMemory wordt ondersteund door een peer-reviewed onderzoekspaper over op zoeken gebaseerd agentgeheugen.

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

---

## Community

- [Word lid van onze Discord](https://discord.gg/ZJ74JB2gVW) voor hulp, feedback en updates
- Volg [@Building_Josh](https://x.com/Building_Josh) op X voor updates
- Volg [@Sauron_Labs](https://x.com/Sauron_Labs) voor bedrijfsnieuws
- [Open een discussie](https://github.com/buildingjoshbetter/TrueMemory/discussions) voor vragen of ideeen
- Lees het paper op [arXiv](https://arxiv.org/abs/2605.04897) · [Google Scholar](https://scholar.google.com/citations?user=YOUR_ID) · [Semantic Scholar](https://www.semanticscholar.org/)
- Bezoek [truememory.net](https://truememory.net) · [sauronlabs.ai](https://sauronlabs.ai)

Als TrueMemory je tijd bespaart, [geef ons een ster](https://github.com/buildingjoshbetter/TrueMemory)

---

## Licentie

[AGPL-3.0](../LICENSE). Gratis voor persoonlijk en onderzoeksgebruik. Commercieel gebruik vereist een aparte licentie. Neem contact op met josh@sauronlabs.ai.

---

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