openclaw-memory-brainbox

Brainbox as OpenClaw's native memory backend, via the exclusive plugins.slots.memory slot. Replaces memory-core's memory_search/memory_get (same names, same param schemas — drop-in for existing system prompts) with graph recall from your Brainbox tenant, and adds memory_store. MEMORY.md and the file layer stay host-owned.

Requires OpenClaw >= 2026.7.1 (registerMemoryCapability; legacy seams used as fallback via optional chaining).

Install

openclaw plugins install openclaw-memory-brainbox
# kind:memory plugins auto-switch the slot on install (verified on 2026.7.1-beta.5).
# If yours didn't: openclaw config set plugins.slots.memory memory-brainbox

Auth — never put the key in plaintext config

Option A, env template (simplest; the gateway process must have the var):

openclaw config set plugins.entries.memory-brainbox.config.apiKey '${BRAINBOX_KEY}'

Option B, macOS Keychain via an exec SecretRef (recommended on Mac):

security add-generic-password -a "$USER" -s brainbox-api-key -w 'bbk_...' -U
openclaw config set --json secrets.providers.keychain '{
  "source": "exec",
  "command": "/usr/bin/security",
  "args": ["find-generic-password", "-s", "brainbox-api-key", "-w"],
  "jsonOnly": false,
  "trustedDirs": ["/usr/bin"],
  "allowInsecurePath": true
}'
openclaw config set --json plugins.entries.memory-brainbox.config.apiKey \
  '{"source": "exec", "provider": "keychain", "id": "brainbox-api-key"}'

Notes learned the hard way:

• trustedDirs + allowInsecurePath are both required for root-owned system binaries like /usr/bin/security — the secrets runtime otherwise insists the command be owned by the current user.
• Exec SecretRefs materialize at gateway startup. openclaw agent --local (embedded, no gateway) resolves env templates but not exec refs — if the key reads as unconfigured under --local, that's why.

Transport

• memory_search → REST POST /ask on brainbox-mcp.thexi.dev (raw recall results: salience, confidence grades, evidence tags, honest abstention).
• memory_get / memory_store → the same worker's /mcp door (hand-rolled JSON-RPC client, no SDK); these need server-side embeddings and R2, which is why they don't use raw Cypher.

All three 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.

Config

| key | default | | | ------------------ | -------------------------------- | -------------------------------- | | apiKey | — | bbk_ tenant key (SecretRef/env) | | baseUrl | https://brainbox-mcp.thexi.dev | | | requestTimeoutMs | 8000 | per-request timeout | | failureCooldownMs| 60000 | backoff after a backend failure |