Garry's Opinionated OpenClaw/Hermes Agent Brain
Connect GBrain to Codex
Adding memory to an existing Codex agent preserves its identity and needs no private repository. Use the memory-only walkthrough. Connecting an existing hosted brain? Choose native OAuth or a private machine handoff. Opening the owner dashboard or managing clients uses MCP administration with its separate owner credential.
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, memory, schedules, and a private repo as its durable body — not just a connection? That's
gbrain bootstrap: see the paste block in the README and docs/guides/bootstrap.md.
Fastest local path: gbrain setup codex
For a brain on this machine, one command creates a keyless brain when there is none, registers the stdio MCP server, wires the read-context hooks with their trust entries and smoke-tests the registration:
bun install -g github:garrytan/gbrain
gbrain setup codex --dry-run # the resolved target and every step; writes nothing
gbrain setup codex # wire and verify
gbrain setup codex --remove # remove only what setup wrote
It writes [mcp_servers.gbrain] and one [hooks.state."…"] trust table per
hook into $CODEX_HOME/config.toml, and the SessionStart and
UserPromptSubmit hooks into $CODEX_HOME/hooks.json. Codex runs a user hook
only when config.toml trusts its exact command, so setup writes both and owns
each entry by its sha256 fingerprint. Transcript capture (SessionEnd, with
--capture) and provider use (--providers) stay off unless you accept them;
--no-hooks registers MCP only. Per-turn push is observed on codex-cli 0.162.1:
setup reports native-verified when it owns the trusted UserPromptSubmit
hook. Details: setup guide.
Codex starts an MCP server with a short list of environment variables, so a key
you exported in your shell does not reach gbrain on its own. Setup therefore
lists the provider key names (OPENAI_API_KEY, VOYAGE_API_KEY,
ANTHROPIC_API_KEY and the other provider *_API_KEY and *_BASE_URL names)
under env_vars in [mcp_servers.gbrain]. Codex forwards each one that is set
and skips the rest, so a key you already use gives the session semantic search.
Only names are written, never values.
Install as a Codex plugin (recommended)
gbrain ships as a native Codex plugin — MCP server + a curated brain-first skill set in two commands:
codex plugin marketplace add garrytan/gbrain@codex-plugin # slim dist branch
codex plugin add gbrain@gbrain
The @codex-plugin ref is the release-published plugin dist (force-advanced
each release, like latest-stable). The bare garrytan/gbrain form also
works but downloads the full development repo and tracks master tip — use it
only for from-source installs. Refresh a snapshot with
codex plugin marketplace upgrade; remove with codex plugin remove gbrain@gbrain + codex plugin marketplace remove gbrain.
Persona variants (Claude-lane only, for now). The gbrain-coding /
gbrain-daily curated variants ship in the Claude Code marketplace; the
codex marketplace deliberately stays at the single full plugin until codex's
handling of multi-entry marketplaces gets its observation run (the dist
branch carries the variant trees already, so enabling is a two-line
marketplace edit once verified — TODOS.md follow-up).
Prerequisites. The plugin cannot ship the gbrain binary; install it once
(bun install -g github:garrytan/gbrain#stable — the npm package
named gbrain is unrelated, never npm install -g gbrain) and create a
brain (gbrain init — zero-config local PGLite by default). The bundled
setup skill walks both. With no binary, the plugin's MCP server exits with
that exact install one-liner on stderr; with no brain, it exits with
"No brain configured. Run: gbrain init". Unix (macOS/Linux) only.
What ships. The MCP server runs gbrain serve on the full surface with
--source-guard through the bundled launcher (.agents/gbrain-launcher,
resolution order: $GBRAIN_BIN → ~/.bun/bin/gbrain → gbrain on PATH — the
sanctioned install location is preferred over PATH so a stray gbrain earlier
on PATH can't shadow it).
full is every operation (the seven memory verbs, page and bulk writes
such as put_pages, graph and skill tools); the plugin keeps it because a plugin
update rewrites existing installs (new gbrain setup registrations pin starter). The curated skills drive host-side work through the
gbrain CLI. A harness that caps its tool count can narrow every new session
on this machine with GBRAIN_SURFACE=starter (or verbs) in the env that
launches Codex, or use the bootstrap lane below. Unlike the OpenClaw bundle, the plugin ships the host-side skills
too (setup, migrate, smoke-test, gbrain-upgrade, schema authoring) — a plugin
user IS the brain host.
Per-turn hook. The plugin also declares the UserPromptSubmit hook
gbrain setup codex writes (gbrain hook user-prompt --harness codex, 15 s),
run through the launcher with GBRAIN_HOOK_LANE=plugin. Codex skips a plugin
hook until you trust it: open /hooks in the CLI, review it, and trust it.
While a brain-first block is installed it puts the brain-first rule beside
each turn (gbrain setup codex --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 gbrain setup codex or gbrain bootstrap already wires the
event in $CODEX_HOME/hooks.json, the plugin's hook exits without output, so
each turn gets it once. GBRAIN_HOOKS=0, or a recorded gbrain setup codex --no-hooks, turns it off.
Routing under the plugin lane. The plugin serve is user-global and runs
with the plugin snapshot as its working directory, so the per-project
.gbrain-source / .gbrain-mount dotfiles never apply. Route the source
axis with GBRAIN_SOURCE=<source-id> in the environment that launches
Codex; route the brain axis with GBRAIN_BRAIN_ID (env only — there is no
config default for the brain axis). --source-guard makes this fail-closed:
when a brain has more than one source to choose from and no binding, write
and admin operations error with an actionable message until a source is bound
(the user-global stdio serve binds the source from GBRAIN_SOURCE, not a flag,
and exits at startup when that value names a source that is missing or
archived); a sole
real source is unambiguous and unaffected, and reads always pass. (Edge case:
a .gbrain-source dotfile placed at $HOME is an ancestor of the plugin
snapshot dir and would bind every plugin-lane write to it — put source pins
in project directories, not $HOME.)
One owner per name. Three lanes can each provide a server named
gbrain: this plugin, a hand-wired codex mcp add (below), and the
gbrain bootstrap harness managed block. Keep one. gbrain bootstrap hooks
skips its registration when the plugin is enabled (override:
--mcp-even-if-plugin), and gbrain doctor warns on a real
double-registration. A plugin being ENABLED is a config signal, not a health
signal — if its server isn't working, fix the binary, or remove the plugin.
Upgrading has two halves: codex plugin marketplace upgrade refreshes
the plugin snapshot (skills + manifests); the gbrain-upgrade skill or a
bun install -g github:garrytan/gbrain#stable re-run refreshes the
binary the launcher resolves.
Connect without the plugin
Recent versions of the Codex CLI (@openai/codex) support remote
streamable-HTTP MCP servers with a bearer token read from an environment
variable. Where the token lives depends on the path:
| Path | Where the bearer token lives |
|---|---|
gbrain connect <url> --token <token> --agent codex [--install] (this page) |
Your shell environment (GBRAIN_REMOTE_TOKEN); Codex's config stores only the variable name. |
gbrain connect <url> --harness codex --credentials-file <handoff> --install (the machine handoff) |
Inline in a managed, 0600 [mcp_servers.<name>] block in ~/.codex/config.toml. |
gbrain bootstrap harness (local agent-framework boxes) |
Inline in the same managed block; stated in its consent block, removable with gbrain bootstrap harness --remove. |
The inline paths exist because framework-spawned Codex inherits no shell
profile. Anything that reads or prints that config file (support bundles,
config diffs, agents inspecting MCP entries) can see a live token. The
--harness codex --install receipt says so: token_storage: "inline",
config_path, the renew_command that writes a fresh token (with
--fresh-token, so it exchanges a new token instead of reinstalling an
unexpired cached one), and if_exposed, which lists the
token invalidation preview and
apply commands for the brain host, then the renew command (a handoff without a
client secret needs a new handoff from the owner instead), then the Codex
reload. When the config file sits in a Git working tree that does not
ignore it, the receipt adds token_warning: add the file to that repository's
.gitignore or move the config, and follow if_exposed if it was already
committed. Rotating a client secret does not invalidate access tokens already
issued, so it is not the fix for an exposed token.
Fastest path: gbrain connect
Use the brain's configured HTTPS endpoint if it already has one. Otherwise,
publish on the brain host with gbrain mcp expose (tailnet-only is enough for
your own laptops; remote MCP guide), which prints
https://your-machine.your-tailnet.ts.net/mcp. Mint a token on the brain host,
then run gbrain connect inside the intended client environment. Substitute
the configured endpoint below for an existing ngrok or cloud-host deployment:
Say to your agent: "use my brain over mcp" — "put my brain on tailscale".
gbrain auth create "codex"
gbrain connect https://your-machine.your-tailnet.ts.net/mcp --token gbrain_xxx --agent codex
PGLite brains:
gbrain auth createopens the database, which fails withlive_servewhile the expose-managed service holds it. Mint the token before the service runs (ahead ofgbrain 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-tokenor the/admindashboard. Postgres brains mint fine while the server runs.
This prints a copy-paste block. Or wire it up directly and smoke-test the token:
gbrain connect https://your-machine.your-tailnet.ts.net/mcp --token gbrain_xxx --agent codex --install
--install runs codex mcp add for you, then makes one real call to the brain so
a wrong/expired token fails right away. Because Codex reads the token from the env
var at runtime, keep GBRAIN_REMOTE_TOKEN exported in your shell profile.
Manual setup
export GBRAIN_REMOTE_TOKEN=gbrain_xxx
codex mcp add gbrain --url https://your-machine.your-tailnet.ts.net/mcp \
--bearer-token-env-var GBRAIN_REMOTE_TOKEN
Codex stores the env-var name (GBRAIN_REMOTE_TOKEN), not the token itself, and
reads the value when it launches the MCP server. Add the export line to your
~/.zshrc / ~/.bashrc so it's set in every session.
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 codex --instructions-only
It writes one short marked block into $CODEX_HOME/AGENTS.md (or a non-empty AGENTS.override.md, since Codex
then reads only the override): 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 codex and gbrain connect --agent codex --install write it for
you; the Codex plugin and a hand-run codex mcp add do not. While the block is
installed, setup's UserPromptSubmit hook also leads every turn with the same rule.
After a hand-run codex mcp add, --instructions-only adds that hook on its own
(a group in $CODEX_HOME/hooks.json that prints only the rule, trusted in
config.toml), unless setup, bootstrap or a gbrain plugin already carries it. It
runs the hook once and exits non-zero with turn_hook_not_loaded when it does
not load (repair); /hooks inside a
session lists it.
gbrain doctor warns when the block is missing or out of date, or its per-turn
hook is missing or untrusted.
Always-loaded core memory
Codex does not put MCP server instructions in the prompt, so core memory (guide) reaches Codex through its user-global instruction file:
gbrain compile-context --target codex-global
This writes the default source's core block into a managed block in
$CODEX_HOME/AGENTS.md (default ~/.codex/AGENTS.md), which Codex loads in
every session. Rerun it after core changes (gbrain doctor names a stale copy);
gbrain compile-context --target codex-global --remove-core takes it out.
Verify
In Codex, ask it to use the brain:
Call get_brain_identity, then search my brain for [topic].
get_brain_identity confirms whose brain you're connected to; list_skills shows
everything it can do.
list_skillsempty? It's gated bymcp.publish_skillson the host — enable it withgbrain config set mcp.publish_skills true. The core tools (search, query, get_page, put_page, capture, think, find_experts) work regardless — prefercapturefor quick notes (auto-slug + dedupe),put_pagefor full-control writes; if a narrowed token's list lacks capture, useput_page. Why brains differ on the default: tutorial A1.
Remove
codex mcp remove gbrain
Notes
- The token is a long-lived secret that carries its grant's scopes (a
gbrain auth createtoken minted without--scopesis full-access). KeepGBRAIN_REMOTE_TOKENout of version control and prefer a scoped token if your host supports one. - Local stdio also works if you run the brain on the same machine:
gbrain setup codexregistersserve --surface starter --advertise verbsbehind gbrain's launcher, so the session directory'sbunfig.tomland.envnever load (gbrain serveregistered with a barecodex mcp addloads them). That is the daily-driver tool list every new registration gbrain writes pins (request_toolsreaches the rest;--surface fullis the opt-in for every operation). AGBRAIN_SURFACEvalue in the Codex server entry'senvtable overrides the flag. - PGLite brains are single-process. PGLite is a single-writer embedded
Postgres: the first running
gbrain serve(the plugin's, or a stdio registration) owns the brain's data directory via the data-dir lock. A secondserve— say, gbrain registered in a second harness on the same machine — or any CLI command that opens the DB fails on the lock while that serve is live (gbrain syncis the one exception: it delegates to the live serve). If multiple processes need the brain at once, run ONE sharedgbrain serve --httpand point every client at it (the remote paths above), or migrate to the Postgres/Supabase engine, which tolerates concurrent connections. Details: serve ↔ sync concurrency. - Ambient recall. Codex has lifecycle hooks (
SessionStart,UserPromptSubmit,SessionEndin$CODEX_HOME/hooks.json, each trusted by a[hooks.state]entry in config.toml);gbrain setup codexwires the two read-context hooks so brain pages named in a prompt arrive as context without a tool call.hooks.jsonis machine-wide, so those hooks name no source: each session reads context from the source its capture uses,GBRAIN_SOURCEfirst, else the.gbrain-sourcefile found walking up from the session's working directory (fixed for the session at its first hook). A repository's committed.gbrain-sourcetherefore picks which source Codex reads there, the same as everygbraincommand run in it. When that source has no serve of its own, the shared serve refuses withsource_mismatch(the hook heartbeat's reason) and the session gets no context rather than another source's (#5941). Without those hooks (the plugin,connector--no-hooks), use the pull path: at the start of a topical thread and after a compaction, callcontext_pack(entities, budget_tokens)to warm the standing entities; on a periodic wake calldelta(session_id, budget_tokens)for "what changed since my last wake" (deduped per session). Both are zero-LLM, sub-second, world-only by default, and on every surface,--surface verbsincluded. See ambient recall for the placement frontier.