Struct MemorySession 

pub struct MemorySession { /* private fields */ }

Everything scoped to one logical conversation.

Implementations

impl MemorySession

pub fn session_id(&self) -> &SessionId

The logical conversation this session represents.

pub fn ledger(&self) -> &Arc<InMemorySessionLedger>

The candidate ledger.

pub fn retriever(&self) -> &Arc<LocalMemoryRetriever>

The retriever serving this session.

pub fn memory_map(&self) -> String

The vocabulary a model needs in order to fill recall_context’s about and attribute fields.

Put this in the system instruction. Without it a model names the right predicate 2% of the time, which is below the 8% at which filtering starts paying for itself; with it, 69%. It is a few hundred tokens and bounded by the user’s vocabulary rather than by how much they have accumulated — 282 tokens at 16,000 records. See crate::retrieval::vocabulary.

Recomputed only when the canonical index has moved, so calling this every turn is cheap.

pub fn config(&self) -> &MemoryRuntimeConfig

The runtime configuration this session was opened with.

pub fn begin_turn(&self, turn_id: TurnId) -> u64

Freeze the prepared snapshot for a turn that is starting.

Everything the model is answered with for this turn comes from the snapshot taken here, so a retrieval landing mid-response cannot change what B appears to remember halfway through a sentence.

pub fn current_turn(&self) -> TurnId

The turn currently in flight.

pub fn active_snapshot(&self) -> PreparedMemorySnapshot

The snapshot the current turn is being answered from.

pub fn prepared_snapshot(&self) -> PreparedMemorySnapshot

The most recently prepared snapshot, whether or not a turn is using it.

pub fn generation(&self) -> &GenerationGuard

The generation guard, for cancelling stale speculative work.

pub async fn prepare( &self, turn_id: TurnId, transcript: &str, ) -> Result<PreparedMemorySnapshot, MemoryError>

Prepare context speculatively from a transcript.

Publishes the resulting snapshot only if the conversation has not moved on since the work started.

pub async fn recall(&self, query: &str, turn_id: TurnId) -> Value

Serve a recall_context tool call.

Reads the frozen snapshot when it plainly covers the query, and otherwise runs a live local search and fuses the snapshot into it. The search is bounded and never reaches the network.

The fusion is the part worth explaining. satisfies decides the fast path by word overlap between the question and the prepared statements — which is the right test for “can I skip the search entirely” and the wrong one for “is this snapshot any good”. Measured against snapshots that already contained the answer, it refused 65 of 93 paraphrased questions, and refused hardest exactly where speculation is most valuable: 0 of 6 asked in-situ, 1 of 20 needing a step of inference. Every one of those refusals threw away a correct answer and replaced it with a lexical search that could not find one.

So a refusal no longer discards the snapshot; it demotes it to one ranking among two. That also gives the speculative path somewhere to deliver: it runs with a 100 ms semantic budget where this path has 10, so a remote backend’s results reach the model here or nowhere.

pub async fn recall_scoped( &self, query: &str, turn_id: TurnId, scope: RecallScope, about: Option<String>, attribute: Option<String>, ) -> Value

Serve a recall_context tool call restricted to a scope or narrowed by the caller’s about/attribute hints.

An unrestricted, unhinted recall may be answered from the frozen snapshot. Anything else runs a live local search, because the snapshot was prepared speculatively and knows neither the restriction nor the hints — serving it would answer a different question quickly.

The hints only ever reorder. See RetrievalPlan::subject_hint for why they must not do more than that.

pub async fn observe_final_transcript( &self, turn_id: TurnId, transcript: &str, ) -> Result<Vec<LedgerOutcome>, MemoryError>

Record a finalized user turn: durable evidence, then extraction.

The transcript event is appended before extraction runs, so a crash between the two loses an extraction that can be retried rather than the evidence itself.

pub async fn on_turn_complete( &self, turn_id: TurnId, ) -> Result<Vec<ScheduledWork>, MemoryError>

Complete a turn and run whatever the cadence says is now due.

pub fn is_idle(&self) -> bool

Whether the session has been idle long enough to seal.

pub async fn finish(&self) -> Result<ReconciliationReport, MemoryError>

Seal the session and reconcile its evidence into canonical memory.

Idempotent by session id: reconciling twice commits once.

pub async fn apply_explicit_command( &self, intent: MutationIntent, statement: &str, turn_id: TurnId, ) -> Result<Value, MemoryError>

Apply an explicit memory command from the user.

Explicit intent takes effect in the conversation immediately and commits durably afterwards. The durable event is appended before the overlay is touched, so the engine never tells a user their correction was recorded when it was not.

pub fn known_predicates(&self) -> Vec<String>

The predicate names this user’s corpus already uses.

Offered to the extraction model so a correction lands on the predicate it is correcting. Reconciliation matches on subject and predicate; a model free to name each fact afresh writes dietary_preference in one session and dietary_identity in the next, and “actually I’m pescatarian now” becomes a second active record rather than superseding the first. This is the entity table’s trick applied to predicates: the vocabulary comes from the corpus.

Bounded, because it goes in a prompt. Session candidates come first — a correction usually chases something said minutes ago.

pub fn known_values(&self) -> Vec<(CanonicalPredicate, Value)>

The predicate/value pairs memory can currently assert.

Session facts shadow canonical ones: something the user said this conversation is a better answer than something recalled from months ago.

pub fn known_statements(&self) -> Vec<String>

Every statement currently retrievable, canonical and provisional.

pub fn pending_explicit_commands(&self) -> Vec<MutationIntent>

Everything the user has explicitly asked to be remembered this session.