Implement layered maps and context retrieval

2026-06-11 12:56:18 +02:00
parent 010e4b83eb
commit c6064f8d94
35 changed files with 4410 additions and 383 deletions
@@ -0,0 +1,53 @@
+# 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:
+
+```bash
+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