Retrieval

A recall is one call — POST /v1/memory/retrieve, search() in the SDKs or search_memory over MCP — that returns a single context: every memory type assembled, ranked and fitted to a token budget, plus a receiptId naming exactly what was delivered.

What comes backCopy Anchor Link

The response is a MemoryContext object. Sections are always present (empty when nothing matched):

Every entry carries its provenance (sourceKind, sourceRef, extractionMethod), bi-temporal fields, policy fields (visibility, ownerAgentId, classification), version and a read-time trust breakdown.

Finding candidatesCopy Anchor Link

Workspace memory is searched by several legs in parallel and the results are fused with reciprocal-rank fusion:

• Vector — embedding similarity (a minimum cosine similarity applies, retrieval.minVectorSimilarity, default 0.25)
• Full text — keyword search
• Graph — memories connected to strong matches by relationships
• Entity — memories that mention the same entities
• Episode derivatives — sentence-level fragments of past episodes

Before any leg runs, the caller's scope is compiled into it: tenant, workspace, application, visibility and (when given) userId and tag filters. A memory you may not see is never a candidate.

RankingCopy Anchor Link

Fused candidates are rescored with five factors — fusion rank, recency, access frequency, importance and confidence — and an adaptive score floor removes weak matches. Optionally:

• Value-aware selection blends each memory's learned utility (from outcomes) into the ranking. Off by default; enable it with the workspace setting retrieval.valueAware.enabled.
• Reranking asks the configured LLM to reorder the top results. It only happens in assisted mode.

Assisted vs deterministicCopy Anchor Link

Sending mode: "deterministic" together with rerank: true is contradictory and is rejected with 400.

Compiling the contextCopy Anchor Link

Ranked results are compiled into the response under a token budget, counted with a real tokenizer (cl100k). The default is the workspace setting retrieval.tokenBudget (4,000 tokens); a request can pass tokenBudget between 256 and 32,000.

• An item that does not fit is skipped, not the rest of its section.
• Platform policies and tenant floors are never truncated. If the requested budget cannot hold them, the request fails with 422 CONTEXT_BUDGET_TOO_SMALL and both numbers (requestedTokens, requiredTokens).
• compilation reports what was included and dropped per section.

Pass raw: true to skip the score floor and the budget entirely: topN is honoured literally and the context is returned untrimmed (useful for RAG and evaluation pipelines).

Superseded and historical memoriesCopy Anchor Link

Memories that a newer memory has replaced are hidden by default on every retrieval path. To see them:

• includeSuperseded: true returns them with supersededAt and supersededBy set.
• asOf slices the store at an instant, on the valid axis (what was true in the world — the default) or the transaction axis (what the system knew), chosen with asOfAxis.

The workspace setting retrieval.hideSuperseded can switch the default off.

Request optionsCopy Anchor Link

excludeSuperseded is still accepted for compatibility but ignored.

"Why was this recalled?"Copy Anchor Link

With explain: true, each entry gains an explanation — which legs found it with what rank and raw score, its fusion contribution, factor contributions, the floor, reranker status and trust — and the response gains diagnostics: candidates per leg, fused count, drops by reason (including policy drops), floors and stage latencies. Over MCP, search_memory(..., explain=true) appends a "Why recalled" section.

To check retrieval quality systematically, use the evaluation endpoint.