cabrain-cli

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

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

kind	name	what it does
command	/cabrain:recall [brain] <query>	hybrid recall, answer from memory
command	/cabrain:retain [brain] <content>	store a memory
command	/cabrain:brains [name]	list brains / brain details
command	/cabrain:new-brain <name>	create a new brain
command	/cabrain:connect [client]	wire the MCP into another client
command	/cabrain:status	endpoint + reachable brains
command	/cabrain:doctor	diagnose CLI / auth / MCP
agent	cabrain-curator	memory-first Q&A + retention (recall→answer→retain)
agent	cabrain-connector	onboarding: install, tokens, brains, datasources
skill	memory-first	the recall→answer/act→retain discipline
hook	SessionStart	auto-injects the memory-first rules into every session
hook	UserPromptSubmit	opt-in auto-recall — pulls relevant memories for each prompt

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

command	what it does
cabrain auth login [--url U] [--token T] [--agent ID] [--brain NS]	save credentials (verifies reachability)
cabrain auth logout	forget the saved token
cabrain auth whoami	show endpoint + which brains your token can reach
cabrain auth token new <agentId> [--admin] [--brain NS]	mint a token, optionally grant it a brain
cabrain auth token list	list tokens + grants (admin)
cabrain mcp	run the stdio MCP server (this is what clients invoke)
cabrain mcp:install <client> [--brain NS] [--name N] [--user]	wire the MCP into a client
cabrain mcp:print <client> [--brain NS]	print the config snippet, write nothing
cabrain mcp:uninstall <client> [--name N]	remove the cabrain entry from a client
cabrain brain list	list brains you can read
cabrain brain create <name> [--description D] [--token]	create a new empty named brain (+ optional scoped token)
cabrain brain delete <name> --confirm	delete a brain and all its memories
cabrain recall <brain> <query…>	hybrid recall (vector + BM25 + rerank)
cabrain retain <brain> <content…>	store a memory

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

Supported clients

client	config file it writes	format
claude-code	./.mcp.json (project) or ~/.claude.json with --user	JSON
claude-desktop	~/Library/Application Support/Claude/claude_desktop_config.json (mac), %APPDATA%\Claude\… (win), ~/.config/Claude/… (linux)	JSON
codex	~/.codex/config.toml [mcp_servers.cabrain]	TOML
gemini	~/.gemini/settings.json	JSON
cursor	~/.cursor/mcp.json	JSON
print	stdout only	JSON

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.

env var	meaning
CABRAIN_API_URL	base URL of the CaBrain app (default https://cabrain.fadymondy.com)
CABRAIN_TOKEN	ACL token, sent as X-Cabrain-Token (per-brain read/write; admin bypasses grants)
CABRAIN_AGENT_ID	this session's agent identity, sent as X-Agent-Id
CABRAIN_DEFAULT_NAMESPACE	bind the MCP session to one brain (tools default namespace to it)

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.