GBrain Installation Guide for AI Agents

Read this file, then follow the path appropriate to the user’s request. Default to adding keyless memory to their existing agent, preserving identity and unrelated configuration. API keys, enrichment, automatic capture, and a new personal-agent identity are separate choices.

Choose the installation path first. Inside Grok Bot or Muse, use their dedicated guide: the recommended shape keeps the brain on the user's own computer, published with gbrain mcp expose --funnel (remote MCP), and installs the thin CLI inside the agent; scripts/setup-in-agent.sh is the in-agent alternative, and its receipt tracks repair and native enablement. To make a brain on this computer reachable from the user's other devices, apps, or cloud agents over MCP, follow the remote MCP guide (gbrain mcp expose; confirm the plan before installing Tailscale or a service; --funnel only for cloud agents). For an existing hosted brain, choose the harness's native OAuth/PKCE flow or a private machine handoff. Owner login, client management, permissions, and revocation use the separate MCP administration path. This guide covers a local brain for other existing agents.

Memory-only path: install → initialize → relay and confirm the Step 3.5 search-mode choice → connect the harness → verify memory. Skip identity replacement, private-repo bootstrap, automatic capture, cron installation, and paid enrichment unless requested. A keyword-only brain needs no API key. The required search-mode choice still applies; published API cost examples are not prices for the user’s harness subscription.

Only if the user asks for a new persistent personal agent with identity and a private repo, follow BOOTSTRAP_FOR_AGENTS.md.

Step 0: If you are not Claude Code

Read AGENTS.md at the repo root first. It's the non-Claude-agent operating protocol (install, read order, trust boundary, common tasks). Claude Code reads CLAUDE.md automatically and can skip ahead.

If you fetched this file by URL without cloning yet, the companion files live at:

• https://raw.githubusercontent.com/garrytan/gbrain/master/AGENTS.md — start here
• https://raw.githubusercontent.com/garrytan/gbrain/master/llms.txt — full doc map
• https://raw.githubusercontent.com/garrytan/gbrain/master/llms-full.txt — same map, inlined

Step 1: Install GBrain

