Module memory_context 

Typed continuous-memory context domain model (task A1).

Implements the closed domain types from the continuous-memory spec:

• §6.1 MemoryContextMode with exact automatic-recall / turn-capture / lifetime semantics,
• §6.2 MemoryContextLease — host-private construction, no Deserialize,
• §6.3 UserIntentProof,
• §19 AuthorizedMemoryAction / apply_memory_context_action and the exhaustive SessionMemoryState transition table.

Authority pattern: like crate::orchestration::validate_user_authorizable_model, untrusted callers (plugins, models, extension JSON) can never mint authority. A MemoryContextLease can only be produced by crate-internal host code via the pub(crate) MemoryContextLease::grant gate, and the struct is #[non_exhaustive] with no Deserialize impl, so neither struct-literal construction nor wire deserialization can forge one outside this crate.

Style (spec §19): typed boundaries and exhaustive enums — no enabled: bool flags, no serde_json::Value past the boundary, no model-created lease IDs, no content-bearing errors.

Structs

BoundedUserQuery

Bounded recall query (spec §6.4). Host-derived from the current user prompt and byte-bounded at construction through the workspace-standard BoundedText budgeting utility — truncation is safe here (the host is shrinking its OWN outbound query, not repairing untrusted input) and is recorded, never silent. No raw String escapes the boundary.

ConfirmationId

Identity of a host-driven confirmation exchange (spec §6.3 ConfirmedPrompt).

ContextDigest

Fixed-size digest of the recent context window (spec §6.4) — proves what the host summarized without shipping the transcript. Host-computed only.

ContextProviderId

Manifest-declared context-provider identity (spec §7.1).

ContributionAccounting

Provider-reported recall accounting (spec §6.5, §10.4): bounded counters only — never content.

ContributionSchemaVersion

Version of the contribution schema a provider produced (spec §6.5). Parse-at-the-boundary: empty/oversized/control input fails closed, so a constructed value is never empty.

DisclosureGrantSet

Bounded set of DisclosureClass values the host is willing to accept back in a contribution (spec §6.4 permitted_classes). Deduplicated at construction; bounded by the closed six-variant vocabulary itself. A provider record whose class is outside this set is rejected by validate_contribution — a plugin cannot volunteer classes the host never authorized.

MemoryContextCapability

Session-scoped memory-context capability handed to tool contexts (task A4), mirroring the shape of crate::mcp::McpLeaseCapability and crate::extensions::lease::ExtensionLeaseCapability: a small Clone handle over the shared per-session SessionMemoryState that the memory_context builtin uses to read and mutate memory-context state.

MemoryContextContribution

A provider’s recall contribution for one turn (spec §6.5, verbatim shape). The host accepts one only through validate_contribution — project identity, schema, and bounds are checked before it may influence budgeting or (in task B4) request assembly.

MemoryContextLease

A host-granted continuous-memory lease (spec §6.2).

MemoryContextStatus

Typed, content-free status of a session’s memory context.

MemoryContributionRecord

One record inside a recall contribution (spec §6.5, verbatim shape). Content fields are BoundedText — byte-bounded at construction, exact truncation accounting preserved.

MemoryId

Identity of one stored memory record (spec §6.5).

MemoryLeaseId

Host-minted lease identity (spec §6.2). Model-created lease IDs are an explicitly unsafe pattern (spec §19); only MemoryContextLease::grant callers mint these.

MemoryObservabilityEvent

One spec §15 metadata-only observability event. Every field is drawn from the §15 ALLOWED list — session/turn correlation IDs, the host-derived project digest identity (never a raw project path), provider ID, mode, record counts, byte/token accounting, duration buckets, disclosure/withholding counts, and a typed outcome code. The struct has no field that could carry user messages, memory bodies, raw tool results, credentials, or provider error text, so the §15 DISALLOWED list is excluded by construction, not by discipline.

MessageDigest

Digest of the exact current user message proving it directly names the requested memory transition (spec §6.3 ExactCurrentRequest).

ProjectId

Project isolation boundary (spec §5.2).

RecallBudget

Engine-authored recall budget (spec §6.4, §10.3). Parse-constructed from the ENGINE’S own memory_budget_tokens output — a provider never chooses its budget, and a value outside the §10.3 floor/ceiling fails closed at construction.

RecallRequest

One recall request the host sends a context provider (spec §6.4, verbatim shape). Every field is a bounded, parse-constructed type with a crate-private constructor, so the request can only be assembled by host code: it carries no credentials, no unrelated project paths, no hidden system instructions, and no unbounded transcript.

RecallSchemaVersion

Version of the recall-request schema the host produced (spec §6.4).

RecallTurnMetadata

