Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.2 KB
Raw Blame

Connect GBrain to Claude Code

For an existing agent, start with the memory-only walkthrough; a personal-agent identity and private repository are optional. For an existing hosted brain, choose native OAuth or a private machine handoff. Owner login and client management use MCP administration, independently of the harness's OAuth scopes.

New to this? The Give your coding agent a memory tutorial walks both paths (local-from-nothing and connect-to-an-existing-brain) end to end, plus the brain-first protocol that makes it worth it. This page is the connection reference.

Want the full agent — identity, per-turn context, schedules, and a private repo as its durable body — not just a memory? That's gbrain bootstrap: see the paste block in the README and docs/guides/bootstrap.md. Open a new empty folder (bootstrap creates the private repo for you), or make an empty private repo under your own account and open the clone — bootstrap adopts it.

Fastest: gbrain setup claude-code

gbrain setup claude-code --dry-run   # the brain, source, launcher and owner it resolved; writes nothing
gbrain setup claude-code             # keyless brain if none, stdio MCP entry, read-context hooks, verified

Setup writes the same stdio entry as Option 1 into ~/.claude.json plus the SessionStart and UserPromptSubmit hooks into ~/.claude/settings.json, owned by hash through a connection receipt, and smoke-tests the registration. Capture hooks (--capture) and providers (--providers) stay off unless you accept them; --remove deletes only unchanged entries it wrote. It refuses instead of starting a second owner on a live PGLite brain or creating a local brain next to a hosted one. Details: gbrain setup.

Option 0: Install as a Claude Code plugin

gbrain ships as a native Claude Code plugin — MCP server + the curated brain-first skill set:

/plugin marketplace add garrytan/gbrain
/plugin install gbrain@gbrain

Two persona variants ship from the same marketplace — curated subsets for sessions that don't want all 67 skills in the native manifest:

/plugin install gbrain-coding@gbrain    # brain-first coding persona
/plugin install gbrain-daily@gbrain     # daily personal-brain persona

Install exactly ONE gbrain plugin per machine — every variant serves the same gbrain MCP server name, so two installed variants would double-serve. Curation lives in skills/plugin-lanes.json#personas (one recorded reason per skill). Alternative without a marketplace round-trip: gbrain skillpack scaffold --harness claude-code copies the same persona set into your user-scope skills dir with a local-edit-respecting update lens (see docs/guides/skillpacks-as-scaffolding.md).

