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

<p align="center">
  <em>La memoria que tu IA deberia haber tenido desde el principio.</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="#por-qué-truememory">Por qué</a> · <a href="#inicio-rápido">Inicio rápido</a> · <a href="#cómo-se-compara-truememory">Comparar</a> · <a href="#niveles">Niveles</a> · <a href="#benchmarks">Benchmarks</a> · <a href="#python-api">API</a> · <a href="#documentación">Docs</a> · <a href="#preguntas-frecuentes">FAQ</a>
</p>

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

---

## Por qué TrueMemory

**Encuentra la señal en el ruido.** Tu IA ve miles de mensajes. TrueMemory descubre cuáles realmente importan, y descarta el resto. Sin etiquetado manual, sin ingeniería de prompts. Simplemente lo sabe.

**Se vuelve más preciso con el tiempo.** No es una base de datos estática. Es una memoria viva que crece contigo, resolviendo contradicciones cuando cambias de opinión, actualizando hechos obsoletos y consolidando lo que sabe. Cuanto más lo usas, mejor funciona.

**Funciona sin que tengas que pensar en ello.** TrueMemory captura automáticamente recuerdos de tus conversaciones e inyecta automáticamente los correctos en tu próxima sesión. Nunca tienes que almacenar ni buscar nada manualmente. Simplemente sucede.

**Es 100% local.** Un archivo SQLite en tu máquina. Nada sale de tu dispositivo. Sin nube, sin claves API necesarias. Tus datos son tuyos.

> **Sin TrueMemory:** "¿Qué framework estamos usando?" Preguntado por 12a vez esta semana. Tu agente comienza cada sesión con amnesia. No sabe tu nombre, tu stack, ni nada de lo que le dijiste ayer.
>
> **Con TrueMemory:** Tu agente ya sabe que usas FastAPI, prefieres Pydantic v2 y que tu middleware de autenticación está en `src/auth/`. Recuerda tus correcciones, tus preferencias y tus decisiones. En cada sesión, para siempre.

---

## Cómo se compara TrueMemory

| Sistema | LoCoMo | LongMemEval | Local primero | Captura automática | Licencia |
|--------|--------|-------------|:-----------:|:------------:|---------|
| **TrueMemory Pro** | **93.0%** | **92.0%** | ✅ | ✅ | AGPL-3.0 |
| **TrueMemory Base** | **87.7%** | **84.1%** | ✅ | ✅ | AGPL-3.0 |
| Mem0 | 61.4% | — | Parcial | ❌ | Apache-2.0 |
| Supermemory | 65.4% | — | ❌ | ❌ | Cloud API |
| MemOS | 75.8% | — | ✅ | ❌ | Apache-2.0 |
| ReadAgent | 79.5% | — | ❌ | ❌ | Research |

> Todos los benchmarks son reproducibles de forma independiente. Los scripts están incluidos en [`benchmarks/`](../benchmarks/).

---

## Inicio rápido

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

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

> Instala todo en un entorno aislado. Descarga ~1.5GB de modelos de IA. Ningún dato sale de tu máquina. No requiere sudo.

<details><summary>¿Nuevo en la terminal? Haz clic aquí para instrucciones paso a paso.</summary>

1. **Abre una terminal:** Mac: `Cmd + Space`, escribe `Terminal`. Linux: `Ctrl + Alt + T`. Windows: abre PowerShell.
2. **Pega el comando de arriba** y presiona Enter.
3. **Espera 3-5 minutos** para que los modelos se descarguen.
4. **Cierra completamente tu herramienta de IA** y vuelve a abrirla (Mac: `Cmd+Q`).
5. **Escribe "Set up TrueMemory"** y elige un nivel.

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

</details>

Eso es todo. TrueMemory recuerda tus conversaciones automáticamente a partir de ahora.

