Coming from Mem0 or Zep

If you have built on a memory layer before, most of what you know transfers. You add content, you scope it to a user, you search it back, you delete on request. Exo does all four. This page maps that vocabulary onto Exo’s routes and is specific about the three places where the model is genuinely different.

Everything below describes Exo’s own API, verified against the published contract. It does not make claims about any other product’s current behaviour. Check their documentation for theirs, then compare against what is written here.

Before you start

A key with write

Migration writes content and provisions subjects.

Your export in hand

Whatever your current layer gives you. Exo ingests plain text.

A user-id mapping

One subject per end user. Your existing user ids usually work as-is.

The vocabulary map

What you probably call it	In Exo	Route
Add a memory	Ingest content	`POST /v1/ingest`
Add many memories	Batch ingest, up to 500 items	`POST /v1/ingest/batch`
Search memories	Hybrid search, no reasoning	`POST /v1/search`
Retrieve context for an LLM	Retrieve, with reasoning and conflicts	`POST /v1/retrieve`
A user id on every call	A subject, selected by header	`PUT /v1/subjects/{id}`, then `X-Exo-Subject`
Update a memory	Edit a node	`PATCH /v1/graph/nodes/{id}`
Delete a memory	Forget a node, tombstoned for 30 days	`DELETE /v1/graph/nodes/{id}`
Delete a user	Erase a subject	`DELETE /v1/subjects/{id}`
Export my data	Async JSON export	`POST /v1/exports`
List what is stored	Page the graph	`GET /v1/graph/nodes`

The two habits worth unlearning:

Scoping is a header, not a body field. X-Exo-Subject selects whose partition you read and write. A user_id in the JSON body does not do it, and nothing warns you: the call silently acts as the key owner.
Writes are asynchronous. Every ingest returns 202 with a jobId. The content is durably queued, not yet searchable. Poll GET /v1/ingest/{jobId}/status, or subscribe to job.completed.

The shortest call that works

Your “add a memory” becomes this:

curl -X POST https://api.get-exo.com/v1/ingest \
  -H "X-Exo-API-Key: $EXO_KEY" \
  -H "X-Exo-Subject: customer_6412" \
  -H "Content-Type: application/json" \
  -d '{"content": "Prefers async review over live calls."}'

import httpx

r = httpx.post(
    "https://api.get-exo.com/v1/ingest",
    headers={"X-Exo-API-Key": EXO_KEY, "X-Exo-Subject": "customer_6412"},
    json={"content": "Prefers async review over live calls."},
)
job_id = r.json()["jobId"]

const r = await fetch("https://api.get-exo.com/v1/ingest", {
  method: "POST",
  headers: {
    "X-Exo-API-Key": process.env.EXO_KEY!,
    "X-Exo-Subject": "customer_6412",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ content: "Prefers async review over live calls." }),
});
const { jobId } = await r.json();

202 Accepted

{ "jobId": "3f9c1d84-6b02-4a71-9f5e-2c8b7d40a115", "status": "pending" }

Moving the data

Provision a subject per user

Idempotent, no request body. Run it over your whole user list; re-running is free.

for user_id in your_users:
    httpx.put(
        f"https://api.get-exo.com/v1/subjects/{user_id}",
        headers={"X-Exo-API-Key": EXO_KEY},
    )

Subject ids allow 1 to 128 characters of A-Za-z0-9._:-. Email addresses do not qualify, because @ is outside that set. Normalize before you start, and keep your own mapping: Exo never returns it.

Batch the content in

POST /v1/ingest/batch takes up to 500 items per call, each with up to 100,000 characters of content plus optional title, source_type and metadata.

import httpx, uuid

def migrate(subject_id: str, memories: list[str]) -> list[str]:
    job_ids: list[str] = []
    for i in range(0, len(memories), 500):
        chunk = memories[i : i + 500]
        r = httpx.post(
            "https://api.get-exo.com/v1/ingest/batch",
            headers={
                "X-Exo-API-Key": EXO_KEY,
                "X-Exo-Subject": subject_id,
                # Deterministic, so a re-run of the same slice never duplicates.
                "Idempotency-Key": f"migrate:{subject_id}:{i}",
            },
            json={"items": [{"content": m} for m in chunk]},
        )
        body = r.json()
        for item in body["results"]:
            if item["status"] == "skipped":
                log.warning("skipped: %s", item["reason"])
        job_ids += body["jobIds"]
    return job_ids

Put your old system’s record id into metadata so you can reconcile later:

{ "content": "Prefers async review.", "metadata": { "legacyId": "mem_44182" } }

Read results, not just status codes

A batch with invalid items still returns 202. Per-item outcomes live in results, in request order.

202 Accepted

{
  "total": 3,
  "succeeded": 1,
  "failed": 2,
  "ingested": 1,
  "skipped": 2,
  "results": [
    { "status": "skipped", "reason": "empty content" },
    { "status": "accepted", "node_id": "", "chunks": 0, "jobId": "8a1f..." },
    { "status": "skipped", "reason": "content too large" }
  ],
  "jobIds": ["8a1f..."]
}

