4cb50a4824
* 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>
29 lines
No EOL
2.4 KiB
Markdown
29 lines
No EOL
2.4 KiB
Markdown
# 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 подсекций:
|
||
1. How it works — диаграмма пути, краткое описание hybrid search
|
||
2. Prerequisites — fork, OpenRouter key, .env пример
|
||
3. Initialize — Docker (auto) + bare metal (manual) пути
|
||
4. setup-memory.sh steps — 6 шагов скрипта (idempotent)
|
||
5. Verify it works — 4 команды end-to-end проверки
|
||
6. Troubleshooting — таблица 6 частых проблем + fixes
|
||
7. Environment variables — полная таблица 10 vars
|
||
|
||
Формат — таблицы и code blocks (не prose), чтобы копипастить команды напрямую. Стиль — как существующий README (English, concise).
|
||
|
||
## Альтернативы
|
||
|
||
- **Отдельный MEMORY.md файл** — отклонено: дробит документацию, README уже содержит Structure/Configuration секции
|
||
- **Только в wiki** — отклонено: wiki не versioned, теряется при fork
|
||
- **Оставить как было (3 строки)** — отклонено: порог входа слишком высокий, приводит к баг-репортам вида "память не работает" без контекста |