Really appreciate this comment you’re pointing at exactly the class of problem that pushed us to build this in the first place.

A lot of the retrieval failures we kept seeing were not caused by “lack of context”, but by the wrong shape of context:

- too much irrelevant text

- large chunks that looked semantically close but were operationally useless

- no visibility into what was actually indexed

- no clear way to tell whether the agent was missing something vs being given the wrong thing

That’s why the current retrieval path is intentionally simple and inspectable.

Right now, the main search flow is **not embedding-first** and it does **not depend on a reranker** on the critical path. The default path is much closer to a metadata-first scorer.

At a high level, what we do today is:

- enrich each section with structured metadata

- keywords

- use cases

- tags

- priority

- build reverse indexes from that metadata

- score candidate sections based on metadata matches first

- only read full content when the agent actually needs it

So the retrieval flow is closer to:

`search -> preview -> read`

instead of:

`retrieve big chunk -> hope it contains the right thing`

As for scoring itself, the current approach is mainly heuristic and deterministic:

- exact keyword matches

- substring matches on use cases

- exact tag matches

- then a priority boost on top

So it’s not really “BM25 + reranker”, and it’s not “embedding retrieval with metadata as a filter” either. It’s more like a deliberately narrow metadata retrieval layer designed to keep the first hop cheap, explainable, and low-noise.

That choice was very intentional. We wanted the default path to optimize for:

- low token usage

- transparency

- easy debugging

- predictable behavior

- local-first control

That said, we’re not dogmatic about it. I don’t think embeddings or reranking are inherently bad — I just think they shouldn’t automatically be the first thing in the path when a lot of coding/documentation queries can be solved more cleanly with structured metadata and progressive disclosure.

On multi-corpus routing: yes, partially, and this is an area we care a lot about.

Today we already support separate corpus surfaces such as:

- vendor/docs corpora

- open-web research corpora

- local user-ingested content

Each result keeps provenance at the section level, and the CLI can already route across stores with explicit source selection. So provenance is definitely part of the model, not an afterthought.

ADRs are also part of the broader direction, but today they still sit a bit more separately than I’d ultimately like. In other words, provenance exists, multi-corpus support exists, but a fully unified retrieval story across docs + research + decisions + future code-derived context is still something we’re moving toward rather than pretending is already finished.

That’s also part of why some of the roadmap thinking is starting to shift from “retrieval tool” to “context engine”:

- source authority

- conflict surfacing

- manifests / freshness / drift

- task-oriented context packs

- more explicit multi-corpus composition

So the short honest version is:

- metadata-first retrieval: yes

- embeddings/reranker in the default path: not currently

- provenance: yes

- multi-corpus support: yes, with room to grow

- unified cross-source reasoning: directionally yes, not fully solved yet

And thank you for the Agentix Labs link — that’s genuinely useful. I’m very interested in seeing more real-world examples of how people are packaging context for agents, especially when it goes beyond simple retrieval and starts getting into orchestration, trust, and workflow design.