Skip to main content

Module memory

Module memory 

Source
Expand description

Governed memory (R0.8 Rusty Learn, waves 1–2): the record model, the structured retrieval contract with its token-bounded deterministic assembly, the journaled read/write seam, and — from wave 2 — the correction loop and the memory operations (consolidation, conflict detection, forgetting) as journaled, evidence-carrying transitions.

The design doc is docs/learn-design.md (“Governed memory”); the learning rule it answers to: no learning process may silently rewrite a production prompt, graph, policy, memory, or tool permission. Memory is therefore a governed record store, not a JSON blob an agent edits through a tool call:

  • MemoryRecord — one serde-versioned, content-addressed record: identity is sha256 over content plus provenance, so a changed record is a new id and there is no in-place update anywhere in the model. Supersession is a chain of immutable records; the superseded record is retained as evidence but filtered from default retrieval.
  • MemoryScope — the five-scope taxonomy: run / agent / team / user / tenant. It maps onto R0.7’s four crate::agents::StateScopes with one honest adaptation, stated exactly as the design draws it: StateScope has no run member, because state outlives runs by design; run scope is new here (memory whose lifetime is bound to one run’s thread); and agent scope is StateScope::Private under its memory name. The taxonomy is a superset, not a fork: an agent manifest’s declared StateScopes translate one-to-one into the memory scopes it may write (MemoryScope::from_state_scope).
  • MemoryProvenance — who wrote it (agent:{id} / human:{id} / distiller:{name} / system), from what evidence (run id + journal event ids, a correction id, a candidate id, the source record ids of a consolidation), and when. Mandatory: a record that cannot name its origin cannot be audited.
  • MemoryQuery + ContextBudget — deliberately structural retrieval (scope, kind, key/tag equality, validity-at-time, minimum confidence, exclude-expired, exclude-superseded, authored-by; no similarity search in R0.8), packed into a prompt assembly by a deterministic rank (explicit priority, then confidence, then recency, with the content address as the final tie-break) until the token budget is exhausted.

§The journaled seam

A memory read is an Effect::ReadOnly effect journaled as RunEventKind::MemoryRead, with the resolved query plus budget as the input payload and the assembly itself — the record ids and their order, plus the token accounting — as the output payload. Two properties the design requires follow from this module’s discipline:

  • Determinism. Equal store state and equal budget produce byte-equal assemblies (assemble is a pure function with a total order), and the resolved query — including the as_of timestamp, stamped through the run’s clock when unset — travels in the journaled request, so the request hash fully determines the result.
  • Replay-serving. Exact replay serves the journaled assembly instead of re-querying the store, per the rule the Flight Recorder already applies to journaled model and tool calls. MemoryReplaySource is the serving cursor (sequence + request hash, the same matching rule crate::replay::ReplaySource applies to model/tool calls), and JournaledMemory::read re-journals the served event byte-identically — including clock-read parity with the live path, so a logical clock’s tick sequence stays aligned with the recorded run.

A memory write is an Effect::Idempotent effect under the derived key memory:{scope}:{memory_id} (memory_effect_key): retried submissions converge, and the write is journaled as RunEventKind::MemoryWrite with its provenance. Writes are never served during replay — a replayed run issuing a write has diverged from its evidence.

§The correction loop and the memory operations (wave 2)

Wave 2 lands the correction loop’s record-plane half: Correction is the highest-trust input the learning system has, so the loop’s rule is a correction becomes an attributed candidate memory or example — never an in-place rewrite of what it corrects. The derived record carries human:{author} provenance with the correction id in evidence (the design’s human:{author} via correction:{id} attribution), confidence 1.0, and — at agent scope or wider — a Candidacy mark: candidacy, not adoption, because a wrong human correction at tenant scope is a production incident with a name attached and evaluation is cheap insurance. Run scope adopts directly: it affects only the run that produced it. Same-key correction-sourced writes auto-supersede the prior record (open question 5’s asymmetry: corrections are trusted because they are attributed; distillations are not because they are inferred).

The three memory operations are journaled transitions over the store, never background daemons:

  • Consolidation — consolidation_summary builds the one summary record that distills N sources: it names them in MemoryEvidence::source_memory_ids (which is also what makes dependent-summary invalidation computable on forgetting) and supersedes them — apply_query treats a summary’s sources as superseded, so default retrieval serves the summary alone. The distillation semantics stay with the caller; the runtime owns the record’s invariants.
  • Conflict detection — detect_conflicts flags live records that share a key, overlap in validity, and carry contradictory content. It flags (MemoryConflict, a review item); it never resolves.
  • Forgetting — plan_forget computes the erasure before anything is deleted: the targets plus the dependent summaries invalidated by walking the source naming in reverse, transitively. Deletion is real (derived state is erasable; run journals are hash-chained evidence and are not — open question 4), and the receipt is the journaled RunEventKind::MemoryForget tombstone: MemoryForgetTombstone carries the id, scope, reason, and dependent invalidations — metadata by construction, with no content field a careless serializer could leak the forgotten bytes through.

