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

<p align="center">
  <em>La memoria che la tua IA avrebbe dovuto avere fin dall'inizio.</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="#perche-truememory">Perche</a> · <a href="#avvio-rapido">Avvio Rapido</a> · <a href="#come-si-confronta-truememory">Confronto</a> · <a href="#livelli">Livelli</a> · <a href="#benchmark">Benchmark</a> · <a href="#python-api">API</a> · <a href="#documentazione">Docs</a> · <a href="#faq">FAQ</a>
</p>

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

---

## Perche TrueMemory

**Trova il segnale nel rumore.** La tua IA vede migliaia di messaggi. TrueMemory capisce quali contano davvero, e scarta il resto. Nessuna etichettatura manuale, nessun prompt engineering. Semplicemente lo sa.

**Diventa piu preciso nel tempo.** Non e un database statico. E una memoria vivente che cresce con te. Risolve le contraddizioni quando cambi idea, aggiornando i fatti obsoleti e consolidando cio che sa. Piu a lungo lo usi, meglio funziona.

**Funziona senza che tu debba pensarci.** TrueMemory cattura automaticamente i ricordi dalle tue conversazioni e inietta automaticamente quelli giusti nella tua sessione successiva. Non devi mai salvare o cercare nulla manualmente. Succede e basta.

**E al 100% locale.** Un singolo file SQLite sulla tua macchina. Nulla lascia il tuo dispositivo. Nessun cloud, nessuna chiave API necessaria. I tuoi dati sono tuoi.

> **Senza TrueMemory:** "Quale framework stiamo usando?" Chiesto per la 12esima volta questa settimana. Il tuo agente inizia ogni sessione con amnesia. Non conosce il tuo nome, il tuo stack, ne nulla di cio che gli hai detto ieri.
>
> **Con TrueMemory:** Il tuo agente sa gia che usi FastAPI, preferisci Pydantic v2, e che il tuo middleware auth si trova in `src/auth/`. Ricorda le tue correzioni, le tue preferenze e le tue decisioni. In ogni sessione, per sempre.

---

## Come si confronta TrueMemory

| Sistema | LoCoMo | LongMemEval | Locale-first | Cattura automatica | Licenza |
|---------|--------|-------------|:-----------:|:------------:|---------|
| **TrueMemory Pro** | **93.0%** | **92.0%** | ✅ | ✅ | AGPL-3.0 |
| **TrueMemory Base** | **87.7%** | **84.1%** | ✅ | ✅ | AGPL-3.0 |
| Mem0 | 61.4% | — | Parziale | ❌ | Apache-2.0 |
| Supermemory | 65.4% | — | ❌ | ❌ | Cloud API |
| MemOS | 75.8% | — | ✅ | ❌ | Apache-2.0 |
| ReadAgent | 79.5% | — | ❌ | ❌ | Research |

> Tutti i benchmark sono riproducibili indipendentemente. Script inclusi in [`benchmarks/`](../benchmarks/).

---

## Avvio Rapido

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

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

> Installa tutto in un ambiente isolato. Scarica ~1,5 GB di modelli IA. Nessun dato lascia la tua macchina. Non richiede sudo.

<details><summary>Nuovo al terminale? Clicca qui per le istruzioni passo-passo.</summary>

1. **Apri un terminale:** Mac: `Cmd + Space`, digita `Terminal`. Linux: `Ctrl + Alt + T`. Windows: apri PowerShell.
2. **Incolla il comando sopra** e premi Invio.
3. **Attendi 3-5 minuti** per il download dei modelli.
4. **Chiudi completamente il tuo strumento IA** e riaprilo (Mac: `Cmd+Q`).
5. **Digita "Set up TrueMemory"** e scegli un livello.

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

</details>

Tutto qui. TrueMemory ricorda automaticamente le tue conversazioni da ora in poi.

