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

<p align="center">
  <em>Das Gedachtnis, das deine KI von Anfang an hatte haben sollen.</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="#warum-truememory">Warum</a> · <a href="#schnellstart">Schnellstart</a> · <a href="#truememory-im-vergleich">Vergleich</a> · <a href="#stufen">Stufen</a> · <a href="#benchmarks">Benchmarks</a> · <a href="#python-api">API</a> · <a href="#dokumentation">Doku</a> · <a href="#faq">FAQ</a>
</p>

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

---

## Warum TrueMemory

**Es findet das Signal im Rauschen.** Deine KI sieht Tausende von Nachrichten. TrueMemory erkennt, welche davon wirklich wichtig sind, und verwirft den Rest. Kein manuelles Taggen, kein Prompt-Engineering. Es weiss es einfach.

**Es wird mit der Zeit besser.** Es ist keine statische Datenbank. Es ist ein lebendiges Gedachtnis, das mit dir wachst. Es lost Widerspruche auf, wenn du deine Meinung anderst, aktualisiert veraltete Fakten und konsolidiert sein Wissen. Je langer du es nutzt, desto besser wird es.

**Es funktioniert, ohne dass du daruber nachdenken musst.** TrueMemory erfasst automatisch Erinnerungen aus deinen Gesprachen und fugt die richtigen automatisch in deine nachste Sitzung ein. Du musst nie manuell etwas speichern oder suchen. Es passiert einfach.

**Es ist 100% lokal.** Eine SQLite-Datei auf deinem Rechner. Nichts verlasst dein Gerat. Keine Cloud, keine API-Schlussel erforderlich. Deine Daten gehoren dir.

> **Ohne TrueMemory:** "Welches Framework benutzen wir?" Zum 12. Mal diese Woche gefragt. Dein Agent startet jede Sitzung mit Amnesie. Er kennt weder deinen Namen, noch deinen Stack, noch irgendetwas, das du ihm gestern gesagt hast.
>
> **Mit TrueMemory:** Dein Agent weiss bereits, dass du FastAPI verwendest, Pydantic v2 bevorzugst und dass deine Auth-Middleware in `src/auth/` liegt. Er erinnert sich an deine Korrekturen, deine Praferenzen und deine Entscheidungen. Uber jede Sitzung hinweg, fur immer.

---

## TrueMemory im Vergleich

| System | LoCoMo | LongMemEval | Lokal-zuerst | Auto-Erfassung | Lizenz |
|--------|--------|-------------|:-----------:|:------------:|---------|
| **TrueMemory Pro** | **93.0%** | **92.0%** | ✅ | ✅ | AGPL-3.0 |
| **TrueMemory Base** | **87.7%** | **84.1%** | ✅ | ✅ | AGPL-3.0 |
| Mem0 | 61.4% | — | Teilweise | ❌ | Apache-2.0 |
| Supermemory | 65.4% | — | ❌ | ❌ | Cloud API |
| MemOS | 75.8% | — | ✅ | ❌ | Apache-2.0 |
| ReadAgent | 79.5% | — | ❌ | ❌ | Research |

> Alle Benchmarks unabhangig reproduzierbar. Skripte enthalten in [`benchmarks/`](../benchmarks/).

---

## Schnellstart

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

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

> Installiert alles in einer isolierten Umgebung. Ladt ~1,5 GB an KI-Modellen herunter. Keine Daten verlassen deinen Rechner. Kein sudo erforderlich.

<details><summary>Neu im Terminal? Klicke hier fur eine Schritt-fur-Schritt-Anleitung.</summary>

1. **Offne ein Terminal:** Mac: `Cmd + Space`, tippe `Terminal`. Linux: `Ctrl + Alt + T`. Windows: offne PowerShell.
2. **Fuge den obigen Befehl ein** und drucke Enter.
3. **Warte 3-5 Minuten**, bis die Modelle heruntergeladen sind.
4. **Beende dein KI-Tool vollstandig** und offne es erneut (Mac: `Cmd+Q`).
5. **Tippe "Set up TrueMemory"** und wahle eine Stufe.

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

</details>

Das war's. TrueMemory merkt sich ab jetzt automatisch deine Gesprache.

### Fur Entwickler (Python-Bibliothek)

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

---

## Stufen

