<div align="center">

# MemoTrail

> 🌐 Це автоматичний переклад. Виправлення від спільноти вітаються! · [English](../../README.md)

[🇨🇳 中文](README.zh-CN.md) · [🇹🇼 繁體中文](README.zh-TW.md) · [🇯🇵 日本語](README.ja.md) · [🇵🇹 Português](README.pt.md) · [🇰🇷 한국어](README.ko.md) · [🇪🇸 Español](README.es.md) · [🇩🇪 Deutsch](README.de.md) · [🇫🇷 Français](README.fr.md) · [🇮🇱 עברית](README.he.md) · [🇸🇦 العربية](README.ar.md) · [🇷🇺 Русский](README.ru.md) · [🇵🇱 Polski](README.pl.md) · [🇨🇿 Čeština](README.cs.md) · [🇳🇱 Nederlands](README.nl.md) · [🇹🇷 Türkçe](README.tr.md) · [🇺🇦 Українська](README.uk.md) · [🇻🇳 Tiếng Việt](README.vi.md) · [🇮🇩 Indonesia](README.id.md) · [🇹🇭 ไทย](README.th.md) · [🇮🇳 हिन्दी](README.hi.md) · [🇧🇩 বাংলা](README.bn.md) · [🇵🇰 اردو](README.ur.md) · [🇷🇴 Română](README.ro.md) · [🇸🇪 Svenska](README.sv.md) · [🇮🇹 Italiano](README.it.md) · [🇬🇷 Ελληνικά](README.el.md) · [🇭🇺 Magyar](README.hu.md) · [🇫🇮 Suomi](README.fi.md) · [🇩🇰 Dansk](README.da.md) · [🇳🇴 Norsk](README.no.md)

**Ваш AI-асистент для коду забуває все. MemoTrail вирішує цю проблему.**

