Module orientation_cache 

v0.4.8 — Orientation cache: an opt-in, namespace-scoped, constant-token “context map” post-processor over the standard recall result set.

Anchor

arXiv:2605.19932 (PEEK — Prefix-Encoded Episodic Knowledge) shows that a small, token-budgeted “orientation map” maintained alongside an agent’s retrieval surface (key entities, constants, schemas that have been useful) helps the agent re-enter long-running contexts with a fraction of the recall payload. The default mnemo recall path (semantic, BM25, graph, recency) returns whole memory records; it has no notion of a distilled orientation summary.

The orientation cache runs after the normal recall result set is computed. Given a namespace (operator-chosen — typically (org_id, agent_id)), a Distiller extracts transferable knowledge from each hit (capitalized entities, UPPER_SNAKE = value constants, fenced schema fragments), and an Evictor enforces a fixed token budget. The recall response carries the resulting bounded map alongside top-k so the caller has both “what is in scope” and “what is relevant right now” in one payload.

Design contract

• Opt-in. Triggered only when RecallRequest::orientation_cache is Some AND the engine has an OrientationCacheStore attached via MnemoEngine::with_orientation_cache_store. The default read path is unchanged.
• Post-processor, not a replacement. Runs over whatever candidates the underlying RetrievalMode produced. Does not re-issue a query.
• Constant-token guarantee. Each rendered map is bounded by the caller’s token_budget (default 512). The Evictor drops entries by priority = freq × recency × (1 - token_share) until the rendered map fits.
• Namespace-scoped. The in-memory store is keyed by (org_id, agent_id) (or "__global__" if neither is set). Updates from one namespace never bleed into another.
• Deterministic distiller. Pure regex/heuristic extraction — no LLM call, no network. Keeps the recall hot path predictable and the bench reproducible.

What this module is NOT

• Not a write-side memory consolidator. It only summarises hits as they pass through recall; it does not rewrite or compact memories on disk.
• Not a learned summariser. The Distiller is heuristic by choice (v0.4.8 ships the deterministic core; an LLM-backed variant is parked for v0.5.x). Treat extracted entries as pointers, not paraphrases.
• Not a context-window extender. The map fits inside the recall response and is bounded by the caller’s token budget. It does not bypass any model context limit.
• Not a faithful PEEK reproduction. PEEK uses a learned prefix encoder and a write-side update path. This module adopts the orientation map + constant-token budget shape only; faithfulness is left to operators who can plug an embedder/LLM behind the Distiller trait in a follow-up cut.
• Not persisted. The store is in-process (Arc<RwLock<HashMap<..>>>). Restart drops it. Persistence to DuckDB / Postgres is a v0.5.x knob, documented in the v0.4.8 CHANGELOG entry.

Structs

ContextMap

Per-namespace context state held by the OrientationCacheStore.

DistillerOutput

Distiller output bucketed by knowledge kind.

Entry

Internal entry in a ContextMap.

OrientationCacheConfig

Opt-in config for the orientation cache. Carried on RecallRequest::orientation_cache.

OrientationCacheStore

In-process per-engine store. Keyed by namespace string.

RenderedContextMap

Bounded, serialisable rendering of a ContextMap returned in the recall response.

RenderedEntry

One rendered entry of a RenderedContextMap.

Constants

DEFAULT_TOKEN_BUDGET

Default token budget per rendered context map.

GLOBAL_NAMESPACE

Default namespace when neither org_id nor agent_id is supplied.

Functions

distill

Heuristic distiller. Pure-Rust, regex-free, deterministic.

resolve_namespace

Derive a namespace key from (operator override, org_id, agent_id).

update_and_render

Update the per-namespace map with the hits and return a bounded rendering. Called from recall::execute when both RecallRequest::orientation_cache is Some and the engine has an OrientationCacheStore attached.