# memo — заметки как миллион файлов, каждый со своей семантикой

Спека v0.1 (только проект, кода нет). Автор идеи — пользователь; форма зафиксирована 02.10.2026.

## 0. Идея в одном абзаце

Обычный провайдер памяти в Hermes — **один** стор на весь профиль (MEMORY.md, holographic, mem0).
Здесь форма другая: **markdown-файлы лежат в дереве папок и являются истиной**, а рядом с каждой
папкой-темой лежит пересобираемый векторный индекс. Коллекций — сколько угодно, они не мешают друг
другу, и «спрашивают про X → ищем в X» решается детерминированной маршрутизацией, а не надеждой на
автопоиск по всему корпусу. Это не память (маленькая и всегда в промпте) и не файловая система
(слепая к смыслу) — это **библиотека со смысловым индексом**.

## 1. Границы: что это и чем не является

- НЕ замена MEMORY.md / USER.md. Курируемая память по-прежнему маленькая и всегда в промпте.
- НЕ граф знаний, НЕ авто-суммаризация, НЕ «агент сам решает, что запомнить».
- НЕ облако: модель эмбеддингов локальная (CPU/ONNX), сеть не нужна ни при индексации, ни при поиске.
- НЕ альтернатива grep: файлы остаются человекочитаемыми, любой поиск по тексту работает и без индекса.

## 2. Правило номер один

**Markdown — истина, `.db` — кэш, который не жалко.**

Следствие: индекс можно удалить целиком и он пересоберётся. Ничего, что существует только в базе,
быть не должно. Любая миграция схемы = `rm -rf` + ленивая пересборка при первом обращении к коллекции.

## 3. Модель данных

```
<root>/                          # корень библиотеки, напр. ~/notes/memo
  _registry.yaml                 # реестр коллекций: имя → описание, путь, эмбеддер, счётчики
  work/
    jira/
      _meta.yaml                 # описание коллекции, теги, модель/димы, версия чанкера
      notes.md                   # основная заметка (markdown, истина)
      pitfalls.md
      .memo/
        index.db                 # sqlite: FTS5 + vec0, пересобираемо
        state.json               # версия чанкера/модели, sweep-время
  life/
    books/
      _meta.yaml
      iphuck10.md
      .memo/index.db
  inbox.md                       # неразобранное; коллекция НЕ индексируется
```

Правила:

1. **Коллекция = папка** (не файл). Один sqlite на заметку — запрещено: inode, соединения, фрагментация.
2. **Заметка = `.md`-файл** внутри коллекции. Ориентир: 10–300 файлов на коллекцию, до ~10⁵ коллекций в теории.
3. **Максимум ~2 уровня вложенности** папок. Глубже — значит тема слишком крупная, её надо дробить.
4. Черновики — в `inbox.md` в корне: не индексируются, агент за них не отвечает.
5. `_meta.yaml` коллекции обязателен: без описания коллекция невидима для маршрутизатора.

```yaml
# _meta.yaml
name: work/jira
description: "Корпоративная Jira: тикеты, флоу, доступы, грабли MCP"
tags: [corp, jira, otp]
embedder: intfloat/multilingual-e5-small   # 384 dims
chunker: headings-v1                        # меняешь — индекс пересобирается
```

## 4. Формат заметки

- Границы чанков = **markdown-заголовки** (`##`/`###`); слишком длинный раздел режется по ~800 токенов
  с перекрытием 15%. Никогда не резать по символам «вслепую».
- Опциональный frontmatter: `id`, `tags`, `updated`. Обязателен только `updated` (руками или скриптом).
- Имена файлов — ASCII-slug, без пробелов: `postgres-restore.md`, не `про восстановление.md`.
- В текст заметки полезно писать **явные синонимы и аббревиатуры** («PBR (policy based routing)») —
  это бесплатно лечит промахи чистого вектора на жаргоне.

## 5. Индекс (одна база на коллекцию)

