Zephr Docs

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

SurfaceTierResidencyNotes
zephr_recall (MCP)coreresidentHybrid lexical + semantic recall of eligible beliefs
zephr_search (MCP)searchresidentUnified search across admitted worktrees
zephr_grep / zephr_graph_query (MCP)searchdeferredLexical 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

  1. One read path — partial. Local RecallService and 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).
  2. 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 (RecallService and hosted memory recall both call the calibration authority before disclosing calibrated probability) — the code/lens tiers are not yet calibrated through the same authority.
  3. 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.
  4. Disclosure. Retrieval reads the belief layer and never the observation ledger — L0 reaches agent context only via Layer 3's zephr_get_observations handle 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.