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

# Brain

> The company's memory primitive — a Postgres-owned knowledge base with document RAG and semantic memory, grounded answers with citations, and provable deletion.

Brain is your company's shared, governed knowledge base and memory. Agents (yours and Naive's) ingest documents once, then ask grounded questions and get answers with citations — or write and recall durable **semantic memory** (facts, entities, relationships) that compounds across runs.

Unlike the open web (`search`), Brain is company-specific and private: policies, docs, past decisions, product info. It is Naive-owned end to end — the canonical source of truth lives in a Postgres "spine" (documents, chunks, episodes, claims, provenance) with a semantic engine (GBrain) projected on top for richer recall. Reads degrade gracefully to the spine when the engine is unavailable, and deletion is provable.

<Note>
  Brain is an **opt-in** primitive. It's disabled by default on new companies. Enable it in the AccountKit's `primitives_config` (dashboard → Account Kits, or the kit's `brain: { enabled: true }`) before use, or calls return `403 primitive_disabled_by_kit`.
</Note>

## Two layers: documents and semantic memory

| Layer               | Write                                        | Read                                   | Use for                                                            |
| ------------------- | -------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------ |
| **Document RAG**    | `add`/`note` (ingest text/url/file)          | `query` (grounded answer + citations)  | Source material: docs, policies, specs, pages                      |
| **Semantic memory** | `remember` (episode → facts/entities/claims) | `recall`, `think`, `graph`, `timeline` | Durable facts that compound: decisions, preferences, relationships |

Both live in the same company-scoped knowledge base. A company gets a default "Default Brain" KB provisioned lazily on first use; you can create additional named KBs.

## CLI first

```bash theme={"theme":"css-variables"}
# Ingest source material
naive brain add --file ./handbook.pdf
naive brain add --text "Our refund policy is 30 days" --source policy

# Ask a grounded question (10 credits)
naive brain query "What is our refund policy?"

# Write + recall durable semantic memory
naive brain remember "Acme Corp prefers quarterly invoicing" --source crm
naive brain recall "Acme invoicing"
naive brain think "How should we bill Acme?"

# Explore the knowledge graph / timeline
naive brain graph --entity "Acme Corp"
naive brain timeline --entity "Acme Corp"
```

## Credits

| Operation                                                              | Cost       |
| ---------------------------------------------------------------------- | ---------- |
| `query`, `think`                                                       | 10 credits |
| document ingest (`add`, `note`, `replace-doc`)                         | 5 credits  |
| `recall`, `graph`, `timeline`, `remember`, `forget`, KB/doc list & get | Free       |

Plan-quota metering also applies per tenant for the `brain` primitive (across HTTP, SDK, and MCP).

## Grounded answers with citations

`query` returns an answer plus citations that map back to your ingested documents. Citations are scoped to the calling company and knowledge base — a citation that can't be mapped to one of your documents is dropped, so answers never leak another tenant's sources.

```json theme={"theme":"css-variables"}
{
  "answer": "Our refund policy allows returns within 30 days of purchase...",
  "citations": [
    { "document_id": "doc-uuid", "title": "handbook.pdf", "snippet": "Refunds are accepted within 30 days..." }
  ],
  "knowledge_base_id": "kb-uuid",
  "answer_mode": "synthesized",
  "session_id": "sess-uuid"
}
```

Pass the returned `session_id` back to `query`/`think` to continue the same conversation thread.

## Governance and deletion

* **Approval-gated destruction.** Deleting a knowledge base, deleting a document, and `forget` are approval-gated for agent (API-key) callers: the call returns `202` with a pending approval that an owner approves. Session owners execute immediately.
* **Provable deletion.** Deletes are provider-first and return a `DeletionReceipt` distinguishing `provider_confirmed` (the purge ran) from `verified` (post-purge emptiness was confirmed). Tombstones prevent forgotten data from resurfacing through the async semantic projection.
* **Memory Gateway.** Agent-produced memory can be routed through a proposal → review → promotion pipeline (`shadow` / `proposal` / `enforced` modes) so canonical company memory is never silently mutated. Review proposals in Mission Control.

## Interfaces

Brain is available across every surface:

* **API** — `/v1/brain/*` (and per-user `/v1/users/:id/brain/*`). See the [Brain API reference](/docs/api-reference/brain/overview).
* **SDK** — `naive.brain.*`. See the [brain sub-client](/docs/sdk/sub-clients/brain).
* **CLI** — `naive brain ...`. See the [CLI reference](/docs/cli/brain).
* **MCP** — 15 `naive_brain_*` tools for agents. See [MCP brain tools](/docs/mcp/brain).

## Typical workflow

```
1. Enable the brain primitive in the AccountKit
2. naive brain add --file ./policies.pdf        → ingest source material
3. naive brain docs                              → confirm status: ready
4. naive brain query "..."                       → grounded answers + citations
5. naive brain remember "..."                    → durable semantic facts
6. naive brain recall / think / graph / timeline → compounding memory
```