(CLI form: claude plugin marketplace add garrytan/gbrain + claude plugin install gbrain@gbrain.) Prerequisites and behavior match the Codex plugin: the gbrain CLI installed (bun install -g github:garrytan/gbrain#stable), a brain (gbrain init), full MCP surface with --source-guard, and the same routing rules (GBRAIN_SOURCE/GBRAIN_BRAIN_ID env — dotfiles don't apply to a plugin-launched serve). Positioning: the plugin is the lightweight brain+skills path; gbrain bootstrap remains the deep lane (identity, hooks, push protocol). One approval-UX difference: the bootstrap lane pre-approves mcp__gbrain via permissions.allow for headless runs; plugin-provided MCP tools use the plugin lane's own approval flow.

Per-turn hook. Every gbrain plugin declares the UserPromptSubmit hook gbrain setup claude-code writes (gbrain hook user-prompt, 3 s), run through the launcher with GBRAIN_HOOK_LANE=plugin. While a brain-first block is installed it puts the brain-first rule beside each turn (gbrain setup claude-code --instructions-only writes the block; doctor harness_wiring and gbrain post-upgrade name that command when it's missing), and it adds the setup hook's read-context block when a serve is running. When setup, gbrain bootstrap or a workspace install already wires the event in your user settings or the project's .claude settings, the plugin's hook exits without output, so each turn gets it once. GBRAIN_HOOKS=0, or a recorded gbrain setup claude-code --no-hooks, turns it off.

Option 1: Local (recommended, zero server needed)

gbrain setup claude-code

Setup registers gbrain serve --surface starter --advertise verbs, adds the brain-first instructions and hooks, and runs a smoke test; --no-hooks skips the hooks. The MCP entry starts serve through gbrain's launcher (<gbrain config dir>/hook-launcher/gbrain-hook): Claude Code starts a stdio server in the session's directory, where a script-mode Bun install would load that directory's bunfig.toml and .env. Don't register gbrain serve with a bare claude mcp add for that reason. Claude Code spawns gbrain serve as a stdio subprocess. No server, no tunnel, no token needed. Works with both PGLite and Supabase engines.

PGLite brains are single-process. PGLite is a single-writer embedded Postgres: the first running gbrain serve owns the brain's data directory via the data-dir lock, for its whole lifetime. A second serve (e.g. a second harness or session registering the same stdio command) — or any CLI command that opens the DB — fails on the lock while that serve is live (gbrain sync is the one exception: it delegates to the live serve). If more than one process needs the brain at once, run ONE shared gbrain serve --http and point every client at it (Options 2/3 below), or migrate to the Postgres/Supabase engine, which tolerates concurrent connections. Details: serve ↔ sync concurrency.

--surface starter lists the daily-driver tools: the seven memory verbs (MEMORY_VERBS v1), search, query, get_page, put_page, capture, graph reads and skills. It is the surface every new registration gbrain writes pins (a bare serve still defaults to full). A parameter it leaves out is still accepted, and request_tools returns full schemas or widens the session to a left-out tool. --surface full lists every operation (put_pages, admin and tuning ops) and is the opt-in; --surface verbs lists only the seven verbs.

Option 2: Remote, one command (fastest from a bearer token)

If GBrain is running somewhere as an HTTP server and you have a bearer token, let gbrain connect generate the wire-up for you using that configured endpoint. If the brain still needs publishing, on the brain host, gbrain mcp expose publishes the server on your Tailscale tailnet and prints https://your-machine.your-tailnet.ts.net/mcp (tailnet-only is enough for your own laptops; remote MCP guide). ngrok stays an alternative (ngrok-tunnel recipe) — substitute its URL below.

Say to your agent: "use my brain over mcp" — "put my brain on tailscale".

Mint the token on the brain host. Run gbrain connect in the intended client environment to print its setup block:

gbrain auth create "claude-code"
gbrain connect https://your-machine.your-tailnet.ts.net/mcp --token gbrain_xxx

PGLite brains: gbrain auth create opens the database, which fails with live_serve while the expose-managed service holds it. Mint the token before the service runs (ahead of gbrain mcp expose, or while the service is stopped briefly), or provision through the running server instead — gbrain mcp grant … --admin-token-file ~/.gbrain/serve/admin-token or the /admin dashboard. Postgres brains mint fine while the server runs.

gbrain connect prints a short, copy-paste block. Paste it into Claude Code — it runs the claude mcp add for you and tells the agent to call get_brain_identity and list_skills so it immediately knows what the brain can do.

Already on the machine you want to wire up? Skip the copy-paste and let connect do it directly, with a built-in token smoke-test:

gbrain connect https://your-machine.your-tailnet.ts.net --token gbrain_xxx --install

(--install runs claude mcp add, then verifies the token by calling get_brain_identity — so a wrong or expired token fails now, not silently on the agent's first request. The URL is normalized: a bare host without /mcp gets it appended; pass an explicit https:// scheme.)

Pipe-friendly machine output (token redacted unless --show-token):

gbrain connect https://your-machine.your-tailnet.ts.net/mcp --token gbrain_xxx --json

Option 3: Remote, manual claude mcp add

Equivalent to what gbrain connect generates, if you'd rather run it yourself:

claude mcp add gbrain -t http \
  https://your-machine.your-tailnet.ts.net/mcp \
  -H "Authorization: Bearer YOUR_TOKEN"

Replace the host with your MagicDNS name (or your ngrok domain) and YOUR_TOKEN with a token from gbrain auth create "claude-code".

A gbrain auth create token is a long-lived secret that carries its grant's scopes (full-access when minted without --scopes). Keep it private (it lands in ~/.claude.json), and prefer a scoped/short-lived token where your host supports one.

Brain-first instructions

Registering the MCP server only makes the tools available. Agents seldom call a brain nobody told them about, so finish the install with:

gbrain setup claude-code --instructions-only

It writes one short marked block into ~/.claude/CLAUDE.md (with --scope project, ./CLAUDE.local.md): before answering any turn, search the brain first, read the best hit, fill gaps with other tools, apply your own access rules, then finish the task. Text outside the markers is never touched, a re-run upgrades the block in place, --dry-run previews it, --no-instructions opts out (and is remembered) and --remove takes it out. gbrain setup claude-code and gbrain connect --install write it for you. While the block is installed, setup's UserPromptSubmit hook also leads every turn with the same rule, beside the user's message, whether or not gbrain serve has context to add (--no-hooks installs no hook). After a plain claude mcp add, --instructions-only adds that hook on its own (a turn-rule-v1 entry in ~/.claude/settings.json that prints only the rule and reads no brain data), unless setup, bootstrap or a gbrain plugin already carries it. It runs the hook once to prove it loads and exits non-zero with turn_hook_not_loaded when it does not (repair); /hooks inside a session lists it. With no absolute gbrain binary to put in the hook, it prints the step instead. gbrain doctor warns when the block is missing or out of date, or its per-turn hook is missing or untrusted.

Verify

In Claude Code, try:

search for [any topic in your brain]

You should see results from your GBrain knowledge base.

list_skills returns nothing? Skill discovery is gated by mcp.publish_skills on the host. gbrain init sets it ON for new brains; a brain whose config never set the key stays OFF until you opt in. Enable it on the host with gbrain config set mcp.publish_skills true. Skill discovery and the core tools named here (search, query, get_page, put_page, think, find_experts) are full-surface — on --surface verbs the agent sees only the seven memory verbs, and list_skills isn't on the surface at all. capture is on the starter and full surfaces (prefer it for quick notes — auto-slug + dedupe; put_page for full-control writes); if your tool list doesn't carry it, use put_page, or remember on the verbs surface. Why brains differ on the default: tutorial A1.

Ambient recall at session boundaries

Two frozen verbs close the "no question fired" gap for long-lived sessions: context_pack (session-start warm-up + post-compaction rehydration) and delta ("what changed since my last wake" for heartbeats). Both are zero-LLM, sub-second, world-visibility by default, and available on --surface verbs.

  • Automatic (PGLite brains via gbrain bootstrap): the bootstrap hook installer wires SessionStart (injects a warm pack; also fires on post-compaction re-entry, source=compact) and PreCompact (banks the window's standing entities so that rehydration pack is warm) into .claude/settings.local.json. Nothing to call; GBRAIN_HOOKS=0 disables every hook event, including capture. Session start never shows another session's activity, and no setting turns that on.
  • Manual (any brain, incl. remote/Postgres): call the verbs yourself at boundaries — context_pack(entities, budget_tokens) at session start / after compaction, delta(session_id, budget_tokens) on wakes. See ambient recall for the placement frontier and the per-verb latency table.

Remove

claude mcp remove gbrain     # the Option 1 local/stdio registration
# Installed as the Option 0 plugin instead? Remove it with:
#   claude plugin uninstall gbrain@gbrain