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

<p align="center">
  <em>Пам'ять, яку ваш ШІ мав би мати від самого початку.</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="#чому-truememory">Чому</a> · <a href="#швидкий-старт">Швидкий старт</a> · <a href="#як-truememory-порівнюється-з-іншими">Порівняння</a> · <a href="#рівні">Рівні</a> · <a href="#бенчмарки">Бенчмарки</a> · <a href="#python-api">API</a> · <a href="#документація">Документація</a> · <a href="#faq">FAQ</a>
</p>

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

---

## Чому TrueMemory

**Він знаходить сигнал серед шуму.** Ваш ШІ бачить тисячі повідомлень. TrueMemory визначає, які з них дійсно важливі, і відкидає решту. Без ручного тегування, без prompt engineering. Він просто знає.

**Він стає розумнішим з часом.** Це не статична база даних. Це жива пам'ять, яка зростає разом з вами. Розв'язує суперечності, коли ви змінюєте думку, оновлює застарілі факти та консолідує те, що знає. Чим довше ви користуєтесь, тим краще він працює.

**Він працює без вашої участі.** TrueMemory автоматично захоплює спогади з ваших розмов і автоматично додає потрібні до наступної сесії. Вам ніколи не потрібно вручну щось зберігати чи шукати. Це просто відбувається.

**Він на 100% локальний.** Один файл SQLite на вашому комп'ютері. Нічого не виходить за межі вашого пристрою. Без хмари, без потреби у API-ключах. Ваші дані належать вам.

> **Без TrueMemory:** "Який фреймворк ми використовуємо?" Запитано вже 12-й раз цього тижня. Ваш агент починає кожну сесію з амнезією. Він не знає вашого імені, вашого стеку чи будь-чого, що ви йому вчора казали.
>
> **З TrueMemory:** Ваш агент вже знає, що ви використовуєте FastAPI, надаєте перевагу Pydantic v2, і що ваш auth middleware знаходиться в `src/auth/`. Він пам'ятає ваші виправлення, вподобання та рішення. У кожній сесії, назавжди.

---

## Як TrueMemory порівнюється з іншими

| Система | LoCoMo | LongMemEval | Локальна | Автозахоплення | Ліцензія |
|--------|--------|-------------|:-----------:|:------------:|---------|
| **TrueMemory Pro** | **93.0%** | **92.0%** | ✅ | ✅ | AGPL-3.0 |
| **TrueMemory Base** | **87.7%** | **84.1%** | ✅ | ✅ | AGPL-3.0 |
| Mem0 | 61.4% | — | Частково | ❌ | Apache-2.0 |
| Supermemory | 65.4% | — | ❌ | ❌ | Cloud API |
| MemOS | 75.8% | — | ✅ | ❌ | Apache-2.0 |
| ReadAgent | 79.5% | — | ❌ | ❌ | Research |

> Усі бенчмарки можна незалежно відтворити. Скрипти включено в [`benchmarks/`](../benchmarks/).

---

## Швидкий старт

### Для Claude Code / Claude CLI / Cursor / Codex CLI / Gemini CLI

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

> Встановлює все в ізольованому середовищі. Завантажує ~1,5 ГБ моделей ШІ. Жодні дані не залишають ваш комп'ютер. Не потребує sudo.

<details><summary>Новачок у терміналі? Натисніть тут для покрокових інструкцій.</summary>

1. **Відкрийте термінал:** Mac: `Cmd + Space`, введіть `Terminal`. Linux: `Ctrl + Alt + T`. Windows: відкрийте PowerShell.
2. **Вставте команду вище** та натисніть Enter.
3. **Зачекайте 3-5 хвилин** на завантаження моделей.
4. **Повністю закрийте ваш інструмент ШІ** та відкрийте його знову (Mac: `Cmd+Q`).
5. **Введіть "Set up TrueMemory"** та оберіть рівень.

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

</details>

Це все. TrueMemory автоматично запам'ятовує ваші розмови відтепер.

