Core concepts
Decision lifecycle
Standing, superseded, and reconciled — how commitments evolve.
Decisions are the fact type with state. A decision is standing from the moment it is retained until a later decision supersedes it.
Supersession
Standing
A decision enters memory as standing. It ranks in recall as though it were said today, no matter how old it is.
Contradiction detected
A later retain extracts a decision that contradicts or replaces it. Illumina links the pair with a supersedes edge.
Superseded
The old decision is marked superseded and the change is written to its history. The structured rationale survives in metadata.decision.rationale.
Reconciled
A reconcile sweep walks the namespace for contradictory standing decisions and links whatever automatic detection missed.
The structured rationale survives supersession, so you can always ask why a commitment was made even after it has been replaced.
The result is a chain you can walk: the lineage endpoint returns a decision's ancestry, and its history records every state change.
Manual control
Automatic detection can be overridden:
POST /memories/{memory_id}/supersedemarks a decision superseded explicitly.DELETE /memories/{memory_id}/supersederevives it to standing.POST /decisions/reconcilesweeps the namespace for contradictory standing decisions and links what automatic detection missed.
Why it matters for recall
Standing decisions never decay below neutral recency in recall scoring. A policy set two years ago ranks like it was said yesterday — until it is superseded, at which point the replacement takes its place and the old one fades unless asked for explicitly.
Record decisions deterministically by setting fact_type: "decision" on the
retain item; see Fact types.