Retention

Removal is not one operation. The protocol keeps four mechanisms distinct because they answer different questions, and collapsing them would make an audit unanswerable.

Mechanism	Changes	Recoverable	Use
`drop`	Membership — a new root	From evidence, if kept	The knowledge is wrong or unwanted
`supersede`	Accessibility only	Yes	A newer block takes precedence
`demote`	Retrieval priority only	Yes	No longer relevant, still true
`prune`	Storage only	No	Reclaim what no retained root needs
`redact`	The bytes themselves	No	Law and safety, never cleanup

from boltzmann.blocks import RemovalMechanism

[m.value for m in RemovalMechanism]
# ['drop', 'supersede', 'demote', 'prune', 'tombstone', 'crypto_shred', 'lineage_rewrite']

Every removal is recorded in provenance — what was removed, by whom, why. RetentionPolicy.record_removals is a property that is always True: no configuration turns auditability off.

Always plan first

Dropping canonical evidence is privileged: it cascades to everything derived from it, because a claim whose source was removed can no longer be justified.

from boltzmann.retention import DropRequest

curator = Actor(id="curator@example.org", kind=ActorKind.HUMAN)

plan = brain.plan_drop(DropRequest(
    blocks=[source_id],
    memory_type=MemoryType.CANONICAL,
    actor=curator,
    reason="ingested in error",
))

plan.privileged          # True for a canonical drop
plan.size                # how many blocks go with it, across every module
plan.dependents          # {MemoryType: [BlockId]}
plan.rederivable         # what could be regenerated instead of lost
plan.provenance_edges

Nothing is written. The cascade is computed from the provenance ledger, so it is exact rather than estimated.

Drop

result = brain.drop(DropRequest(
    blocks=[source_id], memory_type=MemoryType.CANONICAL, actor=curator, reason="ingested in error",
))

result.snapshot
result.dropped           # {MemoryType: [BlockId]}
result.roots             # one commit, several new roots
result.provenance
result.review_required

Older retained roots keep verifying exactly as before, because nothing about them changed. A canonical drop is off by default, since excluding evidence forfeits re-derivation from it:

from boltzmann.retention import PERMISSIVE_POLICY, RetentionPolicy

brain = Brain.open("./my-brain", actor=curator, policy=RetentionPolicy(canonical_drop_allowed=True))
# or, equivalently, policy=PERMISSIVE_POLICY

Batch invalidation

When a producer turns out to have been wrong — a bad model version, a broken pipeline run — drop everything it made:

from boltzmann.retention import ProducerDropRequest

brain.drop_by_producer(ProducerDropRequest(
    producer=Producer(kind=ProducerKind.MODEL, id="claude-opus-5", version="2026-06"),
    memory_types=[MemoryType.SEMANTIC, MemoryType.PROCEDURAL],
    actor=curator,
    reason="the extraction prompt cited the wrong section",
))

This is why Producer records a version: without it, invalidating one model release would mean invalidating every one.

Re-derivation instead of loss

Naming a replacement makes the difference between a deletion and a re-derivation:

plan = brain.plan_drop(DropRequest(
    blocks=[wrong_source], memory_type=MemoryType.CANONICAL, actor=curator,
    reason="the source was a draft",
    rederive_against=corrected_source,
))
plan.rederivable   # the blocks that can be regenerated against the corrected source

Then run a re-derivation task — see Ingestion.

Supersede and demote

Two gentler options, which change accessibility rather than membership. The block stays in the composition and keeps proving into the root.

brain.supersede(block=newer, superseded=older, memory_type=MemoryType.SEMANTIC, reason="corrected")
brain.demote(block=one, memory_type=MemoryType.EPISODIC, reason="no longer relevant")

Demotion is the only option for episodic memory. The chronological record is append-only by protocol, not by policy: an episode is a record of what happened and cannot be rewritten. drop raises AppendOnlyViolationError, and no policy can permit it.

The decay function that governs demotion is a policy decision, not a protocol one.

Prune

Pruning never decides what to forget; a drop already did. It reclaims what no retained composition still needs.

report = brain.prune(dry_run=True)      # always look first -- pruning cannot be undone

report.retained_roots
report.reachable
report.reclaimed
report.reclaimed_count
report.dry_run

