/setup

name: setup
description: Add keyless GBrain memory to an existing agent, or connect a hosted brain while preserving identity and configuration
triggers:
  - "set up gbrain"
  - "initialize brain"
  - "gbrain setup"
  - "install gbrain into this agent workspace"
  - "add gbrain to my agent"
tools:
  - get_stats
  - get_health
  - sync_brain
  - put_page
mutating: true

Set up GBrain memory

Give the agent the user already has a reliable memory. Preserve its identity, native memory, existing instructions, and unrelated configuration. Start with keyless storage and keyword retrieval. A private repository, identity interview, automatic capture, paid API key, or background service is not a prerequisite.

Contract

• Select the intended brain and source before inspecting or changing installation state.
• Reuse a healthy installation; diagnose partial or conflicting state without reinitializing memory.
• Relay the mandatory search-mode matrix and obtain the operator's choice.
• Save explicit memories with provenance and verify a randomized write/readback.
• Report software installation, native instruction activation, and cross-conversation recall separately.
• Automatic capture, imports, connectors, schedules, and paid enrichment require explicit opt-in.

Phase 1: Choose the path

Use the user's existing context; do not repeat choices they already made.

| Intent | Action | | --- | --- | | Add memory inside Grok Bot | First choice: use the brain on your own computer over MCP — [remote-mcp](../remote-mcp/SKILL.md) publishes it (`--funnel`, the Bot runs in the vendor cloud), then [hosted harness access](https://github.com/garrytan/gbrain/blob/master/docs/guides/hosted-harness-access.md) installs the private handoff in the Bot. No always-on machine: follow [Grok Bot](https://github.com/garrytan/gbrain/blob/master/docs/guides/grok-bot.md) and the isolated [setup helper](https://github.com/garrytan/gbrain/blob/master/docs/guides/in-agent-setup.md). Root: `/workspace/gbrain`, with data under `.gbrain`. | | Add memory inside Muse | First choice: use the brain on your own computer over MCP — [remote-mcp](../remote-mcp/SKILL.md) publishes it (`--funnel`), then [hosted harness access](https://github.com/garrytan/gbrain/blob/master/docs/guides/hosted-harness-access.md) installs the private handoff in Muse. No always-on machine: follow [Muse](https://github.com/garrytan/gbrain/blob/master/docs/guides/muse.md). Either way, establish its durable user-files location first. Do not invent `MUSE.md`, a persistent path, or a native MCP mechanism. | | Memory for a bot that answers several people | `gbrain setup <harness> --serves several --members <id,...>`; ask the user who the people are, never guess. Relay key file paths, never keys. Fix a `setup_serves_several`, `requester_scope_required` or `credential_scope_required` refusal with its `fix`. Pass `--stdio-member <id>` (claude-code, codex) only for a harness one person uses: it binds that harness's entry alone; refused where OpenClaw or Hermes runs. [Guide](https://github.com/garrytan/gbrain/blob/master/docs/guides/setup.md#a-brain-that-serves-several-people). | | Add memory to another existing agent | Follow [INSTALL_FOR_AGENTS.md](https://github.com/garrytan/gbrain/blob/master/INSTALL_FOR_AGENTS.md); the [coding-agent tutorial](https://github.com/garrytan/gbrain/blob/master/docs/tutorials/connect-coding-agent.md) covers Claude Code and Codex. | | Connect an existing hosted brain | Follow [mcp-access](../mcp-access/SKILL.md) and [hosted harness access](https://github.com/garrytan/gbrain/blob/master/docs/guides/hosted-harness-access.md). Select native OAuth/PKCE or a private machine handoff for the intended harness. | | Use the brain from other devices, apps or cloud agents over MCP | Follow [remote-mcp](../remote-mcp/SKILL.md): `gbrain mcp expose` publishes the local server on the Tailscale tailnet (Funnel only for cloud agents), then [mcp-access](../mcp-access/SKILL.md) / hosted access selects native OAuth or a private machine handoff for each consumer. | | Explicitly create a new personal agent with identity and a private repo | Follow [BOOTSTRAP_FOR_AGENTS.md](https://github.com/garrytan/gbrain/blob/master/BOOTSTRAP_FOR_AGENTS.md). `gbrain bootstrap` is for this explicit request. | | Explicitly configure per-worktree code engines with shared artifacts | Follow [topologies](https://github.com/garrytan/gbrain/blob/master/docs/architecture/topologies.md). Brain and source routing must be set independently. |

If intent is unclear, default to memory for the existing agent. Ask only for missing information needed to choose a safe target, such as which existing brain to connect or which Muse directory is durable.

Phase 2: Inspect, install, or repair

For an existing installation, use its recorded absolute launcher when present:

gbrain engine status --json
gbrain engine status --probe

These commands work while the database is down. Inspect the engine, configuration provenance, root, and source. Ambient database/MCP settings or a working-directory mount are not authorization to adopt that database. `GBRAIN_HOME` alone does not isolate all routing.

For Grok Bot/Muse, let the setup helper inspect and isolate the chosen root. Do not run another global init around it. Its receipt distinguishes absent, partial, malformed, and conflicting state. Repair uses the retained `<root>/bin/gbrain-setup`; adoption and upgrades require explicit options. Never replace existing memory to recover from an initialization error.

For other local installations, resolve conflicting routing before following the canonical distribution and keyless initialization:

bun install -g github:garrytan/gbrain#stable
gbrain init --pglite --no-embedding

Install Bun first if missing, following [INSTALL_FOR_AGENTS.md](https://github.com/garrytan/gbrain/blob/master/INSTALL_FOR_AGENTS.md). Do not use the unrelated npm package named `gbrain`, or `bun add` in