fix(memory): setup step 5 check index.json + align docs to real state (#85 )

* 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>

2026-07-26 20:12:15 +03:00

3.2 KiB

Raw Permalink Blame History

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 при загрузке.

3.2 KiB Raw Permalink Blame History Unescape Escape