[![PyPI version](https://img.shields.io/pypi/v/memotrail?color=blue)](https://pypi.org/project/memotrail/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](../../LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/HalilHopa-Datatent/memotrail?style=social)](https://github.com/HalilHopa-Datatent/memotrail)

Постійний шар пам'яті для AI-асистентів коду.
Кожна сесія записана, кожне рішення доступне для пошуку, кожен контекст збережений.

[Швидкий Старт](#швидкий-старт) · [Як це Працює](#як-це-працює) · [Доступні Інструменти](#доступні-інструменти) · [Дорожня Карта](#дорожня-карта)

</div>

---

## Що нового в v0.3.0

- **Автоматичне резюмування сесій** — кожна сесія отримує AI-згенероване резюме (API-ключі не потрібні)
- **Автоматичне вилучення рішень** — архітектурні рішення виявляються з розмов за допомогою пошуку за шаблонами
- **BM25 пошук за ключовими словами** — новий інструмент `search_keyword` для точних термінів, повідомлень про помилки, назв функцій
- **Гібридний пошук** — поєднує семантичний + пошук за ключовими словами за допомогою reciprocal rank fusion
- **Підтримка Cursor IDE** — індексує історію чату Cursor з файлів `state.vscdb`
- **Відстеження файлів у реальному часі** — нові сесії індексуються миттєво через watchdog (перезапуск не потрібен)
- **Стратегії поділу** — вибір між token-based, turn-based або рекурсивним розбиттям
- **Розширення VS Code** — пошук, індексація та перегляд статистики безпосередньо з VS Code
- **69 тестів** — всебічне покриття тестами всіх модулів

## Проблема

Кожна нова сесія Claude Code починається з нуля. Ваш AI не пам'ятає вчорашню 3-годинну сесію налагодження, архітектурні рішення минулого тижня чи підходи, які вже не спрацювали.

**Без MemoTrail:**
```
Ви: "Давайте використаємо Redis для кешування"
AI:  "Звісно, налаштуємо Redis"
         ... через 2 тижні, нова сесія ...
Ви: "Чому ми використовуємо Redis?"
AI:  "У мене немає контексту щодо цього рішення"
```

**З MemoTrail:**
```
Ви: "Чому ми використовуємо Redis?"
AI:  "На основі сесії від 15 січня — ви порівнювали Redis та Memcached.
      Redis було обрано за підтримку структур даних та персистентність.
      Обговорення в сесії #42."
```

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

```bash
# 1. Встановити
pip install memotrail

# 2. Підключити до Claude Code
claude mcp add memotrail -- memotrail serve
```

Ось і все. MemoTrail автоматично індексує вашу історію при першому запуску.
Почніть нову сесію і запитайте: *"Над чим ми працювали минулого тижня?"*


<div align="center">
<img src="../../demo.gif" alt="MemoTrail Demo" width="800">
<br>
<sub>Install → Connect → See stats → Search past sessions → Save memory → Duplicate &amp; contradiction detection</sub>
</div>

## Як це Працює

| Крок | Що відбувається |
|:----:|:-------------|
| **1. Запис** | MemoTrail автоматично індексує нові сесії при запуску + відстежує нові файли в реальному часі |
| **2. Поділ** | Розмови розбиваються за допомогою стратегій token, turn-based або recursive |
| **3. Вбудовування** | Кожен фрагмент вбудовується за допомогою `all-MiniLM-L6-v2` (~80МБ, працює на CPU) |
| **4. Вилучення** | Резюме та архітектурні рішення автоматично вилучаються |
| **5. Зберігання** | Вектори йдуть у ChromaDB, метадані в SQLite — все в `~/.memotrail/` |
| **6. Пошук** | Семантичний + BM25 пошук за ключовими словами по всій вашій історії |
| **7. Відображення** | Найбільш релевантний минулий контекст з'являється саме тоді, коли потрібен |

> **100% локально** — без хмари, без API-ключів, дані не покидають вашу машину.
>
> **Мультиплатформність** — підтримує Claude Code та Cursor IDE, інші незабаром.

## Доступні Інструменти

Після підключення Claude Code отримує ці MCP-інструменти:

| Інструмент | Опис |
|------|-------------|
| `search_chats` | Семантичний пошук по всіх минулих розмовах |
| `search_keyword` | BM25 пошук за ключовими словами — чудово підходить для точних термінів, назв функцій, повідомлень про помилки |
| `get_decisions` | Отримання записаних архітектурних рішень (автоматично вилучені + ручні) |
| `get_recent_sessions` | Список нещодавніх сесій з AI-згенерованими резюме |
| `get_session_detail` | Детальний перегляд вмісту конкретної сесії |
| `save_memory` | Ручне збереження важливих фактів або рішень |
| `memory_stats` | Перегляд статистики індексації та використання сховища |

## CLI-команди

```bash
memotrail serve                          # Запустити MCP-сервер (автоіндексація нових сесій)
memotrail search "redis caching decision"  # Пошук з терміналу
memotrail stats                          # Перегляд статистики індексації
memotrail index                          # Ручна переіндексація (опціонально)
```

## Архітектура

```
~/.memotrail/
├── chroma/          # Векторні ембедінги (ChromaDB)
└── memotrail.db     # Метадані сесій (SQLite)
```

| Компонент | Технологія | Деталі |
|-----------|-----------|---------|
| Ембедінги | `all-MiniLM-L6-v2` | ~80МБ, працює на CPU |
| Векторна БД | ChromaDB | Постійне локальне сховище |
| Пошук за ключовими словами | BM25 | Чистий Python, без додаткових залежностей |
| Метадані | SQLite | Однофайлова база даних |
| Відстеження файлів | watchdog | Виявлення сесій у реальному часі |
| Протокол | MCP | Model Context Protocol |

### Підтримувані платформи

| Платформа | Статус | Формат |
|-----------|--------|--------|
| Claude Code | Підтримується | JSONL файли сесій |
| Cursor IDE | Підтримується | state.vscdb (SQLite) |
| GitHub Copilot | Заплановано | — |

### Стратегії поділу

| Стратегія | Найкраще для |
|-----------|-------------|
| `token` (за замовчуванням) | Загальне використання — групує повідомлення до ліміту токенів |
| `turn` | Орієнтований на розмову — групує пари користувач+асистент |
| `recursive` | Довгий контент — розбиває за абзацами, реченнями, словами |

## Чому MemoTrail?

| | MemoTrail | CLAUDE.md / Файли правил | Ручні нотатки |
|---|---|---|---|
| Автоматично | Так — індексує при кожному старті сесії | Ні — ви пишете самі | Ні |
| Пошук | Семантичний пошук | AI читає, але тільки те, що ви написали | Тільки Ctrl+F |
| Масштаб | Тисячі сесій | Один файл | Розкидані файли |
| Контекст | Повертає релевантний контекст | Статичні правила | Ручний пошук |
| Налаштування | 5 хвилин | Постійне обслуговування | Постійне обслуговування |

MemoTrail не замінює `CLAUDE.md` — він доповнює його. Файли правил для інструкцій. MemoTrail для пам'яті.

## Дорожня Карта

- [x] Індексація сесій Claude Code
- [x] Семантичний пошук між розмовами
- [x] MCP-сервер з 7 інструментами
- [x] CLI для індексації та пошуку
- [x] Автоіндексація при запуску сервера
- [x] Автоматичне вилучення рішень
- [x] Резюмування сесій
- [x] Колектор Cursor IDE
- [x] BM25 пошук за ключовими словами + гібридний пошук
- [x] Відстеження файлів у реальному часі (watchdog)
- [x] Різні стратегії поділу (token, turn, recursive)
- [x] Розширення VS Code
- [ ] Колектор Copilot
- [ ] Хмарна синхронізація (Pro)
- [ ] Командна пам'ять (Team)

## Розширення VS Code

MemoTrail включає розширення VS Code для прямої інтеграції з IDE.

**Доступні команди:**
- `MemoTrail: Search Conversations` — семантичний пошук
- `MemoTrail: Keyword Search` — BM25 пошук за ключовими словами
- `MemoTrail: Recent Sessions` — перегляд статистики сесій
- `MemoTrail: Index Sessions Now` — запуск ручної індексації
- `MemoTrail: Show Stats` — відображення статистики індексації

**Налаштування:**
```bash
cd vscode-extension
npm install
npm run compile
# Потім натисніть F5 у VS Code для запуску Extension Development Host
```

## Розробка

```bash
git clone https://github.com/HalilHopa-Datatent/memotrail.git
cd memotrail
pip install -e ".[dev]"
pytest
ruff check src/
```

## Внесок

Внески вітаються! Див. [CONTRIBUTING.md](../../docs/CONTRIBUTING.md) для рекомендацій.

## Ліцензія

MIT — див. [LICENSE](../../LICENSE)

---

<div align="center">

**Створено [Halil Hopa](https://halilhopa.com)** · [memotrail.ai](https://memotrail.ai)

Якщо MemoTrail допомагає вам, поставте зірку на GitHub.

</div>
