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

<p align="center">
  <em>La mémoire que votre IA aurait dû avoir dès le départ.</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="#pourquoi-truememory">Pourquoi</a> · <a href="#démarrage-rapide">Démarrage rapide</a> · <a href="#comparaison-de-truememory">Comparer</a> · <a href="#niveaux">Niveaux</a> · <a href="#benchmarks">Benchmarks</a> · <a href="#python-api">API</a> · <a href="#documentation">Docs</a> · <a href="#foire-aux-questions">FAQ</a>
</p>

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

---

## Pourquoi TrueMemory

**Il trouve le signal dans le bruit.** Votre IA voit des milliers de messages. TrueMemory détermine lesquels comptent vraiment, et écarte le reste. Pas de balisage manuel, pas d'ingénierie de prompts. Il sait, tout simplement.

**Il devient plus précis avec le temps.** Ce n'est pas une base de données statique. C'est une mémoire vivante qui grandit avec vous, résolvant les contradictions quand vous changez d'avis, mettant à jour les faits périmés et consolidant ce qu'elle sait. Plus vous l'utilisez, meilleure elle devient.

**Il fonctionne sans que vous y pensiez.** TrueMemory capture automatiquement les souvenirs de vos conversations et injecte automatiquement les bons dans votre prochaine session. Vous n'avez jamais à stocker ou chercher quoi que ce soit manuellement. Tout se fait automatiquement.

**Il est 100% local.** Un seul fichier SQLite sur votre machine. Rien ne quitte votre appareil. Pas de cloud, pas de clés API nécessaires. Vos données vous appartiennent.

> **Sans TrueMemory :** « Quel framework utilisons-nous ? » Demandé pour la 12e fois cette semaine. Votre agent commence chaque session avec une amnésie. Il ne connaît ni votre nom, ni votre stack, ni rien de ce que vous lui avez dit hier.
>
> **Avec TrueMemory :** Votre agent sait déjà que vous utilisez FastAPI, préférez Pydantic v2 et que votre middleware d'authentification se trouve dans `src/auth/`. Il se souvient de vos corrections, de vos préférences et de vos décisions. A chaque session, pour toujours.

---

## Comparaison de TrueMemory

| Système | LoCoMo | LongMemEval | Local d'abord | Capture auto | Licence |
|--------|--------|-------------|:-----------:|:------------:|---------|
| **TrueMemory Pro** | **93.0%** | **92.0%** | ✅ | ✅ | AGPL-3.0 |
| **TrueMemory Base** | **87.7%** | **84.1%** | ✅ | ✅ | AGPL-3.0 |
| Mem0 | 61.4% | — | Partiel | ❌ | Apache-2.0 |
| Supermemory | 65.4% | — | ❌ | ❌ | Cloud API |
| MemOS | 75.8% | — | ✅ | ❌ | Apache-2.0 |
| ReadAgent | 79.5% | — | ❌ | ❌ | Research |

> Tous les benchmarks sont reproductibles de manière indépendante. Les scripts sont inclus dans [`benchmarks/`](../benchmarks/).

---

## Démarrage rapide

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

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

> Installe tout dans un environnement isolé. Télécharge ~1,5 Go de modèles d'IA. Aucune donnée ne quitte votre machine. Pas besoin de sudo.

<details><summary>Nouveau dans le terminal ? Cliquez ici pour des instructions pas à pas.</summary>

1. **Ouvrez un terminal :** Mac : `Cmd + Space`, tapez `Terminal`. Linux : `Ctrl + Alt + T`. Windows : ouvrez PowerShell.
2. **Collez la commande ci-dessus** et appuyez sur Entrée.
3. **Attendez 3 à 5 minutes** que les modèles se téléchargent.
4. **Quittez complètement votre outil d'IA** et rouvrez-le (Mac : `Cmd+Q`).
5. **Tapez « Set up TrueMemory »** et choisissez un niveau.

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

</details>

C'est tout. TrueMemory mémorise automatiquement vos conversations à partir de maintenant.