```sql
CREATE TABLE chunks(
  id INTEGER PRIMARY KEY, path TEXT, heading TEXT, line INTEGER, ord INTEGER,
  text TEXT, h1 TEXT, mtime REAL, hash TEXT);
CREATE VIRTUAL TABLE chunks_fts USING fts5(text, heading, tokenize='unicode61');
CREATE VIRTUAL TABLE chunks_vec USING vec0(embedding float[768]);   -- sqlite-vec, dim по модели
```

- **Гибридный поиск:** BM25 (FTS5) + вектор, слияние RRF (`k=60`). Чистый вектор обязателен… и
  недостаточен: числа, аббревиатуры, имена файлов находятся только лексикой.
- **Инкремент:** сравниваем `(path, mtime, size)` со таблицей `files`; переэмбеддиваем только
  изменившиеся файлы. Полная пересборка коллекции — по требованию.
- Версия чанкера/модели в `.memo/state.json`: не совпала — коллекция переиндексируется целиком.
- Сортировка результата: RRF-скор, затем свежесть (`mtime`) как тайбрейкер, чтобы свежая заметка
  выигрывала у устаревшей при равном совпадении.

## 6. Эмбеддер

- База: `intfloat/multilingual-e5-small` (384 dims, ~118M параметров, ONNX/CPU через fastembed).
  Мультиязычность не опция: `nomic-embed-text` на русском молча проигрывает.
- Префиксы e5 обязательны: документ — `"passage: …"`, запрос — `"query: …"`; нормализация L2.
- Апгрейд до `bge-m3` (1024) — если качество на реальных вопросах не устроит; тогда переиндекс всех коллекций.
- **Модель грузится один раз** на процесс, лениво, при первом обращении. Это аргумент за
  долгоживущий процесс (MCP-сервер), а не за CLI-утилиту.

## 7. Маршрутизация (самое узкое место)

Проблема не в поиске, а в выборе **где** искать. Миллион коллекций в промпт не влезет.

- До ~50 коллекций: плоский список `name — description` целиком в инструмент (или промпт).
- До ~5 000: дерево имён (`work/*`, `work/jira/*`) — фильтр по префиксу + поиск по описаниям.
- Больше: отдельный роутер (BM25/эмбеддинг по `description` коллекций) → кандидаты → агент выбирает.
- Всегда доступен режим `scope="*"`: искать по всем индексам, но это дорого и только осознанно.

## 8. Интерфейс: инструмент-тень, а не способ записи (v0.2)

Решение v0.2 (идея пользователя, 02.10.2026): **агент пишет и читает только markdown своими обычными
средствами** (`write_file` / `patch` / `read_file`). Индекс никто через API не наполняет — он
наблюдает за файловой системой и догоняет. Инструмент поиска — только чтение, для агента он такой же
обычный, как grep. Источник правды один, и это файл.

| Инструмент | Аргументы | Возврат |
|---|---|---|
| `memo_search` | `path` (файл ИЛИ папка), `query`, `k=8`, `mode=hybrid\|lex\|vec` | `path:line`, `heading`, `score`, текст чанка (~1 200 символов) |
| `memo_status` | `path` (опц.) | что проиндексировано, когда, отстаёт ли индекс от mtime |
| `memo_reindex` | `path`, `full=false` | аварийная пересборка, если watcher ослеп |

- `path` принимает **папку** — поиск рекурсивно по коллекции. Типовой вопрос звучит «где в этой папке
  про X», а не «в этой заметке».
- `memo_write` из v0.1 удалён: две дороги записи = два источника правды.
- Возврат всегда с `path:line` — агент дочитывает нужное `read_file(offset)`, а не открывает файл целиком.

## 8-bis. Наблюдатель (watcher)

- Отдельный процесс: inotify (`watchdog`) → debounce 500 мс → `stat` + `hash` → переэмбеддинг только изменившегося.
- **Событие — триггер, не истина.** Решение «изменилось ли» принимает хэш: редакторы бросают пачку
  событий на одну запись (vim `4913`, atomic rename в VS Code и Obsidian).
