Memory Model

Memory is the Intelligence-plane primitive that persists what the runtime should remember between turns and across sessions. ContextOS treats memory as a promotion pipeline with explicit gates so the durable surface stays small, cited, and correctable.

Definition

A tiered store with explicit promotion: every fact begins as an immutable capture, becomes a typed candidate, enters a review queue, gets promoted to a tier (working / episodic / semantic / durable), and only then is eligible for compilation into a Context Pack. Writes are typed by class, governed by consent, and contradiction-checked.

Why it exists

Naive memory either remembers nothing (every session starts cold) or remembers everything (drifts, leaks PII, accumulates contradictions). A promotion pipeline gives the runtime an append-only audit trail at capture, a governance gate at promotion, and a bounded surface at recall — the three properties that make memory trustworthy under change.

How it works

1. Capture: permitted, minimized observations and control receipts enter the event log under data-flow and retention policy. Reusable credentials and unrestricted raw payloads must not be copied into memory or audit.
2. Extract candidates: a consolidator extracts typed candidate facts from captures (entity, relation, value, evidence_refs, confidence).
3. Review: candidates above a confidence floor enter a queue; operators (or an auto-approval policy bound to risk) approve, edit, or reject. Rejections are remembered.
4. Promote: approved candidates become tier-routed records with provenance and a contradiction check against existing records.
5. Compile: only promoted memory is eligible for the Context Pack Compiler, and it is filtered again at compile time by tenant, role, classification, and intent.

capture (immutable) → candidate → review queue → promoted → compiled context

Recall is reconstruction, not retrieval

Promotion makes a record eligible; it does not make the record currently true, applicable, or authorized. On every recall, the Context Pack Compiler reconstructs usable memory by joining five distinct inputs: current source state, stored memory, fresh evidence, current policy, and current authority. It then applies scope, freshness, contradiction, consent, and task-applicability rules before selecting a bounded candidate set.

Retrieval relevance and applicability are ranking signals, never trust boundaries. Learned ranking may order already-eligible candidates, but it cannot bypass tenant isolation, consent, classification, authority, or an unresolved contradiction. If a required source cannot be refreshed, fallback behavior is explicit: omit, surface uncertainty, request evidence, or escalate—never silently treat the stored record as current truth.

Memory tiers

Promotion-aware knowledge

• Capture needs its own controls. Minimize, classify and authorize capture before writing; the compiler does not query raw captures directly.
• Candidates are not visible to retrieval. They live in the review queue.
• Promotion is governed. Auto-approval is allowed only for classes and conditions explicitly named by policy. Human review is required where policy assigns that obligation; a coarse risk label alone does not choose the reviewer.
• Promoted memory is the only thing the compiler sees. This is what keeps the durable surface small.

Contradiction handling and write-back governance

• Contradiction check: every promotion is diffed against existing records on the same entity/relation. A contradicting record does not silently overwrite; it produces a memory.contradiction event for review (or auto-resolves under an explicit policy rule).
• Write-back classes: writes are typed by class—evidence_link, preference, decision_outcome, correction. Each class has its own allow-list, retention, native-risk policy, approval obligations, and v1 mode projection where required.
• Correction memory: explicit operator corrections are first-class and outrank prior records on the same key; they emit a learning signal to the Improvement Loop.
• No PII write-back without consent: consent is checked at the candidate stage, not at recall time, so non-consenting facts never enter the queue.

Poisoning lifecycle and repair

Memory security is enforced across five boundaries:

1. Capture: preserve source identity, trust class, timestamps, and the exact influence path; untrusted observations remain labeled.
2. Promotion: check classification, scope, consent, freshness, contradictions, evidence, and required review before recall eligibility.
3. Recall: reconstruct under current policy and authority with bounded candidate and top-k budgets.
4. Action: independently revalidate identity, delegation, capability, arguments, destination, and approval; a memory record can inform an action but cannot authorize it.
5. Repair: quarantine suspected records, preserve influence history, replay affected runs, write a superseding correction or tombstone, verify the repaired behavior, and only then restore promotion eligibility.

