memex-mvp 0.5.0

package/HELP.md

@@ -0,0 +1,308 @@
+# Memex — как пользоваться
+
+> **Кратко:** memex — твой локальный архив всех разговоров с AI. Сохраняет дословно. Любой AI-агент через MCP видит всю твою историю.
+
+Если ты только установил memex и не знаешь что делать — этот файл объясняет на конкретных кейсах. Скопируй промпт, вставь в свой AI (Claude Code, Cursor, Cline, Continue, Zed) — и попробуй.
+
+---
+
+## Что memex сохраняет
+
+- **Claude Code** — каждую сессию из `~/.claude/projects/`
+- **Claude Cowork** (включая субагентов) — сессии из `~/Library/Application Support/Claude/local-agent-mode-sessions/`
+- **Cursor** — composer history из `state.vscdb`
+- **Obsidian** — заметки из настроенных vault'ов
+- **Telegram** — экспорты которые ты сам положишь в `~/.memex/inbox/`
+
+Всё это лежит в **одном файле** `~/.memex/data/memex.db` и доступно через MCP-tools любому AI на твоём компьютере.
+
+---
+
+## Как memex реально работает — механика
+
+Когда ты задаёшь вопрос в Claude / Cursor / любом другом MCP-агенте, под капотом происходит **7 шагов**:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  Ты:  «Что я вчера обсуждал с Claude про auth?»                  │
+└──────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  1. Агент (LLM в Claude/Cursor) видит твой вопрос                │
+│     Думает: "Вопрос про прошлое → надо вызвать memex_search"     │
+└──────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  2. Агент через MCP вызывает memex_search(query="auth")          │
+└──────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  3. Memex выполняет FTS5-запрос к SQLite                         │
+│     (миллисекунды, читает только текст, никаких LLM)             │
+└──────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  4. Memex возвращает 5-10 сообщений с snippet'ами:               │
+│                                                                  │
+│     • claude-code · 2026-05-12 · "Решили JWT для auth..."        │
+│     • claude-code · 2026-05-12 · "...refresh tokens..."          │
+│     • cowork · 2026-05-11 · "Auth pattern для multi-tenant..."   │
+└──────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  5. Эти snippet'ы попадают в контекст агента как tool-result     │
+│     (становятся частью контекстного окна LLM ~ 200k токенов)     │
+└──────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  6. LLM (Claude) ЧИТАЕТ снэппеты + твой исходный вопрос          │
+│     Если мало — может вызвать memex_search ЕЩЁ РАЗ или           │
+│     memex_get_conversation для полного transcript'a              │
+└──────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  7. LLM формулирует ответ на твоём языке:                        │
+│                                                                  │
+│     «Вчера ты обсуждал JWT auth с refresh tokens, в Claude       │
+│      Code решил так-то, а в Cowork обсуждал multi-tenant         │
+│      аспекты. Вот точные цитаты: ...»                            │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### Кто что делает — главное
+
+| | **Memex** | **LLM (Claude/GPT/...)** |
+|---|---|---|
+| Тип работы | **Retrieval** (поиск) | **Reasoning** (рассуждение) |
+| Что умеет | Найти релевантные куски текста за миллисекунды через FTS5 | Понимать контекст, формулировать ответ на твоём языке |
+| Что НЕ умеет | Думать, суммаризовать, отвечать | Сам по себе вспоминать что было вчера |
+
+**Аналогия:** memex — как Google для твоего личного архива. LLM — как ты сам, читая результаты Google.
+
+### Куда попадают найденные куски
+
+Это **критически важно понять**: snippet'ы из memex попадают **в контекстное окно LLM** (тот же ~200k токенов где живёт твой текущий разговор). LLM видит их как обычный текст в своём контексте и может на них ссылаться, цитировать, переформулировать.
+
+Это **не RAG в классическом смысле** (где векторный поиск тащит из БД сверху промпта). Это **agentic retrieval**: LLM сам решает когда вызвать memex_search, и сам обрабатывает результаты как любой другой tool-call.
+
+### Что memex делает — а что нет
+
+✅ **Memex делает:**
+- Возвращает дословный текст (verbatim) — никаких пересказов
+- FTS5-поиск с recency boost (свежее → выше в выдаче)
+- Multi-source поиск (Claude + Cursor + TG + Obsidian в одном запросе)
+- Метаданные: source, date, conversation_id (для drill-down)
+
+❌ **Memex НЕ делает:**
+- Не суммаризует найденное
+- Не отвечает на вопросы напрямую
+- Не «думает» про связи между сообщениями
+- Не модифицирует найденный текст
+- Не использует embeddings (пока — FTS5 only, semantic в roadmap'е)
+
+### Что LLM делает с снэппетами
+
+- Читает их как обычный текст в контексте
+- Объединяет с твоим вопросом и формирует ответ
+- Может **уточнить поиск** — вызвать memex_search ещё раз с другим query
+- Может **drill down** — вызвать memex_get_conversation для полного transcript'a одного чата
+- Может **скомбинировать с другими тулзами** — например прочитать локальный PDF через свой file-read tool, и сцепить с контекстом из memex
+
+### Контекстное окно — где это всё живёт
+
+LLM имеет ограниченное контекстное окно (~200k токенов у Claude 4.7). Retrieved snippet'ы из memex занимают часть этого окна — поэтому есть параметры регулирования:
+
+- `expand_match: false` (default) → snippet'ы по 360 chars каждый, экономия токенов
+- `expand_match: true` → полный текст каждого сообщения
+- `group_by_conversation: true` (default) → один лучший hit на чат + count, не все совпадения
+- `limit: N` (default 10) → сколько результатов вернуть
+
+Эти параметры контролируют **сколько токенов** retrieved data занимает в твоём контексте.
+
+---
+
+## 6 типовых сценариев — что попросить агента
+
+### 1. 📋 Превратить рабочий Telegram-чат в action plan
+
+```
+Прочитай через memex_search мой последний месяц переписки с клиентом X
+в Telegram. Сделай чек-лист действий с приоритетами и список открытых
+вопросов на которые надо ответить.
+```
+
+→ Агент находит сообщения через `memex_search`, читает контекст, выдаёт структурированный план. Не нужно вручную перечитывать три месяца переписки.
+
+---
+
+### 2. 📊 Анализ pitch-deck'a из рабочего Telegram
+
+```
+Через memex_search найди в моём чате с маркетологом deck про Q2 launch
+(около двух месяцев назад) и всё обсуждение вокруг него. Открой сам файл
+(путь у memex в metadata) и сведи: 1) ключевые тезисы deck'a, 2) комментарии
+команды из чата, 3) открытые вопросы для следующей встречи.
+```
+
+→ memex даёт контекст разговора, агент читает PDF своими тулами, выдаёт синтез **deck + обсуждение** в одном.
+
+---
+
+### 3. 🌉 Один AI видит историю другого
+
+```
+Найди через memex_search что я вчера обсуждал с Claude про auth.
+Продолжай отсюда — не нужно объяснять заново.
+```
+
+→ Cursor через MCP читает Claude Code сессию. Контекст переходит между AI без повторных объяснений.
+
+---
+
+### 4. 🔍 Найти точную цитату из прошлого
+
+```
+В марте я что-то решал про pricing. Найди дословную формулировку
+в моих сессиях с AI.
+```
+
+→ `memex_search("pricing")` возвращает оригинальные сообщения — не пересказ, точную цитату с датой и из какой сессии.
+
+---
+
+### 5. 🔄 «Где я остановился в этом проекте?»
+
+```
+Возвращаюсь к проекту memex после двух недель. Через memex_list_projects
+и memex_recent покажи где я остановился. Что было сделано, что осталось?
+```
+
+→ Агент собирает картину из последних сессий по этому project_path.
+
+---
+
+### 6. 💡 Найти паттерны во всех AI-разговорах
+
+```
+Через memex_search найди все упоминания Postgres в моих сессиях с AI.
+В каком контексте? Что я решал? Какие проблемы всплывали?
+```
+
+→ Один запрос → агент видит все упоминания через все инструменты и сводит в темы.
+
+---
+
+### 7. 🕐 Timeline эволюции одного документа
+
+Memex по дефолту сортирует по **релевантности** (FTS5 BM25 × recency boost). Это хорошо для «найди что-то конкретное», но плохо для **«покажи как X менялось со временем»** — версии разлетаются хаотично.
+
+**Попроси агента явно отсортировать:**
+
+```
+Найди в memex все упоминания презентации Q2 launch — в моём Telegram-чате
+с маркетологом И в моих AI-сессиях. ОТСОРТИРУЙ результаты строго по дате
+создания (от самой свежей к самой старой). Покажи как deck менялся —
+какие версии были, что менялось между ними.
+```
+
+→ Memex вернёт hits, агент **переупорядочит их по `ts`** (это поле есть в каждом результате) и покажет chronological timeline. Если хитов слишком много в FTS-поиске — попроси `expand_match: true` и `limit: 20`, чтобы получить полные тексты.
+
+**Tip:** если уже видишь хаотичные результаты — просто скажи агенту в чате:
+
+```
+Эти результаты переотсортируй по дате — от свежей к старой.
+Каждый укажи с датой и source.
+```
+
+Агент возьмёт уже-полученные hits и пересортирует. **Дополнительный memex-вызов не нужен.**
+
+**Server-side sort:** `memex_search` принимает параметр `sort: "date_asc"` (от старых к новым — читать эволюцию) или `sort: "date_desc"` (последняя версия первой). FTS5 MATCH всё равно фильтрует кандидатов, меняется только порядок — recency boost отключается. Это правильнее, чем переcортировка на стороне агента, когда хитов много.
+
+---
+
+## Какие MCP-tools агент может вызвать
+
+| Tool | Что делает |
+|---|---|
+| `memex_overview` | Снэпшот корпуса: источники, сколько сообщений, последние чаты, статус auto-capture |
+| `memex_search(query)` | Полнотекстовый поиск (FTS5) с recency boost'ом. Параметры: `project`, `source`, `chat`, `half_life_days`, `expand_match`, `sort` |
+| `memex_list_projects` | Список всех проектов с количеством разговоров |
+| `memex_list_conversations` | Список чатов отсортированных по recency |
+| `memex_get_conversation(id)` | Полный transcript одного чата |
+| `memex_recent` | Последние N сообщений по всем источникам |
+| `memex_archive_conversation(id)` | Скрыть чат из дефолтных списков (не удаляет) |
+| `memex_export_markdown` | Экспорт чата в Markdown (для Obsidian) |
+| `memex_list_sources` | Что и сколько импортировано |
+| `memex_status` | Здоровье memex-sync daemon'a |
+| `memex_sources_status` | Какие источники включены/отключены |
+
+---
+
+## Если что-то не работает
+
+### Поиск пустой
+
+1. Вызови `memex_overview`. Внимание на статус-баннер сверху:
+   - 🟢 daemon работает — всё ок, может ещё не успел проиндексировать
+   - 🔴 daemon установлен но не работает — `launchctl load ~/Library/LaunchAgents/com.parallelclaw.memex.sync.plist`
+   - ⚪ daemon не установлен — `npx memex-sync install` из директории memex-mvp
+
+### Хочу проиндексировать существующие сессии (бэкфилл)
+
+```bash
+npx memex-sync scan
+```
+
+Обходит `~/.claude/projects/`, Cowork-сессии, Cursor state.vscdb, и Obsidian-vault'ы один раз — ингестит всё что уже есть на диске.
+
+### Telegram-чаты не появляются
+
+1. В Telegram **Desktop** (не mobile!): чат → меню → **Export chat history** → **Format: JSON**
+2. Кинь `result.json` в `~/.memex/inbox/`
+3. Memex подхватит автоматически за ~1.5 сек
+
+### Хочу подключить новый Obsidian-vault
+
+```bash
+npx memex-sync vault add ~/path/to/vault
+```
+
+### Я в Cursor, memex не видит мои Claude Code сессии
+
+`memex_overview` покажет что захватывается. Если Claude Code не в списке источников — проверь что `~/.claude/projects/` существует на твоей машине и не пустая. Затем `npx memex-sync scan-claude` для одноразового ингеста.
+
+### Хочу удалить какой-то чат
+
+```bash
+# Скрыть из дефолтных списков (рекомендуется)
+memex_archive_conversation(conversation_id="tg-...")
+
+# Или полностью удалить через sqlite
+sqlite3 ~/.memex/data/memex.db "DELETE FROM messages WHERE conversation_id = '...'"
+```
+
+---
+
+## Где живёт твоя память
+
+- **`~/.memex/data/memex.db`** — твой SQLite-архив. Это main файл. Бэкап через `cp`.
+- **`~/.memex/inbox/`** — куда дроп'ать Telegram-экспорты или другие JSON для импорта
+- **`~/.memex/staging/`** — внутренняя кухня daemon'a, **не трогай**
+- **`~/.memex/data/conversations/`** — импортированные файлы переезжают сюда после успешного парсинга
+- **`~/.memex/data/ingest.log`** — лог daemon'a (`tail -f` чтобы смотреть в реальном времени)
+- **`~/.memex/config.json`** — конфиг (какие источники включены)
+
+---
+
+## Ничего не помогает?
+
+- Issues / баги: https://github.com/parallelclaw/memex-mvp/issues
+- README с архитектурой: https://github.com/parallelclaw/memex-mvp#readme
+- Лендинг с use cases: https://memex.parallelclaw.ai

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 parallelclaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.