### Para desarrolladores (biblioteca 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"))
```

---

## Niveles

Misma arquitectura, tres niveles. Todos incluidos en una sola instalación. Cambia en cualquier momento diciendo "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)** |
| **Modelo de embedding** | 8 MB ligero | 600 MB alta precisión | 600 MB alta precisión |
| **Reranker** | 22M parámetros | 149M parámetros | 149M parámetros |
| **Búsqueda HyDE** | — | — | ✅ (requiere clave API de LLM) |
| **Se ejecuta en** | Cualquier máquina, solo CPU | 4 GB+ RAM | 4 GB+ RAM + clave API |

**Edge** funciona en cualquier lugar. **Base** es el nivel más potente completamente sin conexión. **Pro** añade expansión de consultas impulsada por IA para las puntuaciones más altas.

---

## Benchmarks

<p align="center">
  <img src="../assets/charts/leaderboard-bar.png" alt="Tabla de clasificación de benchmarks" width="700" />
</p>

Probado en tres benchmarks principales con todos los sistemas compartiendo el mismo modelo de respuesta (GPT-4.1-mini), juez (GPT-4o-mini, votación por mayoría 3x) y pipeline de puntuación.

| Benchmark | Qué evalúa | TrueMemory Pro |
|-----------|--------------|:--------------:|
| [LoCoMo](https://github.com/snap-research/locomo) | 1,540 preguntas en 10 conversaciones | **93.0%** |
| [LongMemEval](https://github.com/xiaowu0162/LongMemEval) | 500 preguntas multi-sesión | **92.0%** |
| [BEAM-1M](https://github.com/mohammadtavakoli78/BEAM) | 700 preguntas con 1M+ tokens | **76.6% (SOTA)** |
| BEAM-10M | 200 preguntas con 10M tokens | **65.0%** |

### Reproduce cualquier resultado tú mismo

Cada script de benchmark es autónomo y se ejecuta en [Modal](https://modal.com).

- **[Scripts de LoCoMo](../benchmarks/locomo/scripts/)** — 8 sistemas (TrueMemory, Mem0, Zep, Engram, etc.)
- **[Resultados de LoCoMo](../benchmarks/locomo/BENCHMARK_RESULTS.md)** — desgloses por categoría, latencia, costo
- **[Config de evaluación LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md)** — modelos, prompts y parámetros exactos
- **[Scripts de LongMemEval](../benchmarks/longmemeval/)** — variantes oracle + strict
- **[Resultados de LongMemEval](../benchmarks/longmemeval/results/)** — 6 ejecuciones de TM Pro + 5 resultados de competidores
- **[Script BEAM-1M](../benchmarks/beam/bench_truememory_pro_beam1m.py)** — 35 conversaciones con 1M+ tokens
- **[Script BEAM-10M](../benchmarks/beam/bench_truememory_pro_beam10m.py)** — 10 conversaciones con 10M tokens
- **[Resultados de BEAM](../benchmarks/beam/)** — 3 ejecuciones (1M) + 1 ejecución (10M)

Todos los benchmarks usan el mismo pipeline de evaluación. Nada está oculto. Detalles completos: [LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md) | [LongMemEval](../benchmarks/longmemeval/README.md) | [BEAM](../benchmarks/beam/README.md)

---

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

Los hooks de ciclo de vida capturan conversaciones automáticamente. No se necesita trabajo manual. Tus recuerdos permanecen locales en un solo archivo 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étodo | Descripción |
|--------|-------------|
| `m.add(content, user_id)` | Almacenar un recuerdo |
| `m.search(query, user_id)` | Buscar (pipeline de 6 capas + reranker) |
| `m.search_deep(query, user_id)` | Búsqueda agéntica multi-ronda |
| `m.get(id)` / `m.get_all(user_id)` | Recuperar recuerdos |
| `m.update(id, content)` / `m.delete(id)` | Modificar o eliminar |
| `m.stats()` | Estadísticas del sistema |

[Referencia completa de la API →](../docs/python-api.md)

---

## Documentación

| | |
|---|---|
| [Primeros pasos](../docs/guides/getting-started.md) | De la instalación al primer recuerdo |
| [Referencia de Python API](../docs/python-api.md) | Referencia completa de la clase `Memory` |
| [Referencia de herramientas MCP](../docs/mcp-tools.md) | Las 8 herramientas MCP |
| [Referencia de CLI](../docs/cli.md) | `truememory-mcp` y `truememory-ingest` |
| [Variables de entorno](../docs/env-vars.md) | Todas las opciones de configuración `TRUEMEMORY_*` |
| [Arquitectura en profundidad](../docs/architecture.md) | Pipeline de recuperación de 6 capas, puerta de codificación |
| [Guía de selección de nivel](../docs/guides/tier-selection.md) | Edge vs Base vs Pro |
| [Depuración](../docs/guides/debugging.md) | Logs, trazas, problemas comunes |

---

## Preguntas frecuentes

<details><summary><strong>¿Dónde se almacenan mis datos? ¿Se envía algo a la nube?</strong></summary>

Todo vive localmente en `~/.truememory/memories.db`. Los niveles Edge y Base no realizan ninguna llamada externa. Pro solo envía el texto de tu consulta de búsqueda a un LLM para la expansión de consultas. Tus recuerdos nunca se transmiten.
</details>

<details><summary><strong>¿Necesito tener Python instalado?</strong></summary>

No. El instalador usa [uv](https://docs.astral.sh/uv/) para gestionar un Python 3.12 aislado. Tu Python del sistema nunca se toca.
</details>

<details><summary><strong>¿Por qué no usar simplemente una ventana de contexto más grande?</strong></summary>

Las ventanas de contexto son caras, lentas y están vacías al inicio de cada sesión. TrueMemory ofrece recuperación instantánea con cero tokens de contexto, en menos de 200ms.
</details>

<details><summary><strong>¿TrueMemory recopila telemetría?</strong></summary>

La telemetría de uso anónima (llamadas a herramientas, conteo de sesiones, información de plataforma) está activada por defecto. **Nunca** rastreamos contenido de memoria, consultas, rutas de archivos ni claves API. Desactivar: `export TRUEMEMORY_TELEMETRY=off`
</details>

---

## Empieza en 60 segundos

```bash
pip install truememory
```

¿Preguntas? [Abre una discusión](https://github.com/buildingjoshbetter/TrueMemory/discussions). Si TrueMemory te ahorra tiempo, [danos una estrella](https://github.com/buildingjoshbetter/TrueMemory)

---

## Gracias a nuestros colaboradores

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

---

## Investigación

TrueMemory está respaldado por un artículo de investigación revisado por pares sobre memoria de agentes centrada en la recuperación.

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

---

## Comunidad

- [Unete a nuestro Discord](https://discord.gg/ZJ74JB2gVW) para ayuda, comentarios y actualizaciones
- Sigue a [@Building_Josh](https://x.com/Building_Josh) en X para actualizaciones
- Sigue a [@Sauron_Labs](https://x.com/Sauron_Labs) para noticias de la empresa
- [Abre una discusión](https://github.com/buildingjoshbetter/TrueMemory/discussions) para preguntas o ideas
- Lee el artículo en [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)

Si TrueMemory te ahorra tiempo, [danos una estrella](https://github.com/buildingjoshbetter/TrueMemory)

---

## Licencia

[AGPL-3.0](../LICENSE). Gratis para uso personal e investigación. El uso comercial requiere una licencia separada. Contacta a josh@sauronlabs.ai.

---

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