> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-exo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# When to use Exo

> Exo is worth its complexity when your product needs to know how a person reasons, not only what they wrote. Here is where the line falls.

Most retrieval problems are solved by a vector store. Exo is built for the ones that are not: when your product has to represent a person's reasoning, notice that their beliefs have changed, and say so out loud. That capability costs you a background pipeline and an asynchronous ingest path, so it should be a decision, not a default.

## The short version

**Use a vector store when you need the right passage. Use Exo when you need the right person.**

If you can state your requirement as "find the documents most similar to this query", a vector database answers it with less machinery than Exo. If your requirement contains the words *they*, *their*, *changed*, *decided*, or *usually*, you are asking about a subject rather than a corpus, and that is where Exo starts to pay.

## A plain vector store is enough when

* Your corpus is shared, not personal. Product documentation, a help centre, a legal library.
* Every document is equally authoritative and nothing supersedes anything else.
* You never need to know that the answer changed, only what the answer is now.
* Recency is a filter, not a meaning. A `created_at` sort covers you.
* One retrieval quality bar fits every user, because the users are interchangeable.

In that world, Exo's graph, its per-org model and its background cycle are structure you pay for and never read. Reach for pgvector, Pinecone or whatever your stack already runs.

## A thin memory layer is enough when

Memory products that store facts about a user and replay them into a prompt solve a real problem. They are sufficient when:

* The facts are flat and independent: a name, a plan tier, a stated preference.
* Nothing contradicts anything. The latest write is the true one.
* You want the model to remember, not to reason about how the user reasons.
* You are happy for the memory to be a list rather than a structure you can query.

Exo overlaps here, and if that is your whole requirement, the simpler product is the right call.

## Exo earns its place when

<Columns cols={2}>
  <Card title="Beliefs change and the change matters" icon="history" href="/concepts/belief-and-supersession">
    Exo never overwrites. It supersedes, transfers authority to the new belief, and keeps the chain queryable, so "what did they think before" is a request rather than an archaeology project.
  </Card>

  <Card title="A user disagrees with themselves" icon="git-compare" href="/concepts/contradiction">
    Contradictions come back with the retrieval instead of one side being silently picked. An agent can refuse to act on a belief that is currently in tension.
  </Card>

  <Card title="You need the reasoning, not only the result" icon="brain-circuit" href="/concepts/cognition">
    The `cognition` block reports confidence, the reasoning tier, whether the model escalated to slow deliberate reasoning, and which nodes it settled on.
  </Card>

  <Card title="Every end user needs their own layer" icon="users" href="/guides/subjects">
    Provision a subject per end user of your product. Each one gets an isolated partition, and one header selects it.
  </Card>

  <Card title="You are conditioning someone else's model" icon="message-square-quote" href="/guides/conditioning">
    Exo returns a prompt artifact, not raw facts, so your own LLM reasons and sounds like the subject. It works with Claude, GPT or a local model.
  </Card>

  <Card title="Degraded answers must announce themselves" icon="shield-alert" href="/concepts/retrieval-paths">
    Every retrieval reports `path` and `degradationReason`. There is no silent quality drop when the model is missing or stale.
  </Card>
</Columns>

## How the surfaces compare

Exo ships both primitives, so the comparison below is also a choice you make per call.

|                 | `POST /v1/search`                                                              | `POST /v1/retrieve`                                                       |
| --------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| Engine          | Hybrid vector plus keyword search, fused by reciprocal rank                    | The org's trained ExoBrain, falling back to the same hybrid search        |
| Returns         | `results[]` and `usage`                                                        | `sources[]`, `contradictions[]`, `cognition`, `path`, `degraded`, `usage` |
| Reasoning trace | None                                                                           | Present on the brain path, `null` on the fallback                         |
| Contradictions  | Not detected                                                                   | Detected and returned                                                     |
| Scope           | `user` filters to the effective subject, `org` searches the whole organization | Always the effective subject                                              |
| Use it for      | Ranked passages, cheaply                                                       | Answering about a person                                                  |

If all you ever call is `/v1/search`, you are using Exo as a vector store, and you should ask whether you need the rest of it.

<Note>
  `POST /v1/retrieve` accepts a `scope` field for request-body compatibility, but retrieval is always scoped to the effective subject. Sending `scope: "org"` does not widen it. When you genuinely want an org-wide read, use `POST /v1/search` with `scope: "org"`.
</Note>

## What Exo does not do

Stated plainly, because a comparison page that lists only strengths is an advertisement.

* **It is not a document store.** Ingest is asynchronous by design. You get a job id, then poll. If your product needs write-then-read-immediately, put a cache in front.
* **It does not decide who is right.** Contradictions are surfaced, not resolved. Every one comes back with `status: "open"`, because v1 stores no resolution lifecycle. You close one by superseding the side that lost.
* **A new org has no model.** Until the org's ExoBrain is trained, every retrieval runs on the hybrid path with `degraded: true` and `degradationReason: "no_brain"`. Cognition is `null` there.
* **Connectors are `github` only in v1.** Everything else comes in through ingest or import.
* **Export is JSON only.** The `format` field is pinned to a single value in the contract.
* **The event stream does not replay.** `Last-Event-ID` is accepted for compatibility with resuming clients but is not replayed in v1, and an org may hold five concurrent streams before the sixth is refused with `too_many_streams`.

## Running Exo alongside what you already have

The common shape is not a migration. Keep your vector store for the shared corpus and add Exo for the person: query your index for the documents, query Exo for who is asking and what they already concluded, then hand both to the model. `POST /v1/condition/session` exists exactly for that seam, because it returns a system prompt rather than more text for you to rank.

## Next

<Columns cols={2}>
  <Card title="How Exo works" icon="workflow" href="/how-exo-works">
    Content in, knowledge graph out, conditioned responses. The mental model in one page.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    From a key to a retrieve response in five steps.
  </Card>
</Columns>