GET /v1/graph/nodes/{node_id}/history.
200 application/json
What it is
Supersession, the record that one belief replaced another (in practice, a directed link from the old node to the new one, plus the authority that moved with it). Most stores treat a changed mind as an update: the old text is gone and the new text is all that remains. Exo treats it as an event. The old node stays, the new node is linked to it as its successor, and the old node’s authority decays so retrieval stops preferring it. Nothing is destroyed, so you can still answer “what did they used to think, and when did that change”. That property is what makes the rest of the product possible. Contradictions are only meaningful if the losing side is still on record, and a Phase is only readable if beliefs carry the dates they held.Where it comes from
Supersession is explicit. Nothing supersedes automatically on ingest; you call the route when you know one belief replaced another.Fields
The history response has three arrays that answer three different questions.
A link in the
chain:
A
versions entry carries versionId, changeType, changedBy, an optional free-text rationale, and createdAt. An audit entry carries action, the truncated actorKeyHash of the key that acted, and createdAt. The audit trail names a key, never a person.
How to use it
Record the replacement, then read the trail back.curl will send the raw id, which works, but a URL builder in your language may not.
What confidence does
confidence sits in [0, 1] and drives the authority transfer: the superseded belief decays by 1 - confidence. The default of 1.0 fully demotes the old node, which is what you want when the replacement is certain. Send 0.6 when you are recording a shift you are not sure has settled, and the old belief keeps enough authority to still surface in retrieval.
The successor does not start from scratch. It inherits the higher of the two authorities, so replacing a high-authority belief with a new note does not quietly downgrade the answer. The response reports the successor’s resulting authority as newAuthority, so you never have to infer it.
Details worth knowing
Whether you supply the successor or Exo creates it
Whether you supply the successor or Exo creates it
Either, and exactly one. Send
content and Exo creates a successor node from that text, embeds it and links it. Send nodeId and Exo links a node you already own as the successor. Sending both, or neither, is a 422 validation_error, and so is naming the node itself as its own successor. The created field on the response tells you which of the two happened.Why a chain can be shorter than you expect
Why a chain can be shorter than you expect
The chain names only nodes the effective subject still owns and has not forgotten. A successor that was tombstoned drops out of the chain rather than leaking its id, so a belief revised three times can come back with two links. This is a privacy property, not a bug: forgetting has to be real even when the forgotten node was part of a history someone else can read.
What supersession does to the ExoBrain
What supersession does to the ExoBrain
It dirties it. Every mutation through the public API stamps the org’s brain as changed, so the next
POST /v1/retrieve still serves the brain’s answer but reports degraded: true with degradationReason: "brain_stale". The weights do not know about the new belief until you retrain. See Brain path and hybrid path.Which scope this needs
Which scope this needs
graph:write, which the write umbrella grants. Reading the history needs graph:write too, because the route sits on the mutation router rather than the read one. A read-only key gets a 403 permission_denied on both.Limits
- Supersession is a call you make, not something Exo infers. Ingesting a document that contradicts an earlier one creates a contradiction, not a supersession.
- There is no un-supersede. To reverse one, supersede in the other direction, which appends to the chain rather than erasing it.
- The audit trail names the acting key by a truncated hash. It does not name a person, and there is no route that resolves a hash back to a key.
rationaleis free text and is never parsed. It is for the human reading the history later.
Next
Contradiction
The conflicts a supersession is usually resolving.
How a memory is made
Where supersession sits between editing and forgetting.