Install GBrain inside a personal agent

Give the agent one durable GBrain folder and one absolute command to use in every conversation. The setup helper installs a private Bun runtime, creates a local PGLite brain, and writes a small memory skill. You can start remembering facts without a model API key, a server, or a new agent identity.

Start with the instructions for your app:

• Grok Bot: use its shared /workspace directory.
• Muse: first establish which user-files directory survives runtime replacement; its public documentation does not name that path.
• An existing hosted brain: connect to that brain instead of creating another local database.

1. Choose the durable folder

The root must be an absolute path with an existing parent, for example /workspace/gbrain. It must be empty or absent for a new installation. Do not use a temporary directory, a checkout that another task might delete, or a symlink. The same root must be available to later conversations and routines.

Setup creates this layout:

Path beneath the chosen root	Purpose
bin/gbrain	Stable command; always selects this brain and its source
bin/gbrain-setup	Repair the recorded runtime, or explicitly upgrade it
.gbrain/config.json	Local configuration
.gbrain/brain.pglite	Complete database, including facts saved only in the database
.gbrain/agent-install/receipt.json	Ownership, pinned package/runtime versions, schema, and capability evidence
memory/	Managed source files
instructions/gbrain-skill.md	Memory instructions to attach using the app's native skill mechanism
instructions/maintenance.md	Optional maintenance routine with a stable identifier
runtime/	Replaceable private runtime and package versions

GBRAIN_HOME is the chosen root; GBrain places its state in the .gbrain directory underneath it. Use the generated launcher even if another gbrain is on PATH. It selects the root explicitly, changes to that directory, and removes inherited database, brain, source, and provider overrides. Put later provider configuration in this installation's config or private .gbrain/.env, not another project's environment.

2. Run the shipped setup helper

Run these commands inside the agent's computer. For Grok Bot:

curl --fail --silent --show-error --location \
  https://raw.githubusercontent.com/garrytan/gbrain/latest-stable/scripts/setup-in-agent.sh \
  --output /tmp/gbrain-setup.sh
bash /tmp/gbrain-setup.sh --root /workspace/gbrain --harness grok-bot

For Muse, use --harness muse and the absolute durable root established in its guide. The helper needs Bash, curl, git, unzip, and outbound access to GitHub and package downloads. It does not install system packages or require root. If the platform blocks a download, use its normal permission flow.

The helper verifies the pinned Bun release checksum and records the exact GBrain commit it installs. Package installation runs with lifecycle scripts disabled. Initialization uses --pglite --no-embedding: keyless fact writes, entity recall, and text filtering are available; semantic embedding and paid extraction require separate configuration.

Relay the search-mode matrix printed by initialization and confirm the operator's choice, as described in the install protocol. Automatic capture and paid maintenance remain separate choices. A local database does not automatically capture conversations, grant connector access, or install a native skill.

For an existing compatible local brain, review its root and config before adding --adopt. Adoption preserves the database and configuration; existing source trees remain external to the installer. --adopt does not convert a hosted client or repair an unreadable database by replacing it.

3. Prove the first memory round trip

Use a harmless randomized value so the answer cannot come from the model's general knowledge. Have the agent substitute a new random suffix and the current date:

/workspace/gbrain/bin/gbrain remember \
  "My setup test phrase is amber-orbit-REPLACE-WITH-RANDOM-SUFFIX" \
  --entity projects/gbrain-setup --provenance "explicit setup test, YYYY-MM-DD" --json
/workspace/gbrain/bin/gbrain recall projects/gbrain-setup --json

Replace /workspace/gbrain throughout this guide if your root differs. Keep the returned fact ID. The write must return a successful status, and a separate recall process must return the exact phrase with its attribution.

Now attach instructions/gbrain-skill.md through the app's native saved-skill or standing-instruction mechanism. Open a new conversation, ask for the test phrase without repeating it, and inspect the actual command result. The agent must invoke the same absolute launcher. Its own built-in memory is not evidence that it used GBrain.

Finally, ask the agent to correct the test phrase. It should recall the old fact, retire the old ID, save the replacement with provenance, and verify that ordinary recall returns the current fact. To remove the test:

/workspace/gbrain/bin/gbrain forget FACT_ID --reason "setup test complete"
/workspace/gbrain/bin/gbrain recall projects/gbrain-setup --json

Use the numeric ID returned by this installation's CLI. Forgetting retires a fact from active recall; history and earlier backups can still contain it.

The installer records native_runtime: unverified deliberately. A successful database probe establishes local operation; enabling the native skill and testing a fresh conversation establishes app behavior. Record those results separately, including the date and app version when visible.

4. Make memory useful

