Supersession & audit

Supersession and audit are two sides of the same design principle: memory is never deleted, only updated. Supersession keeps facts current. The immutable log keeps history complete.

Supersession semantics

When you write a new value for a subject that already has a current value, the write creates a supersede event rather than modifying the existing record:

WAL event 1 (remember): auth.provider = "SAML"
WAL event 2 (supersede): auth.provider = "OAuth2"  ← current truth

The subject key (scope=repository, namespace=my-project, topic=auth, field=provider, memory_type=fact) now has one current value: "OAuth2". The "SAML" event is preserved in the WAL and queryable by as_of.

What supersession prevents

Stale facts accumulating — Additive-only memory systems stack contradictions and leave recall ranking to resolve them. Palimem resolves at write time.
Silent overwrites losing history — A silent update would delete the old value. Supersession appends and marks, preserving the full trajectory.
Inconsistent dependent fields — Structured subject keys (topic + field) enable dependent-field propagation: when auth.provider changes, a dependent auth.config_path can be flagged for review.

Subject-key structure and conflict detection

Two records conflict when they share the same five-part subject key:

Part	Type
`scope`	`user` / `session` / `repository`
`namespace`	project or session identifier
`topic`	what the memory is about
`field`	the specific attribute
`memory_type`	`fact` / `belief` / `preference` / `episode` / `note`

Writing to the same key triggers supersession. Writing to a different field (e.g. auth.provider vs auth.expiry) creates independent records.

Retraction

memory_forget appends a retract WAL event. The subject is marked removed in current semantic units. No record is deleted.

WAL event 3 (retract): auth.provider  ← marked removed

After retraction, memory_get returns not_found and memory_search skips the subject. But memory_query_temporal can show the full trajectory including retraction.

Legal hold

When a subject is written with legal_hold: true, memory_forget is rejected:

{ "error": { "code": "legal_hold" } }

Legal hold subjects must be released explicitly before they can be retracted. This supports compliance scenarios where records must be preserved for a defined period.

Point-in-time recall

Every recall call that accepts as_of returns the governed state at that moment, reconstructed from the WAL:

memory_get(
  scope=repository, namespace=my-project,
  topic=auth, field=provider, memory_type=fact,
  as_of="2026-01-15T09:00:00Z"
)
→ "SAML"  ← value that was current on that date

memory_get(
  ...,
  as_of="2026-06-25T12:00:00Z"
)
→ "OAuth2"  ← value after supersession

as_of is supported on memory_search and memory_get. It queries the WAL directly, not the current semantic unit layer.

Belief trajectories

memory_query_temporal returns a belief trajectory — the ordered sequence of all governed values for subjects matching scope filters across one or more audit points:

memory_query_temporal(
  scope=repository, namespace=my-project,
  topic=auth, field=provider
)
→ [
    { seq: 1, value: "SAML",   event: "remember",  timestamp: "2026-01-10" },
    { seq: 2, value: "OAuth2", event: "supersede",  timestamp: "2026-01-20" }
  ]

This is the compliance-ready view of how a fact evolved over time.

Audit export

memory_audit_export exports the full WAL in a structured, compliance-ready format. It includes:

All WAL events (remember, supersede, retract)
Provenance metadata (source, tool, actor, request_id)
Timestamps and sequence numbers
Scope and namespace partitioning

Use audit export for:

Compliance review (“what did the agent know, and when?”)
Debugging unexpected recall behavior
Retention policy enforcement

memory_audit_export(
  scope=repository,
  namespace=my-project,
  from="2026-01-01T00:00:00Z",
  to="2026-06-30T23:59:59Z"
)

Retention and governance

Retention policies can evict low-salience records after a configurable window. Eviction appends a retention retract event — it does not delete WAL history. Records under legal hold are exempt from eviction.

See Governance guide for retention policy configuration.

PII pre-store scanning

When PII scanning is enabled for a namespace, memory_remember runs a scan on the serialized value before WAL append. This is a write-path hook, not a separate tool. Scan results are surfaced through memory_status.

Next steps

Palimpsest model — the three-layer architecture
Scopes — scope isolation and namespace partitioning
Governance guide — retention, audit, and PII policy
MCP tools reference — full arguments for temporal and audit tools