Skip to content
Palimem Docsspec v1.7.0

Palimpsest model

A palimpsest is a manuscript that has been written over — but the earlier layers remain visible through the newer writing. Palimem works the same way.

Every write appends to an immutable log. Derived semantic units hold current truth. Search indexes are rebuildable from the log at any point in time. When facts change, new writes supersede old ones — they do not silently overwrite history.

Three layers

Section titled “Three layers”
┌─────────────────────────────────────────┐
│          CURRENT TRUTH (top layer)      │  ← rebuildable indexes, current semantic units
│  memory_search · memory_get (as_of now) │
├─────────────────────────────────────────┤
│          SEMANTIC UNITS                 │  ← derived from WAL; hold governed current state
│  facts · beliefs · preferences         │
├─────────────────────────────────────────┤
│   WRITE-AHEAD LOG (WAL) — immutable     │  ← every write appended here; never overwritten
│  remember · supersede · retract events  │
└─────────────────────────────────────────┘

Write-ahead log (WAL)

Section titled “Write-ahead log (WAL)”

The WAL is the source of truth. Every memory_remember call appends a new event. Events are never deleted. The WAL records:

  • remember — a new fact, belief, preference, episode, or note
  • supersede — a value that replaces an older value for the same subject key
  • retract — a memory_forget call that marks a subject as removed

Semantic units

Section titled “Semantic units”

Semantic units are the current derived view over the WAL. They answer: what is the current value for this subject? When a subject is superseded, the semantic unit is updated to point at the new WAL event. When a subject is retracted, the semantic unit marks it as removed.

Semantic units are the layer that memory_search and memory_get query by default. They are always consistent with the WAL.

Rebuildable indexes

Section titled “Rebuildable indexes”

Search indexes (BM25/lexical by default) are built from semantic units. If an index becomes corrupt or stale, it can be rebuilt from the WAL without data loss. memory_status reports index freshness.

Supersession

Section titled “Supersession”

Supersession is the core correctness mechanism. When you write a fact that conflicts with an existing fact for the same subject key (scope + namespace + topic + field + memory_type), the new value supersedes the old one:

memory_remember(scope=repository, topic=auth, field=provider, value="OAuth2")
  → WAL event 1: remember auth.provider = "SAML"   ← old value


memory_remember(scope=repository, topic=auth, field=provider, value="OAuth2")
  → WAL event 2: supersede auth.provider = "OAuth2"  ← current truth

The old value is preserved in the WAL. The semantic unit now points at event 2. memory_get returns “OAuth2”. memory_search never returns the superseded “SAML” as current.

This is different from additive-only memory systems that accumulate contradicting facts and leave ranking to resolve them at recall time. Palimem resolves contradiction at write time, through the subject key structure.

Subject key

Section titled “Subject key”

Every memory record has a five-part subject key:

Part Example Purpose
scope repository Where the memory lives (user / session / repository)
namespace my-project The project or session identifier
topic auth What the memory is about
field provider The specific attribute
memory_type fact The confidence level

Two records with the same subject key are in a supersession relationship. The newer one is current.

Memory types

Section titled “Memory types”
Type Confidence Use
fact High — operator-accepted Stable, verified information
belief Medium — agent-inferred Inferences pending confirmation
preference Persistent — user-stated User/team preferences
episode Event record Tool failures, session events
note Low-salience Scratch, drafts

Retraction

Section titled “Retraction”

memory_forget appends a retract event to the WAL. The subject is marked as removed in semantic units. The original WAL events are preserved for audit. Retraction is the only negation surface — there is no physical delete.

When a subject has legal_hold: true, memory_forget is rejected.

Audit and temporal queries

Section titled “Audit and temporal queries”

Because the WAL is immutable, you can query what was true at any point in time:

memory_get(scope=repository, topic=auth, field=provider, as_of="2026-01-15T09:00:00Z")
→ "SAML"  ← the value that was current at that time

memory_query_temporal returns a belief trajectory — the ordered sequence of values for a subject across time.

memory_audit_export exports the full WAL in a compliance-ready format.

Rebuild and consolidation

Section titled “Rebuild and consolidation”

memory_consolidate is an operator tool that deduplicates redundant units and summarizes low-salience noise clusters. It does not remove facts under legal hold or current semantic units. Consolidation is reversible — the WAL is untouched.

Next steps

Section titled “Next steps”