brain.prune(dry_run=False)

Nothing a retained root names is touched, and neither is anything a published tag names: a layout that published v1 keeps the manifest and layers v1 points at.

from boltzmann.retention import mark, reachable_from, reachable_from_tags, sweep

Redact

For law and safety, not for cleanup. Wrong or obsolete knowledge is dropped; redaction destroys bytes that a retained root still names.

result = brain.redact(block_id, MemoryType.CANONICAL, reason="GDPR erasure request")

result.mechanism
result.redacted
result.invalidates_prior_roots

Membership still verifies afterwards, but reconstruction of that block is forfeited. The block becomes a tombstone, which is distinguishable from missing — a removed block must never look like a corrupted one:

report = brain.resolvability()

report.resolvable        # {MemoryType: [BlockId]}
report.tombstoned        # redacted: named by a root, bytes destroyed
report.missing           # not held: a selective install, or damage
report.is_intact         # every block and every datum it names is resolvable or tombstoned

Redaction creates a successor snapshot. Its module composition and Merkle root stay unchanged, while the signed ModuleRef.tombstones list grows to name the destroyed identity. The SDK derives the redact authorization scope from that signed difference; the removal record remains the attributable ledger entry that explains who removed it and why. The member is present exactly when a module has destroyed bytes to name — a module with none omits it, rather than carrying an empty list, so that two implementations compute the same snapshot digest for the same brain state. For ordinary drops, the composition does change. A verifier compares a snapshot with its first parent and requires every identity that disappeared to be named by a reachable removal record for that module. An unexplained absence is rejected as RemovalInvariantError, including during pull. Together, tombstones and the removal ledger distinguish intentional destruction from an incomplete or corrupted artifact. The check depends on nothing in the snapshot being opted into, so nothing in a snapshot can turn it off. When the first parent is not held the difference cannot be taken at all; that is reported as REMOVAL_UNDECIDABLE and does not block — refusing would refuse every brain that pruned its history, which the protocol permits, and passing silently would let a truncated history disable the check. The same split is reported for the content a block names but does not carry, because an episode whose transcript is gone is not a whole episode:

report.content_resolvable   # {MemoryType: [Digest]}
report.content_tombstoned   # destroyed under an erasure policy
report.content_missing      # the block verifies, the datum it names is gone

This is the only reader that reports a datum a block names but the store no longer holds. verify() tolerates absent bytes by design — it answers whether what is present hashes to the identity it is filed under — and a prune reclaims nothing, because a retained root still names the digest. Without content_missing the brain looks intact until pack refuses to publish it.

A drop travels. When two brains are reconciled, exclusion takes precedence — a block one side dropped does not come back because the other still held it — and the removal record you wrote is what explains it on the other side. The same holds in reverse: reconciling with a history that dropped evidence you derived from takes your dependents with it, through this same cascade. See Reconciliation.

Redaction requires explicit policy, or it raises RetentionPolicyError.

The policy

from boltzmann.retention import DEFAULT_RETAINED_ROOTS, RetentionPolicy

policy = RetentionPolicy(
    droppable_modules=[MemoryType.CANONICAL, MemoryType.SEMANTIC, MemoryType.PROCEDURAL, MemoryType.PROVENANCE],
    canonical_drop_allowed=False,
    cascade_review_threshold=50,      # a cascade this large needs human review first
    retained_roots=10,
    redactable_media_types=None,      # None means nothing is redactable
    allowed_mechanisms=None,          # None means every mechanism the module permits
)

policy.record_removals               # always True
policy.requires_review(cascade_size)
policy.authorize(RemovalMechanism.DROP, MemoryType.SEMANTIC)   # raises if forbidden

The policy holds the deployment’s answers to the questions the protocol leaves open — thresholds and permissions, never invariants.

Getting started

Core concepts

Guides

Always plan first

Drop

Batch invalidation

Re-derivation instead of loss

Supersede and demote

Prune

Redact

The policy

​Always plan first

​Drop

​Batch invalidation

​Re-derivation instead of loss

​Supersede and demote

​Prune

​Redact

​The policy

Always plan first

Drop

Batch invalidation

Re-derivation instead of loss

Supersede and demote

Prune

Redact

The policy