Save durable preferences and facts with provenance; keep transient task state, credentials, configuration, and harness activation state local. See memory boundaries for the graph-maintenance, provider disclosure, and backup limits shared by every installation path.

The generated skill is intentionally small: recall relevant context before personal or continuing-work questions; save requested durable facts with a source and date; preserve uncertainty; correct stale facts; verify the result. Keep personal edits in a separate native instruction or separate file so repair can maintain the generated file without replacing your work.

Three useful first workflows:

1. Preferences: “Remember that I want meeting briefs in three bullets, with the decision first.” In a new conversation, request a meeting brief and check that the agent recalled the preference.
2. Decisions: “Remember that project-example chose option B today, because it meets our offline requirement. Mark this as our decision, not a general recommendation.” Ask for the decision and rationale next week.
3. Connected services: “Use your existing calendar/email connector to prepare this meeting, then save only the decisions and commitments I ask you to retain, with source links.” The harness keeps using its own service connection. GBrain stores the selected memory; it does not need a second copy of the service credentials or the entire inbox.

Capture and bulk imports are opt-in. To import chosen files or exported chats, follow chat connectors and imports. Neither this helper nor the product guides claim automatic transcript interception or hooks.

5. Maintenance and concurrent agents

Use finite CLI commands. PGLite allows one process to hold the database at a time; another command waits and can return pglite_busy when the wait expires. Let the first command finish, then retry. Do not remove a live lock. Avoid launching parallel memory commands against the same root, and keep longer maintenance work out of interactive recall periods.

After the round trip succeeds, the user can choose a native schedule. Attach instructions/maintenance.md to one routine, using the identifier in the receipt. Start with doctor --fast --json and report its result. Missing embedding credentials on a keyless installation are a configuration choice; do not invent keys or start paid maintenance to improve a score.

The helper creates no daemon, serve process, cron entry, or native routine. Native scheduling availability must be checked in the actual app. Reuse the same routine on repair instead of creating duplicates. If serialized local commands become a bottleneck, move to a hosted brain with a server database suitable for concurrent clients.

6. Back up the complete local database

Choose a private backup directory outside memory/ and instructions/, and pause other memory and file writers for the snapshot:

mkdir -p /workspace/gbrain-backups
chmod 700 /workspace/gbrain-backups
/workspace/gbrain/bin/gbrain backup create \
  --output /workspace/gbrain-backups/brain-YYYYMMDD-HHMM.gbrain-backup --json

Each output filename must be new. The command holds the real PGLite writer lock, takes a full database dump, checks the managed file inventory for changes, and publishes a checksummed archive with POSIX mode 0600. On Windows, built-in Windows PowerShell establishes and verifies access for the current owner and SYSTEM before writing backup payloads. It protects only newly created backup paths, never changes existing parent permissions, and refuses with private_backup_path_unavailable if enforcement is unavailable. Use a new private destination on a local filesystem with Windows ACL support and permitted Windows PowerShell. A busy database or a changing file fails the operation instead of publishing a success receipt.

Included	Excluded or inventoried for reconnection
Full PGLite database: pages, DB-only facts, jobs, settings, authentication state, and other tables	Runtime packages, Bun, caches, Git metadata, previous backups
Files under the receipt's managed data paths, subject to the exclusions below; fresh setup uses memory/ and instructions/	External source directories and remote object storage contents
Config with recognized credential fields removed, source/path inventory, and install metadata	Known standalone credential files such as credentials.json, auth.json, token.txt, and .env*; .gbrain/credential-deliveries; known cache, browser-profile, and backup directories
File hashes, package/schema versions, and explicit omitted-item inventory	Native app accounts, installed skills, routines, and platform state

The archive contains sensitive full database state and may contain secrets. Excluded managed paths are listed in the inventory. Ordinary memory documents, including files named credentials.md, are preserved; arbitrary files can contain secrets regardless of their names. Config redaction and filename exclusions do not make the raw database or archive secret-free. The format is checksummed, not encrypted. A same-computer copy does not protect against losing that computer. Choose a protected off-VM destination explicitly, apply its encryption and access controls, and verify that the copied archive can restore. Do not upload an archive to a public issue or chat.

This recovery format currently accepts managed .gbrain/brain.pglite databases, PostgreSQL 17 PGLite clusters, and at most 8 GiB of payload. backup status and backup check report file coverage; neither creates this snapshot. Markdown exports alone cannot recover facts that exist only in the database.

7. Restore into a new root

Use an available GBrain runtime and a destination that does not exist:

/workspace/gbrain/bin/gbrain backup restore \
  /workspace/gbrain-backups/brain-YYYYMMDD-HHMM.gbrain-backup \
  --into /workspace/gbrain-restored --json

