Surfacing contradictions in review

Most memory systems resolve conflicts silently: the newest write wins and nobody finds out that a decision reversed. Exo surfaces the conflict instead and leaves the judgement to you. This guide wires that into a review step, from the event that fires to the supersession that closes it.

Before you start

A key with write

Listing needs read. Closing one needs graph:write, which a write key grants.

Some history

A contradiction needs two beliefs that disagree. One import is rarely enough.

A place to show them

A review queue, a Slack channel, or a pull-request comment.

The shortest call that works

curl "https://api.get-exo.com/v1/contradictions?pageSize=25" \
  -H "X-Exo-API-Key: $EXO_KEY"

import httpx

r = httpx.get(
    "https://api.get-exo.com/v1/contradictions",
    headers={"X-Exo-API-Key": EXO_KEY},
    params={"pageSize": 25},
)
page = r.json()

const r = await fetch(
  "https://api.get-exo.com/v1/contradictions?pageSize=25",
  { headers: { "X-Exo-API-Key": process.env.EXO_KEY! } },
);
const page = await r.json();

200 OK

{
  "data": [
    {
      "id": "cc_51a0f8d3b62e947c",
      "a": "usage-based only",
      "b": "seat plus usage",
      "tension": 0.55,
      "status": "open",
      "detectedAt": "2026-07-14T09:12:03Z"
    },
    {
      "id": "cc_4d92e07a3b6f15c8",
      "a": "Mobile is the 2026 priority",
      "b": "Defer mobile until the API ships",
      "tension": 0.75,
      "status": "open",
      "detectedAt": "2026-07-11T16:40:55Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Reading a contradiction

a and b are the two poles. What they contain depends on the kind of conflict:

Kind	`a` and `b` hold	Typical `tension`
Reversal	The from and to concepts, such as `"Postgres"` and `"DynamoDB"`	0.55
Retraction	The before and after belief text	0.75

tension is a 0 to 1 salience computed when you read, not stored. Retractions score higher than reversals because dropping a belief outright is a stronger signal than changing your mind about which option wins. Sort by it to put the sharpest conflicts at the top of a review queue.

Every contradiction comes back with status: "open". v1 stores no resolution state, so ?status=resolved returns an empty page by design rather than an error. Do not build a UI that waits for a contradiction to flip to resolved: it never will. Track closure on your side, and close the underlying conflict by superseding a belief.

Note also that a Contradiction carries no node ids. a and b are text. Closing one therefore takes an extra step: find the node behind the losing side first.

The review loop

Get told, do not poll

Subscribe to contradiction.detected rather than sweeping the list on a timer. Register a webhook so the review still happens when nobody has the dashboard open.

curl -X POST https://api.get-exo.com/v1/webhooks \
  -H "X-Exo-API-Key: $EXO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://hooks.example.com/exo/contradictions",
        "eventTypes": ["contradiction.detected"]
      }'

contradiction.detected is a person-scoped event: it reaches only endpoints registered by the person whose beliefs conflict. See Reacting to change.

Page the open list

Deliveries are thin by design, so fetch current state rather than trusting the payload. Page with nextCursor until hasMore is false.

curl "https://api.get-exo.com/v1/contradictions?pageSize=100&cursor=$CURSOR" \
  -H "X-Exo-API-Key: $EXO_KEY" \
  -H "X-Exo-Subject: customer_6412"

def open_contradictions(subject: str):
    cursor = None
    while True:
        page = httpx.get(
            "https://api.get-exo.com/v1/contradictions",
            headers={"X-Exo-API-Key": EXO_KEY, "X-Exo-Subject": subject},
            params={"pageSize": 100, **({"cursor": cursor} if cursor else {})},
        ).json()
        yield from page["data"]
        if not page["hasMore"]:
            return
        cursor = page["nextCursor"]

async function* openContradictions(subject: string) {
  let cursor: string | null = null;
  for (;;) {
    const qs = new URLSearchParams({ pageSize: "100" });
    if (cursor) qs.set("cursor", cursor);
    const page = await (
      await fetch(`https://api.get-exo.com/v1/contradictions?${qs}`, {
        headers: {
          "X-Exo-API-Key": process.env.EXO_KEY!,
          "X-Exo-Subject": subject,
        },
      })
    ).json();
    yield* page.data;
    if (!page.hasMore) return;
    cursor = page.nextCursor;
  }
}

Show a human both sides

Render a and b side by side with detectedAt and tension. Do not pick a winner automatically. The whole value of surfacing a conflict is that a person decides, and the person usually knows something the graph does not.A useful review card reads: “On 11 July you held Mobile is the 2026 priority. On 14 July you held Defer mobile until the API ships. Which one still stands?”

Find the node behind the losing side

GET /v1/recall/graph/search does a full-text match over stored chunk text and returns node ids, which is what the supersede call needs.

curl -G https://api.get-exo.com/v1/recall/graph/search \
  -H "X-Exo-API-Key: $EXO_KEY" \
  --data-urlencode "q=Mobile is the 2026 priority" \
  --data-urlencode "limit=5"

hits = httpx.get(
    "https://api.get-exo.com/v1/recall/graph/search",
    headers={"X-Exo-API-Key": EXO_KEY},
    params={"q": contradiction["a"], "limit": 5},
).json()

const qs = new URLSearchParams({ q: contradiction.a, limit: "5" });
const hits = await (
  await fetch(`https://api.get-exo.com/v1/recall/graph/search?${qs}`, {
    headers: { "X-Exo-API-Key": process.env.EXO_KEY! },
  })
).json();

A query with no usable search terms returns an empty list rather than an error, so guard for the empty case before you index into it. GET /v1/graph/nodes?q= is the alternative when you want a title substring match with cursor pagination instead.

Supersede the side that lost

POST /v1/graph/nodes/{id}/supersede records old -> superseded_by -> new. The old belief is not deleted: it stays in the chain, and authority moves to the successor.

curl -X POST https://api.get-exo.com/v1/graph/nodes/ingest:4a1e88f0-9c2d-4f31-b7a0-5e6c1d820b93:f38b0a4d7e19/supersede \
  -H "X-Exo-API-Key: $EXO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "content": "Mobile is deferred until the API ships. Revisit in Q1.",
        "confidence": 1.0,
        "reason": "Reviewed 2026-07-30, confirmed by the product council"
      }'

r = httpx.post(
    f"https://api.get-exo.com/v1/graph/nodes/{loser_node_id}/supersede",
    headers={"X-Exo-API-Key": EXO_KEY},
    json={
        "content": "Mobile is deferred until the API ships. Revisit in Q1.",
        "confidence": 1.0,
        "reason": "Reviewed 2026-07-30, confirmed by the product council",
    },
)

const r = await fetch(
  `https://api.get-exo.com/v1/graph/nodes/${loserNodeId}/supersede`,
  {
    method: "POST",
    headers: {
      "X-Exo-API-Key": process.env.EXO_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content: "Mobile is deferred until the API ships. Revisit in Q1.",
      confidence: 1.0,
      reason: "Reviewed 2026-07-30, confirmed by the product council",
    }),
  },
);

