# ADR-046: Reindex memory + finalize kebab-case tool names in docs (PR #104)

## Статус
Accepted (2026-07-26)

## Контекст

После серии PR #100–#103 (Python lazy-init, 5 TS tools, E2E tests, remove plugin + Rust)
инфраструктура памяти была готова, но:
1. Индекс `.rag/index.json` существовал (220 MB, 2379 entries), но `meta.json`
   отсутствовал → Python incremental reindex не мог определить version mismatch
   при будущих запусках (fallback к full reindex или silent skip).
2. Документация (SKILL.md, AGENTS.md, 6 skills, memory-syncer agent, 3 TS tools,
   spec command) содержала stale snake_case tool names (`memory_save`,
   `memory_search`) — агенты могли вызывать несуществующие tools и получать
   "tool not found".
3. `OPENAI_EMBEDDING_BATCH_DELAY` была в issue #99 как требование (throttle
   между батчами для OpenRouter rate limits), но `embedder.py` не поддерживал
   эту env var — добавление в `.env.example` без поддержки в коде вводило бы
   в заблуждение.
4. Memory file `technical/rag-cli-embeddings-model.md` описывал Rust rag-cli
   (candle-transformers, all-MiniLM-L6-v2, 384-dim, GLIBC 2.39) как активный —
   агенты могли пытаться использовать удалённый путь (PR #103 удалил Rust).

## Решение

1. **Переиндекс через Python** — `uv run python -m src.memory index`. Создан
   `.rag/meta.json` с `version: "qwen/qwen3-embedding-8b:512:64"` (Python формат,
   `version` key — НЕ `model_id` который был Rust). Incremental: 86 изменившихся
   файлов, 286s, 2584 entries total (merged со старым index.json).

2. **`OPENAI_EMBEDDING_BATCH_DELAY` — поддержка в коде + `.env.example`**:
   - `embedder.py`: `BATCH_DELAY = float(os.environ.get("OPENAI_EMBEDDING_BATCH_DELAY", "0"))`
   - `time.sleep(BATCH_DELAY)` между батчами (только если `> 0` и не последний батч)
   - `.env.example`: `OPENAI_EMBEDDING_BATCH_DELAY=0.5`
   - Default `0` — backwards compatible, не ломает существующие вызовы.

3. **Stale references cleanup** — `memory_save`/`memory_search`/`memory_setup`
   (snake_case) → `memory-save`/`memory-search`/`memory-doctor` (kebab-case) в
   всех активных файлах (`.opencode/skills/`, `.opencode/agents/`, `.opencode/tools/`,
   `.opencode/commands/`, `AGENTS.md`). Исторические `docs/decisions/` и
   `docs/handoff/` НЕ тронуты (snake_case отражает реальные имена на момент
   написания).

4. **Memory file `rag-cli-embeddings-model.md` переписан** — Rust rag-cli →
   Python + OpenRouter как единственный путь semantic. Зафиксировано что удалено.

5. **SKILL.md (memory)** — добавлена секция "Архитектура (progressive
   enhancement)": keyword всегда, semantic если `OPENAI_BASE_URL` set, fallback,
   auto-setup, `memory-doctor` как read-only диагностика. Default путь исправлен:
   `~/opencode-memory` → `/root/.local/share/opencode/opencode-memory`.

## Альтернативы

- **Не добавлять `OPENAI_EMBEDDING_BATCH_DELAY` в код, только в `.env.example`** —
  отклонено: env var в `.env.example` без поддержки в коде вводит в заблуждение
  (пользователь думает что delay работает, но код его игнорирует). Минимальная
  правка embedder.py (3 строки) делает её рабочей.

- **Трогать исторические `docs/decisions/` и `docs/handoff/`** — отклонено: ADR
  и handoffs — исторические записи, snake_case там отражает реальные имена tools
  на момент написания (до PR #101 переименования). Правка исказила бы историю.

- **Полный reindex (удалить старый index.json)** — отклонено: incremental reindex
  по SHA256 (ADR-036) достаточно. 86 изменившихся файлов переиндексировано,
  остальные merged. Полный reindex = 13 минут + $0.0043, incremental = 286s +
  $0.00012. Нет причины делать полный если incremental корректен.