2.0 KiB
Proposal: Map Context Retrieval
Status
| Field | Value |
|---|---|
| Phase | Proposal |
| Based on | Follow-up to layered-map-protocol |
| Next | Spec |
Problem
After the layered map protocol lands, the agent will know it should load root protocol + root index first, then route through per-directory indexes and rich maps. But the repo will still lack an ergonomic retrieval primitive that can turn a natural-language task into a compact context bundle.
Without that helper, the agent still has to manually inspect directory indexes, rank candidate areas, and expand to rich maps/files. That weakens the value of the new routing layer.
Proposed change
Add a retrieval tool and command shape:
project-map context "<user task>"
The first-class surface should be a Pi tool. CLI support can follow the same shape.
The retrieval result should return a compact context bundle containing:
- relevant indexes,
- strongest-match rich maps,
- likely source files,
- relevant symbols when useful,
- short instructions on what to read next.
This remains a local metadata-driven retrieval feature, not a vector-store or Engram-backed memory system.
In scope
- Add Pi tool support for
project-map context <query> - Add CLI support using the same shape after the tool contract is stable
- Rank results using paired index/map metadata from the layered protocol
- Return a compact, markdown-first, agent-friendly context bundle
- Document recommended usage from prompts and docs
Out of scope
- Full semantic search across arbitrary source contents
- Replacing source verification with map-based answers
- Building a heavyweight external indexer or vector database
Success criteria
- A natural-language task can resolve to likely indexes/maps/files/symbols without manual repo scanning
- Output is compact enough to inject directly into the next step
- Retrieval builds on generated paired metadata rather than bypassing it
- The first version is tool-first and markdown-first