Brainbox

Name: Brainbox
Rating: 3.5 (1 reviews)
Author: CIF-AI

By CIF-AI 👁 39 views ▲ 0 votes

Brainbox as OpenClaw's native memory backend — plugins.slots.memory plugin

GitHub

Install

openclaw plugins install openclaw-memory-brainbox

README

# 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

```bash
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):

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

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

```bash
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  |

tools