Brainbox

Brainbox as opencode's native memory backend.

A Tier-2 memory integration — not just an on-demand tool, but a plugin that:

1. exposes brainbox_recall / brainbox_store / brainbox_get tools the model can call,
2. auto-injects a WakeBrief into the system prompt at session start (recalled context, before turn 1), and
3. files a digest at session end for Brainbox's server-side dream cycle.

Ported from openclaw-brainbox onto opencode's @opencode-ai/plugin hook surface. Same transport client, same never-throws + cooldown contract.

Install

From a local checkout, reference it in ~/.config/opencode/opencode.jsonc:

{
  "plugin": [
    ["file:///Users/you/opencode-brainbox/index.js", { "baseUrl": "https://brainbox-mcp.thexi.dev" }]
  ]
}

(Non-secret options only — the API key comes from the environment, never the config file.)

Auth — never put the key in plaintext config

The bbk_ tenant key is read from BRAINBOX_BBK (or BRAINBOX_KEY). On macOS, keep it in the Keychain and export it at launch:

# one-time: store the key (service name matches the openclaw plugin's convention)
security add-generic-password -a "$USER" -s brainbox-api-key -w 'bbk_...' -U

# per shell / wrapper, before running opencode:
export BRAINBOX_BBK="$(security find-generic-password -s brainbox-api-key -w)"
opencode run -m openrouter/z-ai/glm-5.2 "…"

Hooks used (@opencode-ai/plugin)

Behaviour	Hook
recall / store / get tools	tool
WakeBrief injection at session start	experimental.chat.system.transform
open session + capture user text	chat.message
digest + continuous-encoder turn sync	experimental.text.complete
carry recalled context across compaction	experimental.session.compacting
file digest on explicit session end	event (session.deleted)
best-effort close on teardown	dispose

Note on session end: opencode has no explicit "session ended" hook. For headless opencode run (one-shot), dispose fires on process exit — an exact, clean end. For the long-lived TUI, the digest is filed on session.deleted and on dispose. Server-side lazy-close + TTL sweep means a missed end degrades, never corrupts.

Transport

• brainbox_recall → REST POST /ask (salience-ranked recall, confidence grades, evidence tags, honest abstention).
• brainbox_store / brainbox_get and the session tools → the worker's /mcp door (hand-rolled JSON-RPC streamable-HTTP client, no SDK).

All tools never throw: on any backend failure they return { disabled: true, unavailable: true, error } and open a cooldown window (default 60s) so a dead backend costs one timeout, not one per turn.

Memory-free runs

Set BRAINBOX_RECALL=off to disable the read paths (recall tool + WakeBrief injection) for a run; writes still flow. For a fully memory-free run, simply don't load the plugin. This switch carries no mode semantics — it's plain ergonomics.

Config options

key	default
baseUrl	https://brainbox-mcp.thexi.dev
apiKey	—	prefer ${BRAINBOX_BBK} env; a literal bbk_… is accepted
requestTimeoutMs	8000	per-request timeout
failureCooldownMs	60000	backoff after a backend failure
sessionChoreography	true	set false for tools-only (no WakeBrief / digest)
turnSync	true	continuous-encoder per-turn ingest