slaid098/opencode-config
1
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions
opencode-config/docs/decisions/046-pr-104-reindex-skill-update.md
Sergey 4cf149cb02
docs(memory): reindex + update SKILL.md (#104) 
* 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>
2026-07-27 02:08:35 +03:00

4.7 KiB
Raw Blame History

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 корректен.