### Per sviluppatori (libreria 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"))
```

---

## Livelli

Stessa architettura, tre livelli. Tutti inclusi in una singola installazione. Passa da uno all'altro in qualsiasi momento dicendo "switch to Pro" o "switch to Base."

| | Edge | Base | Pro |
|---|------|------|-----|
| **LoCoMo** | 89.6% | 92.0% | **93.0%** |
| **LongMemEval** | — | — | **92.0%** |
| **BEAM-1M** | — | — | **76.6% (SOTA)** |
| **Modello di embedding** | 8 MB leggero | 600 MB alta precisione | 600 MB alta precisione |
| **Reranker** | 22M parametri | 149M parametri | 149M parametri |
| **Ricerca HyDE** | — | — | ✅ (richiede chiave API LLM) |
| **Requisiti** | Qualsiasi macchina, solo CPU | 4 GB+ RAM | 4 GB+ RAM + chiave API |

**Edge** funziona ovunque. **Base** e il livello offline completo piu potente. **Pro** aggiunge l'espansione delle query basata su IA per i punteggi piu alti.

---

## Benchmark

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

Testato su tre benchmark principali con tutti i sistemi che condividono lo stesso modello di risposta (GPT-4.1-mini), giudice (GPT-4o-mini, voto a maggioranza 3x) e pipeline di valutazione.

| Benchmark | Cosa testa | TrueMemory Pro |
|-----------|-----------|:--------------:|
| [LoCoMo](https://github.com/snap-research/locomo) | 1.540 domande su 10 conversazioni | **93.0%** |
| [LongMemEval](https://github.com/xiaowu0162/LongMemEval) | 500 domande multi-sessione | **92.0%** |
| [BEAM-1M](https://github.com/mohammadtavakoli78/BEAM) | 700 domande a 1M+ token | **76.6% (SOTA)** |
| BEAM-10M | 200 domande a 10M token | **65.0%** |

### Riproduci qualsiasi risultato da solo

Ogni script di benchmark e autonomo e gira su [Modal](https://modal.com).

- **[Script LoCoMo](../benchmarks/locomo/scripts/)** — 8 sistemi (TrueMemory, Mem0, Zep, Engram, ecc.)
- **[Risultati LoCoMo](../benchmarks/locomo/BENCHMARK_RESULTS.md)** — dettagli per categoria, latenza, costi
- **[Configurazione Eval LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md)** — modelli esatti, prompt, parametri
- **[Script LongMemEval](../benchmarks/longmemeval/)** — varianti oracle + strict
- **[Risultati LongMemEval](../benchmarks/longmemeval/results/)** — 6 esecuzioni TM Pro + 5 risultati concorrenti
- **[Script BEAM-1M](../benchmarks/beam/bench_truememory_pro_beam1m.py)** — 35 conversazioni a 1M+ token
- **[Script BEAM-10M](../benchmarks/beam/bench_truememory_pro_beam10m.py)** — 10 conversazioni a 10M token
- **[Risultati BEAM](../benchmarks/beam/)** — 3 esecuzioni (1M) + 1 esecuzione (10M)

Tutti i benchmark usano la stessa pipeline di valutazione. Nulla e nascosto. Dettagli completi: [LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md) | [LongMemEval](../benchmarks/longmemeval/README.md) | [BEAM](../benchmarks/beam/README.md)

---

## Compatibile con

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

I lifecycle hook catturano le conversazioni automaticamente. Nessun lavoro manuale necessario. I tuoi ricordi restano locali in un singolo file 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
```

| Metodo | Descrizione |
|--------|-------------|
| `m.add(content, user_id)` | Salva un ricordo |
| `m.search(query, user_id)` | Ricerca (pipeline a 6 livelli + reranker) |
| `m.search_deep(query, user_id)` | Ricerca agentica multi-round |
| `m.get(id)` / `m.get_all(user_id)` | Recupera ricordi |
| `m.update(id, content)` / `m.delete(id)` | Modifica o elimina |
| `m.stats()` | Statistiche di sistema |

[Riferimento API completo →](../docs/python-api.md)

