3aa5330003
* fix(memory): check index.json not .rag dir in setup step 5 * docs(readme): align to real state after memory PRs * chore(env): remove dead vars from env example * docs(handoff): add handoff + ADR-037 for memory setup step5 fix * docs(handoff): set PR number --------- Co-authored-by: opencode-agent <agent@opencode.local>
28 lines
No EOL
3.2 KiB
Markdown
28 lines
No EOL
3.2 KiB
Markdown
# ADR-037: setup-memory.sh step 5 — check index.json, not .rag dir
|
||
|
||
## Статус
|
||
|
||
Accepted (2026-07-26)
|
||
|
||
## Контекст
|
||
|
||
setup-memory.sh step 5 проверял наличие директории `$MEMORY_DIR/.rag` через `[ ! -d ... ]`, чтобы решить, нужно ли пересобирать RAG индекс. После внедрения Python memory CLI (PR#75) и wrapper'а для opencode-memory plugin (PR#77), наш формат индекса — `index.json` в директории `.rag/`. Однако оригинальный Rust rag-cli (который plugin использовал до wrapper'а) создаёт `meta.json` + `index.bin` в той же директории `.rag/`.
|
||
|
||
Баг: если Rust rag-cli уже отработал, директория `.rag/` существует, но содержит stale Rust-формат без `index.json`. Проверка `[ ! -d "$MEMORY_DIR/.rag" ]` возвращает false → step 5 пропускает rebuild → plugin продолжает использовать Rust rag-cli (wrapper не перезаписан, индекс не в нашем формате). End-to-end проверка после PR#77/#83 подтвердила это: wrapper не перезаписывался, meta.json в Rust схеме.
|
||
|
||
## Решение
|
||
|
||
Заменить проверку директории на проверку файла индекса:
|
||
`[ ! -d "$MEMORY_DIR/.rag" ]` → `[ ! -f "$MEMORY_DIR/.rag/index.json" ]`.
|
||
|
||
Теперь step 5 форсирует rebuild, если:
|
||
- директория `.rag/` не существует (fresh install), ИЛИ
|
||
- директория существует, но `index.json` отсутствует (stale Rust-формат, частичный индекс, удалённый файл).
|
||
|
||
Это гарантирует, что после первого запуска setup-memory.sh с новым кодом индекс будет в нашем Python memory CLI формате, а wrapper (step 5b) перезапишется при следующем запуске plugin'а.
|
||
|
||
## Альтернативы
|
||
|
||
- **Проверять `meta.json` (Rust-формат) и удалять директорию целиком.** Отклонено: деструктивно, может удалить валидный наш индекс при ложном срабатывании. Безопаснее проверять наличие нашего файла, чем absence чужого.
|
||
- **Всегда пересобирать индекс (unconditional rebuild).** Отклонено: ломает idempotent-контракт setup-memory.sh (тест `test_idempotent` ожидает, что 3-й запуск = 1-й по snapshot). Rebuild при каждом запуске = ~минута лишней работы + нагрузка на embeddings API.
|
||
- **Проверять содержимое `index.json` (схему/версию).** Отклонено: over-engineering для bash-скрипта. Проверка существования файла достаточна — формат валидируется Python memory CLI при загрузке. |