brainbox

Connection guides

Every app that can share your one Brainbox memory — the same guides inside the workspace, open to everyone. Nothing here needs or shows any account data.

Claude (web & Desktop) claude.ai · Desktop Recipe verified

Add Brainbox as a custom connector, then keep the rules in a Project.

Recipe verified Custom connectors are standard Claude functionality; OAuth sign-in opens in your browser.

Part 1 · Connect the app

  1. In claude.ai or the Claude Desktop app, open Customize → Connectors → + → Add custom connector (older versions place Connectors under Settings).

  2. Paste the Brainbox connector URL:

    https://brainbox-mcp.thexi.dev/mcp
  3. Sign in with the Brainbox owner account (Google) and approve access when prompted.

  4. Create a Project and paste the memory rules into its instructions (Part 2 below).

Part 2 · Memory rules

Paste the memory rules into A Project's instructions (or your custom instructions). — copy them once for every app:

Part 3 · Optional automation & hooks

Automation is the rules block itself here — instructed recall and an explicit end_session digest. Deterministic hook packs are not available for this app.

Part 4 · Machine API key (headless & CI)

For headless or CI use, create a machine key in the workspace (Connections → Machine keys) and send "Authorization: Bearer bbk_…" to the same URL. The key is shown once at creation; only its hash is stored.

Claude Code terminal Recipe verified

One command, then one explicit authenticate step — adding alone signs nothing in.

Recipe verified The add/authenticate commands are the documented Claude Code MCP flow.

Part 1 · Connect the app

  1. Add the server (user scope loads it in every folder):

    claude mcp add --transport http --scope user brainbox https://brainbox-mcp.thexi.dev/mcp
  2. Start Claude Code, type /mcp, select brainbox, and choose Authenticate — this is what opens the browser to sign in. The add command alone opens nothing.

  3. Run /mcp again to confirm brainbox shows connected.

  4. Paste the memory rules into CLAUDE.md (project root, or ~/.claude/CLAUDE.md for everywhere).

Part 2 · Memory rules

Paste the memory rules into CLAUDE.md (project or user level). — copy them once for every app:

Part 3 · Optional automation & hooks

Automation is the rules block itself here — instructed recall and an explicit end_session digest. Deterministic hook packs are not available for this app.

Part 4 · Machine API key (headless & CI)

For headless or CI use, create a machine key in the workspace (Connections → Machine keys) and send "Authorization: Bearer bbk_…" to the same URL. The key is shown once at creation; only its hash is stored.

ChatGPT · Codex app app Recipe verified

End-to-end sign-in confirmed on this deployment; reconnect if you added Brainbox before.

Recipe verified Confirmed end-to-end here: the connector's Google sign-in completed and whoami returned the owner identity over OAuth.

Part 1 · Connect the app

  1. In ChatGPT (or the Codex app) open Settings → Connectors — enable developer mode first if you don't see it.

  2. Add a custom connector with the Brainbox URL:

    https://brainbox-mcp.thexi.dev/mcp
  3. Sign in with the Brainbox owner account (Google) and approve.

  4. Added Brainbox in ChatGPT before? Open the connector's settings and choose Reconnect, then sign in once — no new connector needed.

  5. Paste the memory rules into your custom instructions (or AGENTS.md for Codex projects). ChatGPT may ask permission before individual tool calls depending on your settings — approving is the normal flow.

Part 2 · Memory rules

Paste the memory rules into Custom instructions, or AGENTS.md in Codex projects. — copy them once for every app:

Part 3 · Optional automation & hooks

Automation is the rules block itself here — instructed recall and an explicit end_session digest. Deterministic hook packs are not available for this app.

Part 4 · Machine API key (headless & CI)

For headless or CI use, create a machine key in the workspace (Connections → Machine keys) and send "Authorization: Bearer bbk_…" to the same URL. The key is shown once at creation; only its hash is stored.

Codex CLI terminal Recipe verified

Adding the server isn't enough — run the separate login step or startup fails.

Recipe verified Commands verified against the current Codex CLI.

