Cognition

The cognition block of a retrieval. Returned by POST /v1/retrieve.

200 application/json

{
  "cognition": {
    "confidence": 0.83,
    "driftRate": 0.02,
    "tier": "growing",
    "useSystem2": false,
    "focalNodeIds": ["ingest:4a1e88f0-9c2d-4f31-b7a0-5e6c1d820b93:7d3c9b1e04a2", "ingest:4a1e88f0-9c2d-4f31-b7a0-5e6c1d820b93:2b8f0c6d91a4"]
  },
  "path": "brain",
  "degraded": false,
  "degradationReason": null
}

What it is

Every retrieval API can tell you what it found. This one tells you what it did. Cognition, the trace of how the org’s trained model arrived at an answer (in practice, five numbers that say which nodes it settled on, how sure it was, how hard it worked, and whether the graph has moved out from under it). The block exists because “here are eight chunks and a score” is not enough to build on. If you are putting an answer in front of a user, deciding whether to ask a follow-up question, or choosing between showing a result and admitting uncertainty, you need the model’s own read on the answer. That is what confidence and useSystem2 are for. If you are running Exo in production over months, you need to know when the model has drifted away from the graph it learned. That is what driftRate is for.

Where it comes from

The block is produced by the ExoBrain forward pass, so it is present on the brain path and null on the hybrid fallback. A hybrid search ranks chunks; it has no reasoning state, so reporting a fabricated one would be worse than reporting nothing.

Fields

Field	Type	What it means
`confidence`	number	How strongly the model settled on this answer, from 0 to 1. Low confidence is the signal to ask a clarifying question rather than to assert.
`driftRate`	number	How far the region the model activated has moved from the state it trained on. 0 means aligned; it rises as the graph grows past the brain.
`tier`	string	The graph-maturity tier that served the call: `seed`, `sprout`, `growing`, `mature` or `deep`.
`useSystem2`	boolean	True when the model escalated to slow deliberate reasoning instead of a fast associative lookup.
`focalNodeIds`	string array	The knowledge-graph nodes the model settled on as the centre of the answer.

tier and useSystem2 are two different things

They are easy to conflate and they measure nothing alike. tier is about the graph. It is derived from how many nodes were in the served subgraph, so it reports how much material the model had to work with:

Tier	Served subgraph
`seed`	Under 20 nodes
`sprout`	Under 100 nodes
`growing`	Under 500 nodes
`mature`	Under 5000 nodes
`deep`	5000 nodes and up

A seed tier is not a worse answer, it is a smaller graph. It is the honest read on how much history a subject has accumulated, which makes it the field to watch during onboarding. useSystem2 is about this one query. The model escalates when its own confidence falls below the decision boundary, so a hard question against a large graph can still come back useSystem2: true. The escalation fires on low confidence, not on high drift. Read them together: tier: "deep" with useSystem2: true means a rich graph and a genuinely hard question. tier: "seed" with useSystem2: true means the model does not have enough to go on yet.

How to use it

Gate on the model’s own uncertainty instead of assuming every answer is equally good.

curl -sS -X POST https://api.get-exo.com/v1/retrieve \
  -H "X-Exo-API-Key: $EXO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Where did we land on the pricing model?", "topK": 8}'

import os, requests

r = requests.post(
    "https://api.get-exo.com/v1/retrieve",
    headers={"X-Exo-API-Key": os.environ["EXO_KEY"]},
    json={"query": "Where did we land on the pricing model?", "topK": 8},
)
r.raise_for_status()
body = r.json()

cog = body.get("cognition")
if cog is None:
    answer_mode = "sources_only"          # hybrid path, no reasoning state
elif cog["confidence"] < 0.5 or cog["useSystem2"]:
    answer_mode = "ask_a_follow_up"       # the model is not settled
else:
    answer_mode = "assert"

print(answer_mode, body["path"], body["degraded"])

const r = await fetch("https://api.get-exo.com/v1/retrieve", {
  method: "POST",
  headers: {
    "X-Exo-API-Key": process.env.EXO_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "Where did we land on the pricing model?",
    topK: 8,
  }),
});
if (!r.ok) throw new Error(`${r.status} ${await r.text()}`);
const body = await r.json();

const cog = body.cognition;
const answerMode =
  cog == null
    ? "sources_only"
    : cog.confidence < 0.5 || cog.useSystem2
      ? "ask_a_follow_up"
      : "assert";

console.log(answerMode, body.path, body.degraded);

focalNodeIds are ordinary node ids, so you can drill straight into one with GET /v1/graph/nodes/{node_id} to show a user exactly which memory the answer rests on.

Details worth knowing

Why cognition is null

The hybrid path served the call. Check path: it is hybrid whenever the org has no trained brain, the brain is unavailable, or the subject has no content yet. The hybrid path is vector plus keyword search with reciprocal-rank fusion, which produces rankings but no reasoning state, so cognition is null rather than zero-filled. Brain path and hybrid path covers how to tell the cases apart.

What a rising driftRate means in practice

The brain trained on a snapshot of the graph. Every ingest, edit and forget moves the graph away from that snapshot, and driftRate reports how far the region this query activated has moved. It is an early warning rather than an error: the answer is still the best one available. When it climbs, retrain with POST /v1/brain/train.driftRate and degradationReason: "brain_stale" are related but not the same. Drift is measured per query, at the region the query touched. Staleness is a property of the whole brain, and it is also raised when a mutation through the API dirties the graph in a way a node count would not notice.

Whether unknown keys in the block are safe to ignore

Yes, and you should plan on them. The block is versioned additively: a future reasoning tier may report extra fields, so treat unknown keys as forward compatible rather than as an error. Do not use a strict schema that rejects them.

How to see more of the reasoning than this block carries

POST /v1/brain/query runs one forward pass and returns the full glass-box result: the focal set with a per-node snippet, the plain nearest-neighbour head alongside it for comparison, the subgraph it ran over, and how many negative edges were in play. It is the route behind a “what did the model attend to” visualisation. It requires a trained brain and reads the key owner’s own content, so it does not accept the X-Exo-Subject selector.

Limits

cognition is null on every hybrid retrieval. Write your reader so a missing block is a normal branch, not an exception.
tier is documented as a string rather than a closed enum. The five values above are what ships today; do not switch exhaustively on them without a default.
The block reports the model’s own confidence, which is a statement about how firmly it settled, not a probability that the answer is factually correct.
There is no field that says which contradiction influenced the answer. Contradictions come back in their own array on the same response; the link between the two is the node id.

Brain path and hybrid path

Why cognition is null, what degraded means, and how to read degradationReason.

ExoBrain

The per-org model that produces this block, and when to retrain it.

The model

The seven objects

How it stays honest

Cognition

What it is

Where it comes from

Fields

tier and useSystem2 are two different things

How to use it

Details worth knowing

Limits

Next

Brain path and hybrid path

ExoBrain

​What it is

​Where it comes from

​Fields

​tier and useSystem2 are two different things

​How to use it

​Details worth knowing

​Limits

​Next

Brain path and hybrid path

ExoBrain

What it is

Where it comes from

Fields

tier and useSystem2 are two different things

How to use it

Details worth knowing

Limits

Next