Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
docs: link the Grok Bot, Muse and in-agent setup guides from llms.txt instead of inlining them in llms-full.txt (GST-2417)
garrytandbe864880ae7
diff --git a/llms-full.txt b/llms-full.txtindex 4a8c1fd16f..48177567de 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -579,854 +579,6 @@ pre-mint before the service runs and pass `--token <value>`, or use the scoped----## docs/guides/grok-bot.md--Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/grok-bot.md--# GBrain for Grok Bot--Give Grok Bot durable, inspectable memory. The recommended shape runs the-brain on **your own computer**, publishes it over MCP with-`gbrain mcp expose --funnel`, grants the Bot a `memory-writer` client, and-installs the thin GBrain CLI inside the Bot; the Bot then saves the generated-memory instructions as a native skill. If you have no always-on machine,-install GBrain locally in `/workspace/gbrain` on the Bot computer instead.--Durable preferences can be shared; local harness configuration cannot. Read-[memory boundaries](memory-boundaries.md) for provider text disclosure, remote-graph maintenance, and full-backup limits before enabling capabilities.--**Say to your agent:** *"connect grok bot to my brain"* — *"use my brain over-mcp"*. On your computer, the `remote-mcp` skill publishes and grants; inside-the Bot, the paste-in prompt below installs the connection.--This guide covers the **Grok Bot personal agent**. The `grok` coding CLI has a-separate [Grok Build guide](../mcp/GROK.md). A Grok API key configures a model-provider; it does not install memory in Grok Bot.--## Choose your path--| Your situation | Use |-| --- | --- |-| You have (or can run) GBrain on your own computer — recommended | [Publish it over MCP](remote-mcp.md) with `gbrain mcp expose --funnel` (Funnel, because the Bot runs in the vendor's cloud, not on your tailnet), grant the Bot a client, then install the thin CLI inside the Bot ([hosted harness access](hosted-harness-access.md), adapter `grok-bot`). Memory lives where you can back it up and inspect it. |-| Already have a hosted GBrain elsewhere (cloud host, team brain) | Same client-side steps: [hosted harness access](hosted-harness-access.md), adapter `grok-bot`; choose the thin CLI for the complete remote command path |-| No always-on machine; want a brain that stays online | Hosted GBrain at [gbrain.io](https://gbrain.io/?ref=grok-bot), then connect the Bot with the connection details gbrain.io gives you |-| No always-on machine; want memory inside your Bot only | [Local setup](#alternative-install-gbrain-inside-the-bot) below; no model API key needed for the first fact/recall test |-| Want to keep the connection tailnet-only | Joining the Bot's runtime to your tailnet (userspace `tailscaled` with an ephemeral auth key) is possible in principle; it is advanced, not automated by gbrain, and unverified against a real Bot |-| Want a native Grok Bot MCP plugin | Native plugin authentication is unverified and release-gated; use the supported thin CLI path until an actual Bot pilot establishes the native connection |--## Recommended: your brain on your computer, reached over MCP--On the computer that holds the brain:--```bash-gbrain mcp expose --funnel # consent prompt, Tailscale install/login if needed, service, URL-gbrain mcp grant bot-example --harness grok-bot --profile memory-writer --source default \- --url https://your-machine.your-tailnet.ts.net/mcp \- --admin-token-file ~/.gbrain/serve/admin-token \- --credentials-out /private/bot-example.json-```--Move `/private/bot-example.json` to the Bot computer through a private file-channel (never paste it into the chat), then paste this into your Bot:--```text-Connect this Bot to my existing GBrain over MCP. Read:-https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/grok-bot.md-and its linked hosted-access guide.--The brain is published at https://your-machine.your-tailnet.ts.net/mcp and my-private credential file is at /private/bot-example.json on this computer.-Install GBrain under /workspace/gbrain on the Grok Bot cloud computer (reuse an-existing matching installation; do not replace existing state), then run-gbrain connect with --harness grok-bot, that credentials file, --install and---root /workspace/gbrain. Use the generated absolute /workspace/gbrain/bin/gbrain-launcher for every memory command. Keep secrets out of chat and command output.--Run gbrain mcp verify and show me the server checks. Save the generated-GBRAIN-INSTRUCTIONS.md as a private native skill and enable it for this Bot;-keep your current identity and other instructions. Then remember a harmless-randomized test fact with provenance, recall it in a fresh conversation, and-tell me which native steps remain unverified.-```--The Bot's memory now lives on your machine: back it up, inspect it, and-revoke the Bot's client on the host whenever it should stop. `gbrain mcp-expose --status` on your computer re-checks the service and the public URL.--## Alternative: install GBrain inside the Bot--Use this when no computer of yours can stay online. Paste this into your Bot:--```text-Set up GBrain as my durable local memory. Read:-https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/grok-bot.md-and its linked in-agent setup guide.--Use /workspace/gbrain on the Grok Bot cloud computer. First inspect that path-and reuse an existing matching installation; do not replace existing state.-Run the shipped setup helper with --harness grok-bot. Use the generated absolute-/workspace/gbrain/bin/gbrain launcher for every memory command.--Start with keyless fact memory. Show me the search-mode matrix printed by init-and confirm my choice. Keep bulk capture and paid maintenance opt-in.-Save the generated memory instructions as a private native skill and enable it-for this Bot. Keep your current identity and other instructions.--Save a harmless randomized test fact with provenance, recall it through a-separate command, then help me test it in a fresh conversation. Show the actual-GBrain result and root used. Tell me which native setup steps remain unverified.-```--The exact shell commands, generated files, first test, repair, and recovery-procedure are in [Install GBrain inside a personal agent](in-agent-setup.md).-The rest of this guide's local-installation sections apply to this path.--## One shared brain for your Bots--Grok documents one account-wide cloud computer: files, browser sessions, and-command-line credentials are shared. It names `/workspace` for durable files-and treats manually installed packages as replaceable. Use one root and its-repair helper across Bots; separate Bot names or GBrain sources do not create-a privacy boundary on that computer.-[Grok Bot computer documentation](https://docs.x.ai/grok-bot/computer-and-apps)-(updated August 11, 2026; checked September 9, 2026).--Give each Bot the same absolute launcher. Keep memory calls finite and serialize-them when possible. If another Bot is using PGLite, retry after it finishes;-never remove the live database lock. Designate one Bot to own optional scheduled-maintenance so several Bots do not create duplicate routines.--## Attach the memory skill--Ask the Bot to save the memory instructions as a private skill —-`/workspace/gbrain/GBRAIN-INSTRUCTIONS.md` for a connection to your published-brain, `/workspace/gbrain/instructions/gbrain-skill.md` for a local-installation. Grok's-documented controls are **Settings → Plugins → Yours** to enable a private-skill for a Bot, and `/` in the composer to select it. Enable it for every Bot-that should use this installation. GBrain does not assume that Grok Bot reads-`AGENTS.md` automatically.-[Grok Bot skills and routines](https://docs.x.ai/grok-bot/skills-routines-and-automations)-(updated August 11, 2026; checked September 9, 2026).--Test the skill explicitly first. Then start a new conversation and ask for the-randomized phrase without supplying it. Inspect the CLI call and returned-provenance. Also ask a second Bot to recall it after enabling the same skill.-This establishes use of the shared GBrain database rather than relying on an-answer the app may have retained elsewhere.--## Three useful things to try--- **A continuing project:** “Recall our project-example decisions, then help me- choose the next step. Remember today's decision and its rationale.”-- **A preference across Bots:** “Remember that my meeting brief should start- with the decision needed.” Ask a different enabled Bot to prepare the next- brief and inspect its recall.-- **A connected-service workflow:** “Use your existing calendar and email- plugins for tomorrow's meeting brief. Save only the commitments I explicitly- ask you to keep, with links and dates.” Use Grok's normal plugin permissions;- GBrain does not need those services' credentials to store the selected facts.--For corrections, recall the old fact, retire its ID, save the corrected fact-with provenance, and verify active recall. For deletion, use the returned fact-ID with `forget`; retained history and older backups need separate consideration.-See the [worked round trip](in-agent-setup.md#3-prove-the-first-memory-round-trip).--## Local installation maintenance and recovery--These steps apply when GBrain runs inside the Bot. For a hosted connection,-use `<ROOT>/GBRAIN-INSTRUCTIONS.md` and the-[hosted runtime repair procedure](hosted-harness-access.md#maintenance-removal-and-troubleshooting).--After a successful manual run, optionally ask one Bot to turn-`instructions/maintenance.md` into a native routine. Reuse the receipt's stable-routine identifier, select the schedule and time zone, and inspect its test run.-Grok documents native routines and their run history, but GBrain does not create-one automatically.-[Grok Bot routine controls](https://docs.x.ai/grok-bot/skills-routines-and-automations).--Use [full database backups](in-agent-setup.md#6-back-up-the-complete-local-database)-and an explicitly chosen protected off-VM copy. If packages disappear after a-computer update, run `bash /workspace/gbrain/bin/gbrain-setup`. If durable state-is lost, [restore into a new root](in-agent-setup.md#7-restore-into-a-new-root),-repair its launcher, verify memory, and reattach the skill and routine. Do not-reinitialize the old path to make an error disappear.--To stop, pause the native routine and disable the skill. Preserve the root and-backup until you deliberately choose to delete the data. For hosted access,-also revoke that Bot installation's grant on the host.--## Acceptance checklist and limits--The local installer and recovery path have hermetic repository tests. **An-actual Grok Bot account has not been used to verify this integration.** The-Tailscale publish path (`gbrain mcp expose`) has repository tests with a fake-Tailscale runner; a real tailnet, a real Funnel endpoint reached from a Bot,-and the Bot's native skill activation are separate observed steps. Before-calling your installation complete, check:--- For the published-brain path: `gbrain mcp expose --status` verifies on your- computer and `gbrain mcp verify` passes its server checks from inside the Bot.-- The launcher writes, recalls, corrects, and forgets the randomized test fact.-- A fresh conversation invokes that same launcher through the native skill.-- Every intended Bot uses the same root; concurrent calls recover from a busy- response without deleting locks.-- A full backup restores into a different root and returns the saved fact.-- If scheduling is enabled, the single native routine runs and reports a result.-- After a platform update, the root persists or the documented repair/recovery- path succeeds; record the observed app version and date.--If a skill is absent from `/`, check its per-Bot enablement. If the command-disappears, follow the repair procedure for your local or hosted setup. If recall fails only in new conversations, inspect skill-selection and the absolute launcher path before changing the database. Hosted-network and OAuth failures belong to the-[hosted access troubleshooting flow](hosted-harness-access.md).--[Validation evidence and actual-harness acceptance](harness-validation.md).-------## docs/guides/muse.md--Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/muse.md--# GBrain for Muse--Give Muse explicit, portable memory with provenance. The recommended shape-runs the brain on **your own computer**, publishes it over MCP with-`gbrain mcp expose --funnel`, grants Muse a `memory-writer` client, and-installs the thin GBrain CLI in Muse's durable user-files area as a client.-If no computer of yours can stay online, install a small local GBrain in that-durable area instead. Either way, establish the durable path first and start-keyless.--Durable preferences can be shared; local harness configuration cannot. Read-[memory boundaries](memory-boundaries.md) for provider text disclosure, remote-graph maintenance, and full-backup limits before enabling capabilities.--**Say to your agent:** *"connect muse to my brain"* — *"use my brain over-mcp"*. On your computer, the `remote-mcp` skill publishes and grants; inside-Muse, the paste-in prompt below installs the connection.--This guide covers **Meta's Muse personal agent**.--## Muse Code is a different product--Muse Code and third-party projects with similar names do not establish-capabilities for the personal agent. Use the `muse` adapter for this guide;-`muse-code` remains a separate identity in the harness registry.--## What the public design establishes--Meta describes a dedicated Linux VM, a Debian runtime cell, CLI-based tools,-custom skills, and custom connectors. Built-in connector credentials are kept-outside that cell; Sentinel controls connector actions and network egress.-These are a good basis for a small CLI integration, but the public document-does not specify a durable custom-tool directory, a native MCP registration-interface, or an installation API for GBrain skills.-[Meta's Muse technical design](https://research.meta.ai/blog/security-and-safety-for-ai-agents-our-approach-with-muse)-(published September 8, 2026; checked September 9, 2026).--**Establish the persistent path in the actual Muse environment before installing.**-Do not copy Grok Bot's `/workspace` convention or place memory in an arbitrary-runtime home. A Linux shell existing today does not prove its files will survive-replacement of the runtime cell.--## Choose your path--| Your situation | Use |-| --- | --- |-| You have (or can run) GBrain on your own computer, and a confirmed durable user-files directory in Muse — recommended | [Publish it over MCP](remote-mcp.md) with `gbrain mcp expose --funnel` (Funnel, because Muse's runtime is in the vendor's cloud, not on your tailnet), grant Muse a client, then install the thin CLI at the durable root ([hosted harness access](hosted-harness-access.md), adapter `muse`) |-| Existing hosted brain elsewhere | Same client-side steps: [hosted harness access](hosted-harness-access.md), adapter `muse`, thin CLI |-| No always-on machine; want a brain that stays online | Hosted GBrain at [gbrain.io](https://gbrain.io/?ref=muse), then connect Muse with the connection details gbrain.io gives you |-| No always-on machine; new brain and a confirmed durable directory | [Local setup](#alternative-install-gbrain-inside-muse) below, adapter `muse` |-| No confirmed persistent custom-files location | Resolve that platform capability before installing either the thin CLI or durable local memory |-| Want to keep the connection tailnet-only | Joining Muse's runtime to your tailnet (userspace `tailscaled`, ephemeral auth key) is advanced, not automated by gbrain, and unverified; Sentinel's egress policy applies either way |-| A native MCP option appears in your account | Treat it as a new capability to verify; this guide does not claim Muse supports native MCP |--## Recommended: your brain on your computer, reached over MCP--On the computer that holds the brain:--```bash-gbrain mcp expose --funnel # consent prompt, Tailscale install/login if needed, service, URL-gbrain mcp grant muse-example --harness muse --profile memory-writer --source default \- --url https://your-machine.your-tailnet.ts.net/mcp \- --admin-token-file ~/.gbrain/serve/admin-token \- --credentials-out /private/muse-example.json-```--Deliver `/private/muse-example.json` into Muse's durable user-files area-through the product's supported secure file flow (never paste it into chat),-then paste this into Muse:--```text-Connect this agent to my existing GBrain over MCP. Read:-https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/muse.md-and its linked hosted-access guide.--First identify the documented or platform-confirmed durable user-files area-available to your runtime and choose an absolute gbrain root there; tell me the-persistence evidence, or report the blocker instead of using a temporary path.--The brain is published at https://your-machine.your-tailnet.ts.net/mcp and my-private credential file is at <durable-area>/private/muse-example.json.-Install GBrain at that root (reuse a matching installation; preserve existing-state), then run gbrain connect with --harness muse, that credentials file,---install and the absolute --root. Use the generated absolute bin/gbrain-launcher for every memory command. Keep secrets out of chat and command output.-Use Muse's normal permission and secure credential flows for any blocked-download or egress; a denial is a reported boundary, not something to route-around.--Run gbrain mcp verify and show me the server checks. Attach the generated-GBRAIN-INSTRUCTIONS.md through the native custom-skill mechanism available in-this account and report its exact location or name; keep your current identity.-Then remember a harmless randomized test fact with provenance, recall it in a-fresh conversation, and report each unverified platform step separately.-```--Muse's memory now lives on your machine. `gbrain mcp expose --status` on your-computer re-checks the service and public URL; revoke Muse's client on the-host when it should stop.--## Alternative: install GBrain inside Muse--Use this when no computer of yours can stay online. Paste this into Muse:--```text-Set up GBrain as my durable memory. Read:-https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/muse.md-and its linked in-agent setup guide.--First identify the documented or platform-confirmed durable user-files area-available to your runtime. Inspect it and choose an absolute gbrain root there.-Tell me the persistence evidence. If you cannot establish persistence, report-that blocker instead of treating a temporary runtime directory as durable.--Use the shipped setup helper with --harness muse and that absolute --root.-Reuse a matching installation and preserve existing state. Use its generated-absolute bin/gbrain launcher for every memory command. Keep your current identity.--Start with keyless facts and recall. Show me init's search-mode matrix and-confirm my choice; keep paid maintenance and bulk capture opt-in. Attach the-generated memory instructions using the native custom-skill mechanism available-in this account, and report its exact location or name.--Save and recall a harmless randomized test fact, then help me verify a fresh-conversation actually invokes GBrain. Use Muse's normal permission and secure-credential flows for any blocked download or later hosted connection. Report-each unverified platform step separately from successful local CLI checks.-```--Once the durable root is established, follow the-[shared setup commands](in-agent-setup.md#2-run-the-shipped-setup-helper), replacing-the example root and selecting `--harness muse`. The helper works without root-and does not create a system service or agent identity. Initial fact storage and-recall do not require extracting credentials from a Muse connector. The rest-of this guide's local-installation sections apply to this path.--## Attach instructions and test a fresh conversation--Read the memory instructions — `<ROOT>/GBRAIN-INSTRUCTIONS.md` for a-connection to your published brain, `<ROOT>/instructions/gbrain-skill.md` for-a local installation — and save them through Muse's available-custom-skill or standing-instruction mechanism. Keep the exact absolute-`<ROOT>/bin/gbrain` path in that skill. Public documentation does not establish-an automatic `AGENTS.md` loader or hook API, so merely writing a repository file-is not evidence that Muse will use it.--Follow the [randomized round trip](in-agent-setup.md#3-prove-the-first-memory-round-trip).-In a fresh conversation, ask for the phrase without repeating it and inspect-the command result. Test a correction and deletion too. Record the actual-native skill location/name and the date of the test; the installer deliberately-leaves native integration marked unverified.--## Three useful things to try--- **A durable preference:** “Remember that I want a short recommendation followed- by the evidence.” Ask a new conversation to recall that preference before- preparing a recommendation.-- **A project handoff:** “Recall the current project-example decision and open- questions. After we decide, remember the new decision with today's date.”-- **Existing connected services:** “Use your connected calendar and email to- prepare this meeting. Save the selected commitments I ask you to retain,- with source links.” Let Muse use its existing connectors and permissions;- store the chosen facts in GBrain without duplicating service credentials.--Do not request raw connector tokens or change Sentinel policy to make GBrain-work. For a hosted brain, the allowed destination and secure credential delivery-are part of the [hosted setup](hosted-harness-access.md); finish them through the-actual product's supported flow. A denied request is a reported setup boundary,-not a reason to try another route around it.--## Local installation maintenance, backup, and recovery--These steps apply when GBrain runs inside Muse. A hosted connection instead-uses `<ROOT>/GBRAIN-INSTRUCTIONS.md` and the-[hosted runtime repair procedure](hosted-harness-access.md#maintenance-removal-and-troubleshooting).--After manual memory succeeds, use `<ROOT>/instructions/maintenance.md` as the-basis of an optional native schedule, if that feature is available in your-account. Maintain one routine for the installation and test it. Do not install-a speculative daemon or assume a shell cron is the product's native scheduler.--Create a [full private backup](in-agent-setup.md#6-back-up-the-complete-local-database)-and choose a protected off-VM copy explicitly. The raw database can contain-sensitive memories and authentication state. Its `0600` mode does not encrypt-it or protect against loss of the whole VM.--After a runtime replacement, use `bash <ROOT>/bin/gbrain-setup` to repair the-recorded package without resetting memory. If data is lost, restore into an-absent root, rerun the helper with `--harness muse`, reconnect excluded state,-and test before reattaching the native skill. The-[restore procedure](in-agent-setup.md#7-restore-into-a-new-root) preserves the-original brain and starts no automation.--To stop, pause the native routine and disable the skill. Keep the root and a-protected backup until you deliberately choose to delete the memory. Revoke-hosted grants separately if you connected to an existing brain.--## Acceptance checklist and limits--The local installer, CLI, and recovery path have hermetic repository tests.-**An actual Muse account has not been used to verify this integration.** The-Tailscale publish path (`gbrain mcp expose`) has repository tests with a fake-Tailscale runner; a real Funnel endpoint reached from Muse and Muse's native-skill activation are separate observed steps. The-remaining acceptance checks are concrete:--- Establish and record the durable root and its behavior across runtime replacement.-- For the published-brain path: `gbrain mcp expose --status` verifies on your- computer and `gbrain mcp verify` passes its server checks from inside Muse.-- Complete allowed package downloads and run the generated launcher.-- Save, recall, correct, and forget the randomized fact through separate commands.-- Make a fresh conversation select the native skill and invoke that launcher.-- Restore a private backup into another root and verify the saved fact.-- If used, test the account's native schedule and its failure reporting.-- For a hosted brain, verify the real egress and secure credential flow; no- native MCP or privileged credential-service integration is assumed.--If installation is blocked, preserve the exact platform denial. If memory works-only in the current conversation, inspect the native skill attachment. If the-runtime vanishes, run repair against the same durable root. If that root was not-preserved, restore a backup rather than initializing a replacement brain at the-old path. More errors and fixes are in the-[shared troubleshooting table](in-agent-setup.md#troubleshooting).--[Validation evidence and actual-harness acceptance](harness-validation.md).-------## docs/guides/in-agent-setup.md--Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/in-agent-setup.md--# 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](grok-bot.md): use its shared `/workspace` directory.-- [Muse](muse.md): first establish which user-files directory survives runtime- replacement; its public documentation does not name that path.-- [An existing hosted brain](hosted-harness-access.md): 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:--```bash-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](muse.md). 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](../../INSTALL_FOR_AGENTS.md).-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:--```bash-/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:--```bash-/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](memory-boundaries.md) 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](chat-connectors.md). 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](hosted-harness-access.md)-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:--```bash-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](https://github.com/garrytan/gbrain/issues/6649)).--## 7. Restore into a new root--Use an available GBrain runtime and a destination that **does not exist**:--```bash-/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-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-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-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:--```bash-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--<a id="in-agent-troubleshooting"></a>--| 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](#large-or-non-standard-brains-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](harness-validation.md).------## docs/guides/hosted-harness-access.mdSource: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/hosted-harness-access.mddiff --git a/scripts/llms-config.ts b/scripts/llms-config.tsindex 1b34f1136c..0b5d363600 100644--- a/scripts/llms-config.ts+++ b/scripts/llms-config.ts@@ -39,9 +39,12 @@ export const SECTIONS: DocSection[] = [heading: "Choose your agent setup",entries: [{ title: "Use your brain from anywhere over MCP", path: "docs/guides/remote-mcp.md", description: "`gbrain mcp expose`: publish serve --http on your Tailscale tailnet (Funnel explicit for cloud agents), user service, admin token file, grant/connect/verify hand-off, --status/--remove, troubleshooting, security posture, ngrok and cloud-host alternatives." },- { title: "Grok Bot", path: "docs/guides/grok-bot.md", description: "Recommended: keep the brain on your computer, publish it with `gbrain mcp expose --funnel`, grant the Bot a client and install the thin CLI; local in-Bot memory as the no-host alternative. Native skill activation, shared-computer trust and dated evidence." },- { title: "Muse personal agent", path: "docs/guides/muse.md", description: "Verify durable storage first; connect Muse to your published brain (`gbrain mcp expose --funnel` + thin CLI) or add local explicit memory with provenance alongside Muse's native memory; distinguish Muse Code and unverified native MCP." },- { title: "Inside an existing agent", path: "docs/guides/in-agent-setup.md", description: "Isolated setup, absolute launcher, receipts, keyless maintenance, complete private backup and safe restoration." },+ // Linked, not inlined: these three guides only apply inside Grok Bot, Muse or another+ // hosted agent, and AGENTS.md (inlined) routes those agents to them. Dropping them from the+ // bundle freed about 48 KB of FULL_SIZE_BUDGET.+ { title: "Grok Bot", path: "docs/guides/grok-bot.md", description: "Recommended: keep the brain on your computer, publish it with `gbrain mcp expose --funnel`, grant the Bot a client and install the thin CLI; local in-Bot memory as the no-host alternative. Native skill activation, shared-computer trust and dated evidence.", includeInFull: false },+ { title: "Muse personal agent", path: "docs/guides/muse.md", description: "Verify durable storage first; connect Muse to your published brain (`gbrain mcp expose --funnel` + thin CLI) or add local explicit memory with provenance alongside Muse's native memory; distinguish Muse Code and unverified native MCP.", includeInFull: false },+ { title: "Inside an existing agent", path: "docs/guides/in-agent-setup.md", description: "Isolated setup, absolute launcher, receipts, keyless maintenance, complete private backup and safe restoration.", includeInFull: false },{ title: "Memory boundaries", path: "docs/guides/memory-boundaries.md", description: "Durable shared preferences versus harness state; remote graph maintenance, provider text disclosure, authorization and full-backup limits; large pages (segmented storage up to 256 MiB on Postgres, append_page / gbrain append, upload sessions, windowed reads, limits per entry point).", includeInFull: false },{ title: "Page history", path: "docs/guides/page-history.md", description: "Why a page changed: an optional reason on page writes, replaced_because in get_versions, the gbrain-reason commit trailer, remote visibility and repo-less brains.", includeInFull: false },{ title: "Brain versus session memory", path: "docs/guides/brain-vs-memory.md", description: "Route durable facts and preferences to shared memory, configuration to the harness, and temporary work to session state.", includeInFull: false },