Part 1 · Connect the app

  1. Add Brainbox to your MCP config:

    codex mcp add brainbox --url https://brainbox-mcp.thexi.dev/mcp
  2. Sign in (a separate step — without it Codex reports “MCP startup incomplete (failed: brainbox)”):

    codex mcp login brainbox
  3. Headless / CI: skip OAuth entirely and use a machine key via an environment variable:

    codex mcp add brainbox --url https://brainbox-mcp.thexi.dev/mcp --bearer-token-env-var BRAINBOX_KEY
  4. Export BRAINBOX_KEY with a key from Part 4, and paste the memory rules into AGENTS.md.

Part 2 · Memory rules

Paste the memory rules into AGENTS.md in the project Codex works in. — copy them once for every app:

Part 3 · Optional automation & hooks

Automation is the rules block itself here — instructed recall and an explicit end_session digest. Deterministic hook packs are not available for this app.

Part 4 · Machine API key (headless & CI)

For headless or CI use, create a machine key in the workspace (Connections → Machine keys) and send "Authorization: Bearer bbk_…" to the same URL. The key is shown once at creation; only its hash is stored.

OpenCode terminal Recipe verified

A remote MCP entry in the config; OAuth is handled for you.

Recipe verified Config shape confirmed against the official OpenCode MCP documentation.

Part 1 · Connect the app

  1. Add Brainbox to your opencode config (~/.config/opencode/opencode.json):

    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "brainbox": {
          "type": "remote",
          "url": "https://brainbox-mcp.thexi.dev/mcp",
          "enabled": true
        }
      }
    }
  2. Authenticate once — this opens the browser and stores the tokens:

    opencode mcp auth brainbox
  3. Paste the memory rules into AGENTS.md (OpenCode reads it each session).

Part 2 · Memory rules

Paste the memory rules into AGENTS.md at the project root. — copy them once for every app:

Part 3 · Optional automation & hooks

The deeper plugin automation (wake briefs at session start, deterministic session digests) is awaiting migration to this deployment — its old hooks and endpoints (/ask, /turn/sync, /dream/end) no longer exist, so don't install the legacy plugin or hooks pack. Use the standard MCP connection and the memory rules above.

Part 4 · Machine API key (headless & CI)

For headless or CI use, create a machine key in the workspace (Connections → Machine keys) and send "Authorization: Bearer bbk_…" to the same URL. The key is shown once at creation; only its hash is stored.

Goose terminal · desktop Recipe verified

A remote Streamable HTTP extension; goose handles OAuth on first use.

Recipe verified Confirmed against the official goose extensions documentation.

Part 1 · Connect the app

  1. Run goose configure → Add Extension → Remote Extension (Streamable HTTP), name it brainbox, paste the URL:

    https://brainbox-mcp.thexi.dev/mcp
  2. Or edit ~/.config/goose/config.yaml directly:

    extensions:
      brainbox:
        name: Brainbox
        type: streamable_http
        uri: https://brainbox-mcp.thexi.dev/mcp
        enabled: true
        timeout: 300
  3. For a one-off session: goose session --with-streamable-http-extension with the same URL. Tip: disable goose's built-in memory extension so the two don't overlap.

Part 2 · Memory rules

Paste the memory rules into Your agent prompt file — paste the memory rules there so they are available in each conversation. — copy them once for every app:

Part 3 · Optional automation & hooks

The deeper plugin automation (wake briefs at session start, deterministic session digests) is awaiting migration to this deployment — its old hooks and endpoints (/ask, /turn/sync, /dream/end) no longer exist, so don't install the legacy plugin or hooks pack. Use the standard MCP connection and the memory rules above.

Part 4 · Machine API key (headless & CI)

For headless or CI use, create a machine key in the workspace (Connections → Machine keys) and send "Authorization: Bearer bbk_…" to the same URL. The key is shown once at creation; only its hash is stored.

Amp terminal Recipe verified

One add command; Amp starts the OAuth flow in your browser.

Recipe verified Command shape confirmed against the official Amp MCP documentation.

Part 1 · Connect the app

  1. Add Brainbox:

    amp mcp add brainbox https://brainbox-mcp.thexi.dev/mcp
  2. Start the Amp TUI — for remote OAuth servers Amp opens the browser and stores the tokens automatically.

  3. Paste the memory rules into AGENTS.md.

Part 2 · Memory rules

