<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` для точных терминов, сообщений об ошибках, имён функций
- **Гибридный поиск** — объединяет семантические + ключевые результаты с использованием слияния обратных рангов
- **Поддержка Cursor IDE** — индексация истории чатов Cursor из файлов `state.vscdb`
- **Отслеживание файлов в реальном времени** — новые сессии индексируются мгновенно через watchdog (перезапуск не нужен)
- **Стратегии разбиения** — выбор между токенным, пошаговым или рекурсивным разбиением
- **Расширение 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. Разделение** | Разговоры разбиваются с помощью токенных, пошаговых или рекурсивных стратегий |
| **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 для запуска хоста разработки расширений
```

## Разработка

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