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

<p align="center">
  <em>A memoria que sua IA deveria ter tido desde o inicio.</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-que-truememory">Por que</a> · <a href="#inicio-rapido">Inicio Rapido</a> · <a href="#como-truememory-se-compara">Comparacao</a> · <a href="#niveis">Niveis</a> · <a href="#benchmarks">Benchmarks</a> · <a href="#python-api">API</a> · <a href="#documentacao">Docs</a> · <a href="#perguntas-frequentes">FAQ</a>
</p>

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

---

## Por que TrueMemory

**Encontra o sinal no ruido.** Sua IA ve milhares de mensagens. O TrueMemory descobre quais realmente importam, e descarta o resto. Sem tags manuais, sem engenharia de prompts. Ele simplesmente sabe.

**Fica mais preciso com o tempo.** Nao e um banco de dados estatico. E uma memoria viva que cresce com voce, resolvendo contradicoes quando voce muda de ideia, atualizando fatos desatualizados e consolidando o que sabe. Quanto mais voce usa, melhor ele fica.

**Funciona sem voce pensar nisso.** O TrueMemory captura automaticamente memorias das suas conversas e injeta automaticamente as corretas na sua proxima sessao. Voce nunca precisa armazenar ou buscar nada manualmente. Simplesmente acontece.

**E 100% local.** Um unico arquivo SQLite na sua maquina. Nada sai do seu dispositivo. Sem nuvem, sem chaves de API necessarias. Seus dados sao seus.

> **Sem TrueMemory:** "Qual framework estamos usando?" Perguntado pela 12a vez nesta semana. Seu agente comeca cada sessao com amnesia. Ele nao sabe seu nome, sua stack, ou qualquer coisa que voce disse ontem.
>
> **Com TrueMemory:** Seu agente ja sabe que voce usa FastAPI, prefere Pydantic v2, e que seu auth middleware fica em `src/auth/`. Ele lembra suas correcoes, suas preferencias e suas decisoes. Em todas as sessoes, para sempre.

---

## Como TrueMemory se compara

| Sistema | LoCoMo | LongMemEval | Local-first | Captura automatica | Licenca |
|--------|--------|-------------|:-----------:|:------------:|---------|
| **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 os benchmarks sao reproduziveis de forma independente. Scripts incluidos em [`benchmarks/`](../benchmarks/).

---

## Inicio rapido

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

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

> Instala tudo em um ambiente isolado. Baixa ~1.5GB de modelos de IA. Nenhum dado sai da sua maquina. Nao precisa de sudo.

<details><summary>Novo no terminal? Clique aqui para instrucoes passo a passo.</summary>

1. **Abra um terminal:** Mac: `Cmd + Space`, digite `Terminal`. Linux: `Ctrl + Alt + T`. Windows: abra o PowerShell.
2. **Cole o comando acima** e pressione Enter.
3. **Aguarde 3-5 minutos** para o download dos modelos.
4. **Feche completamente sua ferramenta de IA** e reabra (Mac: `Cmd+Q`).
5. **Digite "Set up TrueMemory"** e escolha um nivel.

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

</details>

E so isso. O TrueMemory lembra suas conversas automaticamente a partir de agora.

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

---

## Niveis

Mesma arquitetura, tres niveis. Todos incluidos em uma unica instalacao. Troque a qualquer momento dizendo "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)** |
| **Modelo de embedding** | 8 MB leve | 600 MB alta precisao | 600 MB alta precisao |
| **Reranker** | 22M parametros | 149M parametros | 149M parametros |
| **Busca HyDE** | — | — | ✅ (requer chave de API LLM) |
| **Roda em** | Qualquer maquina, somente CPU | 4 GB+ RAM | 4 GB+ RAM + chave de API |

**Edge** funciona em qualquer lugar. **Base** e o nivel mais forte totalmente offline. **Pro** adiciona expansao de consulta com IA para as maiores pontuacoes.

---

## Benchmarks

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

Testado em tres grandes benchmarks com todos os sistemas compartilhando o mesmo modelo de resposta (GPT-4.1-mini), juiz (GPT-4o-mini, votacao por maioria 3x) e pipeline de pontuacao.

