MemoryService

Return the canonical exact Memory Revision matching memory.

Return the current head of the same Memory identity.

Return history in ascending order within (since_revision, through_revision].

The upper bound defaults to the current head. The history limit applies to the requested interval, and oversized intervals are never truncated.

Return the current Memory head by its stable Artifact identity.

Measure an exact Revision, including eligible tombstones even when compaction is disabled.

Eligibility can load complete manifests across the tombstone recovery window. Cost scales with their combined size; this is not a cheap counter.

Drop aged, untagged tombstones; retain every prior Revision and entry body.

Previews are available while compaction is disabled. Reclaimed bytes are the signed difference of complete canonical contents, including the audit changes and reason, which can outweigh a small manifest reduction.

Return the current Memory head together with its validated entry objects.

entries re-reads the caller's Memory to prove it matches storage, which a head read straight from the backend already satisfies. Callers that need both the head and its entries use this instead, so a read-only pass over many Scopes does not re-fetch every Memory Revision it just loaded.

Return one exact Memory Revision by its stable reference.

Append or extract validated entry changes against one exact head.

Validate and prepare a write without mutating authoritative storage.

Apply one prepared write through this service's transaction boundary.

Deactivate logical entries without deleting immutable content.

Restore inactive logical entries without creating body versions.

Apply only exact deduplication and canonical normalization.

Read compact change summaries without expanding entry bodies.

Search explicit current Memory heads with capability-safe fallback.

admission=None applies the historical fusion-time thresholds bit for bit.

query_embedding lets a caller reuse a vector it already paid for (RFC 1560's expansion rounds reuse the round-0 vector). Reuse is best-effort and honest: it is applied only when the supplied profile equals the one this search resolved, and the call reports embedding_calls = 0 in that case, 1 when it embedded. The resolved vector is handed back on :attr:MemorySearchResult.query_embedding so the next round can reuse it. When the mode resolved to fts there is no vector to report, so the field stays None and the next round must pay again.

Resolve — or reuse — the query vector for a vector or hybrid search.

Returns (selected_mode, query_vector, resolved_embedding, embedding_calls). resolved_embedding is None exactly when the search fell back to fts, which is also when the caller must drop the embedding profile from the backend request.

Reuse applies only when the supplied profile equals the resolved one; otherwise the round embeds and reports one call. A failed embedding is still counted as one call, because the call was issued — the cost is real even though it produced nothing.

Apply the optional reranker and report what this search paid and admitted.

generation_calls counts the RFC 0080 rerank call this search actually issued: 1 when the reranker ran over a non-empty pool, 0 otherwise. It is never inferred from configuration — a deployment whose rerank flag is on but whose reranker did not run reports 0, which is the honest number.

Expand exact hit anchors and reject cross-Revision substitutions.

Return the entry objects referenced by one exact current Memory head.

Rebuild current-head search projections from authoritative Memory revisions.

Resolve one exact Handoff citation.

Build active-head projections, reusing unchanged vectors and embedding only changes.

Ask the configured gate about one candidate set; None means no gate is active.