Note that failed is total minus succeeded, so it includes the skipped items. If you are counting migration losses, read skipped, and read results to find out which of your records did not make it.

Wait for the graph to build

Ingest creates nodes. The connections, domains, identity and the rest are built by a background cycle afterwards, so a migration that finished five minutes ago will not yet answer well.

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

Watch for every job to reach succeeded, then give the cycle time before you judge retrieval quality. See How a memory is made.

Switch reads over

Point your retrieval at POST /v1/retrieve, and read path and degraded on the first responses. A freshly migrated organization has no trained brain, so expect "path": "hybrid" with "degradationReason": "no_brain". That is the honest baseline, and it is comparable to a vector store. Train a brain to get the reasoning layer. See Training and serving an ExoBrain.

What changes about conflicting facts

This is the difference that will actually affect your code. A memory layer that stores facts has to decide what happens when a new fact disagrees with an old one, and the usual answer is that the newer write wins and the older one is updated or dropped. That keeps reads clean. It also means a reversal, someone changing their mind, is indistinguishable from a correction, and neither is visible to your product. Exo does not overwrite. It keeps both and surfaces the conflict:

Part of a POST /v1/retrieve response

{
  "contradictions": [
    {
      "id": "cc_51a0f8d3b62e947c",
      "a": "usage-based only",
      "b": "seat plus usage",
      "tension": 0.55,
      "status": "open",
      "detectedAt": "2026-07-14T09:12:03Z"
    }
  ]
}

Three consequences to plan for:

Your agent can check before it acts. includeContradictions defaults to true on retrieve, so an agent can refuse to act on a contested belief rather than confidently picking the stale side.
You resolve conflicts explicitly, by superseding the side that lost with POST /v1/graph/nodes/{id}/supersede. The old belief stays in the chain and authority moves to the successor. See Contradictions in review.
status is always "open". v1 stores no resolution lifecycle, so ?status=resolved returns an empty page by design. Track closure on your side.

If you want last-write-wins behaviour, you can have it: supersede with the default confidence of 1.0 on every update, which fully demotes the previous belief. You just have to ask for it rather than get it silently.

What Exo adds

None of these has an equivalent in a store-and-search memory layer, and each is a real object with a real payload:

Cognition

Why the answer, not just what: focal nodes, gate confidence, and whether it reasoned fast or slow.

ConditioningPack

A ready-to-inject system prompt that makes your own LLM reason and write like the subject.

ManifoldState

The axes a person’s thinking actually varies along, discovered rather than assumed.

Honest degradation

path, degraded and degradationReason say when you are on the fallback, instead of quietly returning worse results.

What Exo does not do yet

Stated plainly, so you can check it against your requirements before you migrate rather than after:

Limit	Detail
Export format	JSON only. The contract pins `format` to a single value
Connectors	GitHub only in v1
Contradiction lifecycle	No stored resolution state. Every tension reads as `open`
SSE replay	`Last-Event-ID` is accepted but not replayed. Use a webhook for anything you cannot miss
Concurrent streams	5 per organization, then `429 too_many_streams`
Webhook endpoints	20 per organization
Team insights	`AgentFailurePattern` is defined in the contract, but no route serves it in v1
Undelete	Restores a node’s position, never its content. `contentRestored` is always false

When it goes wrong

What you see	Why	What to do
Everything landed on one user	The user id went in the body instead of `X-Exo-Subject`	Move it to the header, then erase and re-migrate the affected subject
`403 permission_denied` mid-migration	You ingested for a subject before provisioning it	`PUT /v1/subjects/{id}` first. An unprovisioned selector is refused before the handler runs. See permission_denied
Counts do not match your source	Items were skipped, and `202` hid it	Read `skipped` and `results`. `failed` counts skipped items too
Retrieval is worse than your old stack	No brain yet, or the background cycle has not run	Check `degradationReason`. `no_brain` and `cold_start` are both expected right after a migration
A retried batch created duplicates	No `Idempotency-Key`, or a different key on the retry	Use a deterministic key per slice, as in the migration snippet above
`422 validation_error` on a subject id	The id contains characters outside `A-Za-z0-9._:-`, such as `@`	Normalize ids before provisioning. See validation_error

One memory per end user

Provisioning, selecting and erasing the subjects you just created.

When to use Exo

The honest version of when a plain vector store is enough.

Start

Building with Exo

Platform

Coming from Mem0 or Zep

Before you start

A key with write

Your export in hand

A user-id mapping

The vocabulary map

The shortest call that works

Moving the data

What changes about conflicting facts

What Exo adds

Cognition

ConditioningPack

ManifoldState

Honest degradation

What Exo does not do yet

When it goes wrong

Next

One memory per end user

When to use Exo

​Before you start

A key with write

Your export in hand

A user-id mapping

​The vocabulary map

​The shortest call that works

​Moving the data

​What changes about conflicting facts

​What Exo adds

Cognition

ConditioningPack

ManifoldState

Honest degradation

​What Exo does not do yet

​When it goes wrong

​Next

One memory per end user

When to use Exo

Before you start

The vocabulary map

The shortest call that works

Moving the data

What changes about conflicting facts

What Exo adds

What Exo does not do yet

When it goes wrong

Next