cabrain-cli

Connect any AI client to the CaBrain memory system in one command.

cabrain is a single, dependency-free Go binary that is both the MCP server and its installer. It speaks the Model Context Protocol over stdio (a thin adapter over the CaBrain REST API), and it wires that server into every MCP host — Claude Desktop, Claude Code, Codex, Gemini CLI, Cursor — so a new user goes from zero to a working brain in two commands.

┌────────────┐   spawns    ┌──────────────┐   HTTPS + X-Cabrain-Token   ┌──────────────┐
│ MCP client │ ──────────▶ │ cabrain mcp  │ ──────────────────────────▶ │ CaBrain API  │
│ (Claude…)  │  (stdio)    │ (this binary)│                             │ brains + ACL │
└────────────┘             └──────────────┘                             └──────────────┘

Install

curl -fsSL https://cabrain.fadymondy.com/install.sh | sh

or, with Go:

go install github.com/togo-framework/cabrain-cli@latest   # installs `cabrain`

or, with npm:

npm i -g cabrain-cli

Upgrade to the latest anytime (npm / go / binary aware):

curl -fsSL https://cabrain.fadymondy.com/upgrade.sh | sh

Related MCP server: Letta MCP Server

Use it as a Claude Code plugin

This repo is also a Claude Code plugin — it bundles the CaBrain MCP, memory-first slash commands, two agents, and a skill. Install:

/plugin marketplace add togo-framework/cabrain-cli
/plugin install cabrain@cabrain

At enable time it prompts for your CaBrain token (and optional endpoint / default brain) and wires the MCP automatically — no .mcp.json editing. Requires the cabrain binary on PATH (any install method above), since the plugin's MCP server is cabrain mcp.

What the plugin adds

Hooks — auto push/pull

The plugin ships two hooks (backed by cabrain hook …, so no jq/python needed — the binary parses the hook JSON itself, and every hook fails open: any error → no output, never blocks you):

• Memory-first rules (SessionStart) — injects the recall→answer→retain discipline at the start of every session, so the model reaches for the brain automatically. On by default; turn off with the inject_rules plugin option or CABRAIN_HOOK_RULES=0.

• Auto-recall / pull (UserPromptSubmit) — uses each prompt to recall the top matching memories from your default brain and injects them as context. Opt-in (it hits the brain every prompt): enable the auto_recall plugin option or CABRAIN_HOOK_AUTORECALL=1, and set a default brain (CABRAIN_AUTORECALL_BRAIN, CABRAIN_DEFAULT_NAMESPACE, or the plugin's default-brain option). Needs a saved token (cabrain auth login) or the plugin's api_token.

Push (writing to the brain) stays model-driven on purpose — retention should be selective and distilled, not a firehose. The injected rules tell the model to memory_retain what's durable; /cabrain:retain and the cabrain-curator agent do it explicitly.

Standalone (outside the plugin) you can wire the same hooks in your own settings.json:

{
  "hooks": {
    "SessionStart":     [{ "hooks": [{ "type": "command", "command": "cabrain hook rules" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "cabrain hook recall" }] }]
  }
}

One-liner that installs, logs in, and wires a client in a single shot:

CABRAIN_TOKEN=cbt_… CABRAIN_CLIENT=claude-desktop \
  sh -c "$(curl -fsSL https://cabrain.fadymondy.com/install.sh)"

Quick start

cabrain auth login --token cbt_…          # save endpoint + token to ~/.cabrain/config.json
cabrain mcp:install claude-desktop        # wire the brain into your client — done
# restart the client; the brain tools (memory_recall, memory_retain, …) appear automatically

Get a token from an admin: cabrain auth token new my-laptop (admin), or ask the brain owner.

Commands

Colon (mcp:install) and space (mcp install) forms are equivalent.

Supported clients

Installs merge into existing config (other MCP servers are preserved) and are idempotent — re-running replaces just the cabrain entry.

Creating and sharing a brain

cabrain brain create research --description "market + competitor notes" --token

This seeds the namespace, mints a non-admin token scoped to just that brain, grants it read+write, and prints a ready-to-paste MCP snippet you can hand to a teammate — they paste it into their client (or run cabrain mcp:install <client> --brain research) and they're in, with access to only that brain.

Brains are enumerated from stored memories, so brain create writes one genesis marker to make the namespace exist and be connectable.

Configuration

Resolution order (highest wins): flags → environment → ~/.cabrain/config.json.

The installer bakes these into each client's env block, so the client launches cabrain mcp fully configured.

MCP tools exposed

memory_recall, memory_retain, memory_get, memory_forget, memory_edit, memory_gaps, memory_resolve_gap, brain_list, brain_details, brain_create, brain_delete, brain_grant, brain_revoke_grant, brain_create_token, brain_tokens, brain_chat, secret_list/store/reveal/delete, datasource_list/create/sync/delete — 24 tools mirroring the CaBrain REST contract.

Build

go build -ldflags "-X main.version=$(git describe --tags)" -o cabrain .

Zero external dependencies (stdlib only) → one static binary per platform.