# v2.2 Advanced Retrieval Implementation Plan

> Goal: Improve recall relevance while keeping the default behavior safe and fast. Ship LLM re-ranking off by default, but allow local-only re-ranking to be enabled per-install.

## Scope
- Add query expansion (cheap heuristics) behind a config flag.
- Add LLM re-ranking behind config flags, default off.
- Add feedback capture tool (thumbs up/down) and apply it as a light ranking penalty/boost.
- Add slow-query logs (already present) to include rerank + QMD timings (metadata-only).

## Files
- Modify: `src/types.ts`, `src/config.ts`, `openclaw.plugin.json`
- Add: `src/retrieval.ts`, `src/rerank.ts`, `src/relevance.ts`
- Modify: `src/orchestrator.ts`, `src/local-llm.ts`, `src/tools.ts`
- Add: `tests/retrieval.test.ts`
- Modify: `package.json` (add `test` script)
- Docs: `README.md` + optional `docs/advanced-retrieval.md`

## Tasks (TDD)
1. Add `tests/retrieval.test.ts` for:
   - query expansion returns original query first and at least one expansion for multi-word input.
   - rerank response parsing handles missing/extra ids deterministically.
2. Implement minimal `expandQuery()` + parser to make tests pass.
3. Wire query expansion into `Orchestrator.recallInternal()` behind `queryExpansionEnabled`.
4. Implement local-only rerank:
   - timeboxed (`rerankTimeoutMs`)
   - capped candidates (`rerankMaxCandidates`)
   - fail-open (keep original order on error)
   - optional in-memory cache
5. Add `memory_feedback` tool:
   - store up/down votes in `state/relevance.json`
   - apply small boost/penalty during `boostSearchResults`
6. Update `README.md` + plugin schema docs:
   - defaults off, how to enable local-only rerank in `openclaw.json`
7. Verify:
   - `npm run check-types`
   - `npm run build`
   - `npm test`