Authority is non-escalating across the lifecycle. Memory cannot broaden the principal, delegated authority, capability/resource scope, data classification, amount, time window, approval state, or ActionRisk ceiling that the live run would otherwise have.

Read/write policy model

• Read filters: tenant scope, role, data classification, freshness, and intent.
• Write filters: allow-list keys, PII rules, evidence requirements.
• Consent gating: explicit consent for sensitive facts or regulated classes.
• Redaction before write: policy rules apply prior to persistence, not at retrieval time.

Consent records

Consent is a first-class, typed, append-only record — not a flag inside another record. Every PII / regulated promotion checks the consent record at the candidate stage and records the matched consent_id on the resulting promoted record.

{
  "consent_id": "cns_2026_05_04_a01",
  "subject_ceid": "customer:cus_77",
  "tenant_id": "tenant_acme_prod",
  "purpose": "support_personalization",
  "scope": {
    "predicates_allowed": ["prefers_communication_channel", "preferred_language"],
    "data_classifications_allowed": ["INTERNAL"]
  },
  "basis": "user_opt_in",
  "captured_at": "2026-05-04T09:30:00Z",
  "valid_until": "2027-05-04T09:30:00Z",
  "revoked_at": null,
  "evidence_refs": ["channel:app_chat:msg_881", "consent_screen:v3"],
  "auditor_id": null
}

Invariants

• Every promotion of a preference / decision_outcome / correction write class on a PII-classified attribute resolves a live consent_id or is rejected at the candidate stage.
• Revocation (revoked_at) is honored on the next recall; existing records are tombstoned on the consent revocation pass.
• Consent records are never modified; corrections are new records superseding prior ones with explicit supersedes link.
• Cross-tenant consent does not exist; consent is always tenant-scoped.

Lifecycle

• captured → active → revoked / expired → tombstoned.
• A revoked consent triggers a memory.consent_revoked event; the Improvement Loop may surface a Note if the impacted record set is large.

Owned namespaces and lifecycle receipts

A personal or enterprise memory namespace binds tenant, owner, purpose and permitted readers. A shared device or process grants no cross-owner access. Authenticated broker observations establish access to that namespace; record fields, model text and recalled memories cannot authenticate themselves. Reader expansion, cross-tenant writes and purpose substitution require independently authorized new scope, rather than an edit to a remembered record.

MemoryLifecycleRecord is an additive profile attachment for propose, promote, correct and delete; it does not add required fields to MemoryProposal. The deterministic validateMemoryLifecycle helper checks namespace/owner scope, source provenance, bounded retention, required review, current data-flow policy and tracked derived copies. It consumes verified adapter observations and performs no storage or erasure. The existing compiler still consumes caller-supplied promoted memory; this helper does not create a Memory Fabric backend.

Select memory.lifecycle@1 whenever admitted features include persistent memory, through the Control Profiles. The Execution Contract keeps this requirement separate from a model’s recall request or a numeric confidence threshold. Published lifecycle attachment schemas validate structure; namespace isolation, actual retention jobs and copy deletion require runtime evidence.

Review binds the complete lifecycle intent (including target artifact, readers, sources, policy, retention and action/operation correlation). Propagation receipts separately bind that intent, record, operation and affected artifact. Mutating arguments or reusing a receipt from another operation cannot establish completion. Actual payload redaction, credential exclusion, reader enforcement and namespace isolation remain adapter obligations.

A valid deletion request may be allowed while propagation is pending, failed or external_unknown. These states are visible separately from completion_verified. Confirmed completion requires current verified receipts for the primary target and every known derived copy, plus a verified complete inventory. Missing indexes, caches or external copies cannot be omitted to manufacture success. A correction also tracks affected copies so stale projections do not silently remain active.

