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>
2.4 KiB
2.4 KiB
pr: 86 title: docs(readme): add memory setup instructions with troubleshooting
Что сделано
Расширил секцию ## Memory setup в README.md — с 3 строк до полной инструкции:
- How it works — ASCII-диаграмма пути plugin → wrapper → Python CLI → OpenRouter
- Prerequisites — fork memory repo, получить OpenRouter key, заполнить .env (с примером блока)
- Initialize — два пути: Docker (recommended, авто-инициализация) + bare metal (uv sync + ручной запуск)
- setup-memory.sh steps — 6 шагов что делает скрипт (idempotent, безопасно перезапускать)
- Verify it works — 4 команды для end-to-end проверки (wrapper content, meta format, .rag/ listing, search через wrapper)
- Troubleshooting — таблица из 6 частых проблем + fixes (semantic unavailable, no scores, version mismatch, env not set, 429 rate limit, stale Rust artifacts)
- Environment variables — полная таблица из 10 vars с defaults и описанием
Почему
После PR #75/#77/#83 память заработала end-to-end, но README не объяснял как её развернуть с нуля. Пользователь (и будущие контрибьюторы) не знали: какие ключи нужны, как проверить что wrapper перезаписан, что делать со stale Rust артефактами. Теперь README содержит полный flow от clone до verify — снижает порог входа и количество вопросов.
Pending
—
Watch out
- Troubleshooting таблица ссылается на
index.bin(Rust артефакт) — если через 2-3 месяца все мигрируют на Python CLI, строку можно убрать - Environment variables таблица дублирует часть Configuration таблицы выше — намеренно (Memory vars сгруппированы отдельно для контекста)
- Verify commands используют
$OPENCODE_MEMORY_DIR— в Docker это/root/.local/share/opencode/opencode-memory(задаётся в docker-compose.yml), на bare metal — env var