| Benchmark | O que testa | TrueMemory Pro |
|-----------|--------------|:--------------:|
| [LoCoMo](https://github.com/snap-research/locomo) | 1.540 perguntas em 10 conversas | **93.0%** |
| [LongMemEval](https://github.com/xiaowu0162/LongMemEval) | 500 perguntas multi-sessao | **92.0%** |
| [BEAM-1M](https://github.com/mohammadtavakoli78/BEAM) | 700 perguntas com 1M+ tokens | **76.6% (SOTA)** |
| BEAM-10M | 200 perguntas com 10M tokens | **65.0%** |

### Reproduza qualquer resultado voce mesmo

Cada script de benchmark e autocontido e roda no [Modal](https://modal.com).

- **[Scripts LoCoMo](../benchmarks/locomo/scripts/)** — 8 sistemas (TrueMemory, Mem0, Zep, Engram, etc.)
- **[Resultados LoCoMo](../benchmarks/locomo/BENCHMARK_RESULTS.md)** — detalhamentos por categoria, latencia, custo
- **[Config de Eval LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md)** — modelos, prompts e parametros exatos
- **[Scripts LongMemEval](../benchmarks/longmemeval/)** — variantes oracle + strict
- **[Resultados LongMemEval](../benchmarks/longmemeval/results/)** — 6 execucoes TM Pro + 5 resultados de concorrentes
- **[Script BEAM-1M](../benchmarks/beam/bench_truememory_pro_beam1m.py)** — 35 conversas com 1M+ tokens
- **[Script BEAM-10M](../benchmarks/beam/bench_truememory_pro_beam10m.py)** — 10 conversas com 10M tokens
- **[Resultados BEAM](../benchmarks/beam/)** — 3 execucoes (1M) + 1 execucao (10M)

Todos os benchmarks usam o mesmo pipeline de avaliacao. Nada esta oculto. Detalhes completos: [LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md) | [LongMemEval](../benchmarks/longmemeval/README.md) | [BEAM](../benchmarks/beam/README.md)

---

## Funciona com

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

Hooks de ciclo de vida capturam conversas automaticamente. Nenhum trabalho manual necessario. Suas memorias ficam locais em um unico arquivo 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 | Descricao |
|--------|-------------|
| `m.add(content, user_id)` | Armazenar uma memoria |
| `m.search(query, user_id)` | Buscar (pipeline de 6 camadas + reranker) |
| `m.search_deep(query, user_id)` | Busca agentica multi-rodada |
| `m.get(id)` / `m.get_all(user_id)` | Recuperar memorias |
| `m.update(id, content)` / `m.delete(id)` | Modificar ou remover |
| `m.stats()` | Estatisticas do sistema |

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

---

## Documentacao

| | |
|---|---|
| [Primeiros Passos](../docs/guides/getting-started.md) | Da instalacao ate a primeira memoria |
| [Referencia da API Python](../docs/python-api.md) | Referencia completa da classe `Memory` |
| [Referencia de Ferramentas MCP](../docs/mcp-tools.md) | Todas as 8 ferramentas MCP |
| [Referencia do CLI](../docs/cli.md) | `truememory-mcp` e `truememory-ingest` |
| [Variaveis de Ambiente](../docs/env-vars.md) | Todas as opcoes de config `TRUEMEMORY_*` |
| [Arquitetura em Profundidade](../docs/architecture.md) | Pipeline de recuperacao de 6 camadas, gate de codificacao |
| [Guia de Selecao de Nivel](../docs/guides/tier-selection.md) | Edge vs Base vs Pro |
| [Depuracao](../docs/guides/debugging.md) | Logs, traces, problemas comuns |

---

## Perguntas frequentes

<details><summary><strong>Onde meus dados sao armazenados? Algo e enviado para a nuvem?</strong></summary>

Tudo fica localmente em `~/.truememory/memories.db`. Os niveis Edge e Base fazem zero chamadas externas. O Pro envia apenas o texto da sua consulta de busca para um LLM para expansao de consulta. Suas memorias nunca sao transmitidas.
</details>

<details><summary><strong>Preciso ter Python instalado?</strong></summary>

Nao. O instalador usa [uv](https://docs.astral.sh/uv/) para gerenciar um Python 3.12 isolado. Seu Python do sistema nunca e tocado.
</details>

<details><summary><strong>Por que nao usar uma janela de contexto maior?</strong></summary>

Janelas de contexto sao caras, lentas e comecam vazias em cada sessao. O TrueMemory oferece recall instantaneo com zero tokens de contexto, em menos de 200ms.
</details>

<details><summary><strong>O TrueMemory coleta telemetria?</strong></summary>

Telemetria anonima de uso (chamadas de ferramentas, contagens de sessao, info da plataforma) esta ativada por padrao. Nos **nunca** rastreamos conteudo de memoria, consultas, caminhos de arquivo ou chaves de API. Para desativar: `export TRUEMEMORY_TELEMETRY=off`
</details>

---

## Comece em 60 segundos

```bash
pip install truememory
```

Duvidas? [Abra uma Discussao](https://github.com/buildingjoshbetter/TrueMemory/discussions). Se o TrueMemory economiza seu tempo, [nos de uma ⭐](https://github.com/buildingjoshbetter/TrueMemory)

---

## Agradecimentos aos nossos contribuidores

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

---

## Pesquisa

O TrueMemory e respaldado por um artigo de pesquisa revisado por pares sobre memoria de agente centrada em recuperacao.

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

---

## Comunidade

- [Entre no nosso Discord](https://discord.gg/ZJ74JB2gVW) para ajuda, feedback e atualizacoes
- Siga [@Building_Josh](https://x.com/Building_Josh) no X para atualizacoes
- Siga [@Sauron_Labs](https://x.com/Sauron_Labs) para noticias da empresa
- [Abra uma Discussao](https://github.com/buildingjoshbetter/TrueMemory/discussions) para perguntas ou ideias
- Leia o artigo no [arXiv](https://arxiv.org/abs/2605.04897) · [Google Scholar](https://scholar.google.com/citations?user=YOUR_ID) · [Semantic Scholar](https://www.semanticscholar.org/)
- Visite [truememory.net](https://truememory.net) · [sauronlabs.ai](https://sauronlabs.ai)

Se o TrueMemory economiza seu tempo, [nos de uma ⭐](https://github.com/buildingjoshbetter/TrueMemory)

---

## Licenca

[AGPL-3.0](../LICENSE). Gratuito para uso pessoal e de pesquisa. Uso comercial requer uma licenca separada. Entre em contato pelo josh@sauronlabs.ai.

---

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