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 issha256over 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 fourcrate::agents::StateScopes with one honest adaptation, stated exactly as the design draws it:StateScopehas norunmember, because state outlives runs by design; run scope is new here (memory whose lifetime is bound to one run’s thread); andagentscope isStateScope::Privateunder its memory name. The taxonomy is a superset, not a fork: an agent manifest’s declaredStateScopes 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 (
assembleis a pure function with a total order), and the resolved query — including theas_oftimestamp, 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.
MemoryReplaySourceis the serving cursor (sequence + request hash, the same matching rulecrate::replay::ReplaySourceapplies to model/tool calls), andJournaledMemory::readre-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_summarybuilds the onesummaryrecord that distills N sources: it names them inMemoryEvidence::source_memory_ids(which is also what makes dependent-summary invalidation computable on forgetting) and supersedes them —apply_querytreats 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_conflictsflags live records that share a key, overlap in validity, and carry contradictory content. It flags (MemoryConflict, a review item); it never resolves. - Forgetting —
plan_forgetcomputes 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 journaledRunEventKind::MemoryForgettombstone:MemoryForgetTombstonecarries 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§
- Context
Budget - A prompt-assembly budget, in estimated tokens (see the module docs for
the accounting rule).
ContextBudgetis the seam a model-precise tokenizer plugs into later: the type stays, the estimate behindestimated_tokensis 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.
- Forget
Plan - 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.
- InMemory
Memory Store - 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. - Journaled
Memory - A memory handle bound to a run’s journal: the journaled read/write seam node code (and later waves’ run integration) uses.
- Memory
Assembly - The result of a token-bounded retrieval: the filtered records, ranked
and packed. This is the
RunEventKind::MemoryReadevent’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. - Memory
Conflict - 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.
- Memory
Evidence - 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.
- Memory
Forget Tombstone - The journaled receipt of a forgetting — the
RunEventKind::MemoryForgetevent’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. - Memory
Provenance - 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. - Memory
Query - 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.
- Memory
Record - One governed memory record: content-addressed, immutable, scoped, attributed.
- Memory
Replay Source - The serving side of exact replay for memory reads: an ordered cursor
over a journaled run’s recorded
RunEventKind::MemoryReadevents. - Scope
Address - A
MemoryScopeplus 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. - Token
Accounting - 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.
- Validity
Window - The interval the record claims to be true:
[valid_from, valid_until), open-ended whenvalid_untilisNone. Contradiction is handled by time (and supersession), never by deletion.
Enums§
- Budget
Overflow - 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
RunEventKindfollows. Not part of the content address: candidacy is governance state, not identity — the same readingtagsandpriorityalready take. - Correction
Target - What a correction corrects. Closed enum — the three targets the design names; consumers match exhaustively.
- Forget
Reason - 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.
- Memory
Kind - What a memory record is. Closed enum — retrieval and consolidation match exhaustively on it.
- Memory
Scope - 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
StateScopetaxonomy is the module’s load-bearing contract (see the module docs andMemoryScope::from_state_scope). - Memory
Source - Where a journaled memory handle answers reads from: the live store (record mode) or a recorded journal (replay mode).
- Provenance
Author - 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§
- Memory
Store - A governed memory store. The two server backends (JSON files, Postgres)
implement it over their own layouts;
InMemoryMemoryStoreis the dev/test implementation, the same roleInMemoryCheckpointerplays for checkpoints.
Functions§
- apply_
query - Apply
queryto a universe of records (one tenant’s namespace), pure: the superseded set is computed over the universe, then every declared filter runs throughMemoryQuery::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
recordsunderbudget, deterministically. - consolidation_
summary - Build the one
summaryrecord that distillssources, under the invariants the runtime owns: the sources are named inMemoryEvidence::source_memory_ids(which supersedes them — seeapply_query— and makes dependent-summary invalidation computable on forgetting), the author isdistiller:{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:
sha256over 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) atnow. - estimated_
tokens - Estimated tokens for
bytesof serialized content under the declared accounting:ceil(bytes / TOKEN_BYTES_PER_ESTIMATE)scaled up by the margin, saturated atu32::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
JournaledMemoryread journals (and aMemoryReplaySourcematches) as a memory read’s request: the resolved query (withMemoryQuery::as_ofstamped) 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 rulecrate::replay::model_call_requestsets for model calls. - plan_
forget - Plan a forgetting over
universe(one tenant’s namespace):targetsare 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_querydefines it: everything named in asupersedesfield, plus everything asummaryrecord 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.