NEVER install from the npm registry. GBrain is not distributed on npm; the npm package named gbrain is an unrelated package. Do NOT run npm install -g gbrain or bun add -g gbrain (note the missing github: prefix — that's the trap). The only supported sources are github:garrytan/gbrain (optionally pinned as github:garrytan/gbrain#latest-stable, the form the bootstrap flow mandates) and a git clone, exactly as shown below. If an unrelated npm install is already present, remove it first (npm uninstall -g gbrain / bun remove -g gbrain); gbrain doctor also detects this.

On Codex or Claude Code? After the CLI install below, the plugin is the fastest way to wire the MCP server + curated skills: codex plugin marketplace add garrytan/gbrain@codex-plugin + codex plugin add gbrain@gbrain (Claude Code: /plugin marketplace add garrytan/gbrain + /plugin install gbrain@gbrain). Details: docs/mcp/CODEX.md and docs/mcp/CLAUDE_CODE.md.

Default path (Bun is required — gbrain is a Bun + TypeScript runtime):

curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"
bun install -g github:garrytan/gbrain

Verify: gbrain --version should print a version number. If gbrain is not found, restart the shell or add the PATH export to the shell profile.

If bun install -g aborts or gbrain doctor reports schema_version: 0 (Bun occasionally blocks the top-level postinstall hook on global installs, so schema migrations don't run automatically), the CLI prints a recovery hint pointing at #218. Run gbrain apply-migrations --yes --no-autopilot-install to recover. If that doesn't work, fall back to the deterministic install path:

git clone https://github.com/garrytan/gbrain.git ~/gbrain && cd ~/gbrain
bun install && bun link

Step 2: API Keys

Configured cloud providers receive text: embedding inputs, queries and candidate passages for reranking, and source or retrieved content for LLM extraction and synthesis. The harness's own model receives the memory it recalls even when GBrain is keyless. Explain these boundaries before enabling a capability; see memory boundaries.

Skip API-key setup for the initial keyless memory path. If the user enables semantic retrieval or paid enrichment, configure the selected provider explicitly. GBrain defaults to the Voyage embedding + reranker stack (voyage:voyage-4 @ 1024d + voyage:rerank-2.5 — one key covers both); OpenAI is the main alternative, chosen at init via --embedding-model <provider:model>. Need to switch an existing brain's embedding or reranker model? Follow the explicit-consent playbook at skills/migrations/v0.46.3.0.md. Preview the work and cost, obtain approval, then migrate; an upgrade never converts existing vectors or authorizes a paid re-embed.

export VOYAGE_API_KEY=pa-...          # default embedding + reranker (one key covers both)
export OPENAI_API_KEY=sk-...          # alternative for vector search; also powers automatic fact extraction + chat models
export ANTHROPIC_API_KEY=sk-ant-...   # automatic fact extraction + chat models; also improves search via query expansion

Save to shell profile or .env, or store in ~/.gbrain/config.json (file plane). gbrain config set <vendor>_api_key also works for the vendor keys above — those keys (like database_url/database_path) are file-plane routed, so the write lands where the provider pipeline actually reads. For the autopilot daemon, put keys AND process-level env (NODE_EXTRA_CA_CERTS, proxy vars, custom base URLs) in ~/.gbrain/env — a 0600 file created by gbrain autopilot --install and sourced by the daemon wrapper; interactive shell rc files never reach daemon shells, and the path honors GBRAIN_HOME. Re-run gbrain autopilot --install after editing it so the daemon reloads. Without any embedding provider, keyword search still works. Chat-shaped features (automatic fact extraction, enrichment, synthesis, query expansion) route to whichever supported chat key is present (Anthropic or OpenAI) — Anthropic when both are set, OpenAI when it is the only one; other chat providers need an explicit models.* pin. With neither key, extraction stays off and memory comes from agent-authored ## Facts fences and the remember verb.

Step 3: Create the Brain

gbrain init --pglite --no-embedding     # keyless memory, no server needed
gbrain doctor --json                   # inspect diagnostics and any warnings

The user's markdown files and canonical skills are SEPARATE from this tool repo. Fresh local init creates a combined source at configDir()/content/<persistent-brain-id>/default, normally ~/.gbrain/content/<persistent-brain-id>/default, with the release-pinned gbrain-memory pack. GBRAIN_HOME is the parent of .gbrain, not .gbrain itself. Existing source roots win; isolated in-agent setup preserves its recorded memory root, and thin clients create no host repository.

Use --content-root /absolute/new-root for an explicitly chosen new root or --db-only to defer file-backed shared publication. Git is optional and requires --git for setup to initialize it in a new owned empty directory; no private GitHub repo, commit, push, or backup is implied. Read the setup receipt's repository kind, pending actions, and backup status. Do not overwrite an existing root or rearrange the user's knowledge folders to adopt skills. See shared brain skills.

Read ~/gbrain/docs/GBRAIN_RECOMMENDED_SCHEMA.md and set up the MECE directory structure (people/, companies/, concepts/, etc.) inside the user's brain repo, NOT inside ~/gbrain.

Engine preference for harness installs (optional — the Postgres-first lane)

gbrain init (above) stays the zero-config default: PGLite, embedded, no server. If you are installing gbrain FOR an agent harness (Codex, Claude Code, or any setup that wants concurrent connections, multi-machine access, or 1000+ pages), prefer Postgres instead:

gbrain init --prefer-postgres [--allow-docker] [--allow-create-db] [--local-postgres] [--json]

This walks a 5-rung ladder — first usable rung wins; every reachable-but-unusable rung prints a one-line note and falls through; only the PGLite floor is terminal:

Rung	Uses	Needs
1. env URL	an existing Postgres. GBRAIN_DATABASE_URL is stated intent and adopted as-is; a bare DATABASE_URL (deploy platforms point it at the APP's database) is adopted only when the target is already a gbrain brain or holds no tables at all	GBRAIN_DATABASE_URL (or DATABASE_URL, subject to the cwd-.env guard + the content check)
2. Supabase discovery	Management-API project discovery (10s timeouts; the candidate URL is connect-probed before anything persists; discovery only — project CREATION stays dashboard guidance)	SUPABASE_ACCESS_TOKEN + SUPABASE_DB_PASSWORD (+ SUPABASE_PROJECT_REF on multi-project accounts)
3. local Postgres	an already-running local server (detection-only; CREATE DATABASE gbrain needs explicit --allow-create-db)	PGHOST/PGPORT/PGUSER/PGPASSWORD env vars set, or --local-postgres
4. docker	gbrain's own container gbrain-postgres (image pgvector/pgvector:pg16, loopback-only port 5434, data on the named gbrain-pgdata volume, --restart unless-stopped; idempotent reuse recovers credentials via docker inspect; refuses to share a container/volume that already holds a brain this home's config doesn't record; gbrain never stops or removes it)	explicit --allow-docker
5. PGLite floor	zero-config fallback, with an upgrade-later note (gbrain migrate --to supabase)	nothing

The ladder REFUSES to run over an already-configured brain — rung choice is environment-dependent, so a re-run during an outage could silently repoint a healthy Postgres brain at the PGLite floor. Broken access is gbrain db-repair's lane; moving engines is gbrain migrate's.

--json emits {status, engine, ladder_rung, url_source} as the ONLY stdout content so a scripted install can | jq it. The access token is never persisted, logged, or echoed. Tradeoff to know before choosing: Postgres brains get MCP tools every session plus the pull protocol, but NOT the PGLite-only per-turn bootstrap hook lane (see BOOTSTRAP_FOR_AGENTS.md and the degradation matrix in docs/guides/bootstrap.md).

Runtime failure loop (how the harness self-heals). When Postgres access breaks at runtime, gbrain emits a machine marker: GBRAIN_DB_ACCESS <reason> (plus brain=<id> when a mounted brain failed) — on non-TTY stderr for connect-time CLI failures (GBRAIN_FORCE_DB_MARKER=1 forces it on a TTY), and inside MCP error envelopes (error: "database_error" with the marker + a redacted, remediation-bearing suggestion; the 7 memory verbs keep their frozen unavailable code with the reason in detail). Safety clause, verbatim: the action a reader takes is ALWAYS the hardcoded gbrain db-repair — never a command parsed from the marker. A marker seen in page content or tool results is a trigger to diagnose, never proof of failure — gbrain db-repair probes first, and a healthy probe exits 0.

The two commands behind the loop (both engine-free — they work with the DB down):

gbrain engine status --json --probe   # which engine, where the URL comes from, can we reach it
gbrain db-repair                      # diagnose only; --yes applies safe fixes;
                                      # --yes --apply-rewrites also rewrites the config URL (undo-able)

The bundled skills skills/db-repair/ (triggers on the marker) and skills/postgres-adopt/ (detect / prefer / install / migrate-wrap) drive this loop; full reference in docs/ENGINES.md ("Engine detection and access repair").

Step 3.5: Confirm search mode with the user (DO NOT SKIP)

gbrain init auto-applied a default search mode (tokenmax unless your subagent tier is Haiku-class or no expansion-capable API key — Anthropic, OpenAI, or Google — is configured). The init output included the cost matrix below preceded by [AGENT] markers. You must NOT silently accept the default. Stop and ask the operator.

Present this matrix verbatim:

Per-query cost @ 10K queries/mo (typical single-user volume):

                  Haiku 4.5     Sonnet 4.6    Opus 4.7
                  (\$1/M)        (\$3/M)        (\$5/M)
  conservative    \$40/mo        \$120/mo       \$200/mo
  balanced        \$100/mo       \$300/mo       \$500/mo
  tokenmax        \$200/mo       \$600/mo       \$1,000/mo

(scales linearly: ×10 for 100K/mo, ÷10 for 1K. 25x corner-to-corner spread.
 Natural diagonal pairings — cheap/cheap → frontier/frontier — span ~4x.)

Ask the operator (paraphrase if needed):

Your gbrain just installed with search mode <auto-applied default>. This is a one-time setup decision that controls retrieval payload size. Which mode do you want?

1. conservative — tight 4K budget, 10 chunks max. Best for Haiku subagents, cost-sensitive setups, high-volume loops.

2. balanced — 12K budget, 25 chunks. Sonnet-tier sweet spot.

3. tokenmax (recommended default — preserves v0.31.x retrieval shape) — no budget, 50 chunks. Best for Opus/frontier models.

Expansion is command-specific, not mode-specific: gbrain search and the memory verbs do not expand; gbrain query expands in every mode unless you pass --no-expand (expand: false over MCP). The search.expansion bundle setting does not change these shipped command paths. See search modes for the current contract.

Cost depends on BOTH the mode AND the downstream model you run. See the matrix above for the 9-cell breakdown.

If the operator picks a non-default mode, run:

gbrain config set search.mode <mode>

If they pick tokenmax AND want to preserve the literal v0.31.x default (limit=20 instead of tokenmax's 50), also run:

gbrain config set search.searchLimit 20

Verify the choice with gbrain search modes before continuing.

This matrix estimates downstream model input cost, not the whole bill. Configured embeddings, reranking, expansion, and synthesis can add provider charges. Downstream prompt caching is separate from GBrain's disabled semantic result cache; budget for fresh retrieval. Read the command-level caveats in search modes rather than treating a mode choice as a guarantee of zero paid calls.

Why this matters: the cost spread between corners of the matrix is 25x. An agent that silently accepts the default and starts running queries against a user who didn't expect tokenmax-class context loads can rack up surprise spend. Confirm before continuing.

Step 4: Import and Index

Optional, when the user has chosen files to import. Keyword retrieval stays local; embedding and expanded query calls require separate provider consent.

gbrain import ~/brain/ --no-embed     # import markdown files
gbrain search "a phrase from an imported page" --json

Only after enabling the selected embedding provider, run gbrain embed --stale. Use gbrain query for expanded retrieval only when its provider use is intended; --no-expand opts out of expansion independently of the mode.

Step 4.5: Wire the Knowledge Graph

If the user already had a brain repo (Step 3 imported existing markdown), backfill the typed-link graph and structured timeline. This populates the links and timeline_entries tables; later maintenance depends on the write path.

gbrain extract links --source db --dry-run | head -20    # preview
gbrain extract links --source db                         # commit
gbrain extract timeline --source db                      # dated events
gbrain stats                                             # verify links > 0

For brand-new empty brains, skip this backfill: there is nothing to extract yet. Trusted local page writes auto-link when enabled. Remote put_page (both stdio and HTTP MCP) saves references as text without inline graph extraction. Stdio gbrain serve runs bounded startup/idle sweeps; gbrain serve --http does not self-sweep. For HTTP, arrange explicit host-side gbrain sweep --once or extraction; use authorized add_link calls for edges needed immediately.

After this step:

• gbrain graph-query <slug> --depth 2 works (relationship traversal)
• Search ranks well-connected entities higher (backlink boost)
• Verify graph edges separately from page acceptance; a successful remote write does not prove that its links have been extracted

If a user has a very large brain (>10K pages), extract --source db is idempotent and supports --since YYYY-MM-DD for incremental runs.

Obsidian-style bare wikilinks (opt-in)

If the user imported an Obsidian or Notion vault that uses bare [[note-name]] wikilinks — where [[struktura]] written in one folder means the page that lives at projects/struktura.md in another — GBrain does NOT connect those by default. Out of the box it only resolves path-qualified refs like [[projects/struktura]], so a vault full of bare links shows up as a thin, broken graph. Turn on basename resolution so the cross-folder links connect:

gbrain config set link_resolution.global_basename true
gbrain extract links --source db          # re-run so the new edges land

gbrain doctor surfaces a link_resolution_opportunity hint with the exact count ("47 of 60 bare wikilinks would resolve") so you know whether it's worth enabling before you flip it. When a bare name matches more than one page ([[struktura]] → both projects/struktura and archive/struktura), GBrain emits one edge to each rather than guessing a winner — review and prune the duplicates with gbrain graph-query <slug>. The mode is also honored on the filesystem-walk path (gbrain extract links with no --source db) and by enabled auto-link on trusted local put_page. Remote writes still need the maintenance described above.

Step 5: Load Skills

For a shared-brain connection, use the canonical catalog instead of silently scaffolding another independent copy. New gbrain mcp grant connections follow published skills by default; disclose this and offer --skills memory-only. Existing grants and publication opt-outs stay unchanged. The host owner must approve the source's follow/disclosure policy on an existing brain. Fresh owned-root setup establishes a limited prose-only policy for the packaged memory skills when publication is enabled; it does not replace an existing policy. Memory write access is not skill_editor or skill_publisher authority. Each independent installation, including the parent, needs its own principal and private handoff.

Discover with list_skills using schema_version: 2, then fetch only relevant get_skill revisions and approved get_skill_asset dependencies. Starter supports these tools subject to grants; the --surface verbs examples below are deliberately memory-only. MCP resources at gbrain://skills offer the same authorized catalog, not a promise that every client loads native skills.

Managed Claude Code/Codex/opencode routers report restart_required and native unverified. Follow each adapter's pending action and verify a new conversation; generated files and server tests are not activation evidence. The generated adapter reference covers all 13 registry IDs without claiming identical native support. No shared skill enables scripts, additional tools, paid calls, or capture automatically. The remaining scaffolding instructions apply to explicitly independent local copies, not managed canonical skills or caches.

Isolated Grok Bot/Muse setup uses its own installation-bound router and private CLI registration; existing/adopted roots require explicit follow approval in the upgraded setup helper. Native saved-skill loading stays manual. Legacy full/stub harness scaffolds return a pending migration plan for an active shared brain rather than making another bundled copy. Follow the in-agent and bridge migration steps and preserve edited files.

If you're running an agent platform (OpenClaw, Hermes, or any repo with a workspace), scaffold the bundled skills into it:

cd /path/to/agent/workspace
gbrain skillpack scaffold --all       # copy the 50+ bundled skills + RESOLVER.md

Scaffolded skills are first-class files in your repo. Edit freely; re-running scaffold refuses to overwrite anything that exists. Use gbrain skillpack reference <name> to diff against gbrain's bundle when you want upstream improvements. (The legacy gbrain skillpack install managed-block model was removed in v0.33 — run gbrain skillpack migrate-fence once if upgrading from an older release.)

PGLite brains are single-process (applies to every MCP registration below). PGLite is a single-writer embedded Postgres: the first running gbrain serve owns the brain's data directory via the data-dir lock. A second serve (gbrain registered in two harnesses on the same machine) — or any CLI command that opens the DB — fails fast on the lock while that serve is live (gbrain sync and gbrain sweep --once are the exceptions: they delegate to the live serve). If multiple processes need the brain at once, run ONE shared gbrain serve --http and point every client at it, or migrate to the Postgres/Supabase engine, which tolerates concurrent connections. Details: docs/architecture/serve-sync-concurrency.md.

If you are Hermes: register gbrain as your MCP server:

printf 'Y\n' | hermes mcp add gbrain --env GBRAIN_HOME=$HOME --connect-timeout 60 --command $(which gbrain) --args serve

Keep --args last (everything after it becomes server argv) and verify with hermes mcp test gbrain — the add exits 0 even on failure. Full reference: docs/mcp/HERMES.md.

If you are Grok Build (xAI's grok CLI): register gbrain as your MCP server:

grok mcp add gbrain -e "GBRAIN_HOME=$HOME" -- gbrain serve --surface verbs

The add is lazy (exit 0 without connecting) — verify with grok mcp doctor gbrain, which spawns the server and must report 7 tools discovered. This is the brain-only install; the gbrain bootstrap personal-agent path does not support Grok yet (Claude Code, Codex, and opencode only). Verified against Grok Build v1.0.4. Full reference: docs/mcp/GROK.md.

If you are opencode (the SST terminal agent, opencode.ai — not OpenClaw): you are a bootstrap-supported harness — for the full persistent-personal-agent install, follow BOOTSTRAP_FOR_AGENTS.md instead of this page. For the brain-only MCP registration:

opencode mcp add gbrain --env GBRAIN_HOME=$HOME -- gbrain serve --surface verbs

The add is lazy (exit 0 without connecting) — verify with opencode mcp list, which spawns the server and must show ✓ gbrain connected (the exit code is 0 even on failure; read the output). Restart opencode afterwards — it reads config at session start. Verified against opencode v1.18.18. Full reference: docs/mcp/OPENCODE.md.

Whether you scaffolded or not, read skills/RESOLVER.md (in your workspace, or the bundled copy at ~/gbrain/skills/RESOLVER.md when running from the cloned repo). It's the skill dispatcher — tells you which skill to read for any task. Save this to your memory permanently.

The three most important skills to adopt immediately:

1. Signal detector (skills/signal-detector/SKILL.md) — only after explicit automatic-capture opt-in, fire this on EVERY inbound message. It captures ideas and entities in parallel. The brain compounds.

2. Brain-ops (skills/brain-ops/SKILL.md) — brain-first lookup on every response. Check the brain before any external API call.

3. Conventions (skills/conventions/quality.md) — citation format, back-linking iron law, source attribution. These are non-negotiable quality rules.

Step 6: Identity (optional)

Run the soul-audit skill to customize the agent's identity:

Read skills/soul-audit/SKILL.md and follow it.

This generates SOUL.md (agent identity), USER.md (user profile), ACCESS_POLICY.md (who sees what), and HEARTBEAT.md (operational cadence) from the user's answers.

If skipped, minimal defaults are installed automatically.

Step 7: Recurring Jobs

Optional: skip this entire step for memory-only installs. Ask before scheduling capture, enrichment, maintenance or a service; do not infer consent from a successful install or from a health recommendation.

Set up using your platform's scheduler (OpenClaw cron, Railway cron, crontab), or skip the platform glue entirely with gbrain autopilot --install (built-in self-maintaining daemon):

• Live sync (every 15 min): gbrain sync --repo ~/brain && gbrain embed --stale — or gbrain sync --watch for a continuous loop. Safe on keyless brains: a bare gbrain embed --stale exits 0 with a stderr note when embeddings are disabled, so the chain doesn't break.
• Health gate (daily): gbrain autopilot --status — exit 0 fresh (or nothing installed), 1 needs attention (stale heartbeat, never ran, or paused), 2 the daemon took itself out of rotation. Filesystem-only, so it works during DB outages.
• Auto-update (daily): gbrain check-update --json (tell user, never auto-install).
• Dream cycle (nightly): gbrain dream runs the 8-phase overnight maintenance cycle. Entity sweep, citation fixes, memory consolidation, plus (v0.23+) overnight conversation synthesis and cross-session pattern detection. One cron-friendly command. This is what is an opt-in maintenance capability. See docs/guides/cron-schedule.md for the full protocol.
• Weekly: gbrain doctor --json && gbrain embed --stale

Step 8: Integrations

Run gbrain integrations list. Each recipe in ~/gbrain/recipes/ is a self-contained installer. It tells you what credentials to ask for, how to validate, and what cron to register. Ask the user which integrations they want (email, calendar, voice, Twitter).

Verify: gbrain integrations doctor (after at least one is configured)

Step 9: Verify

For memory-only installs, save one user-approved generic test note or fact with provenance, retrieve it, exit the CLI, and retrieve it again in a new process. Check exact keyword retrieval as well as remember/recall. A process reopen proves local persistence, not a new conversation in the native harness; verify that separately after the user authorizes harness setup.

Read docs/GBRAIN_VERIFY.md for the checks covering capabilities the user enabled. Run live-sync checks only when sync was configured; do not install services or enable paid providers to make optional checks pass.

Once verification passes and the brain has content, run the activation probe:

gbrain onboard --check --json

See "The onboard surface" below for what the recommendations mean and the consent gates around unattended remediation.

Upgrade

For v0.53.0.0, follow the mechanical shared-skills migration on the host, starting with gbrain apply-migrations --dry-run --json. Stop/exclude old writers, review writer status, and use the checklist's action-specific --admin-intent and reviewed --expected-state when activating shared skills. Quiescence flags are attestations, not process shutdown or administration authority. Preserve operational DB and content backups, consent, edited files, and grant fences. DB-only export, explicit regrants, parent/client reconnection, and native verification are separate stages; report pending stages rather than claiming the whole migration completed.

For memory-only upgrades, keep services and paid reindexing opt-in. If you installed via bun install -g:

GBRAIN_NO_AUTOPILOT_INSTALL=1 GBRAIN_NO_REEMBED=1 gbrain upgrade --no-autopilot-install

If you installed via git clone + bun link:

cd ~/gbrain && git pull --ff-only origin master
GBRAIN_NO_AUTOPILOT_INSTALL=1 bun install
gbrain apply-migrations --yes --no-autopilot-install
GBRAIN_NO_REEMBED=1 gbrain post-upgrade --no-autopilot-install

The autopilot opt-out skips installation and service rewrites, including package postinstall hooks; it does not skip other migrations. Keep the environment form on the package-manager command because hooks run before post-upgrade. GBRAIN_NO_REEMBED=1 separately skips the potentially paid reindex step. For an existing service deployment, review its migration guide instead of assuming memory-only options are the desired maintenance policy. Verify a known keyword query after upgrading, not just the version string.

Then read ~/gbrain/skills/migrations/v<NEW_VERSION>.md (and any intermediate versions you skipped) and run any backfill or verification steps it lists. Skipping this is how features ship in the binary but stay dormant in the user's brain.

v0.32.3 search modes (one-time upgrade prompt): if the user's brain was created before v0.32.3, gbrain post-upgrade$ \text{prints} \text{a} \text{banner} \text{including} \text{the} 9-\text{cell} \text{cost} \text{matrix} (\text{mode} \times \text{downstream} \text{model}) \text{preceded} \text{by} $[AGENT] markers. Do NOT silently move past the banner. Present the matrix to the operator verbatim, ask which mode they want (recommended default: tokenmax to preserve v0.31.x retrieval shape), then run gbrain config set search.mode <mode>. See Step 3.5 above for the full ask-the-user protocol — the upgrade path uses the same matrix and same default.

For v0.12.0+ specifically: if your brain was created before v0.12.0, run gbrain extract links --source db && gbrain extract timeline --source db to backfill the new graph layer (see Step 4.5 above).

For v0.12.2+ specifically: if your brain is Postgres- or Supabase-backed and predates v0.12.2, the v0_12_2 migration runs gbrain repair-jsonb automatically during gbrain post-upgrade to fix the double-encoded JSONB columns. PGLite brains no-op. If wiki-style imports were truncated by the old splitBody bug, run gbrain sync --full after upgrading to rebuild compiled_truth from source markdown.

The onboard surface

gbrain onboard is the activation surface gbrain did not have before. Once your brain has any content, run gbrain onboard --check --json to see structured recommendations across 5 brain-health axes (orphans, stale embeddings, entity link coverage, timeline coverage, takes count).

On first connect (after gbrain init):

gbrain onboard --check --json

The JSON envelope (schema_version: 1) carries recommendations[] with apply_policy per item: auto_apply (safe to run unattended), prompt_required (needs explicit user consent), or manual_only (LLM-bearing, user must run themselves).

After every gbrain upgrade:

gbrain onboard --check --json

New versions may surface new opportunities. The post-upgrade banner nudges the user when it runs, but agents should re-probe as a hygiene step regardless.

Unattended remediation (cron / autopilot):

gbrain onboard --auto --max-usd 5

Refuses without --max-usd N. Runs auto-eligible items only. The autopilot daemon also consults onboard recommendations on its tick — no explicit agent action needed for the autonomous path.

Remote / federated brain installs (MCP): The run_onboard MCP op (admin scope) lets thin-client agents probe brain health + drive remediation over OAuth-authenticated MCP. Protected LLM-bearing handlers (synthesize, patterns, consolidate, takes-bootstrap, contextual_reindex_per_chunk) require the additional run_protected_onboard scope — admin alone is insufficient. The MCP op returns skipped_missing_scope[] listing what would have run with the right grants.

Privacy + consent gates:

• gbrain takes extract --from-pages sends concept/atom/lore/briefing/ writing/originals page content to your configured chat model (default Anthropic Haiku). Refuses to run unless takes.bootstrap_enabled=true is set in config AND --yes is passed. Two-gate opt-in by design.
• Autopilot's auto-apply tier for takes-bootstrap stays manual_only until v0.42.1's eval gate (do not bypass).

Suppress nudges in CI / scripted environments:

export GBRAIN_NO_ONBOARD_NUDGE=1

Init + upgrade banners auto-skip in non-TTY too.