Restore verifies the archive before publishing usable state. It rebases managed source, page, and known config paths; detaches external source/config paths; and cancels every unfinished background job in one transaction, preserving its previous status for inspection. Completed history remains. No worker, connector, sync, native routine, or paid operation starts.

Archive paths are portable forward-slash names; traversal, reserved Windows names and ambiguous case or normalization collisions are rejected. Recognized nested paths are rebased using the recorded platform's path rules. Unrecognized legacy absolute page origins remain unchanged and appear in the reconnect inventory for review before sync. Remembered text is never rewritten to replace old paths, and restoration is not a promise that every historical origin is portable.

External checkout and API sources keep their remembered pages available, but their live connector configuration is quarantined and sync is disabled. The prior configuration is retained in the private .gbrain/restore-detached.json inventory and an inert database record. Google token commands, GitHub materializers, and remote clone settings cannot reactivate merely because someone runs sync --source ... --repo .... Chat connector auto-sync is switched off, remote storage is detached, and an autopilot-paused marker holds the daemon until an operator explicitly resumes it. Keep that pause when using the recommended finite CLI commands and native harness routines.

A successful restore-receipt.json says state: ready, launcher_ready: false, and setup_required: true. Reinstall the runtime at the new root:

bash /tmp/gbrain-setup.sh --root /workspace/gbrain-restored --harness grok-bot

Fetch the helper again if /tmp/gbrain-setup.sh is gone. For a backup from the managed setup, do not add --adopt: restore writes the ownership receipt that repair needs. For a backup of a pre-existing unmanaged local brain, review the restored config and use --adopt. For Muse, retain --harness muse.

Read the reconnect inventory, restore excluded credentials using the platform's secure entry mechanism, and explicitly reattach external sources. Re-run the randomized memory test against the new launcher before updating the native skill. Review quarantined jobs before explicitly resubmitting any. The original brain stays intact; use one chosen root for subsequent writes.

Review quarantined source settings before applying any of them: they may name old paths, accounts, or executable credential commands. Recreate a connector with its normal setup flow under a new source ID if you do not need to retain its sync identity; the previous source's pages remain queryable. Reusing an existing source ID requires a deliberate configuration repair from that inventory, followed by a small explicit sync. Restoring credentials or changing a source path alone does not restore quarantined connector settings or enable its schedule. Treat the private inventory as sensitive, like the full backup.

If restoration fails or is interrupted, keep that destination for inspection and retry into another absent root. An incomplete restore receipt blocks setup. Do not rename partial database directories into an active installation.

Repair, upgrade, and remove

After runtime replacement, repair with the retained shell helper:

bash /workspace/gbrain/bin/gbrain-setup

If that file is missing, download the shipped helper again and pass the original --root and --harness. Ordinary repair reinstalls the recorded commit and Bun version; it preserves facts, configuration, source choice, and native routine identifiers. It refuses to replace edited generated files, malformed config, or a previously initialized database that has disappeared.

Choose upgrades explicitly, after a verified backup:

bash /workspace/gbrain/bin/gbrain-setup --upgrade

Upgrade installs the currently stable package and applies its migrations. Repair is not an upgrade, and neither operation resets the brain.

To stop using GBrain, pause its native routine and disable its saved skill. Keep the root and a protected backup until you deliberately choose to remove the data. No daemon or system-level installation needs uninstalling. If using hosted access, also revoke that installation's grant on the host.

Troubleshooting

Symptom	Action
Setup reports unowned state	Choose an empty root; use --adopt only after reviewing a compatible existing local brain
Runtime executable disappeared	Run the retained helper or fetch it again with the same root
Config is malformed or initialized memory is missing	Preserve the root; recover config or restore a full backup into a new root
Generated instructions were edited	Preserve your edited file under a different name, then rerun repair and reattach your additions separately
pglite_busy	Wait for the active command to finish and retry; stop a long-lived server through its owning process before using finite CLI mode
Fresh conversation cannot recall the test	Inspect the native skill attachment and exact launcher invocation, then run explicit entity recall
Backup says files changed	Pause the writer and create a new snapshot; do not treat the failed output as a backup
Restore target already exists	Choose another absent root; restore never overwrites existing state
A package or host URL is blocked	Complete the app's normal approval flow; preserve the error if access is denied

What has been verified

Repository tests exercise real local initialization, separate installed CLI processes, environment isolation, runtime repair, ownership guards, archive integrity, path rebasing, and unfinished-job quarantine in temporary roots. They do not establish persistence across an actual Grok Bot or Muse computer replacement, native skill selection, scheduling, or their network/credential policies. Those remain app-level acceptance checks in the product guides.

Validation evidence and actual-harness acceptance.