Core concepts
Decision lifecycle
How a commitment moves from standing to superseded to reconciled.
Decisions are the fact type with state. A decision is standing from the moment it is committed until a later decision supersedes it.
Supersession
Standing
A decision enters memory as standing. It ranks in search as though it were said today, no matter how old it is.
Contradiction detected
A later commit 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 search
Standing decisions never decay below neutral recency in search scoring. A policy set two years ago ranks like it was said yesterday. Once something supersedes it, the replacement takes its place and the old one fades unless you ask for it.
Record decisions deterministically by setting fact_type: "decision" on the
commit item; see Fact types.