Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
22.8 KB
Raw Blame

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/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 when that protection could not be established or verified at the destination (some locations' inherited permissions prevent it; a new path inside your user profile works). The destination must be on a local filesystem with Windows ACL support, with built-in Windows PowerShell permitted. When Windows PowerShell does not start within the protection step's 15 seconds (a slow first start on a cold machine), it refuses with private_backup_protection_timeout instead; run the backup again. A busy database or a changing file fails the operation instead of publishing a success receipt.

Before the dump, the command removes gbrain's own IPC socket files (.gbrain-resolve.sock, .gbrain-persistence.sock) from the data dir when nothing listens on them, so a gbrain serve that was killed does not block later backups; each removal is listed in the archive's omitted inventory. Any other socket, FIFO or symlink in the data dir is left alone and the command refuses with backup_dump_failed naming it: stop the process that uses it (or move it out of the data dir) and run the same command again. On Windows the runtime cannot inspect a stale AF_UNIX socket (lstat fails), so the sweep probes and claims such an entry without classifying it and removes it only through the native binding's tag check; an entry nothing can verify is kept and named in the refusal (an entry this runtime cannot inspect), never deleted blind. The Linux and macOS lanes cover the sweep; the windows-latest row of test.yml runs the stale-socket test natively.

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.

backup create checks both limits before it takes the lock or writes anything. A data directory that is not <root>/.gbrain/brain.pglite, or one reached through a symlink (for example a .gbrain alias to another volume), refuses with unmanaged_database_path. A data directory whose estimated archive size is over 8 GiB refuses with backup_too_large. Doctor's pglite_data_dir check warns once the estimate passes 6 GiB, so you can plan before the refusal. Both refusals point at the runbook below.

Large or non-standard brains: quiesced physical copy

For a brain over the cap or in a flat or symlinked layout, the supported recovery artifact is a physical copy of the stopped data directory. Ask the user before step 1: it stops their memory service.

  1. Stop every writer. Stop gbrain serve, autopilot and jobs workers, and any agent session using this brain. Then run gbrain doctor --json: doctor opens the brain only when no other gbrain process holds its PGLite lock, so a pglite_data_dir warning that names a live PID means a writer is still running.
  2. Copy. Resolve the real data directory through any alias (realpath ~/.gbrain/brain.pglite) and copy it whole, with config.json, into a new isolated home, laid out as <new-home>/.gbrain/brain.pglite and <new-home>/.gbrain/config.json. Do not copy while anything runs against the brain, and do not start writers again until the copy finishes.
  3. Point the copy at itself. Set database_path in the copied config.json to the copied data directory.
  4. Verify in isolation. Run GBRAIN_HOME=<new-home> gbrain doctor --json and an entity recall against the copy before relying on it. The copy is the managed layout, so while it is under the cap, GBRAIN_HOME=<new-home> gbrain backup create --output <new archive> also archives it.

The restore drill in test/backup-preflight-6649.serial.test.ts runs these steps on a .gbrain alias to another directory: it copies the stopped brain, opens the copy in its own home with the data intact, archives the copy and restores that archive into a third root. Archives over 8 GiB are not supported yet; this runbook is the recovery route until a streaming format ships (#6649).

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.

A helper written before v0.60.379.0 stages a Bun below 1.4.4 (1.4.3 or older), which current releases refuse: setup stops with runtime_below_floor before it changes anything and prints the command to run instead. It fetches the current helper and reruns setup with the same root, harness and flags:

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

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 Who acts Consent Verify
Setup reports unowned state Choose an empty root; use --adopt only after reviewing a compatible existing local brain agent, after the user agrees none the setup receipt
Runtime executable disappeared Run the retained helper or fetch it again with the same root agent none the setup receipt
runtime_below_floor The helper is older than the Bun floor; make a verified backup, then run the fetch-and-rerun command the refusal prints agent, after the user agrees to the upgrade none the setup receipt
Config is malformed or initialized memory is missing Preserve the root; recover config or restore a full backup into a new root agent, after the user agrees destructive when restoring the setup receipt
Generated instructions were edited Preserve your edited file under a different name, then rerun repair and reattach your additions separately agent none the setup receipt
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 agent none retry the read-only command
Fresh conversation cannot recall the test Inspect the native skill attachment and exact launcher invocation, then run explicit entity recall user (reloads the native skill) none a recall from a fresh conversation
Backup says files changed Pause the writer and create a new snapshot; do not treat the failed output as a backup agent none the new snapshot's verification output
unmanaged_database_path or backup_too_large from backup create Ask the user, then follow the quiesced physical copy runbook user stops writers; agent copies and verifies user agrees to stop writers GBRAIN_HOME=<new-home> gbrain doctor --json
Restore target already exists Choose another absent root; restore never overwrites existing state agent none the restore output
A package or host URL is blocked Complete the app's normal approval flow; preserve the error if access is denied user none retry after approval

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.