### Pour les développeurs (bibliothèque 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"))
```

---

## Niveaux

Même architecture, trois niveaux. Tous inclus dans une seule installation. Changez à tout moment en disant « switch to Pro » ou « switch to Base ».

| | Edge | Base | Pro |
|---|------|------|-----|
| **LoCoMo** | 89.6% | 92.0% | **93.0%** |
| **LongMemEval** | — | — | **92.0%** |
| **BEAM-1M** | — | — | **76.6% (SOTA)** |
| **Modèle d'embedding** | 8 Mo léger | 600 Mo haute précision | 600 Mo haute précision |
| **Reranker** | 22M paramètres | 149M paramètres | 149M paramètres |
| **Recherche HyDE** | — | — | ✅ (nécessite une clé API LLM) |
| **Fonctionne sur** | N'importe quelle machine, CPU seul | 4 Go+ RAM | 4 Go+ RAM + clé API |

**Edge** fonctionne partout. **Base** est le niveau le plus puissant entièrement hors ligne. **Pro** ajoute l'expansion de requêtes par IA pour les meilleurs scores.

---

## Benchmarks

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

Testé sur trois benchmarks majeurs avec tous les systèmes partageant le même modèle de réponse (GPT-4.1-mini), juge (GPT-4o-mini, vote majoritaire 3x) et pipeline de notation.

| Benchmark | Ce qu'il teste | TrueMemory Pro |
|-----------|--------------|:--------------:|
| [LoCoMo](https://github.com/snap-research/locomo) | 1 540 questions sur 10 conversations | **93.0%** |
| [LongMemEval](https://github.com/xiaowu0162/LongMemEval) | 500 questions multi-session | **92.0%** |
| [BEAM-1M](https://github.com/mohammadtavakoli78/BEAM) | 700 questions à 1M+ tokens | **76.6% (SOTA)** |
| BEAM-10M | 200 questions à 10M tokens | **65.0%** |

### Reproduisez n'importe quel résultat vous-même

Chaque script de benchmark est autonome et s'exécute sur [Modal](https://modal.com).

- **[Scripts LoCoMo](../benchmarks/locomo/scripts/)** — 8 systèmes (TrueMemory, Mem0, Zep, Engram, etc.)
- **[Résultats LoCoMo](../benchmarks/locomo/BENCHMARK_RESULTS.md)** — détails par catégorie, latence, coût
- **[Config d'évaluation LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md)** — modèles, prompts et paramètres exacts
- **[Scripts LongMemEval](../benchmarks/longmemeval/)** — variantes oracle + strict
- **[Résultats LongMemEval](../benchmarks/longmemeval/results/)** — 6 exécutions TM Pro + 5 résultats concurrents
- **[Script BEAM-1M](../benchmarks/beam/bench_truememory_pro_beam1m.py)** — 35 conversations à 1M+ tokens
- **[Script BEAM-10M](../benchmarks/beam/bench_truememory_pro_beam10m.py)** — 10 conversations à 10M tokens
- **[Résultats BEAM](../benchmarks/beam/)** — 3 exécutions (1M) + 1 exécution (10M)

Tous les benchmarks utilisent le même pipeline d'évaluation. Rien n'est caché. Détails complets : [LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md) | [LongMemEval](../benchmarks/longmemeval/README.md) | [BEAM](../benchmarks/beam/README.md)

---

## Compatible avec

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

Les hooks de cycle de vie capturent automatiquement les conversations. Aucun travail manuel nécessaire. Vos souvenirs restent locaux dans un seul fichier 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éthode | Description |
|--------|-------------|
| `m.add(content, user_id)` | Stocker un souvenir |
| `m.search(query, user_id)` | Rechercher (pipeline à 6 couches + reranker) |
| `m.search_deep(query, user_id)` | Recherche agentique multi-tours |
| `m.get(id)` / `m.get_all(user_id)` | Récupérer des souvenirs |
| `m.update(id, content)` / `m.delete(id)` | Modifier ou supprimer |
| `m.stats()` | Statistiques système |

[Référence API complète →](../docs/python-api.md)

---

## Documentation

| | |
|---|---|
| [Premiers pas](../docs/guides/getting-started.md) | De l'installation au premier souvenir |
| [Référence Python API](../docs/python-api.md) | Référence complète de la classe `Memory` |
| [Référence des outils MCP](../docs/mcp-tools.md) | Les 8 outils MCP |
| [Référence CLI](../docs/cli.md) | `truememory-mcp` et `truememory-ingest` |
| [Variables d'environnement](../docs/env-vars.md) | Toutes les options de configuration `TRUEMEMORY_*` |
| [Architecture en profondeur](../docs/architecture.md) | Pipeline de récupération à 6 couches, porte d'encodage |
| [Guide de sélection de niveau](../docs/guides/tier-selection.md) | Edge vs Base vs Pro |
| [Débogage](../docs/guides/debugging.md) | Logs, traces, problèmes courants |

---

## Foire aux questions

<details><summary><strong>Où sont stockées mes données ? Est-ce que quelque chose est envoyé dans le cloud ?</strong></summary>

Tout est stocké localement dans `~/.truememory/memories.db`. Les niveaux Edge et Base ne font aucun appel externe. Pro n'envoie que le texte de votre requête de recherche à un LLM pour l'expansion de requêtes. Vos souvenirs ne sont jamais transmis.
</details>

<details><summary><strong>Dois-je avoir Python installé ?</strong></summary>

Non. L'installateur utilise [uv](https://docs.astral.sh/uv/) pour gérer un Python 3.12 isolé. Votre Python système n'est jamais touché.
</details>

<details><summary><strong>Pourquoi ne pas simplement utiliser une fenêtre de contexte plus grande ?</strong></summary>

Les fenêtres de contexte sont coûteuses, lentes et vides au début de chaque session. TrueMemory offre un rappel instantané pour zéro token de contexte, en moins de 200 ms.
</details>

<details><summary><strong>TrueMemory collecte-t-il de la télémétrie ?</strong></summary>

La télémétrie d'utilisation anonyme (appels d'outils, nombre de sessions, informations de plateforme) est activée par défaut. Nous ne suivons **jamais** le contenu des souvenirs, les requêtes, les chemins de fichiers ou les clés API. Désactiver : `export TRUEMEMORY_TELEMETRY=off`
</details>

---

## Démarrez en 60 secondes

```bash
pip install truememory
```

Des questions ? [Ouvrez une discussion](https://github.com/buildingjoshbetter/TrueMemory/discussions). Si TrueMemory vous fait gagner du temps, [donnez-nous une étoile](https://github.com/buildingjoshbetter/TrueMemory)

---

## Merci à nos contributeurs

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

---

## Recherche

TrueMemory est soutenu par un article de recherche évalué par des pairs sur la mémoire d'agents centrée sur la récupération.

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

---

## Communauté

- [Rejoignez notre Discord](https://discord.gg/ZJ74JB2gVW) pour de l'aide, des retours et des mises à jour
- Suivez [@Building_Josh](https://x.com/Building_Josh) sur X pour les mises à jour
- Suivez [@Sauron_Labs](https://x.com/Sauron_Labs) pour les actualités de l'entreprise
- [Ouvrez une discussion](https://github.com/buildingjoshbetter/TrueMemory/discussions) pour vos questions ou idées
- Lisez l'article sur [arXiv](https://arxiv.org/abs/2605.04897) · [Google Scholar](https://scholar.google.com/citations?user=YOUR_ID) · [Semantic Scholar](https://www.semanticscholar.org/)
- Visitez [truememory.net](https://truememory.net) · [sauronlabs.ai](https://sauronlabs.ai)

Si TrueMemory vous fait gagner du temps, [donnez-nous une étoile](https://github.com/buildingjoshbetter/TrueMemory)

---

## Licence

[AGPL-3.0](../LICENSE). Gratuit pour un usage personnel et de recherche. L'usage commercial nécessite une licence séparée. Contactez josh@sauronlabs.ai.

---

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