200 OK

{
  "oldNodeId": "ingest:4a1e88f0-9c2d-4f31-b7a0-5e6c1d820b93:f38b0a4d7e19",
  "newNodeId": "ingest:4a1e88f0-9c2d-4f31-b7a0-5e6c1d820b93:5a2e8c1f0d63",
  "edgeId": "api:ingest:4a1e88f0-9c2d-4f31-b7a0-5e6c1d820b93:f38b0a4d7e19:ingest:4a1e88f0-9c2d-4f31-b7a0-5e6c1d820b93:5a2e8c1f0d63:contradicts",
  "created": true,
  "newAuthority": 0.9
}

Send exactly one of content (create a successor from text) or nodeId (link an already-owned node as the successor). Sending both, or neither, is a validation error. Both nodes must belong to the effective subject; anything else is a 404.

Choosing a confidence

confidence drives the authority transfer. The successor inherits the higher of the two authorities, and the superseded belief decays by 1 - confidence.

`confidence`	Effect on the old belief	Use when
`1.0` (default)	Fully demoted	The reviewer is certain the old position is dead
`0.7`	Partly demoted, still carries weight	The new position is current but the old one had merit
`0.3`	Barely demoted	You are recording a shift in emphasis, not a reversal

Reach for a value below 1.0 when the old belief may still be right in some context. That is what keeps the chain honest rather than turning supersession into a soft delete.

Contradictions inline with retrieval

You do not have to run a separate review to see conflicts. POST /v1/retrieve returns the ones bearing on the current query in the same response as the answer:

curl -X POST https://api.get-exo.com/v1/retrieve \
  -H "X-Exo-API-Key: $EXO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is our mobile plan?", "includeContradictions": true}'

This is the version worth wiring into an agent: before it acts on a belief, it can check whether that belief is contested. includeContradictions defaults to true, so set it to false only when you want the cheaper call.

When it goes wrong

What you see	Why	What to do
`?status=resolved` returns an empty page	v1 stores no resolution lifecycle	Expected. Track closure on your side. See Contradiction
The list is empty on a rich graph	Contradictions need two beliefs that actually conflict, detected by the background cycle	Confirm content landed with `GET /v1/jobs`, then give the cycle time. See How a memory is made
`recall/graph/search` returns nothing for `a`	The pole text is a concept label, not a verbatim chunk	Search a distinctive phrase from the belief instead, or list nodes by domain
`404 node_not_found` on supersede	The node is not owned by the effective subject	Check `X-Exo-Subject`. Cross-subject nodes are 404, never a leak. See node_not_found
`422 validation_error` on supersede	Both `content` and `nodeId` were sent, or neither	Send exactly one. See validation_error
The same contradiction reappears	You superseded a different node than the one behind the pole	Confirm with `GET /v1/graph/nodes/{id}/history` that the chain records the belief you meant

Contradiction

The object itself, why status is always open, and how tension is derived.

Belief and supersession

Authority transfer, and reading a chain from GET /v1/graph/nodes/{id}/history.

Start

Building with Exo

Platform

Surfacing contradictions in review

Before you start

A key with write

Some history

A place to show them

The shortest call that works

Reading a contradiction

The review loop

Choosing a confidence

Contradictions inline with retrieval

When it goes wrong

Next

Contradiction

Belief and supersession

​Before you start

A key with write

Some history

A place to show them

​The shortest call that works

​Reading a contradiction

​The review loop

​Choosing a confidence

​Contradictions inline with retrieval

​When it goes wrong

​Next

Contradiction

Belief and supersession

Before you start

The shortest call that works

Reading a contradiction

The review loop

Choosing a confidence

Contradictions inline with retrieval

When it goes wrong

Next