Module retrieval 

Optional read-cache decorator over a single backend recall.

RetrievalPipeline wraps a Memory trait object and composes as an outermost decorator around any backend (or wrapper stack). Its only behavioral add-on is an optional in-process hot cache over recall results. When the cache is off the decorator is a transparent pass-through and recall is byte-identical to the inner backend.

Memory exposes a single hybrid backend-recall operation today, so the decorator makes exactly one backend recall per query. It does NOT split that call into distinct FTS and vector stages: [memory] retrieval_stages only toggles the hot cache (via a "cache" entry), and the "fts" / "vector" names plus fts_early_return_score are reserved for a future backend contract that exposes those operations. They are inert today.

Cache coherence: the hot cache is per-handle and in-process, and it is OFF by default (the shipped retrieval_stages default carries no "cache"), so activating the decorator does not change default per-agent recall. When a caller opts the cache in, within-handle correctness is guaranteed by a generation counter (a recall that began before a mutation cannot repopulate the cache after that mutation cleared it) and by invalidating on every mutation attempt, including a backend error. Cross-handle / cross-process coherence over a shared store is intentionally out of scope and remains a documented limitation of the opt-in cache.

Structs

RetrievalConfig

Configuration for the RetrievalPipeline decorator.

RetrievalPipeline

Optional-cache decorator wrapping a Memory backend.