4cf149cb02
* feat(memory): add OPENAI_EMBEDDING_BATCH_DELAY support * docs(memory): update SKILL.md for progressive enhancement and auto-setup * docs(memory): update AGENTS.md tool usage policy * docs(memory): fix stale snake_case tool references in skills, agents, tools * docs(handoff): add handoff + ADR for reindex-skill-update * docs(handoff): set PR number * refactor(memory): extract _embed_in_batches to satisfy xenon rank A --------- Co-authored-by: opencode-agent <agent@opencode.local>
67 lines
No EOL
4.7 KiB
Markdown
67 lines
No EOL
4.7 KiB
Markdown
# 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 корректен. |