Paste the memory rules into AGENTS.md at the repo root. — copy them once for every app:

Part 3 · Optional automation & hooks

The deeper plugin automation (wake briefs at session start, deterministic session digests) is awaiting migration to this deployment — its old hooks and endpoints (/ask, /turn/sync, /dream/end) no longer exist, so don't install the legacy plugin or hooks pack. Use the standard MCP connection and the memory rules above.

Part 4 · Machine API key (headless & CI)

For headless or CI use, create a machine key in the workspace (Connections → Machine keys) and send "Authorization: Bearer bbk_…" to the same URL. The key is shown once at creation; only its hash is stored.

Grok app Unverified

Custom connectors have been reported; not confirmed against primary documentation.

Unverified Unverified: reported by the previous deployment (custom connectors, reportedly requiring SuperGrok / X Premium+). Confirm in your own Grok settings before relying on it.

Part 1 · Connect the app

  1. Reportedly: grok.com/connectors → New Connector → Custom → paste the Brainbox URL → sign in:

    https://brainbox-mcp.thexi.dev/mcp
  2. If the connectors panel is absent or behind a paid tier in your account, that is the current limit — nothing here is confirmed by Grok's documentation.

  3. Where supported, paste the memory rules into a Project's or your custom instructions.

Part 2 · Memory rules

Paste the memory rules into A Project's or custom instructions, where available. — copy them once for every app:

Part 3 · Optional automation & hooks

Automation is the rules block itself here — instructed recall and an explicit end_session digest. Deterministic hook packs are not available for this app.

Part 4 · Machine API key (headless & CI)

For headless or CI use, create a machine key in the workspace (Connections → Machine keys) and send "Authorization: Bearer bbk_…" to the same URL. The key is shown once at creation; only its hash is stored.

Google Antigravity agent manager · IDE Legacy recipe

Bridges through mcp-remote; two apps, one customization panel.

Legacy recipe Previous-deployment recipe — the panel location may have moved; re-verify in your Antigravity version.

Part 1 · Connect the app

  1. There are two apps — the Antigravity agent manager and the Antigravity IDE; set up whichever you use (the panel exists in both).

  2. Agent Manager → ••• → Customizations → Add MCP → command npx with these args:

    -y mcp-remote@latest https://brainbox-mcp.thexi.dev/mcp
  3. Sign in with the Brainbox owner account when the browser opens.

  4. Customizations → Rules → + Global, and paste the memory rules.

Part 2 · Memory rules

Paste the memory rules into Customizations → Rules (global). — copy them once for every app:

Part 3 · Optional automation & hooks

Automation is the rules block itself here — instructed recall and an explicit end_session digest. Deterministic hook packs are not available for this app.

Part 4 · Machine API key (headless & CI)

For headless or CI use, create a machine key in the workspace (Connections → Machine keys) and send "Authorization: Bearer bbk_…" to the same URL. The key is shown once at creation; only its hash is stored.

Gemini app app Not available yet

A place for Gemini — a verified Brainbox setup is still pending.

Not available yet We have not verified a custom MCP setup for the Gemini app. This is separate from Gemini CLI and Antigravity.

Part 1 · Connect the app

  1. There is no verified Gemini app setup in this guide yet.

  2. For a connection you can use now, choose one of the verified guides above. The Antigravity guide is also available, marked as a legacy recipe.

Part 2 · Memory rules

Paste the memory rules into — — copy them once for every app:

Part 3 · Optional automation & hooks

Automation is the rules block itself here — instructed recall and an explicit end_session digest. Deterministic hook packs are not available for this app.

Part 4 · Machine API key (headless & CI)

For headless or CI use, create a machine key in the workspace (Connections → Machine keys) and send "Authorization: Bearer bbk_…" to the same URL. The key is shown once at creation; only its hash is stored.

OpenClaw agent gateway Legacy recipe

Standard MCP over Streamable HTTP with a machine key.

Legacy recipe Command shape from the previous deployment — re-verify against your OpenClaw version (openclaw mcp --help).

