When a fact stops being true
Recording the new decision is easy. The hard part is making sure the old one stops being followed. That is what supersession is for.
A familiar mess
Six months ago the project chose DynamoDB for the event store. Last month it moved to Postgres. Both facts are written down. Today an agent asks what the event store runs on.
If memory is a pile of text ranked by similarity, both facts come back. They are about the same subject, in nearly the same words. Nothing in the result says which one is still true. The agent picks one. Sometimes it picks the old one, because it was phrased more confidently, or it matched the question’s wording better. Then it writes DynamoDB code.
Similarity has no opinion about what is still true. That is not a tuning problem you fix with better embeddings. Something in the record has to know the decision was reversed.
Retire the fact, keep the story
When a decision replaces an earlier one, Stele draws a supersedes link. The old fact is retired: it stops being served as truth and ranks below live facts.
It is not deleted. It stays in the record, marked, and pointing at what replaced it. That matters for two reasons the codebase cannot cover on its own:
- “What did we decide before, and why did we change?” stays answerable. The rejected option often leaves no trace in the code.
- A mistaken retirement is a wrong label you can still see and correct, not a fact you have lost.
Every retirement has to say why
Retiring a fact is a claim that the world changed. Stele will not record it bare. A supersedes link needs a reason (what standing state ended) and evidence (a verbatim line from the source showing it ended).
That rule is doing real work. Compare:
| The new fact says | Did the old state end? |
|---|---|
| “We’ve moved off DynamoDB entirely.” | Yes. A termination. Supersede it. |
| “We also added a read replica.” | No. Additive. Nothing was retired. |
| “We’re still on Postgres.” | No. Continuation. |
| “We were planning the migration; now it’s running.” | No. Same story developing. Grow the fact instead. |
If the agent cannot state the reason, it is told to use relates-to instead: keep the connection, assert nothing.
The replacement always arrives with it
Marking a fact stale is only half an answer. “Don’t trust this,” with nothing else attached, forces the agent to guess.
So a retired fact never surfaces alone. When one is recalled, the fact that replaced it is pulled in alongside, ranked above it, carrying the reason for the change. That matters most when you ask using the old decision’s vocabulary and the stale fact is the closest word match.
contradicts: both stay live, both stay served, and the conflict is surfaced to be reconciled rather than flattened into a fake consensus.Catching a quiet mistake
A wrong retirement is quiet. The fact is still there, just labelled stale and ranked low. The health check surfaces claim-bearing links drawn without a reason. The verification sweep re-tests whether each retirement still meets the two-part rule: was it a standing state, and did it actually end? An edge that fails gets demoted; the fact it wrongly buried comes back.
Further reading
- When facts conflict (full walkthrough)
- The self-repairing graph
- Ingest