How Exo works

Exo is cognition middleware. It gives a model more than a user’s context: it gives it how that user reasons. Three things happen to get there, and the API exposes all three.

The loop

Every arrow into the graph is asynchronous, and every arrow out is a normal request. That asymmetry is the single most important thing to internalise: writes return a job id, reads return data.

Step one: content in

You push anything a person thinks in. Raw text through POST /v1/ingest, files and transcripts through POST /v1/import, coding-agent sessions through the session family, and repositories through the GitHub connector. Each call returns immediately with a job id:

202 application/json

{ "jobId": "b1f0c6d2-8a44-4b21-9a1e-6d1f0c6d28a4", "status": "pending" }

A background worker then chunks the content, embeds it, writes the nodes and links them into the graph. Poll GET /v1/ingest/{job_id}/status for progress, or GET /v1/jobs/{job_id} for the canonical cross-family view, where a finished import reports what your content actually became:

200 application/json

{
  "id": "b1f0c6d2-8a44-4b21-9a1e-6d1f0c6d28a4",
  "jobType": "import",
  "status": "succeeded",
  "result": { "nodesCreated": 41, "edgesCreated": 118, "domainsDetected": 6 },
  "createdAt": "2026-07-29T16:40:11Z",
  "completedAt": "2026-07-29T16:42:05Z",
  "error": null
}

That result block is the multi-phase import pipeline reporting itself. A single POST /v1/ingest writes one node through a leaner path and reports no result block at all, so result is null on those jobs. Read the absence as “this job type does not report”, not as “nothing happened”.

The two status routes speak different vocabularies for the same job. GET /v1/jobs/{job_id} returns the public set, pending | running | succeeded | failed | canceled. GET /v1/ingest/{job_id}/status is the older permanent alias and returns the worker’s own set, where success is spelled done. Poll for a terminal state rather than for one spelling of success.

Send an Idempotency-Key and a retry returns the original job id rather than a second copy. See Ingesting content.

Step two: the graph

What comes out is not an index of passages. It is a graph.

Nodes are units of content with a title, text and an authority level. Authority is why an imported document outranks a line an agent narrated about itself.
Edges are typed relations between nodes, some derived from structure, some from similarity, some asserted by you. An edge you assert has capped authority, so organic evidence always outranks a hand-written link.
Domains are communities the graph discovers in itself rather than a taxonomy you supply.

Node ids are opaque strings, and they contain colons. Their shape depends on how the content arrived, for example ingest:<user_id>:<content_hash> for a generic ingest and import:<user_id>:<index>:<hash> for an imported note. Store them as text with room to spare, encode them when you put one in a URL path, and never parse or regenerate one. The content hash is why re-ingesting identical content updates the same node instead of duplicating it.

Then a background cycle runs over it and writes the parts that make Exo different: identity signals and the cognitive manifold, phases clustered from real content dates, contradictions mined from belief reversals and retractions, and proposed edges the system is not confident enough to assert on its own. That cycle is why a brand-new organization returns empty recall collections. Nothing is broken. There is not enough content yet for the structure to exist. See How a memory is made.

Step three: reads

Four surfaces read the graph, and choosing between them is most of the integration design.

Surface	Ask it for	Returns
`POST /v1/retrieve`	The answer to a question about a person	Ranked `sources`, `contradictions`, `cognition`, and the `path` that served it
`POST /v1/search`	Ranked passages, without the reasoning layer	`results` and `usage`
`GET /v1/recall/{type}`	The cognitive state itself	`identity`, `graph`, `insights` or `temporal`
`POST /v1/condition/session`	A prompt for your own model	`systemPrompt`, `userVoiceHint`, `orgRecentContext`, `expiresAt`

retrieve is the flagship because it is the one that answers with provenance. condition is the one that matters if you are wiring Exo into an agent you already own: it hands back a prompt artifact rather than more text for you to rank.

The one asymmetry to plan around

Retrieval runs on the org’s trained ExoBrain when there is one, and falls back to hybrid vector plus keyword search when there is not. The response always says which:

`path`	`degraded`	`degradationReason`	What it means
`brain`	`false`	`null`	The trained model served the call
`brain`	`true`	`brain_stale`	The model answered, but the graph has changed since it trained
`hybrid`	`true`	`no_brain`	No model exists for this org yet, and the fallback found matching content
`hybrid`	`true`	`cold_start`	The fallback ran and matched nothing at all. Usually an org with no content yet

cognition is populated only on the brain path. On the hybrid path it is null, because there is no reasoning state to report. Build for null from day one: every new org starts there. See Brain path and hybrid path.

The objects you will meet

Seven named objects carry the capability that a vector store cannot express. Each has its own page with a real payload.

Cognition

Confidence, reasoning tier, whether it escalated to slow deliberate reasoning, and the nodes it settled on. From POST /v1/retrieve.

Contradiction

Two poles of a belief conflict and how tense it is. From GET /v1/contradictions.

Belief and supersession

How a belief was replaced and where authority went. From GET /v1/graph/nodes/{id}/history.

ManifoldState

Discovered thinking dimensions, basins and trajectory. From GET /v1/recall/identity.

Phase

Eras of thought clustered from content dates. From GET /v1/recall/temporal.

ConditioningPack

A ready-to-inject prompt with a voice profile and an expiry. From POST /v1/condition/session.

AgentFailurePattern

The recurring ways a team’s coding agents go wrong, anonymised. Defined in the contract, surface not in v1.

One layer per end user

If you are building a product with your own users, provision a subject for each of them. A subject is an isolated memory partition, backed by physical per-organization schema isolation rather than a filter on a shared table.

cURL

curl -X PUT https://api.get-exo.com/v1/subjects/customer_6412 \
  -H "X-Exo-API-Key: $EXO_KEY"

After that, every call acts as that subject when you send the X-Exo-Subject header, and acts as the key owner when you do not. DELETE /v1/subjects/{id} erases everything that end user ever stored, which is the documented erasure path. See One memory per end user and Subjects and isolation.

Where to go next

Quickstart

Five calls, from a key to a retrieve response you can read.

Concepts

What Exo stores, and why it is a graph rather than an index.

API reference

All 80 operations, with the traps the generated schema cannot carry.

Start

Building with Exo

Platform

How Exo works

The loop

Step one: content in

Step two: the graph

Step three: reads

The one asymmetry to plan around

The objects you will meet

Cognition

Contradiction

Belief and supersession

ManifoldState

Phase

ConditioningPack

AgentFailurePattern

One layer per end user

Where to go next

Quickstart

Concepts

API reference

​The loop

​Step one: content in

​Step two: the graph

​Step three: reads

​The one asymmetry to plan around

​The objects you will meet

Cognition

Contradiction

Belief and supersession

ManifoldState

Phase

ConditioningPack

AgentFailurePattern

​One layer per end user

​Where to go next

Quickstart

Concepts

API reference

The loop

Step one: content in

Step two: the graph

Step three: reads

The one asymmetry to plan around

The objects you will meet

One layer per end user

Where to go next