Gleiche Architektur, drei Stufen. Alle in einer einzigen Installation enthalten. Wechsle jederzeit, indem du "switch to Pro" oder "switch to Base" sagst.

| | Edge | Base | Pro |
|---|------|------|-----|
| **LoCoMo** | 89.6% | 92.0% | **93.0%** |
| **LongMemEval** | — | — | **92.0%** |
| **BEAM-1M** | — | — | **76.6% (SOTA)** |
| **Embedding-Modell** | 8 MB leichtgewichtig | 600 MB hohe Genauigkeit | 600 MB hohe Genauigkeit |
| **Reranker** | 22M Parameter | 149M Parameter | 149M Parameter |
| **HyDE-Suche** | — | — | ✅ (erfordert LLM-API-Schlussel) |
| **Lauft auf** | Jedem Rechner, nur CPU | 4 GB+ RAM | 4 GB+ RAM + API-Schlussel |

**Edge** funktioniert uberall. **Base** ist die starkste vollstandig offline arbeitende Stufe. **Pro** fugt KI-gestutzte Abfrageerweiterung fur die hochsten Werte hinzu.

---

## Benchmarks

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

Getestet uber drei grosse Benchmarks, wobei alle Systeme dasselbe Antwortmodell (GPT-4.1-mini), denselben Bewerter (GPT-4o-mini, 3x Mehrheitsabstimmung) und dieselbe Bewertungspipeline nutzen.