Spec §10.4 explainability metadata retained for the current turn’s accepted recall. Counters, identities, and durations only — bounded by the §10.3 record limits; never memory content. Rendered for /memory why by RecallTurnMetadata::render (task B5).

RequestId

Identity of the exact frontend command request that authorized a transition (spec §6.3 ExplicitCommand).

SessionId

Chat-session identity a lease is scoped to.

SessionMemoryState

Per-session memory-context state machine. All transitions are exhaustive over (current slot state, action); there are no boolean mode flags and no raw JSON past this boundary (spec §19).

TurnId

Identity of the chat turn a recall request targets (spec §6.4).

Enums

AuthorizedMemoryAction

A fully authorized memory transition (spec §19). Because every lease-bearing variant embeds a MemoryContextLease — which only host code can mint — an AuthorizedMemoryAction carrying authority cannot be forged outside this crate.

AutomaticRecall

Automatic-recall column of the spec §6.1 semantics table.

CapturePolicy

Capture policy carried by a lease (spec §6.2). Placeholder shape until the capture flow lands.

ContextSegment

Typed context segment admitted to provider request assembly (spec §10.1): accepted memory enters as ContextSegment::Memory(...), never as raw text, never appended to the user message, and never as system policy. Deliberately a single-variant enum today — it exists to make the “typed segment, not raw text” boundary explicit and extensible. Per-provider wire translation of the segment is task B4; in Phase A the segment only feeds the T29 context-budget lane.

DurableStatus

Durable-slot component of MemoryContextStatus.

MemoryContextError

Typed memory-context failure. Deliberately content-free (spec §19: no content-bearing errors): only host-minted identities and static field names appear.

MemoryContextMode

Continuous-memory context mode (spec §6.1).

MemorySource

Source class of a recalled record (spec §6.5). Minimal closed set for the Phase A typed boundary; the retrieval pipeline (task B1) extends it to the full spec §9 vocabulary.

ModeLifetime

Lifetime column of the spec §6.1 semantics table.

OneShotStatus

One-shot-slot component of MemoryContextStatus.

RankReason

Why the provider ranked a record into the contribution (spec §6.5, §10.4 explainability). Minimal closed set until task B1.

RecallPolicy

Recall policy carried by a lease (spec §6.2). Placeholder shape until the recall flow lands.

RetentionClass

Retention class of a recalled record (spec §6.5). Placeholder single variant until the consolidation/retention flow lands (spec §11, Phase B).

TurnCapture

Turn-capture column of the spec §6.1 semantics table.

UserIntentProof

Proof of exact user intent behind a memory transition (spec §6.3).

Constants

MEMORY_BUDGET_CAPACITY_PERCENT

Spec §10.3: memory may use at most this percentage of the effective provider input capacity.

MEMORY_BUDGET_MAX_TOKENS

Spec §10.3 hard ceiling on the memory recall budget, in estimated tokens.

MEMORY_BUDGET_MIN_TOKENS

Spec §10.3 minimum useful recall budget in estimated tokens. Below this, recall is skipped entirely — core safety/output/tool-result reserves are NEVER reduced to make room for memory.

MEMORY_MAX_RENDERED_RECORD_BYTES

Spec §10.3: maximum rendered bytes for one individual record (2 KiB).

MEMORY_MAX_SELECTED_RECORDS

Spec §10.3: maximum selected records per contribution.

MEMORY_QUERY_MAX_BYTES

Byte ceiling for the recall query derived from the current user prompt (spec §6.4: the request never carries an unbounded transcript).

RECALL_HARD_TIMEOUT

Spec §16.2 hard recall dispatch timeout: a slow provider can never delay the turn beyond this bound (the recall path fails open past it).

Functions

apply_memory_context_action

Apply one fully authorized memory transition to a session’s state — the single engine transition every frontend shares (spec §19, verbatim shape).

memory_budget_tokens

The memory recall budget for a request, per spec §10.3 exactly: min(4096, 10% of effective_provider_input_capacity) estimated tokens, or None (skip recall) when the computed value falls below the MEMORY_BUDGET_MIN_TOKENS floor. Pure — no engine state is read.

render_context_segment

Task B4 (spec §10.2, §5.3): build the synthetic wire message carrying one validated recall contribution. Pure — no engine state is read.

render_recall_why

The ONE /memory why text entry point (task B5, spec §10.4): renders the retained metadata when a recall was accepted this turn, and a clear, NON-error explanation when none is available (memory off, no eligible prompt yet, or the last recall was skipped).

validate_contribution

Host-side contribution acceptance gate — the FULL spec §6.5 rejection matrix (task B1): “The host validates project ID, record count, record sizes, total size, disclosure classes, and schema version”.