---

## Documentazione

| | |
|---|---|
| [Per iniziare](../docs/guides/getting-started.md) | Dall'installazione al primo ricordo |
| [Riferimento Python API](../docs/python-api.md) | Riferimento completo della classe `Memory` |
| [Riferimento MCP Tool](../docs/mcp-tools.md) | Tutti gli 8 strumenti MCP |
| [Riferimento CLI](../docs/cli.md) | `truememory-mcp` e `truememory-ingest` |
| [Variabili d'ambiente](../docs/env-vars.md) | Tutte le opzioni di configurazione `TRUEMEMORY_*` |
| [Architettura in dettaglio](../docs/architecture.md) | Pipeline di recupero a 6 livelli, encoding gate |
| [Guida alla scelta del livello](../docs/guides/tier-selection.md) | Edge vs Base vs Pro |
| [Debug](../docs/guides/debugging.md) | Log, trace, problemi comuni |

---

## FAQ

<details><summary><strong>Dove vengono salvati i miei dati? Viene inviato qualcosa al cloud?</strong></summary>

Tutto risiede localmente in `~/.truememory/memories.db`. I livelli Edge e Base non effettuano nessuna chiamata esterna. Pro invia solo il testo della tua query di ricerca a un LLM per l'espansione della query. I tuoi ricordi non vengono mai trasmessi.
</details>

<details><summary><strong>Devo avere Python installato?</strong></summary>

No. L'installatore usa [uv](https://docs.astral.sh/uv/) per gestire un Python 3.12 isolato in sandbox. Il Python di sistema non viene toccato.
</details>

<details><summary><strong>Perche non usare semplicemente una finestra di contesto piu grande?</strong></summary>

Le finestre di contesto sono costose, lente e vuote all'inizio di ogni sessione. TrueMemory offre un richiamo istantaneo con zero token di contesto, in meno di 200 ms.
</details>

<details><summary><strong>TrueMemory raccoglie dati di telemetria?</strong></summary>

La telemetria di utilizzo anonima (chiamate agli strumenti, conteggio sessioni, informazioni sulla piattaforma) e attiva per impostazione predefinita. Non tracciamo **mai** il contenuto dei ricordi, le query, i percorsi dei file o le chiavi API. Per disattivare: `export TRUEMEMORY_TELEMETRY=off`
</details>

---

## Inizia in 60 secondi

```bash
pip install truememory
```

Domande? [Apri una Discussione](https://github.com/buildingjoshbetter/TrueMemory/discussions). Se TrueMemory ti fa risparmiare tempo, [dacci una stella](https://github.com/buildingjoshbetter/TrueMemory)

---

## Grazie ai nostri contributori

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

---

## Ricerca

TrueMemory e supportato da un articolo di ricerca peer-reviewed sulla memoria degli agenti basata sul recupero.

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

- [Unisciti al nostro Discord](https://discord.gg/ZJ74JB2gVW) per aiuto, feedback e aggiornamenti
- Segui [@Building_Josh](https://x.com/Building_Josh) su X per aggiornamenti
- Segui [@Sauron_Labs](https://x.com/Sauron_Labs) per notizie aziendali
- [Apri una Discussione](https://github.com/buildingjoshbetter/TrueMemory/discussions) per domande o idee
- Leggi l'articolo su [arXiv](https://arxiv.org/abs/2605.04897) · [Google Scholar](https://scholar.google.com/citations?user=YOUR_ID) · [Semantic Scholar](https://www.semanticscholar.org/)
- Visita [truememory.net](https://truememory.net) · [sauronlabs.ai](https://sauronlabs.ai)

Se TrueMemory ti fa risparmiare tempo, [dacci una stella](https://github.com/buildingjoshbetter/TrueMemory)

---

## Licenza

[AGPL-3.0](../LICENSE). Gratuito per uso personale e di ricerca. L'uso commerciale richiede una licenza separata -- contatta josh@sauronlabs.ai.

---

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