Part 1 · Connect the app

  1. Add the server with a machine key from Part 4:

    openclaw mcp add brainbox --url https://brainbox-mcp.thexi.dev/mcp --transport streamable-http --header "Authorization=Bearer <bbk_key>"
  2. Verify the connection — it should list the registered Brainbox tools:

    openclaw mcp probe brainbox
  3. Paste the memory rules into ~/.openclaw/workspace/AGENTS.md and keep that config private — it holds your key.

Part 2 · Memory rules

Paste the memory rules into ~/.openclaw/workspace/AGENTS.md. — copy them once for every app:

Part 3 · Optional automation & hooks

The deeper plugin automation (wake briefs at session start, deterministic session digests) is awaiting migration to this deployment — its old hooks and endpoints (/ask, /turn/sync, /dream/end) no longer exist, so don't install the legacy plugin or hooks pack. Use the standard MCP connection and the memory rules above.

Part 4 · Machine API key (headless & CI)

For headless or CI use, create a machine key in the workspace (Connections → Machine keys) and send "Authorization: Bearer bbk_…" to the same URL. The key is shown once at creation; only its hash is stored.

Hermes Agent terminal Legacy recipe

A YAML MCP entry with the key read from the environment — never from the file.

Legacy recipe Config shape from the previous deployment (verified then against Hermes 0.18.x) — re-verify against your Hermes version.

Part 1 · Connect the app

  1. Add to ~/.hermes/config.yaml — the ${…} substitution keeps your key out of the file:

    mcp_servers:
      brainbox:
        url: "https://brainbox-mcp.thexi.dev/mcp"
        headers:
          Authorization: "Bearer ${BRAINBOX_KEY}"
  2. Export BRAINBOX_KEY with a machine key from Part 4, then test — it should list the registered Brainbox tools:

    hermes mcp test brainbox
  3. Paste the memory rules into your Hermes profile / system prompt.

Part 2 · Memory rules

Paste the memory rules into Your Hermes profile / system prompt. — copy them once for every app:

Part 3 · Optional automation & hooks

The deeper plugin automation (wake briefs at session start, deterministic session digests) is awaiting migration to this deployment — its old hooks and endpoints (/ask, /turn/sync, /dream/end) no longer exist, so don't install the legacy plugin or hooks pack. Use the standard MCP connection and the memory rules above.

Part 4 · Machine API key (headless & CI)

For headless or CI use, create a machine key in the workspace (Connections → Machine keys) and send "Authorization: Bearer bbk_…" to the same URL. The key is shown once at creation; only its hash is stored.

https://brainbox-mcp.thexi.dev/mcp

Added Brainbox to an app before? Just sign in again when the app asks (for example /mcp → Authenticate, or codex mcp login brainbox) — no duplicate entry needed.

The memory rules — one block, pasted wherever your AI reads every conversation
You have a persistent memory — Brainbox. Rules:

0. These rules apply ONLY when the Brainbox tools are present in this
   conversation (begin_session, recall, recent, remember, learn_lesson,
   correct, forget, end_session). If they are absent, skip all of this
   silently — do not mention Brainbox or look for workarounds.
1. At the start of a substantive conversation, call begin_session (a one-line
   digest of the session's intent is optional). Keep the session_id it
   returns — you will pass it to end_session in rule 5.
2. Before answering anything about the owner, their work, projects, or topics
   discussed before, call recall with the key terms. For "latest / recent /
   catch me up" questions use recent instead — recall is semantic, not
   temporal.
3. If recall returns nothing above its relevance floor, say so plainly —
   never invent a memory. Memory holds only what was explicitly stored.
4. When you learn something durable, store it in the SAME turn — one short,
   self-contained sentence; do not batch; skip small talk.
   - remember — facts, decisions, people, preferences, states of the world.
   - learn_lesson — reusable rules or insights that apply beyond this topic.
5. End substantive conversations with end_session, passing the session_id
   from rule 1 and a short explicit digest (key decisions, facts,
   corrections). The digest is stored exactly as you write it — Brainbox
   never invents or derives lessons from it.
6. Never store anything the owner has asked to keep out of this brain — for
   example employer-confidential data or other people's private information.
   Nothing is captured automatically or hidden from the owner.

Sessions close with the digest your agent files at end_session, carrying the session_id from begin_session — it's stored exactly as written, and nothing is derived from it automatically.