Brain. Memory API

Docs / Agents & IDEs

Agents & IDEs

Give coding agents the contract, constraints, and proof.

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:

cURL
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 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.