Brain path and hybrid path

Four fields on every retrieval that say which engine answered and whether you should trust it as much as usual. Returned by POST /v1/retrieve.

200 application/json

{
  "path": "hybrid",
  "degraded": true,
  "degradationReason": "no_brain",
  "cognition": null,
  "usage": { "readUnits": 8, "embedTokens": 12, "brainInference": false }
}

What it is

Exo has two engines behind one route. Brain path, the org’s trained ExoBrain answering from learned weights (in practice, a model that has seen this graph and settled on a region of it). Hybrid path, vector plus keyword search over stored content, fused by reciprocal rank (in practice, ordinary retrieval, run when the brain cannot serve). You never choose. The route picks, then tells you what it picked. That last part is the design decision worth the page: a memory API that quietly degrades is worse than one that fails, because you cannot tell a thin answer from a wrong one. So path names the engine, degraded is the one boolean to branch on, and degradationReason says why.

Where it comes from

Two things in that diagram surprise people. A stale brain still answers: staleness is reported, not routed around, because a slightly out-of-date brain is still the best answer available. And cold_start overrides the other reasons: if the hybrid fallback ran and found nothing at all, the reason you get back is cold_start regardless of why you were on the fallback in the first place.

Fields

Field	Type	What it means
`path`	`"brain"` or `"hybrid"`	Which engine served the call.
`degraded`	boolean	True whenever the answer is not the best this org can produce. The single field to branch on.
`degradationReason`	string or null	`no_brain`, `brain_stale` or `cold_start`. Null only when `degraded` is false.
`cognition`	object or null	The reasoning trace. Present on the brain path, null on hybrid. See Cognition.
`usage.brainInference`	boolean	True when a brain forward pass ran. Mirrors `path` and is what you meter against.

The four states you can actually see

`path`	`degraded`	`degradationReason`	What happened
`brain`	`false`	`null`	The healthy case. The brain answered and the graph has not moved under it.
`brain`	`true`	`brain_stale`	The brain answered, but the graph was mutated through the API since it trained. The answer is real, the weights are behind.
`hybrid`	`true`	`no_brain`	No trained brain for this org. Train one, or accept ordinary search.
`hybrid`	`true`	`brain_stale`	A brain exists but its node and edge counts diverged far enough that it declined to serve.
`hybrid`	`true`	`cold_start`	The fallback ran and matched nothing. Usually an empty or still-processing subject, not an engine problem.

path: "hybrid" with degraded: false cannot happen. Every hybrid response is degraded by definition.

no_brain and brain_stale are different problems

no_brain is a setup gap: nobody has trained this org’s brain. The fix is POST /v1/brain/train, once. brain_stale is a maintenance signal: a brain exists and the graph has moved. It is raised two ways. The brain itself reports divergence when node and edge counts drift far enough, which sends you to the hybrid path. Separately, every mutation through the public API stamps the brain dirty, which keeps you on the brain path but sets degraded: true. That second mechanism exists because editing a node’s text or tombstoning it never changes a count, so a count check alone would call a stale brain healthy. cold_start is neither. It says the search found nothing, so check that the subject has content and that their import jobs have finished before you look at the brain at all.

How to use it

Branch on degraded once, and let degradationReason decide what you tell the user.

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()

if not body["degraded"]:
    notice = None
elif body["degradationReason"] == "cold_start":
    notice = "Nothing indexed for this subject yet."
elif body["degradationReason"] == "no_brain":
    notice = "Running on search. Train a brain for reasoning."
else:
    notice = "Answer may lag recent changes."

print(body["path"], notice)

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 notice = !body.degraded
  ? null
  : body.degradationReason === "cold_start"
    ? "Nothing indexed for this subject yet."
    : body.degradationReason === "no_brain"
      ? "Running on search. Train a brain for reasoning."
      : "Answer may lag recent changes.";

console.log(body.path, notice);

Write the null branch of cognition first. On a new org every retrieval is hybrid, so the degraded path is the one your code will exercise before any other.

Details worth knowing

Whether a degraded answer is a worse answer

Usually thinner rather than wrong. Hybrid retrieval still ranks the right content; what it cannot give you is the reasoning trace, the focal set, or the brain’s own confidence. If your product only shows sources, a degraded response may be indistinguishable to the user. If it shows confidence or explains itself, degraded is the field that should change the wording.

What still works on the hybrid path

sources with full provenance, contradictions, usage, traceId, latencyMs, expand=sources.content and streaming. Only cognition is withheld, because the hybrid path has no reasoning state to report and inventing one would be the exact dishonesty these fields exist to prevent.

How to clear brain_stale

Retrain with POST /v1/brain/train. Training is asynchronous and one train per org may be in flight, so a second call while one is running returns 409 conflict. The serve path picks the new brain up on its own once training finishes; you do not restart anything.

Why cold_start can appear on an org that has plenty of content

Because it is per call, not per org. It fires when this particular query matched nothing for the effective subject. A wrong X-Exo-Subject, a subject who has genuinely ingested nothing, or an import that is still running all produce it. Check GET /v1/jobs before assuming the query was bad.

Limits

The route decides. There is no parameter that forces the brain path or forbids it.
degradationReason is typed as a plain string. The three values above are what ships today; keep a default branch.
A brain_stale response does not say how stale. cognition.driftRate is the closest thing to a magnitude, and it only covers the region this query touched.
path describes the engine, not quality. It is not a confidence score, and it should not be shown to end users as one.

Cognition

The block that is present on one path and null on the other.

ExoBrain

What the per-org model is, and what training it costs you.

The model

The seven objects

How it stays honest

Brain path and hybrid path

What it is

Where it comes from

Fields

The four states you can actually see

no_brain and brain_stale are different problems

How to use it

Details worth knowing

Limits

Next

Cognition

ExoBrain

​What it is

​Where it comes from

​Fields

​The four states you can actually see

​no_brain and brain_stale are different problems

​How to use it

​Details worth knowing

​Limits

​Next

Cognition

ExoBrain

What it is

Where it comes from

Fields

The four states you can actually see

no_brain and brain_stale are different problems

How to use it

Details worth knowing

Limits

Next