Brain. Memory API

Docs / Connect Brain

Connect Brain

Install, connect, verify, repair, and revoke.

Connect Brain. Your coding agent integrates it, tests it, and shows you the proof.

Five-minute setup

Ask the Brain operator for three values:

  • the hosted MCP URL;
  • a Brain-bound key with records:read and context:read;
  • the company or personal Brain name you expect brain_status to return.

Install the unpublished, checksum-verified CLI directly from your service:

cURL
curl -fsSL https://docs.brain.new/downloads/install.sh | sh
export BRAIN_API_KEY="..."
brain connect --url "$BRAIN_MCP_URL" --company "Acme" --client auto
brain doctor --json

brain connect detects Codex, Claude Code, and Cursor. Use --client codex,claude,cursor to name them explicitly. The installer verifies the CLI, canonical Skill, reference, and generated client wrappers; brain connect installs the matching wrapper without overwriting a customer-owned file. It never accepts a key as an argument and never writes one into the repository.

Connect your agent

Give the agent the generated brain-integrate Skill, then ask it to resume from .brain/integration.json. The receipt is the state machine; chat history is not.

The agent must begin read-only, run brain_status, integrate Context at one product seam, resolve one citation with get_record, preserve the full response state, run the repository tests, and run the doctor. It may add remember only when writes are explicitly requested.

Codex setup

cURL
codex mcp add brain --url https://your-brain.example/mcp \
  --bearer-token-env-var BRAIN_API_KEY

Copy the generated Skill to your Codex skills directory, or keep it in the project instructions. The CLI emits the exact path it configured.

Claude Code setup

cURL
claude mcp add --transport http brain https://your-brain.example/mcp \
  --header 'Authorization: Bearer ${BRAIN_API_KEY}'

The generated Claude wrapper and canonical Skill have the same workflow; neither contains a credential.

Cursor setup

brain connect --client cursor merges only the brain entry into ~/.cursor/mcp.json and preserves unrelated servers. The header keeps ${env:BRAIN_API_KEY} as an environment reference. If Cursor was opened from the Dock, ensure its process receives that environment variable.

Generic MCP

Use Streamable HTTP at /mcp with Authorization: Bearer $BRAIN_API_KEY. Tool discovery returns exactly brain_status, context, get_record, and remember.

Read-only integration

Call context where the application must decide using prior facts—not at every screen or model call. Preserve:

  • status, including processing;
  • citations and their record_id values;
  • unknowns, conflicts, and abstained.reason;
  • budget, cost, watermark, and request identity.

Resolve at least one citation with get_record before the application treats Context as evidence. The application—not Brain and not the coding agent—keeps authority over accepted business state.

Idempotent writes

Add records:write only when the product genuinely needs new Records. One logical event gets one stable source identity and one stable idempotency key. A retry reuses both. Pass remember's watermark to the next context call as min_watermark; processing is an honest result, not a failure to hide.

On a dedicated test Brain with an explicitly writable key, brain doctor --json --write-probe adds two labelled synthetic Records with visibility: shareable: a stable Record whose replay must return the same Record and watermark, plus a per-run freshness Record whose watermark must produce a cited read-your-write result that resolves. Do not run it on customer production data by accident.

Citations and authority

Records are immutable inputs. Memories are derived claims. Objects are application-accepted state. Context is a bounded view for one task. A model can propose an Object; it cannot silently accept one. A citation proves what evidence Brain used, not that the application must agree with it.

Processing and watermarks

A successful write can still return a processing Record. The watermark names the evidence boundary. Retry Context with that boundary until it is ready, using bounded backoff. Never serve older Context as if it included the new write.

Errors and repair

brain doctor --json checks authentication, identity, tool discovery, annotations, scopes, failure shapes, Context, and citation resolution. Each failure records a stable code, surface, whether an agent can repair it, the next action, retry command, request ID when available, and a documentation URL.

Run brain receipt to inspect progress and brain support-bundle --json for a redacted handoff. Neither output includes a key, memory content, or Record identifier.

Status and doctor

cURL
brain status --json
brain doctor --json --query "a known customer fact"
brain receipt

Use a query whose answer the customer is authorized to inspect. The doctor stores only counts and check states; it never puts returned content into the receipt.

Revocation and deletion

brain disconnect removes only Brain-owned client configuration. It does not pretend to revoke the server credential. Ask the Brain operator to revoke the key by its safe last four characters; revocation takes effect on the next request. Rotate with a new key rather than restoring a revoked one.

Record or Brain deletion is a separate custody operation in the HTTP API. It is intentionally not an MCP tool and should never be part of an unattended agent installation.

Support bundles

cURL
brain support-bundle --output brain-support.json --json

Review the JSON before sharing it. It contains CLI version, safe endpoint metadata, receipt state, checks, and failure codes—not credentials, customer content, citation IDs, or query text.

Limitations

  • The design-partner path is scoped bearer authentication, not OAuth discovery.
  • Key issuance and server revocation are operator actions today.
  • The CLI is downloaded from the service; it is not published to npm.
  • The public sandbox is ephemeral InMemoryStore; customer durability is proven only on the authenticated SpineStore service.
  • Context conflicts and Object arbitration remain named product gaps; see Known limitations.