Retention expiry blocks new promotion/correction under the expired record’s authority. It does not itself prohibit an otherwise authorized cleanup request. A configured retention exception blocks for policy-owner escalation. Append-only history describes event lineage; it is not permission to retain sensitive capture payloads forever. Deletion of controlled stores cannot promise removal from previously exported systems, model weights or immutable external records.

Memory access patterns

• Recall by intent: fetch promoted memory ranked by relevance to the current task.
• Temporal recall: prefer recent, higher-confidence entries within freshness windows.
• Conflict-aware recall: unresolved contradictions are surfaced to the planner, not silenced.
• Provenance-first: every recall includes source IDs, timestamps, and the originating capture event.

Implementation references

• Memory Fabric
• Context Pack
• API Contracts
• Workflow Examples

Interfaces

Inputs

• Capture stream from every plane (tool results, decisions, effects)
• Memory write policy and consent records
• Redaction and PII rules
• Run Context (tenant_id, role, classification scope)

Outputs

• Promoted memory records with provenance
• Review queue items and decisions
• Contradiction events
• Memory write proposals consumed by the next turn’s compiler
• Recall decision records containing admitted, omitted, stale, contradictory, and quarantined candidates with reasons
• Repair lineage linking quarantined records, affected runs, replay verdicts, and superseding corrections

Failure modes

• Writing sensitive data without consent — caught at the candidate stage.
• Over-retention causing classification drift — mitigated by class-specific TTL.
• Context overload from raw captures leaking into the compiler — capture is never compiled directly.
• Drift from conflicting summaries that auto-resolve incorrectly — mitigated by surfacing contradictions to review.
• Memory poisoning from untrusted sources — mitigated by source-class trust scoring at the candidate stage.
• Missing consent for PII or regulated classes — recall returns no record, never a redacted stub.
• Promotion mistaken for permanent truth, allowing a stale but relevant record to override current source state or policy.
• Poisoned memory remains active after correction because its downstream influence history was not preserved or replayed.

Operational concerns

• Retention schedules and cost budgets per tier and per class.
• Consent and regulatory requirements per data_classification.
• Cache invalidation and replay against pinned Context Pack versions.
• Backfill / cleanup when ontology versions advance.
• Review-queue throughput and operator load monitoring.
• Quarantine, blast-radius analysis, repair replay, and re-promotion runbooks.
• Recall fallback policy for unavailable sources, expired evidence, and unresolved contradictions.

Evaluation metrics

• Memory hit rate per workflow.
• Token cost reduction vs. retrieval-only baseline.
• PII write-back violation rate (target: zero).
• Contradiction resolution time.
• Correction adoption rate (operator corrections that change downstream decisions).
• Memory accuracy on regression tests.
• Memory Decision Scorecard: eligibility precision/recall, contradiction handling, authority non-escalation, fallback correctness, and provenance completeness.
• Poisoning detection-to-quarantine time and repair replay pass rate.

Example

A condensed memory write proposal for review:

This is the existing MemoryProposal shape, not a storage authorization or completed promotion receipt. consent_check and auto_promote_eligible must be produced by trusted policy/review processing; model-supplied values cannot establish consent or bypass MemoryLifecycleRecord checks.

{
  "proposal_id": "mwp_2026_05_04_0931_a17",
  "candidate": {
    "entity_ceid": "customer:cus_77",
    "predicate": "prefers_communication_channel",
    "value": "email",
    "evidence_refs": ["tool:crm.lookup:tc_212", "session:sess_42f1"],
    "confidence": 0.93
  },
  "class": "preference",
  "tier_target": "semantic",
  "consent_check": "passed",
  "contradiction_check": {
    "existing": null,
    "verdict": "no_conflict"
  },
  "auto_promote_eligible": true
}

Common misconceptions

• Memory is not a raw log store. Capture is the log; memory is what survives promotion.
• More memory is not better. Relevance, evidence, and safety win.
• Recall is not retrieval. Retrieval queries the Knowledge Graph; recall queries promoted memory only.
• Auto-promotion is not the default. It is an explicit policy choice for specific low-risk classes.