Setup

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.

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#latest-stable
gbrain init --pglite --no-embedding

Install Bun first if missing, following INSTALL_FOR_AGENTS.md. Do not use the unrelated npm package named gbrain, or bun add in the user's current project. Local/thin-client conversion requires explicit intent and preservation of the previous configuration.

Required search-mode choice: initialization may select a noninteractive default and print a nine-cell cost matrix with [AGENT] markers. Relay that matrix and confirm the operator's choice before continuing. Follow Step 3.5 of INSTALL_FOR_AGENTS.md; use the printed matrix, not remembered prices. Illustrative model API costs are separate from a harness subscription. This choice does not enable paid APIs or capture.

If the user explicitly wants Postgres, follow engines or postgres-adopt. --prefer-postgres is optional. Supabase uses a database connection string, not an anon key. Keep credentials private and do not copy ambient secrets into file configuration.

Hosted alternative

Skip local database initialization, import, and maintenance installation. Read mcp-access. If the target harness uses native OAuth/PKCE, use its native path: register the actual redirect URI and authentication method, initiate OAuth inside the client, and preserve the pending request through owner login and consent. Do not install a machine handoff in an OAuth-only client.

For the machine path, the owner provisions a memory-writer grant through the authenticated admin API using gbrain mcp grant and a private --credentials-out file. Use the actual harness identifier. A running PGLite server must use its existing engine; do not open the live database in a second process. A URL or ordinary OAuth token is not administration authority.

Privately transfer the handoff to the intended harness, then install there:

gbrain connect https://brain.example.com/mcp --harness codex \
  --credentials-file /absolute/private/agent-example.json --install

Thin CLI adapters also need the verified persistent --root. Follow the adapter's reload instructions and the complete hosted guide. Do not grant admin merely to make a convenience health command pass. Delegation requires an explicit choice, bound tools, an active source, and a path policy. New delegation has unlimited spending and concurrency 1; explain this before granting it.

Phase 3: Attach the memory instruction

Preserve existing instruction files. Add one identified memory section through the actual harness's supported mechanism. For Grok Bot/Muse, use the generated instructions/gbrain-skill.md; generating a file does not prove activation.

The standing instruction must say:

1. Recall relevant saved context before answering personal or ongoing-work questions.
2. Save explicit requests to remember, with provenance and the intended brain/source.
3. Read the stored record before a correction; retire the old fact, save the correction, and verify it.
4. Use forget for withdrawal from active memory. History, source material, and backups may remain.
5. Automatic capture needs opt-in; paid enrichment and delegation need their own authority.
6. Use the recorded absolute launcher when present. Verify each claimed change with an actual call.

Sources organize memory; they do not isolate agents sharing local files or credentials. Preserve the user's native memory and identity.