Garry's Opinionated OpenClaw/Hermes Agent Brain
Connect GBrain to Grok Build
This guide is for the Grok Build CLI. For the personal Grok Bot with its own computer, use the dedicated Grok Bot guide.
This page is the MCP-registration reference for Grok Build — xAI's official
grokCLI (early beta, subscriber-gated; not the communitysuperagent-ai/grok-cli, which ships a collidinggrokbinary — see Troubleshooting). For the full brain install — CLI, engine, skills, dream cycle — follow INSTALL_FOR_AGENTS.md first; this page wires the finished brain into Grok Build over stdio MCP. Thegbrain bootstrappersistent-personal-agent path is not yet supported for Grok (Claude Code and Codex only today) — brain-only install is what this page delivers.
Grok Build spawns gbrain serve as a local stdio subprocess. No server, no
tunnel, no token needed. Works with both PGLite and Supabase engines.
Register (recommended)
grok mcp add gbrain -e "GBRAIN_HOME=$HOME" -- "$(command -v gbrain)" serve --surface starter --advertise verbs
--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 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.
Three facts about grok mcp add, all observed:
- The env flag is repeatable, one
KEY=valueper flag (-e A=1 -e B=2). Server argv goes after--. - Registration is lazy. The add writes config and exits 0 without
connecting — even for a nonexistent command. Verify with
grok mcp doctor(below), never with the add's exit code. - Scope: the default writes to
~/.grok/config.toml; add-s projectto write a committable./.grok/config.tomlinstead (reference secrets as${VAR}in project scope — values are stored verbatim).
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 grok-build --instructions-only
Grok Build has no instruction file gbrain writes, so this prints the block to paste into your Grok Build instructions: search the brain before reading sources one by one, read the best hit, fill gaps with other tools, apply your own access rules, then finish the task. Keep the marker lines, so a later paste replaces the old block; delete the block to opt out.
Direct config (equally supported)
The add command writes an [mcp_servers.gbrain] block into
~/.grok/config.toml (or ./.grok/config.toml with project scope; the
GROK_HOME env var relocates the user config dir). You can write it
yourself instead:
[mcp_servers.gbrain]
command = "gbrain"
args = ["serve", "--surface", "verbs"]
startup_timeout_sec = 60
enabled = true
[mcp_servers.gbrain.env]
GBRAIN_HOME = "/home/alice-example"
startup_timeout_sec defaults to 30; raise it (or export
GROK_MCP_STARTUP_TIMEOUT_SECS) if gbrain runs from source via bun run,
which cold-transpiles on first spawn. To remove gbrain, delete the block (or
set enabled = false to disable without losing the config).
Zero-config vendor fallback
Grok Build also reads MCP registrations from ~/.claude.json, .cursor/mcp.json,
and a project .mcp.json — at lower priority than its own config, and only
for folders you have trusted in Grok (fresh folders report
folder untrusted until you accept the trust prompt). If you already
registered gbrain for Claude Code, Grok may pick it up with zero
configuration. grok mcp doctor --json reports every source it consulted
and which one each server came from — check the source field to see which
config won before assuming the native one did.
Verify
grok mcp list --json # entry: {"name":"gbrain","enabled":true,...}
grok mcp doctor gbrain # THE real probe: spawns the server
grok mcp doctor gbrain performs the actual handshake — expect the checks
command found, server started, handshake OK, and N tools discovered
(the full surface; 7 on --surface verbs), exit 0. A broken registration exits 1 with a failing
check and a hint. Then one real round-trip:
grok -p "use the gbrain recall tool to answer: what did I import most recently?"
grok -p (single-turn headless) prints the final answer on stdout.
Import session logs
Grok Build writes one chat_history.jsonl per session under
~/.grok/sessions/<url-encoded-cwd>/<uuid>/ (GROK_HOME relocates the
user dir). Those dead logs import through the same gbrain transcripts ingest
lane as Claude Code / Codex / OpenClaw / Hermes:
gbrain transcripts ingest # discover, including ~/.grok/sessions
gbrain transcripts ingest --all # import every discovered harness log
gbrain transcripts ingest ~/.grok/sessions --format grok --dry-run
Say to your agent: "Archive my grok session transcripts" — "Import my Grok Build chat history into the brain."
Sidecars (updates.jsonl, events.jsonl, summary.json, prompt_history.jsonl)
are skipped; only chat_history.jsonl is a session. User/assistant text
turns land as conversation pages; system prompts, reasoning, and tool
traffic do not.
Headless auth + model pin
For cron jobs, CI, or any non-TTY run:
Auth: export
XAI_API_KEY(from console.x.ai). Keyless headless runs exit 1 withNot signed in;grok login --device-codeis the interactive-terminal alternative,grok loginthe browser one.Model pin: pass
-m <model>per call, or set it in config:[models] default = "grok-4.5"Updates: Grok self-updates by default. For pinned/reproducible environments, seed:
[cli] auto_update = false
Pair with cron
Grok Build has no built-in cron; schedule headless one-shots with your system scheduler:
# crontab: brain maintenance every 4 hours
0 */4 * * * XAI_API_KEY=... grok -p "Run gbrain sync and report anything unusual" --output-format plain
See docs/guides/cron-schedule.md for the full brain maintenance protocol (sync, embed, dream cycle).
Troubleshooting
- Wrong
grokon PATH — the communitysuperagent-ai/grok-clialso installs agrokbinary. The official CLI answersgrok --versionwithgrok X.Y.Z (buildhash); anything else is the other tool. Install the official one vianpm install -g @xai-official/grokorcurl -fsSL https://x.ai/cli/install.sh | bash. - grok ≠ groq ≠ ngrok — Grok Build (xAI,
XAI_API_KEY) is not Groq (the inference provider,GROQ_API_KEY) and not ngrok (tunnels). A mis-set key produces auth errors against the wrong service. Not signed in(exit 1) — no auth in a headless run. ExportXAI_API_KEYor rungrok login --device-code.- Doctor says
folder untrusted— the registration came from a vendor config (.mcp.json/~/.claude.json) in a folder Grok hasn't been told to trust. Trust the folder in an interactive session, or register natively withgrok mcp add. - Doctor times out on
server started— raisestartup_timeout_sec(orGROK_MCP_STARTUP_TIMEOUT_SECS=90) if gbrain runs viabun run. - Skills note:
gbrain skillpack scaffoldwritesskills/<name>/SKILL.mdinto your workspace, which Grok does not auto-discover as Grok skills (it reads.grok/skills,~/.grok/skills,~/.agents/skills, plugins). gbrain's skills still work as reference documents the agent reads;grok inspectshows what Grok actually discovered. grok inspect— the config-discovery audit: version, cwd trust, instructions, permissions, skills, agents, MCP sources.
Verified against Grok Build v1.0.4 (early beta — expect churn; the pin is enforced in CI). Dev-facing observed-behavior notes (exact flag semantics, exit-code caveats, config schema, CI pin values) live in GROK-CLI-PIN.md.