§Token accounting

The budget is enforced in estimated tokens: serialized content bytes ÷ 4, plus a declared safety margin (ContextBudget::margin_percent, default DEFAULT_TOKEN_MARGIN_PERCENT), recorded as such on every assembly (TokenAccounting). This is the design’s open-question-3 default, stated plainly: provider-precise tokenizers differ per model and are heavyweight; model-precise counting plugs in later behind the same ContextBudget type, and until then the margin is the honest hedge.

Golden-file tests under tests/golden/ pin every wire shape in this module; any accidental contract drift fails CI.

Structs§

ContextBudget
A prompt-assembly budget, in estimated tokens (see the module docs for the accounting rule). ContextBudget is the seam a model-precise tokenizer plugs into later: the type stays, the estimate behind estimated_tokens is what a later wave may sharpen.
Correction
A human correction: the highest-trust input the learning system has, and the loop treats it accordingly — a correction becomes an attributed candidate memory or example, never an in-place rewrite of what it corrects.
ForgetPlan
What a forgetting will do, computed over the namespace before anything is deleted: the explicitly forgotten records and the dependent summaries the erasure invalidates. Planning is a pure function of store state, so the route can journal exactly what it is about to do — the tombstone names this plan, and the deletion then executes it.
InMemoryMemoryStore
In-memory MemoryStore (dev and test): one map keyed by content address. No persistence, no tenant concept — the honest reference for the contract’s semantics.
JournaledMemory
A memory handle bound to a run’s journal: the journaled read/write seam node code (and later waves’ run integration) uses.
MemoryAssembly
The result of a token-bounded retrieval: the filtered records, ranked and packed. This is the RunEventKind::MemoryRead event’s output payload — the record ids and their order are first-class (MemoryAssembly::memory_ids, the design’s journaled assembly), and the full records travel with them so the prompt a model saw is reconstructable from the journal alone, never from a store query re-run later against mutated state.
MemoryConflict
A flagged conflict: two live records that share a key, overlap in validity, and carry contradictory content. A review item — the design’s rule is that detection is evidence and resolution is governance, so nothing here (or anywhere in the runtime) resolves the pair: Zep and Mem0 resolve contradictions inside the ingestion pipeline with an LLM, which is precisely the silent-mutation pattern the learning rule exists to forbid.
MemoryEvidence
What a memory record was derived from: the evidence an auditor walks. Every field is optional and absent from the wire when unset — a human-authored fact may carry no derivation at all, and sparse evidence must not change the shape for dense readers.
MemoryForgetTombstone
The journaled receipt of a forgetting — the RunEventKind::MemoryForget event’s output payload. Metadata by construction: the forgotten id, its scope, the reason, and the dependent invalidations. There is no content field to leave unset — a tombstone that could carry the forgotten bytes would be one careless serializer away from defeating the erasure it receipts.
MemoryProvenance
A record’s origin: who wrote it, from what evidence, and when. Part of the content address (MemoryRecord::new) — two records with identical content but different origins are different records, because they answer differently to an audit.
MemoryQuery
A structured memory query. Deliberately not semantic: R0.8 has no similarity search (the design’s not-built list), so writers key and tag records deliberately and consumers treat absence of a hit as absence of a key, not absence of a fact.
MemoryRecord
One governed memory record: content-addressed, immutable, scoped, attributed.
MemoryReplaySource
The serving side of exact replay for memory reads: an ordered cursor over a journaled run’s recorded RunEventKind::MemoryRead events.
ScopeAddress
A MemoryScope plus the concrete scope id (agent id, user id, team id, run id, or the tenant name). Scope ids are tenant-relative names: the store namespaces every record under its tenant, so an id never needs to re-encode the tenant it belongs to.
TokenAccounting
The accounting an assembly was packed under, journaled with it: the estimate rule (bytes per token and margin), the budget, and how much of it the assembly used. Recorded — not recomputed — so an auditor reads the accounting the read actually applied.
ValidityWindow
The interval the record claims to be true: [valid_from, valid_until), open-ended when valid_until is None. Contradiction is handled by time (and supersession), never by deletion.

Enums§

