docs(readme): add memory setup instructions with troubleshooting (#86 )

* docs(readme): add memory setup instructions with troubleshooting

* docs(handoff): add handoff + ADR-038 for PR #86

---------

Co-authored-by: opencode-agent <agent@opencode.local>

2026-07-26 20:25:21 +03:00

2.4 KiB

Raw Blame History

ADR-038: README memory setup instructions

Статус

Accepted (2026-07-26)

Контекст

После серии PR #75 (refactor) → #77 (wrapper) → #83 (incremental index) → #85 (setup bug fix + docs align) память заработала end-to-end: plugin → Python wrapper → OpenRouter Qwen3 8B → semantic search. Однако README не содержал пошаговой инструкции развёртывания — только 3 строки с общими словами. Новый пользователь не мог развернуть память без чтения исходников setup-memory.sh и embedder.py.

Дополнительно: после обнаружения бага в setup-memory.sh step 5 (PR #85, проверка .rag dir вместо index.json) стало ясно что нужен раздел Troubleshooting — пользователи с Rust legacy артефактами (index.bin) могут столкнуться с неработающей памятью.

Решение

Расширить секцию ## Memory setup в README.md до 7 подсекций:

How it works — диаграмма пути, краткое описание hybrid search
Prerequisites — fork, OpenRouter key, .env пример
Initialize — Docker (auto) + bare metal (manual) пути
setup-memory.sh steps — 6 шагов скрипта (idempotent)
Verify it works — 4 команды end-to-end проверки
Troubleshooting — таблица 6 частых проблем + fixes
Environment variables — полная таблица 10 vars

Формат — таблицы и code blocks (не prose), чтобы копипастить команды напрямую. Стиль — как существующий README (English, concise).

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

Отдельный MEMORY.md файл — отклонено: дробит документацию, README уже содержит Structure/Configuration секции
Только в wiki — отклонено: wiki не versioned, теряется при fork
Оставить как было (3 строки) — отклонено: порог входа слишком высокий, приводит к баг-репортам вида "память не работает" без контекста

2.4 KiB Raw Blame History Unescape Escape