### Для розробників (бібліотека 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"))
```

---

## Рівні

Та сама архітектура, три рівні. Усі включені в одну інсталяцію. Перемикайте будь-коли, сказавши "switch to Pro" або "switch to Base".

| | Edge | Base | Pro |
|---|------|------|-----|
| **LoCoMo** | 89.6% | 92.0% | **93.0%** |
| **LongMemEval** | — | — | **92.0%** |
| **BEAM-1M** | — | — | **76.6% (SOTA)** |
| **Модель Embedding** | 8 МБ легка | 600 МБ висока точність | 600 МБ висока точність |
| **Reranker** | 22M параметрів | 149M параметрів | 149M параметрів |
| **HyDE search** | — | — | ✅ (потрібен LLM API key) |
| **Працює на** | Будь-якому комп'ютері, лише CPU | 4 ГБ+ RAM | 4 ГБ+ RAM + API key |

**Edge** працює скрізь. **Base** це найпотужніший повністю офлайновий рівень. **Pro** додає розширення запитів на базі ШІ для найвищих результатів.

---

## Бенчмарки

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

Протестовано на трьох основних бенчмарках, де всі системи використовують одну й ту саму модель відповідей (GPT-4.1-mini), суддю (GPT-4o-mini, мажоритарне голосування 3x) та конвеєр оцінювання.

| Бенчмарк | Що тестує | TrueMemory Pro |
|-----------|--------------|:--------------:|
| [LoCoMo](https://github.com/snap-research/locomo) | 1 540 запитань з 10 розмов | **93.0%** |
| [LongMemEval](https://github.com/xiaowu0162/LongMemEval) | 500 багатосесійних запитань | **92.0%** |
| [BEAM-1M](https://github.com/mohammadtavakoli78/BEAM) | 700 запитань при 1M+ токенів | **76.6% (SOTA)** |
| BEAM-10M | 200 запитань при 10M токенів | **65.0%** |

### Відтворіть будь-який результат самостійно

Кожен скрипт бенчмарку є самодостатнім і працює на [Modal](https://modal.com).

- **[Скрипти LoCoMo](../benchmarks/locomo/scripts/)** — 8 систем (TrueMemory, Mem0, Zep, Engram тощо)
- **[Результати LoCoMo](../benchmarks/locomo/BENCHMARK_RESULTS.md)** — розбивка за категоріями, затримки, вартість
- **[Конфігурація оцінювання LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md)** — точні моделі, промпти, параметри
- **[Скрипти LongMemEval](../benchmarks/longmemeval/)** — варіанти oracle + strict
- **[Результати LongMemEval](../benchmarks/longmemeval/results/)** — 6 запусків TM Pro + 5 результатів конкурентів
- **[Скрипт BEAM-1M](../benchmarks/beam/bench_truememory_pro_beam1m.py)** — 35 розмов при 1M+ токенів
- **[Скрипт BEAM-10M](../benchmarks/beam/bench_truememory_pro_beam10m.py)** — 10 розмов при 10M токенів
- **[Результати BEAM](../benchmarks/beam/)** — 3 запуски (1M) + 1 запуск (10M)

Усі бенчмарки використовують однаковий конвеєр оцінювання. Нічого не приховано. Повні деталі: [LoCoMo](../benchmarks/locomo/EVAL_CONFIG.md) | [LongMemEval](../benchmarks/longmemeval/README.md) | [BEAM](../benchmarks/beam/README.md)

---

## Сумісність

<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 автоматично захоплюють розмови. Жодної ручної роботи. Ваші спогади залишаються локально в одному файлі 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")  # багаторундовий, вища точність
```

| Метод | Опис |
|--------|-------------|
| `m.add(content, user_id)` | Зберегти спогад |
| `m.search(query, user_id)` | Пошук (6-шаровий конвеєр + reranker) |
| `m.search_deep(query, user_id)` | Багаторундовий агентний пошук |
| `m.get(id)` / `m.get_all(user_id)` | Отримати спогади |
| `m.update(id, content)` / `m.delete(id)` | Змінити або видалити |
| `m.stats()` | Статистика системи |

