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: every tool result, decision, and turn-level effect is appended to an immutable event log.
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

Memory tiers

Promotion-aware knowledge

• Capture is cheap and safe. Cheap to write, never queried directly by the compiler.
• Candidates are not visible to retrieval. They live in the review queue.
• Promotion is governed. Auto-approval is allowed for low-risk classes when an explicit policy permits it; high-risk classes require human review.
• 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, and approval-mode binding.
• 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.

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.

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

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.

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.

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.

Example

A condensed memory write proposal for review:

{
  "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.