- **Реконсиляция обязательна:** inotify слепнет на FUSE/sshfs/SMB и теряет события при переполнении
  очереди. Раз в 10–15 мин — скан `(path, mtime, size)` по коллекции; холодный поиск тоже форсит перескан.
- **Два процесса над одним sqlite → WAL** (`journal_mode=WAL`), иначе «database is locked» на живой записи.
- Разделение: watcher пишет, MCP-сервер читает. stdio-MCP живёт только внутри сессии Hermes, поэтому
  фоновая индексация в нём невозможна — watcher это **отдельный сервис** (`/opt/memo/`, systemd или
  podman-compose), MCP подключается к его базе. Альтернатива «всё в одном» — streamable-http демон
  со встроенным потоком-watcher.
- **Задержки быть не должно:** `memo_search` перед поиском делает быстрый `stat`+`hash` по целевому
  пути и догоняет разницу сам. Тогда «агент записал и сразу ищет» находит правку сразу, а watcher
  остаётся страховкой для правок, сделанных человеком и другими инструментами.
- Остаётся от v0.1: **карта тем** (раздел 9). Прозрачность файлового слоя не отменяет вопрос «в какой
  папке искать» — её даёт скилл, а не инструмент.

## 9. Правила записи (скилл, а не код)

Файлы гниют не от поиска, а от записи «куда попало». Нужен тонкий слой дисциплины — скилл вида:

```
Тема            → коллекция
инфра/серверы   → infra
работа/Jira     → work/jira
книги           → life/books
личное          → life/misc
нет темы        → inbox.md (не индексируется)
```

- Новая тема = новая папка + `_meta.yaml` + строчка в скилле. Один раз.
- Дедуп: перед записью — `memo_search` по этой же коллекции; хэш точной копии не пишем дважды.
- Заметка в двух местах — запрещено; при переносе файла индекс коллекции переиндексируется, история mtime сохраняется.

## 10. Что проверяем до того, как что-то оптимизировать

1. 20–30 **реальных** вопросов к своим заметкам (не «тестовых») — вручную смотрим recall@5.
2. Отдельно — вопросы на точные значения: числа, версии, имена хостов, аббревиатуры (тут решает BM25).
3. Отдельно — вопросы «смысловые», другими словами, чем в заметке (тут решает вектор).
4. Замер: холодная индексация коллекции на N файлов, горячий поиск. Целевые ориентиры: поиск < 100 мс.

Если recall@5 на реальных вопросах ниже ~0.8 — виноват не индекс, а формулировки заметок и slug'и.

## 11. Открытые развилки (решать после прототипа, не сейчас)

- Корень библиотеки: `~/notes/memo` или внутри конкретного репо?
- Один MCP-сервер на библиотеку или свой процесс на коллекцию? (Сейчас: один на всё, коллекции — аргумент.)
- Нужен ли `memo_gc` (перемещение/удаление) или файлы двигает только человек?
- Автоматический захват сессий в `inbox.md` (крон) — или только ручные записи агента.

## 12. Чем отличается от готового в Hermes

| | провайдер Hermes (holographic / mem0) | memo |
|---|---|---|
| Стор | один на профиль | много папок, по теме |
| Истина | база данных | markdown на диске |
| Пересборка | миграция | удалить `.db` |
| Гранулярность | факт/эпизод | заметка/раздел |
| Маршрутизация | не нужна | требуется (реестр + scope) |

Вывод: для Hermes-агента это не замена провайдера, а дополнение «библиотека»; для своего агента —
самостоятельный сервис, подключаемый по MCP.

## 13. Портатив на Kotlin — из чего собирается (проверено 02.10.2026)

Разведка нашла всё, о чём говорил пользователь. Своего кода нужно мало.