| Benchmark | Was er testet | TrueMemory Pro |
|-----------|--------------|:--------------:|
| [LoCoMo](https://github.com/snap-research/locomo) | 1.540 Fragen uber 10 Gesprache | **93.0%** |
| [LongMemEval](https://github.com/xiaowu0162/LongMemEval) | 500 Multi-Session-Fragen | **92.0%** |
| [BEAM-1M](https://github.com/mohammadtavakoli78/BEAM) | 700 Fragen bei 1M+ Tokens | **76.6% (SOTA)** |
| BEAM-10M | 200 Fragen bei 10M Tokens | **65.0%** |

### Jedes Ergebnis selbst reproduzieren

Jedes Benchmark-Skript ist eigenstandig und lauft auf [Modal](https://modal.com).

- **[LoCoMo-Skripte](../benchmarks/locomo/scripts/)** — 8 Systeme (TrueMemory, Mem0, Zep, Engram usw.)
- **[LoCoMo-Ergebnisse](../benchmarks/locomo/BENCHMARK_RESULTS.md)** — Aufschlusslung nach Kategorien, Latenz, Kosten
- **[LoCoMo-Eval-Konfiguration](../benchmarks/locomo/EVAL_CONFIG.md)** — Genaue Modelle, Prompts, Parameter
- **[LongMemEval-Skripte](../benchmarks/longmemeval/)** — Oracle- und Strict-Varianten
- **[LongMemEval-Ergebnisse](../benchmarks/longmemeval/results/)** — 6 TM Pro-Durchlaufe + 5 Wettbewerberergebnisse
- **[BEAM-1M-Skript](../benchmarks/beam/bench_truememory_pro_beam1m.py)** — 35 Gesprache bei 1M+ Tokens
- **[BEAM-10M-Skript](../benchmarks/beam/bench_truememory_pro_beam10m.py)** — 10 Gesprache bei 10M Tokens
- **[BEAM-Ergebnisse](../benchmarks/beam/)** — 3 Durchlaufe (1M) + 1 Durchlauf (10M)

Alle Benchmarks verwenden dieselbe Evaluierungspipeline. Nichts ist verborgen. Vollstandige Details: [LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md) | [LongMemEval](../benchmarks/longmemeval/README.md) | [BEAM](../benchmarks/beam/README.md)

---

## Kompatibel mit

<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 erfassen Gesprache automatisch. Kein manueller Aufwand erforderlich. Deine Erinnerungen bleiben lokal in einer einzigen SQLite-Datei.

---

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

| Methode | Beschreibung |
|---------|-------------|
| `m.add(content, user_id)` | Eine Erinnerung speichern |
| `m.search(query, user_id)` | Suche (6-stufige Pipeline + Reranker) |
| `m.search_deep(query, user_id)` | Multi-Runden-agentenbasierte Suche |
| `m.get(id)` / `m.get_all(user_id)` | Erinnerungen abrufen |
| `m.update(id, content)` / `m.delete(id)` | Andern oder loschen |
| `m.stats()` | Systemstatistiken |

[Vollstandige API-Referenz →](../docs/python-api.md)

---

## Dokumentation

| | |
|---|---|
| [Erste Schritte](../docs/guides/getting-started.md) | Von der Installation zur ersten Erinnerung |
| [Python API-Referenz](../docs/python-api.md) | Vollstandige `Memory`-Klassenreferenz |
| [MCP-Tool-Referenz](../docs/mcp-tools.md) | Alle 8 MCP-Tools |
| [CLI-Referenz](../docs/cli.md) | `truememory-mcp` und `truememory-ingest` |
| [Umgebungsvariablen](../docs/env-vars.md) | Alle `TRUEMEMORY_*`-Konfigurationsoptionen |
| [Architektur-Tiefgang](../docs/architecture.md) | 6-stufige Abruf-Pipeline, Encoding-Gate |
| [Stufenauswahl-Leitfaden](../docs/guides/tier-selection.md) | Edge vs Base vs Pro |
| [Fehlerbehebung](../docs/guides/debugging.md) | Logs, Traces, haufige Probleme |

---

## FAQ

<details><summary><strong>Wo werden meine Daten gespeichert? Wird etwas in die Cloud gesendet?</strong></summary>

Alles liegt lokal in `~/.truememory/memories.db`. Edge und Base machen keinerlei externe Aufrufe. Pro sendet nur deinen Suchanfragetext an ein LLM zur Abfrageerweiterung. Deine Erinnerungen werden niemals ubertragen.
</details>

<details><summary><strong>Brauche ich eine Python-Installation?</strong></summary>

Nein. Der Installer verwendet [uv](https://docs.astral.sh/uv/) zur Verwaltung einer isolierten Python 3.12-Umgebung. Dein System-Python wird nicht verandert.
</details>

<details><summary><strong>Warum nicht einfach ein grosseres Kontextfenster verwenden?</strong></summary>

Kontextfenster sind teuer, langsam und zu Beginn jeder Sitzung leer. TrueMemory bietet sofortigen Zugriff fur null Kontext-Tokens, in unter 200 ms.
</details>

<details><summary><strong>Sammelt TrueMemory Telemetriedaten?</strong></summary>

Anonyme Nutzungstelemetrie (Tool-Aufrufe, Sitzungsanzahl, Plattforminformationen) ist standardmassig aktiviert. Wir erfassen **niemals** Erinnerungsinhalte, Suchanfragen, Dateipfade oder API-Schlussel. Deaktivieren: `export TRUEMEMORY_TELEMETRY=off`
</details>

---

## In 60 Sekunden loslegen

```bash
pip install truememory
```

Fragen? [Eroffne eine Diskussion](https://github.com/buildingjoshbetter/TrueMemory/discussions). Wenn TrueMemory dir Zeit spart, [gib uns einen Stern](https://github.com/buildingjoshbetter/TrueMemory)

---

## Danke an unsere Mitwirkenden

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

---

## Forschung

TrueMemory basiert auf einem begutachteten Forschungsartikel uber abrufzentrierten Agentenspeicher.

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

- [Tritt unserem Discord bei](https://discord.gg/ZJ74JB2gVW) fur Hilfe, Feedback und Updates
- Folge [@Building_Josh](https://x.com/Building_Josh) auf X fur Updates
- Folge [@Sauron_Labs](https://x.com/Sauron_Labs) fur Unternehmensneuigkeiten
- [Eroffne eine Diskussion](https://github.com/buildingjoshbetter/TrueMemory/discussions) fur Fragen oder Ideen
- Lies den Artikel auf [arXiv](https://arxiv.org/abs/2605.04897) · [Google Scholar](https://scholar.google.com/citations?user=YOUR_ID) · [Semantic Scholar](https://www.semanticscholar.org/)
- Besuche [truememory.net](https://truememory.net) · [sauronlabs.ai](https://sauronlabs.ai)

Wenn TrueMemory dir Zeit spart, [gib uns einen Stern](https://github.com/buildingjoshbetter/TrueMemory)

---

## Lizenz

[AGPL-3.0](../LICENSE). Kostenlos fur personliche Nutzung und Forschung. Kommerzielle Nutzung erfordert eine separate Lizenz. Kontaktiere josh@sauronlabs.ai.

---

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