# 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 строки)** — отклонено: порог входа слишком высокий, приводит к баг-репортам вида "память не работает" без контекста