| Нужда | Что берём | Где лежит | Координаты / состояние |
|---|---|---|---|
| SQLite + **вектор** + FTS5 | `caffeine-mgn/ksqlite` (наш, GitHub) | GitHub `caffeine-mgn/ksqlite`, README.ru есть | Maven Central: `pw.binom.db:ksqlite:0.1.4`. Внутри амальгама SQLite 3.53.4 + **sqlite-vec 0.1.9** (авто-регистрация), FTS3/4/5, RTREE, JSON1. JVM (JNI `.so`) + linux/mingw/Android/a… klib |
| Текстовый эмбеддинг | `subochev/text-embedding-kmp` — SigLIP2 int8, **768 dims** | git.binom.pw | caffeine: `pw.binom.ai.embeddingtext:api` / `:siglip` — актуальная **5**. Модель с `http://static.binom.pw/models/siglip2/` |
| Текст + vision в одном | `subochev/embedder-kmp` | git.binom.pw | caffeine: `pw.binom.embedder:embedder-api-text` / `-impl-text` (и vision) — **1**. Модели в артефакт не кладутся, пути отдаёт потребитель |
| Qdrant (если б понадобился) | `subochev/qdrant` (core/ktor/strong) | git.binom.pw | в caffeine **не выложен**, и это HTTP-клиент к внешнему серверу → при embedded-схеме не нужен |
| MCP (stdio + http) | `subochev/mcp` (server-shared / server-cli / server-http, `AITool<T>`) | git.binom.pw | **не опубликован** (наружу только `shared`) → либо submodule/исходники, либо свой MCP на Ktor |
| Слежение за файлами | **готового нет** | — | JVM: `java.nio.file.WatchService` (inotify под капотом), register RECURSIVE + debounce + reconcile — пишем сами, ~150 строк |

Вывод разведки: «клёвая библиотека для векторного поиска» = **sqlite-vec внутри ksqlite**, а не
отдельный Qdrant. Это ровно та схема, что в разделе 5 спеки — то есть зависимость одна:
`pw.binom.db:ksqlite` + наш эмбеддер.

### Модули (JVM-first, один Gradle-проект `memo`)

1. `memo-core` — чанкер по заголовкам, хэши/`files`-таблица, схема БД через ksqlite,
   инкрементальная переиндексация, гибридный поиск (FTS5 BM25 + `vec0` KNN + RRF).
2. `memo-watch` — демон: WatchService на корень, debounce 500 мс, очередь, reconcile раз в 10–15 мин, WAL.
3. `memo-mcp` — MCP stdio+http: `memo_search` / `memo_status` / `memo_reindex`.
4. `memo-cli` — `memo index|search|status` для ручных проверок и приёмки без агента.

`core` не знает ни про MCP, ни про watcher — это драйверы. Так ядро потом переиспользуется
на Android (`-android`/`-jvm` артефакты уже есть у обеих библиотек).

### Что придётся написать руками

Чанкер, RRF-слияние, watcher с реконсиляцией, схему/миграцию, MCP-инструменты. Ориентир суммарно:
**600–900 строк Kotlin**. Всё остальное — готовые артефакты из таблицы.

### Приёмка (то, что пойдёт в ТЗ для opencode)

1. `memo index ~/notes/memo` создаёт `~/notes/memo/<тема>/.memo/index.db`, повторный прогон — no-op.
2. `memo search "<смысловой вопрос>"` находит нужный раздел (recall@5 на 20 реальных вопросах).
3. Вопрос с числом/аббревиатурой находит точное совпадение (проверка BM25, не вектора).
4. Файл, поправленный руками (`echo >> note.md`), виден в поиске ≤1 с; правка, сделанная сразу
   перед поиском, видна **в том же вызове** (stat-догон).
5. MCP-сервер проходит протокольный зонд: `tools/list` + `tools/call` с непустым результатом.
6. Без сети: эмбеддинг и поиск работают при выключенном внешнем интерфейсе.

### Развилка, зафиксированная по умолчанию

Берём **JVM** (демон + watcher + CLI + MCP — серверная история, KMP-таргеты тут ничего не дают).
Android-таргеты — вторым шагом и без watcher (там индексация по запросу): библиотеки это позволяют.