BudgetOverflow
What the assembly does when the next-ranked record does not fit the remaining budget.
Candidacy
The governance state of a correction-derived record (R0.8 wave 2). Closed enum with the single honest state this wave needs — wave 3’s evaluation outcomes extend it additively, the same evolution rule RunEventKind follows. Not part of the content address: candidacy is governance state, not identity — the same reading tags and priority already take.
CorrectionTarget
What a correction corrects. Closed enum — the three targets the design names; consumers match exhaustively.
ForgetReason
Why a record was forgotten. Closed enum, carried on the tombstone: the reason is what distinguishes a reaper’s expiry from a GDPR-shaped erasure request in the audit trail.
MemoryKind
What a memory record is. Closed enum — retrieval and consolidation match exhaustively on it.
MemoryScope
The scope a memory lives at: whose memory it is and how far its visibility reaches. Closed enum; the superset mapping onto R0.7’s StateScope taxonomy is the module’s load-bearing contract (see the module docs and MemoryScope::from_state_scope).
MemorySource
Where a journaled memory handle answers reads from: the live store (record mode) or a recorded journal (replay mode).
ProvenanceAuthor
Who wrote a memory record. Closed enum: a record that cannot name its origin cannot be audited, so provenance is mandatory, not optional — and the attribution travels with the record through every later consumer (distiller, evaluator, auditor).

Constants§

DEFAULT_TOKEN_MARGIN_PERCENT
The default safety margin of the estimated-token accounting, in percent (design open question 3’s “declared safety margin”): a record’s estimated cost is ceil(bytes / 4) * (1 + margin), so tokenizer drift against the estimate eats the margin before it eats the budget.
MEMORY_SCHEMA_VERSION
The memory schema version a run pins in its manifest (crate::record::RunManifest::memory_schema). Bump only on a breaking change to the record model; additive evolution uses serde defaults so previously written records keep deserializing.
TOKEN_BYTES_PER_ESTIMATE
The divisor of the estimated-token accounting: estimated tokens are serialized content bytes ÷ TOKEN_BYTES_PER_ESTIMATE, rounded up, before the safety margin. See the module docs for why the estimate — not a provider-precise tokenizer — is the R0.8 default.

Traits§

MemoryStore
A governed memory store. The two server backends (JSON files, Postgres) implement it over their own layouts; InMemoryMemoryStore is the dev/test implementation, the same role InMemoryCheckpointer plays for checkpoints.

Functions§

apply_query
Apply query to a universe of records (one tenant’s namespace), pure: the superseded set is computed over the universe, then every declared filter runs through MemoryQuery::matches. Both store backends share this function — the JSON backend scans and applies it directly; Postgres pre-filters on columns and applies the same function to the reduced set, so filter semantics live in exactly one place.
assemble
Rank and pack records under budget, deterministically.
consolidation_summary
Build the one summary record that distills sources, under the invariants the runtime owns: the sources are named in MemoryEvidence::source_memory_ids (which supersedes them — see apply_query — and makes dependent-summary invalidation computable on forgetting), the author is distiller:{name}, and the confidence is the minimum of the sources’: a summary is a claim no stronger than its weakest source, and the model is honest about that.
derive_memory_id
The content address of a record: sha256 over the canonical serialization of {content, provenance} — content by hash (so inline and artifact-referenced forms of the same body address identically) and provenance in full (origin is identity).
detect_conflicts
Flag the conflicts in universe (one tenant’s namespace) at now.
estimated_tokens
Estimated tokens for bytes of serialized content under the declared accounting: ceil(bytes / TOKEN_BYTES_PER_ESTIMATE) scaled up by the margin, saturated at u32::MAX (an over-budget estimate only means the record does not fit — the estimate never wraps).
memory_effect_key
The derived idempotency key of a memory write: memory:{scope}:{memory_id} (the design’s write-path rule). Retried submissions of the same write converge on one key, and recovery can re-derive it without consulting the store.
memory_forget_effect_key
The derived idempotency key of a forgetting: memory_forget:{scope}:{memory_id}. Retried erasures converge on one key — forgetting an already-forgotten record is the same journaled effect, not a second one.
memory_read_request
The canonical JSON shape a JournaledMemory read journals (and a MemoryReplaySource matches) as a memory read’s request: the resolved query (with MemoryQuery::as_of stamped) and the budget, exactly as passed to the store. The hash of this value’s canonical serialization is the request identity exact replay matches on — the same rule crate::replay::model_call_request sets for model calls.
plan_forget
Plan a forgetting over universe (one tenant’s namespace): targets are the records to erase; the dependent-summary walk runs in reverse over source naming until the closure stops growing. Targets absent from the universe are skipped (the caller decides whether absence is an error — the single-id route 404s before planning).
superseded_set
The tenant namespace’s superseded set, as apply_query defines it: everything named in a supersedes field, plus everything a summary record names as a source (see its docs). Shared by conflict detection and forget planning, which must agree with retrieval about what is superseded — three readers, one definition.