[Повна довідка API ->](../docs/python-api.md)

---

## Документація

| | |
|---|---|
| [Початок роботи](../docs/guides/getting-started.md) | Від встановлення до першого спогаду |
| [Довідка Python API](../docs/python-api.md) | Повна довідка класу `Memory` |
| [Довідка інструментів MCP](../docs/mcp-tools.md) | Усі 8 інструментів MCP |
| [Довідка CLI](../docs/cli.md) | `truememory-mcp` та `truememory-ingest` |
| [Змінні середовища](../docs/env-vars.md) | Усі параметри конфігурації `TRUEMEMORY_*` |
| [Архітектура: глибоке занурення](../docs/architecture.md) | 6-шаровий конвеєр пошуку, encoding gate |
| [Посібник з вибору рівня](../docs/guides/tier-selection.md) | Edge vs Base vs Pro |
| [Налагодження](../docs/guides/debugging.md) | Логи, трасування, типові проблеми |

---

## FAQ

<details><summary><strong>Де зберігаються мої дані? Чи надсилається щось у хмару?</strong></summary>

Все зберігається локально у `~/.truememory/memories.db`. Рівні Edge та Base не здійснюють жодних зовнішніх викликів. Pro надсилає лише текст вашого пошукового запиту до LLM для розширення запиту. Ваші спогади ніколи не передаються.
</details>

<details><summary><strong>Чи потрібен мені встановлений Python?</strong></summary>

Ні. Інсталятор використовує [uv](https://docs.astral.sh/uv/) для керування ізольованим Python 3.12. Ваш системний Python залишається недоторканним.
</details>

<details><summary><strong>Чому б просто не використати більше контекстне вікно?</strong></summary>

Контекстні вікна дорогі, повільні та порожні на початку кожної сесії. TrueMemory забезпечує миттєве пригадування при нульовій кількості токенів контексту, менш ніж за 200мс.
</details>

<details><summary><strong>Чи збирає TrueMemory телеметрію?</strong></summary>

Анонімна телеметрія використання (виклики інструментів, кількість сесій, інформація про платформу) увімкнена за замовчуванням. Ми **ніколи** не відстежуємо вміст спогадів, запити, шляхи до файлів або API-ключі. Відмова: `export TRUEMEMORY_TELEMETRY=off`
</details>

---

## Почніть за 60 секунд

```bash
pip install truememory
```

Маєте запитання? [Відкрийте обговорення](https://github.com/buildingjoshbetter/TrueMemory/discussions). Якщо TrueMemory економить ваш час, [поставте нам зірку](https://github.com/buildingjoshbetter/TrueMemory)

---

## Подяка нашим контриб'юторам

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

---

## Дослідження

TrueMemory підкріплений рецензованою науковою роботою про пам'ять агентів, орієнтовану на пошук.

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

---

## Спільнота

- [Приєднуйтесь до нашого Discord](https://discord.gg/ZJ74JB2gVW) для допомоги, зворотного зв'язку та оновлень
- Слідкуйте за [@Building_Josh](https://x.com/Building_Josh) у X для оновлень
- Слідкуйте за [@Sauron_Labs](https://x.com/Sauron_Labs) для новин компанії
- [Відкрийте обговорення](https://github.com/buildingjoshbetter/TrueMemory/discussions) для запитань або ідей
- Прочитайте статтю на [arXiv](https://arxiv.org/abs/2605.04897) · [Google Scholar](https://scholar.google.com/citations?user=YOUR_ID) · [Semantic Scholar](https://www.semanticscholar.org/)
- Відвідайте [truememory.net](https://truememory.net) · [sauronlabs.ai](https://sauronlabs.ai)

Якщо TrueMemory економить ваш час, [поставте нам зірку](https://github.com/buildingjoshbetter/TrueMemory)

---

## Ліцензія

[AGPL-3.0](../LICENSE). Безкоштовно для особистого та дослідницького використання. Комерційне використання потребує окремої ліцензії. Зверніться на josh@sauronlabs.ai.

---

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