parallelclaw 1.0.0

package/HELP.md

@@ -0,0 +1,600 @@
+# ParallelClaw — как пользоваться
+
+> **Кратко:** ParallelClaw — твой локальный архив всех разговоров с AI (CLI-команда — `memex`). Сохраняет дословно. Любой AI-агент через MCP видит всю твою историю.
+
+Если ты только установил memex и не знаешь что делать — этот файл объясняет на конкретных кейсах. Скопируй промпт, вставь в свой AI (Claude Code, Cursor, OpenClaw) — и попробуй.
+
+---
+
+## Что memex сохраняет
+
+- **Claude Code** — каждую сессию из `~/.claude/projects/`
+- **Claude Cowork** (включая субагентов) — сессии из `~/Library/Application Support/Claude/local-agent-mode-sessions/`
+- **Cursor** — composer history из `state.vscdb`
+- **Obsidian** — заметки из настроенных vault'ов
+- **Telegram** — v0.10+: daemon сам ловит экспорты из `~/Downloads/Telegram Desktop/` → пакует в pending → ты per-chat подтверждаешь импорт (`memex telegram pending` + `memex telegram import 1 3 5`). Никакого ручного копирования
+
+Всё это лежит в **одном файле** `~/.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ортировка на стороне агента, когда хитов много.
+
+---
+
+### 8. 🔗 Сохранение URL'ов в memex (Perplexity, статьи, AI-share'ы)
+
+Ты читаешь что-то — Perplexity research thread, длинную статью, GitHub-обсуждение, AI-chat share — и хочешь чтобы это жило в memex-памяти, искалось из любого AI-чата.
+
+**В любом MCP-агенте (Claude Code, Cursor, OpenClaw):**
+
+```
+Сохрани https://perplexity.ai/share/<id> в memex
+Добавь эту статью в memex: https://example.com/great-post
+Захвати этот ChatGPT-разговор: https://chat.openai.com/share/<id>
+```
+
+**Что происходит за кулисами:**
+
+1. Агент сам делает fetch URL'a (через свой WebFetch)
+2. Если страница защищена Cloudflare (Perplexity, npm.com, Twitter, Medium…) — агент авто-retry через `r.jina.ai` proxy (бесплатный JS-runtime, обходит Cloudflare). **Точный recipe** (зафиксирован эмпирически на реальных Cloudflare-страницах в 2026-05):
+   ```bash
+   curl -H "Accept: text/markdown" https://r.jina.ai/https://<original-url>
+   ```
+   Критично: **`https://` после `r.jina.ai/`** (НЕ `http://`, НЕ голый домен), **`Accept: text/markdown`** header (иначе возвращается HTML или mixed-формат). Если WebFetch агента не умеет задавать headers — shell out на curl с `-H`.
+3. Агент вызывает `memex_store_document(content, url, title)`
+4. Memex сохраняет содержимое как conversation с `source: "web"` — ищется через `memex_search` рядом с AI-чатами
+
+**Для Perplexity-thread'ов:** thread должен быть **PUBLIC**. В Perplexity: открой thread → Share → toggle "Public link" → скопируй новый URL → дай его агенту. URL из адресной строки браузера (`perplexity.ai/search/<id>`) — это **твой owner-URL, не shareable**.
+
+Если забудешь — memex детектит «private» в ответе и agent тебе явно скажет что делать.
+
+**Login-walled или paywalled контент не fetch'нется** (NYT subscription, твои приватные ChatGPT-чаты). Для них вставь контент руками:
+
+```
+Сохрани этот текст в memex (название: "..."): <вставь содержимое>
+```
+
+**Tag'и при сохранении** — для последующей фильтрации:
+
+```
+Сохрани https://... в memex, поставь теги "research" и "perplexity"
+```
+
+**Поиск:**
+
+```
+Найди в memex что Perplexity говорил про X на прошлой неделе
+```
+
+`memex_search` возвращает совпадения **и из AI-чатов, и из сохранённых URL'ов** в одном запросе — отсортировано по релевантности или дате.
+
+**Memex принципиально НЕ делает outbound network calls.** Fetcher живёт в твоём AI-агенте. Если он использует Jina для обхода Cloudflare — Jina видит URL (но НЕ остальной memex-корпус). Это выбор агента, не memex'a.
+
+---
+
+## Какие MCP-tools агент может вызвать
+
+| Tool | Что делает |
+|---|---|
+| `memex_overview` | Снэпшот корпуса: источники, сколько сообщений, последние чаты, статус auto-capture |
+| `memex_search(query)` | Полнотекстовый поиск (FTS5) с recency boost'ом. Параметры: `project`, `source`, `chat`, `conversation_id` (поиск ВНУТРИ одной сессии), `since_ts`/`until_ts` (фильтр по диапазону дат), `origin` (v0.14 — с какого УЗЛА захвачено: "vps1", "macbook-pro"), `half_life_days`, `expand_match`, `sort` |
+| `memex_store_document(content, url?, title?)` | Сохранить внешний документ (web-страница, AI-chat share, paste) в memex. Агент сам делает fetch, memex хранит verbatim. Учит Jina-трюк для Cloudflare-страниц |
+| `memex_list_projects` | Список всех проектов с количеством разговоров |
+| `memex_list_conversations` | Список чатов отсортированных по recency |
+| `memex_get_conversation(id)` | Transcript одного чата. Параметры: `limit`, `offset` (листать длинные сессии), `order` (`asc`=старые/`desc`=свежие первыми), `include_subagents`. Вывод сообщает `total` — сколько всего сообщений |
+| `memex_recent` | Последние N сообщений по всем источникам |
+| `memex_archive_conversation(id)` | Скрыть чат из дефолтных списков (не удаляет) |
+| `memex_export_markdown` | Экспорт чата в Markdown (для Obsidian) |
+| `memex_list_sources` | Что и сколько импортировано |
+| `memex_status` | Здоровье memex-sync daemon'a |
+| `memex_sources_status` | Какие источники включены/отключены |
+| `memex_telegram_check` *(v0.10+)* | Состояние Telegram-pipeline: Desktop установлен? login age? сколько pending? Возвращает `next_step` для агента |
+| `memex_telegram_pending` *(v0.10+)* | Список экспортов в `~/.memex/pending/` с chat name + msg count + дата range |
+| `memex_telegram_import` *(v0.10+)* | Импорт выбранных экспортов в memex.db (по индексу или title). Auto-allowlist |
+| `memex_telegram_skip` *(v0.10+)* | Пометить чаты как «не индексировать» — применяется к будущим re-export'ам |
+| `memex_telegram_mode` *(v0.10+)* | Get/set режим: `pick` (default), `auto`, `manual` |
+
+---
+
+## 🔎 Рецепты поиска для агентов (как доставать память эффективно)
+
+Частые задачи и точный способ их решить — особенно для длинных сессий и узких запросов:
+
+| Задача | Как сделать |
+|---|---|
+| **Тема за конкретный период** («что обсуждали про X в июне») | `memex_search(query, since_ts, until_ts)`. Это фильтр по датам — в отличие от `sort` (только порядок) и `half_life_days` (только буст). |
+| **Ключевое слово внутри одной большой сессии** | `memex_search(query, conversation_id=<id>)` — точный скоуп в один чат (а не нечёткий `chat` по названию). |
+| **Самые свежие сообщения длинной сессии** | `memex_get_conversation(id, order:"desc")` — хвост в один вызов. Дефолт `asc` отдаёт самые старые. |
+| **Навигация по сессии на тысячи сообщений** | Сначала `memex_search(query, conversation_id)` чтобы найти место, потом `memex_get_conversation(id, offset, limit)` чтобы прочитать окно вокруг. |
+| **Листать длинный чат страницами** | `memex_get_conversation(id, limit, offset)` — `offset` 0, 200, 400… Вывод показывает `total`, чтобы знать докуда листать. |
+| **Эволюция документа/решения во времени** | `memex_search(query, sort:"date_asc")` — старые→новые, читать вперёд. |
+| **Найти в чате по человеку/названию** | `memex_search(query, chat:"<часть названия>")` — нечёткий подстрочный матч по заголовку. |
+| **«Что я обсуждал с агентом на конкретной машине»** (synced-меш) | `memex_search(query, origin:"vps1")` — v0.14: каждый узел штампует свои захваты своим именем. Какие origins есть — видно в `memex_overview`. В слитых чатах (два агента в одном Telegram) `memex_get_conversation` помечает строки `[@origin]`. Строки до v0.14 — без origin. |
+
+> Даты — Unix-секунды. Напр. «с 1 июня 2026» → `since_ts: 1780272000`. Не уверен в границах — сначала `memex_list_conversations(since_ts=…)` чтобы увидеть, какие сессии попадают в окно.
+
+---
+
+## 🔁 Синк между устройствами (v0.13) — 2 шага
+
+Ноут с Claude/Cursor + сервер с агентом → одна общая память. Без публичных
+портов, фаервол не трогаем, SSH-ключи руками не носим.
+
+**Шаг 1 — промпт агенту на сервере** (он сделает всё сам):
+
+```
+Настрой memex-sync как хаб и выдай join-токен для моего ноута:
+1. npm install -g parallelclaw@latest   (пропусти, если уже стоит)
+2. memex-sync sync-server install --bind 127.0.0.1
+3. memex-sync sync-server invite --join
+Пришли мне строку memex-join:...
+```
+
+**Шаг 2 — одна команда на ноуте:**
+
+```bash
+memex-sync sync-join memex-join:eyJ2...
+```
+
+Поднимет самовосстанавливающийся SSH-туннель, сделает первый синк, поставит
+авто-синк (15м) + watchdog (1ч) и **докажет** петлю тестовой заметкой.
+Проверить состояние в любой момент: `memex-sync sync-status` (туннель,
+расписание, watchdog, когда был последний успешный синк). Если синк замолчит
+дольше часа — watchdog пришлёт уведомление и запишет `~/.memex/sync-alert.txt`.
+
+Типовые проблемы: токен «expired» сразу после выпуска → проверь часы на обеих
+машинах (`date -u`), пере-выпусти токен; «SSH failed» → команда печатает твой
+pubkey — отдай его агенту сервера и повтори. Подробности и продвинутые
+топологии — [SYNC.md](https://github.com/parallelclaw/memex-mvp/blob/main/SYNC.md).
+
+---
+
+## 💻 Терминальный CLI (v0.7+) — когда MCP не работает
+
+Если MCP-интеграция не подцепилась к твоему агенту (или ты в агенте без MCP-поддержки, но с shell-доступом) — у memex есть **terminal-режим** на том же бинаре. Один пакет, два режима.
+
+```bash
+memex search "Postgres миграция"                  # FTS5 поиск
+memex search "Q2 deck" --chat "Memex Bot"         # фильтр по title чата
+memex search "auth" --source claude-code --limit 5 --sort date_desc
+memex search "JWT" --as-of 2026-05-01             # time-travel (v0.8.1+) — только до даты
+
+memex when "Brian Chesky"                          # «когда мы об этом говорили»
+memex when "JWT decision" --limit 5                #  → chronological list of chats, без snippets
+
+memex recent --limit 5                             # последние сообщения
+memex recent --source telegram
+
+memex list                                         # все conversations
+memex list --source web                            # только сохранённые URL'ы
+
+memex get web-1582ab51a7b7                         # полный контент conversation
+
+memex overview                                     # snapshot корпуса (+ capture streak v0.8.1+)
+memex projects                                     # уникальные project_paths
+
+# Telegram pipeline (v0.10+):
+memex telegram check                               # Desktop? 24h? watcher? pending?
+memex telegram pending                             # список pending экспортов
+memex telegram import 1 3 5                        # импорт по индексам или title'у
+memex telegram skip 4                              # не индексировать; запомнить
+memex telegram allow "Family"                      # auto-import на следующих re-export'ах
+memex telegram block "*bank*"                      # никогда не индексировать (glob)
+memex telegram mode auto                           # pick (default) / auto / manual
+memex telegram notifications on --show-titles      # macOS notif когда детектится новый export
+memex telegram notifications target claude-cli     # клик по баннеру → откроет Claude Code CLI
+memex telegram open-pending                        # открыть pending в лучшем доступном клиенте
+memex telegram open-pending --in terminal          # forcefully в Terminal с командой
+memex telegram scan                                # one-shot ре-скан Downloads
+memex telegram status                              # all decisions
+
+# Импорт файла из ЛЮБОГО пути (v0.10.12+) — без танцев с inbox/pending:
+memex import ~/projects/memex/result.json          # автодетект формата
+memex import ~/Downloads/ChatExport_2026-05-18/    # директория Telegram HTML
+memex import ~/path/to/session.jsonl               # Claude Code JSONL
+memex import ~/Downloads/result.json --force       # пропустить privacy-gate
+memex import file --format claude-jsonl --json     # явный формат + JSON-вывод
+
+memex help                                         # эта инструкция в терминале
+memex --help                                       # справка по командам
+memex --version
+```
+
+**Все query-команды поддерживают `--json`** для пайпов и скриптов:
+
+```bash
+memex search "TODO" --json | jq '.results[].snippet'
+memex list --source telegram --json | jq -r '.conversations[].title'
+memex get web-1582ab51a7b7 --json > backup.json
+```
+
+**БД открывается read-only** — безопасно запускать пока daemon-writer работает.
+
+**Когда использовать CLI вместо MCP:**
+
+- MCP-интеграция в твоём агенте не подключилась → `memex overview` подтвердит что сам memex здоров, проблема в MCP-config'е клиента
+- Агент без MCP-поддержки (OpenCode + Kimi, любые CLI-only агенты), но с shell-доступом
+- Shell-скрипты / автоматизация
+- Дебаг: «вижу ли я свою историю напрямую?»
+
+**`memex` (без аргументов)** — это MCP stdio-сервер. Это поведение по умолчанию для Claude Code / Cursor / OpenClaw через их MCP-config'и. CLI-команды активируются только при наличии распознанного subcommand'a.
+
+---
+
+## 📥 Импорт файла из произвольного пути (v0.10.8+ → v0.10.12+ MCP)
+
+Если у тебя файл `result.json` (Telegram export) или `.jsonl` (Claude/Cowork-сессия) лежит где-нибудь в `~/Downloads/`, `~/Desktop/`, `~/projects/foo/` — **не нужно** копировать его руками в `~/.memex/inbox/`. Одна команда:
+
+```bash
+memex import ~/projects/memex/result.json
+```
+
+Что произойдёт:
+- Авто-детект формата (Telegram JSON / HTML / Claude Code JSONL / Cowork JSONL)
+- Для Telegram: проверяет твои decision-предпочтения (`allow` / `skip` / `block`)
+  - Новый чат → выводит preview (title, кол-во сообщений, диапазон дат, senders) и спрашивает подтверждения (`--force` чтобы импортить)
+  - Уже в `allowed` → импортит сразу
+  - В `skipped` / `blocked` → отказывается (или `--force` чтобы переопределить)
+- Для Claude/Cowork JSONL — импортит сразу (своя память, нет privacy-gate)
+- Идемпотентно — повторный импорт того же файла не задвоит (UNIQUE constraint)
+
+**То же самое через AI-агента:** любой агент с MCP-соединением может вызвать `memex_import_file({path: "..."})` одним tool-call'ом, получить структурированный ответ. Это **в 100 раз дешевле по токенам** чем агент через bash руками таскает файлы в inbox и парсит логи.
+
+---
+
+## 🖥 Web-дашборд (v0.10.8+) — посмотреть память глазами
+
+Когда хочется не звать AI, а **самому полистать** что у тебя в memex'е — есть локальный read-only веб-UI. Та же SQLite, другая поверхность.
+
+```bash
+memex web --open                       # localhost:8765, откроется в браузере
+memex web --port 9000                  # свой порт
+memex web --public --token s3cret      # 0.0.0.0 с bearer-авторизацией (для туннеля)
+memex web --help
+```
+
+**5 страниц:**
+
+- `/` — статы (messages / conversations / sources / imports), sources breakdown, callout про pending Telegram, последние 10 чатов
+- `/conversations` — список с **live FTS5-поиском** через htmx (печатаешь — обновляется за 200мс), фильтры-чипы по source
+- `/c/:id` — **verbatim** транскрипт chat-bubble'ами (то самое, что не делает claude-mem — он только AI-резюмирует); поиск внутри чата с подсветкой; пагинация для 1000+ сообщений
+- `/pending` — Telegram-экспорты с чекбоксами; нажимаешь Import / Skip — тот же гейт privacy, что и `memex telegram import`
+- `/settings` — daemon status, путь и размер БД, установленные хуки, decisions count (read-only)
+
+**Что важно:**
+- Не always-on. `memex web` поднял — Ctrl+C погасил. Никакого фонового сервера.
+- Read-only. Единственные записи — это TG import / skip на `/pending`.
+- Localhost-only by default. Для remote — `--public --token …`.
+- Без build-step'a. Raw Node `http` + tagged template literals + htmx 14KB. Клиентский bundle ≈ 30KB (для сравнения у claude-mem ~10MB React-бандл).
+- Брендирование как на лендинге (mint #6ee7b7 на тёмном).
+
+**Когда полезно:**
+- Хочешь сам прокрутить большой Telegram-чат и не вспоминать какой именно поиск ввести
+- Демо коллеге — открыл вкладку, показал что у тебя реально лежит дословно (это и есть verbatim-moat — на любой чат с любого источника можно перейти и увидеть сырое, не AI-пересказ)
+- Аудит pending'a с мышкой и галочками вместо `memex telegram import 1 3 5`
+- Cron-friendly remote endpoint (тот же сервер потом получит multi-host sync API в v0.13+)
+
+---
+
+## 🪄 Auto-context (v0.8+) — Brian Chesky moment
+
+Magic-фича. Когда ты открываешь Claude Code в проекте, Claude **сам** инжектит 500-1500 токенов контекста про этот проект — что ты делал недавно, какие conversations касались темы. Ты ещё ничего не спросил, а AI **уже знает**.
+
+**Технически:** SessionStart hook в `~/.claude/settings.json`. При старте каждой Claude Code сессии хук вызывает `memex context` → memex выдаёт markdown summary → Claude получает его как system message _до_ твоего первого вопроса.
+
+**Установка:** проще всего — `curl -fsSL https://memex.parallelclaw.ai/install.sh | bash` поставит memex + daemon + auto-context хук одной командой. Если ставил memex вручную — во время `memex-sync install` будет промпт `[Y/n]` (соглашайся, Y по default'у). Или установи хук позже:
+
+```bash
+memex hook install         # добавить хук
+memex hook uninstall       # удалить (только memex-запись, другие хуки сохраняются)
+memex hook status          # узнать текущее состояние
+```
+
+**Посмотреть что будет инжектиться** (dry-run в текущей директории):
+
+```bash
+memex context              # markdown как для хука
+memex context --json       # структурированный
+memex context --no-source telegram   # исключить telegram (privacy)
+memex context --freshness-days 30    # только последние 30 дней
+```
+
+**Privacy:** хук ничего не отправляет наружу — это локальная инъекция в локальную Claude-сессию. Но в context могут попасть фрагменты из любых indexed sources (включая Telegram). Чтобы исключить — добавь `--no-source telegram` в команду хука (правится в `~/.claude/settings.json`).
+
+**Где это пока не работает:** Cursor — нет native SessionStart hook'а; fallback через MCP-tool (v0.9+). Сейчас auto-context работает в **Claude Code и OpenClaw**.
+
+---
+
+## Если что-то не работает
+
+### Поиск пустой
+
+1. Вызови `memex_overview`. Внимание на статус-баннер сверху:
+   - 🟢 daemon работает — всё ок, может ещё не успел проиндексировать
+   - 🔴 daemon установлен но не работает — `launchctl load ~/Library/LaunchAgents/com.parallelclaw.memex.sync.plist`
+   - ⚪ daemon не установлен — самый простой способ: `curl -fsSL https://memex.parallelclaw.ai/install.sh | bash` (поставит сам всё). Или вручную: `memex-sync install`.
+
+### Хочу проиндексировать существующие сессии (бэкфилл)
+
+```bash
+npx memex-sync scan
+```
+
+Обходит `~/.claude/projects/`, Cowork-сессии, Cursor state.vscdb, и Obsidian-vault'ы один раз — ингестит всё что уже есть на диске.
+
+### Telegram-чаты не появляются
+
+В Telegram **Desktop** (не mobile!): чат → меню (⋮ или ☰) → **Export chat history**.
+
+**memex поддерживает оба формата экспорта (v0.9+):**
+
+- **«Machine-readable JSON»** ← рекомендуется. Один файл `result.json`, чисто ингестится.
+- **«HTML»** ← тоже работает (с v0.9+). Получишь директорию `ChatExport_<chat>_<date>/`.
+
+**v0.10+ flow — privacy-first, без ручного копирования:**
+
+1. Сохрани экспорт куда обычно (по умолчанию `~/Downloads/Telegram Desktop/ChatExport_*`).
+2. Daemon **сам** детектит и переносит в `~/.memex/pending/`.
+3. Получишь уведомление (через 4 канала: tip в CLI, в auto-context хуке Claude, в response любого MCP-tool, optionally macOS native notification). Подробнее: `memex telegram notifications status`.
+4. Запусти `memex telegram pending` → увидишь список с превью.
+5. Импорт: `memex telegram import 1 3 5` (по индексу) или просто скажи AI агенту «импортируй family и work».
+6. Sensitive чаты можно пропустить: `memex telegram skip 4 7` — memex запомнит и не будет предлагать снова.
+
+**Старый flow тоже работает** (для совместимости): кинь `result.json` или `ChatExport_*/` прямо в `~/.memex/inbox/` — попадёт сразу в `memex.db` без pending review.
+
+**Modes** (`memex telegram mode <pick|auto|manual>`):
+- `pick` (default): всё через pending, ты явно подтверждаешь
+- `auto`: чаты из allow-list импортятся сами, новые — в pending
+- `manual`: watcher выключен, только ручной inbox
+
+Если ингест не произошёл — проверь `~/.memex/data/memex.log`. Для HTML-export'а парсер пишет actionable error если что-то не так (формат изменился у Telegram, директория повреждена, и т.д.).
+
+**Что НЕ работает:**
+- ❌ Мобильный экспорт (Telegram mobile не экспортирует структурированно)
+- ❌ Скриншоты чатов
+- ❌ Только-медиа чаты (без текста парсятся как `[photo]`/`[voice]` placeholders, но без content)
+
+### Хочу подключить новый 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.