Demand-shaped context

How It Works

Pelorus keeps the normal RAG path of retrieving source chunks, then adds a demand-shaped layer above it. As users and agents ask real questions, repeated needs can become source-grounded Extracts that are easier to inspect, reuse, and improve.

What an Extract contains

An Extract is a self-contained, source-grounded data packet built to accommodate an associated query, or a cluster of related queries for a Cluster Extract. It is true to the corpus, but shaped around the user need rather than the original document boundary. The cited chunks are always there — they are the grounding, and everything else traces back to them. The remaining fields are shaped by the Extract creation strategy; taken together they should accommodate the associated query or queries while staying faithful to the corpus.

Extract

Strategy-shaped data packet

Context Terms, scope, and key insights needed to interpret the content or excerpts correctly. Example: define policy terms, date ranges, product names, or assumptions from the corpus.

Content An information-dense summary of the cited chunks — faithful to them, and self-contained enough to stand in for them. When current, this is what gets served. Nothing is paraphrased away: the summary may resolve a pronoun or spell out an entity so it reads standalone, but every claim in it traces to the chunks it normalises.

Cited chunks The corpus chunks the Extract is grounded in, by id. This is the grounding — everything the Extract says traces back to them. When no summary is current, these chunks are what gets served, so the Extract is always answerable from the corpus itself.

Excerpts The verbatim passages the extractor selected while working. Kept for tracing and evaluation — never part of what is served. Verbatim is required, not stylistic: excerpts are matched back to their chunks by exact text, which is how cited chunk ids are established. Rewriting one — even to clarify a pronoun — breaks that link. Clarification belongs in the summary or in context.

Notes Caveats, limits, contradictions, or interpretation details. Example: what should not be assumed, where the source is incomplete, or why the Extract is scoped narrowly.

What gets matched, what gets returned

Pelorus decouples the thing being matched from the data returned. An incoming query is matched against a stored query or a cluster of related queries, because query-to-query similarity is usually a cleaner signal than query-to-chunk similarity. The matched target then returns its associated Extract: a custom data packet shaped to answer that query or cluster while accurately representing the corpus.

Matched target Query Observed user message stored as a vector.

Returned data Extract Curated packet for that query.

Matched target Cluster Member queries with a centroid or classifier.

Returned data Extract Curated packet for related queries.

Matching is not a single winner-take-all path. If a query matches overlapping clusters, Pelorus can return both Cluster Extracts. If a specific Query Extract or document chunks are close enough under the retrieval settings, those can surface too. Cluster coverage is meant to give unseen queries useful context, while still allowing more specific Extracts and chunks to handle nuance.

Aside: Know your embedding model. Every match on this page — query to Query Extract, query to chunk, query to cluster boundary — is a similarity score in the units of one specific embedding model, and those units are narrower and stranger than the textbook -1 to 1 range suggests. Understanding how the model behaves is the difference between tuning thresholds deliberately and guessing. See Know Your Embedding Model for what scores really mean, what the default model does, and what to re-check when integrating another one.

Query Extracts

A Query Extract couples one observed query with one Extract. The query is the matching surface; the Extract is the information served when an incoming query matches that stored query closely. This makes repeated queries concrete objects you can inspect and curate.

Cluster Extracts

A Cluster Extract couples a cluster of related queries with one Extract. Cluster matching is handled separately from query-vector matching: a cluster can use a centroid with a proximity threshold, or a trained classification model for harder shapes. The matched cluster returns its associated Extract.

What happens when a query runs

A runtime query returns from what Pelorus already knows. It can match one or more Cluster Extracts, match a close Query Extract, include closely related document chunks, fall back to chunks when no Extract fits, or return a miss. Normal query handling does not build a new Extract before responding.

Incoming queries can match Cluster Extracts, match Query Extracts, fall back to document chunks, and create demand that later becomes a new Extract. — Runtime query flow

