Retrieval
Retrieval is the single read path across the memory belief layer and the code-intelligence tiers. It owns fusion of heterogeneous rankers, trust-aware ranking, abstention, candidate re-authorization, and the cross-backend ranking-parity gate. It does not own how evidence is written (Memory), review state (Trust), or the internals of any code tier (Code intelligence) — it consumes all of them and is answerable for what is finally disclosed.
Availability
| Surface | Tier | Residency | Notes |
|---|---|---|---|
zephr_recall (MCP) | core | resident | Hybrid lexical + semantic recall of eligible beliefs |
zephr_search (MCP) | search | resident | Unified search across admitted worktrees |
zephr_grep / zephr_graph_query (MCP) | search | deferred | Lexical and graph tiers |
zephr recall, search, grep (CLI) | — | — | See the CLI reference |
Recall is never billed — ranking and disclosure carry no price components
and exhaustion never suspends a tenant. Fair-use rate ceilings still apply
on the retrieval surfaces: per-identity hourly and burst quotas by tier (pro
is the default on the local transport). An over-limit call is refused with a
structured capacity_exceeded / rate_limited response and an upgrade hint —
throttled, never charged.
How it works
- One read path — partial. Local
RecallServiceand hosted memory recall share one fused pipeline: rank-only RRF over the lexical and semantic channels, calibration, and trust-aware ranking, with scope filtering on both channels. The read path over code is still separate — grep/LSP and graph queries run through their own tools — and the single planner that would refuse a tier bypass is specified, not built (see Status honesty). - Fusion. Ranks are combined, never raw scores; the fusion policy is
versioned and recorded per hit. Calibration to a comparable probability is
implemented on the memory fuse path (
RecallServiceand hosted memory recall both call the calibration authority before disclosing calibrated probability) — the code/lens tiers are not yet calibrated through the same authority. - Trust-aware ranking. Review state and staleness demote candidates; a contradiction at the top of the ranking forces an abstention. Every vector hit is a candidate until re-authorized against review state — and re-authorization is never cached across a review-state change.
- Disclosure. Retrieval reads the belief layer and never the observation
ledger — L0 reaches agent context only via Layer 3's
zephr_get_observationshandle lookup. Typed exclusion records are specified, not built: candidates dropped by policy, review state, or authorization are dropped silently today (see Status honesty).
Status honesty
Shipped and CI-enforced: local RecallService recall, the local + hosted
memory fuse (rank-only RRF, calibration, trust tie-breaks), and the
cross-backend ranking parity gate (parity-bench exit 1 and exit 2 both fail
CI). Partial: the read path over code (grep/LSP/graph) is not unified through
the fused memory pipeline, and calibration is live on the memory fuse path
only. Specified but not built on any read path today: intent
classification / query rewrite planning, cross-encoder reranking (fusion order
is served directly), typed exclusion records (policy-filtered candidates still
drop silently), and a single planner that refuses tier bypass. Don't build on
those behaviors yet.
Abstention
Insufficient evidence returns a structured abstention — never a plausible guess:
- Kinds are enumerated and distinguishable; thresholds are configurable per caller and bounded.
- An abstention publishes coverage (what was searched), not just its refusal.
- Abstention never degrades into a guess downstream.
Persistence, security, observability
Retrieval is read-only over the belief layer and code tiers; persistence is owned by memory and code intelligence and the storage topology is described in Architecture. Scope binding decides what a query may see (ref-scoped evidence is filtered by the requesting ref; commons grants widen reads without widening the tenant). Retrieval is deterministic for identical inputs, which makes reported quality reproducible; a machine-readable retrieval explanation with per-hit serving tuples and typed exclusion records is specified, not built (see Status honesty).
Limits and failures
- Reranking has a latency ceiling and is skippable; latency is budgeted per rung and enforced.
- Staleness demotes results and can refuse the query outright.
- No provenance, no disclosure — an unprovenanced hit is not returned.
- Degradation is honest, never silent: when a tier or backend fails, the response says so.
- Partition-local lexical statistics are never compared across partitions; backend lexical divergence is disclosed to the caller.
Recall-quality and stale-index symptoms are covered in Troubleshooting.