# Brain for agents and IDEs

Start read-only.

Use the canonical OpenAPI or a generated SDK. Never invent credentials, endpoints, resources,
operations, fields, enum values, or response guarantees.

## Install the context

There is no package required for direct HTTP. Give an agent the exact API instructions and
contract without copying them into a prompt:

```bash
export BRAIN_API_BASE="https://your-brain.example/v1"
export BRAIN_API_KEY="..."
export BRAIN_ID="..."

BRAIN_ORIGIN="${BRAIN_API_BASE%/v1}"
curl -fsSL "$BRAIN_ORIGIN/agent.md" -o .brain-agent.md
curl -fsSL "$BRAIN_ORIGIN/openapi.yaml" -o .brain-openapi.yaml
```

Add `.brain-agent.md` and `.brain-openapi.yaml` to the agent's project context. Keep
`BRAIN_API_KEY` only in the runtime environment. The generated clients build from OpenAPI, but the
Brain client is **not published to npm or PyPI** yet; do not invent an install command or package
name.

## Integration order

1. Read `/llms.txt`.
2. Read `/agent.md` and `/openapi.yaml`.
3. Create or select a Brain outside the agent if the credential policy requires it.
4. Call `createContext` with a concrete task and a bounded token budget.
5. Preserve `citations`, `unknowns`, `conflicts`, `processing`, `abstained`, and `cost`.
6. Follow a citation with `getRecord` before turning retrieved text into an assertion.
7. Add writes only after the read path and custody boundary are verified.
8. Call `acceptObject` only when a human or deterministic application rule deliberately takes
   authority for the structured value.

This is the risk ladder: **read → verify → write idempotently → accept authority explicitly**.
The model may propose an Object value. It may not silently promote its own Memory into authority.

## Write rules

Use `Idempotency-Key` for retried writes. Do not persist an API key in source control, chat,
generated files, local storage, query strings, or logs. Do not treat a `202` Record as readable
until its processing watermark is ready.

## Truth and authority

Records are inputs. Memories are derived. Objects are application-accepted. Context is task-scoped.
Do not silently promote one layer into another. No read knob may change what is true.

## Response rules

Preserve citations and their `record_id`. Preserve named unknowns and conflicts even if the calling
model could produce a fluent answer without them. Preserve the three-field cost receipt:
`model_calls_total`, `embedding_calls`, and `generative_calls`.

## Deployment truth

The public sandbox uses `InMemoryStore`; it proves the contract and developer experience, not the
real memory engine. A private or local `SpineStore` deployment carries live memory. Never imply
that fixture data is customer data.

## Current limitations

Context `memories` are selected by exact Record lineage and keep tri-state ownership. Context
`conflicts` remain empty. Accepted Objects do not yet arbitrate Context.
The public sandbox's trace storage is process-local; private SpineStore traces are durable.
Operation scopes, forced row-level isolation, and spine deletion are implemented, but they do not
close the Context arbitration gaps.
Read [Known limitations](/guide/limits.html) before presenting the integration as production
complete.

## IDE snippets

### Codex and AGENTS.md

Tell Codex to read `/agent.md` and `/openapi.yaml`, start with `createContext`, keep the work
read-only, and cite every product claim to a returned Record.

### Claude Code and CLAUDE.md

Tell Claude Code that Brain has five resources and fifteen operations, that `openapi.yaml` is
binding, and that writes require an `Idempotency-Key`.

### Cursor, Copilot, and Windsurf

Attach `/llms.txt`, `/agent.md`, and `/openapi.yaml` as project context. Keep the credential in the
runtime environment as `BRAIN_API_KEY`; never paste it into an instruction file.