The adaptive part happens after the response. When a useful chunk fallback exposes unmet demand, Pelorus can queue asynchronous Extract creation. The next similar query can then reuse a curated Extract instead of relying only on document chunks.

Semantic retrieval paths

Queries

Cluster Extracts

Matched by cluster boundaries around related queries.

Query Extracts

Matched query-to-query against vectorized queries.

Chunks

Matched by comparing the incoming query to chunk vectors.

Gaps and partial coverage

Not every observed need can be answered accurately from the corpus. Pelorus can preserve that outcome as missing or partial coverage, so the same gap is visible instead of repeatedly disappearing into retrieval misses. As more demand arrives, you can tune thresholds, refine Extracts, split or merge clusters, or decide the corpus itself needs new source material.

Questions your corpus cannot answer

A plain vector store has no way to say “nothing here answers that.” Top-K is a structural promise: ask it something your documents never covered and it still returns K passages, ranked, with scores attached. The absence of an answer looks exactly like the presence of a weak one, and the difference only surfaces downstream, in whatever your LLM decides to do with material that does not answer the question. Pelorus treats that case as an outcome worth keeping.

The gap is recorded once. When a query arrives that nothing in the corpus answers, Pelorus records the query together with that outcome. The next time the same question is asked it matches the recorded outcome instead of raising fresh extraction demand — so a question your corpus cannot answer stops costing you an extraction every time somebody asks it.
It stays visible as a gap. Not serving is not deleting. The record keeps existing and keeps matching, which is what puts the gap on the Query Map and into the supply-and-demand analytics rather than letting it disappear into a stream of near-miss retrievals.
It is never served as a ranked result. A recorded absence can never be sorted, hold a rank against content, or spend a slot in the result budget alongside other candidates. That gate matters more than it sounds: a recorded “nothing answers this” matches its own query almost perfectly, so without it the record would take the top slot and push the real source passages out.
A verified gap is served as a disclosure, alone. When every curated candidate is withheld and one of them is a verified gap — the corpus was searched and confirmed to have no answer — the response serves that absence as a single labeled item, and nothing else. No chunks ride alongside it: a disclosure of absence sitting next to five plausible-looking answerless chunks would undo the point of disclosing it. The label travels through both runtimes (is_gap on the served item, pelorus_gap in analytics row metadata) so a consumer can say “I don't know” because it was told, grounded in a served fact about the response, rather than because it declined to trust passages it was handed.

Designed: not yet built

Freshness for a recorded gap. A recorded “nothing answers this” is a claim about the corpus, and unlike an ordinary Extract it cites no source passages — so nothing ties it to the material it is a claim about. Add a document and the claim can quietly become wrong. Re-validating these records when the corpus changes is designed and not built; it belongs with cite re-resolution on a re-chunk, because the claim needs re-checking rather than discarding. Its other job — keeping the same question from re-queueing extraction work forever — stays correct either way. (Staleness detection already runs continuously and still raises re-extraction demand when the corpus contradicts a recorded gap; only the re-validation-on-change piece is unbuilt.)

Summary

Cluster matching can serve broad areas of related demand by matching a query against a cluster boundary and returning the associated Cluster Extract.
Query matching handles more specific needs by comparing the incoming query to vectorized queries attached to Query Extracts.
Chunk fallback remains available when no Extract is strong enough, so retrieval can still return source passages from the underlying corpus.
Thresholds are configurable. Cluster Extracts, Query Extracts, and chunks surface based on match settings instead of fixed proximity labels.
Overlap is expected. A query can genuinely fit more than one cluster, and a narrower query or chunk match can still surface when it provides better coverage.
Traffic becomes visible. Repeated user needs become durable queries that can be inspected, clustered, curated, and used to create better Extracts.
A question the corpus cannot answer is an outcome, not a miss. The gap is recorded once, stays visible in analytics, and is never served as an answer — retrieval falls back to document chunks.
Coverage evolves as more traffic arrives. You can grow, split, overlap, and refine queries and clusters as demand changes or drifts in real time.