# Agents working on GBrain This is your install + operating protocol. Claude Code reads `./CLAUDE.md` automatically. Everyone else (Codex, Cursor, OpenClaw, Aider, Continue, or an LLM fetching via URL): start here. > **Default: add memory to the existing agent.** Preserve its identity and unrelated instructions. Start keyless; automatic capture and paid enrichment are opt-in. No bootstrap interview or private repository is required. > > **Inside Grok Bot or Muse:** follow [Grok Bot](docs/guides/grok-bot.md) or [Muse](docs/guides/muse.md). The recommended path connects an isolated thin CLI to a brain on the user's own computer, published with `gbrain mcp expose --funnel` when needed; use the isolated [in-agent setup](docs/guides/in-agent-setup.md) when no machine stays online. Use the absolute recorded launcher on every call. Sources organize local memory; they do not isolate agents that share files or credentials. Do not mark generated skills or routines as activated without native-harness evidence. > > **Existing hosted brain:** follow [hosted harness access](docs/guides/hosted-harness-access.md). Choose native OAuth/PKCE or a private machine handoff for the intended harness. For login links, clients, permissions, or token lifecycle, follow [MCP administration](docs/mcp/ADMIN.md) or `skills/mcp-access/SKILL.md`. A URL or ordinary OAuth token is not owner administration authority. > > **Creating a new personal agent, explicitly requested by the user:** follow [BOOTSTRAP_FOR_AGENTS.md](BOOTSTRAP_FOR_AGENTS.md), then return here for the operating protocol. ## Install (5 min) 1. Install gbrain via Bun (the canonical path): ```bash curl -fsSL https://bun.sh/install | bash export PATH="$HOME/.bun/bin:$PATH" bun install -g github:garrytan/gbrain ``` If `bun install -g` aborts or `gbrain doctor` reports `schema_version: 0`, the CLI prints a recovery hint pointing at [#218](https://github.com/garrytan/gbrain/issues/218). Run `gbrain apply-migrations --yes --no-autopilot-install` to recover without installing services. It exits 0 only when the schema is at head; exit 1 with `migrations_pending` means the schema is still behind, and another `--yes` repeats the failure, so run `gbrain doctor --json` and fall back to the deterministic install: `git clone https://github.com/garrytan/gbrain.git ~/gbrain && cd ~/gbrain && bun install && bun link`. 2. Init keyless memory: `gbrain init --pglite --no-embedding` (zero-config). For 1000+ files or multi-machine sync, init suggests Postgres + pgvector via Supabase. 3. **STOP — ask the user about search mode.** `gbrain init` auto-applied a default but printed a 9-cell cost matrix (mode × downstream model) preceded by `[AGENT]` markers. You MUST relay the matrix to the operator and confirm their choice before continuing. Cost spread between corners is 25x — silent acceptance is the wrong default. See [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md) Step 3.5 for the exact ask-the-user protocol. The same banner fires on `gbrain post-upgrade` for a brain created before v0.32.3, when search modes arrived. 4. Read [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md) for the full step-by-step flow (keyless memory, optional API capabilities, maintenance, verification). ## Memory operating protocol Recall relevant saved context before answering. Save explicit requests to remember with provenance; confirm corrections against the stored record. Automatic capture requires opt-in. Withdrawal (`forget`) removes a fact from active memory; history, source material, and private backups may remain. Never promise physical erasure. Verify changes with actual GBrain calls and distinguish a local test from a new-conversation test in the harness. Durable preferences and facts belong in shared memory when the user wants them recalled later. Transient task state, credentials, local configuration, and harness activation state do not. Remote `put_page` saves references as text without inline graph extraction; a post-commit `links` effect then adds plain mention edges to existing pages the writer can see (`mcp.remote_auto_links`, on by default). Typed edges rely on stdio's best-effort startup/idle sweeps, explicit host maintenance or authorized `add_link` calls. Configured model providers can receive text; Markdown export is not a full database backup. Read [memory boundaries](docs/guides/memory-boundaries.md) before promising portability, graph freshness, privacy, or recovery. ## Agent operator protocol Every gbrain error, refusal, degraded result and recommendation carries the same machine contract. The quick version: 1. Read `code` (fall back to `error` on older servers). `message` says what happened, `why` says why. 2. Follow `fix.next`: - `run` → run `fix.argv` (CLI) or call `fix.mcp` (MCP) exactly as given. - `ask_user` → relay `user_message` to the user and stop; run the fix only after they agree. - `tell_user_to_run` → give the user `fix.command`; it needs them or the brain host's operator. - `wait` → retry after the stated delay with the same request. - `report` → tell the user what happened and run `gbrain doctor --json`. 3. Then run `fix.verify` (always read-only) to confirm the fix worked. 4. Treat `[gbrain notice …]` blocks and `[AGENT]` blocks the same way. A degraded result is not proof of "no notes". Exit 3 always means "stop and ask the user". Full contract, transcripts, effects, exit codes and marker grammar: [`docs/protocol/AGENT_OPERATOR_v1.md`](./docs/protocol/AGENT_OPERATOR_v1.md). ## Read this order 1. `./AGENTS.md` (this file) — install + operating protocol. 2. [`./CLAUDE.md`](./CLAUDE.md) — orientation + resolver: architecture, cross-cutting invariants, the reference map, inline ship rules. It routes to on-demand detail docs: [`./docs/architecture/KEY_FILES.md`](./docs/architecture/KEY_FILES.md) (per-file index — read a file's entry before editing it), [`./docs/TESTING.md`](./docs/TESTING.md) (test tiers + isolation lint + E2E lifecycle), and [`./docs/architecture/thin-client.md`](./docs/architecture/thin-client.md) (remote-MCP seam). 3. [`./docs/architecture/brains-and-sources.md`](./docs/architecture/brains-and-sources.md) — the two-axis mental model (brain = which DB, source = which repo in the DB). Every query routes on both axes. Read before writing anything that touches brain ops. 4. [`./skills/conventions/brain-routing.md`](./skills/conventions/brain-routing.md) — agent-facing decision table: when to switch brain, when to switch source, how cross-brain federation works (latent-space only; the agent decides). 5. [`./skills/RESOLVER.md`](./skills/RESOLVER.md) — skill dispatcher. Read before any task. ## Trust boundary (critical) GBrain distinguishes **trusted local CLI callers** (`OperationContext.remote = false`, set by `src/cli.ts`) from **untrusted agent-facing callers** (`remote = true`, set by `src/mcp/server.ts`). Security-sensitive operations like `file_upload` tighten filesystem confinement when `remote = true` and default to strict behavior when unset. If you are writing or reviewing an operation, consult `src/core/operations.ts` for the contract. ## Common tasks - **Configure:** [`docs/ENGINES.md`](./docs/ENGINES.md), [`docs/guides/live-sync.md`](./docs/guides/live-sync.md), [`docs/mcp/DEPLOY.md`](./docs/mcp/DEPLOY.md), [`docs/guides/remote-mcp.md`](./docs/guides/remote-mcp.md) (`gbrain mcp expose`). - **Bring in your chat history:** `gbrain transcripts ingest` imports a downloaded ChatGPT / Claude export (or agent session logs); `gbrain connectors` connects the account and syncs new conversations live, incrementally and on an opt-in schedule (cookie/OAuth credentials stay on your machine, 0600). Full guide: [`docs/guides/chat-connectors.md`](./docs/guides/chat-connectors.md). - **Debug:** a gbrain call failed, refused, or printed `[AGENT]` or `[gbrain notice …]`: follow the [agent operator protocol](#agent-operator-protocol) above (full contract: [`docs/protocol/AGENT_OPERATOR_v1.md`](./docs/protocol/AGENT_OPERATOR_v1.md)); `gbrain errors ` explains any code offline. Symptoms with who acts, consent and a verify step: [`docs/guides/troubleshooting.md`](./docs/guides/troubleshooting.md#symptom-table); database unreachable or `GBRAIN_DB_ACCESS`: `gbrain db-repair` ([`docs/ENGINES.md`](./docs/ENGINES.md#engine-detection-and-access-repair)); health checks: [`docs/GBRAIN_VERIFY.md`](./docs/GBRAIN_VERIFY.md). - **Sync held a file** (`Held : invalid_frontmatter …`, doctor `git_held_files`, `get_page.file_held`, `stale` search hits): the sync succeeded and only that file waits. Read it with `gbrain sources status `, preview the fix with `gbrain repair frontmatter --source ` (writes nothing), and ask the user before any `--apply`, especially `--include-ambiguous` interpretations; never retry a `put_page` refused on a held page. A source a broken file blocked before upgrading recovers on its next sync (`gbrain sync --source --no-pull` does it now). Write brain files through `put_page`/`capture` or a YAML serializer and check generated content with `gbrain frontmatter validate --stdin --path

`. Walkthrough: [held files](docs/guides/repair.md#held-files). A hold with code `invalid_fence` or `frontmatter_slug_conflict` is about the file's content, not its YAML, and the content-repair lane clears it by itself: the next maintenance run repairs what it can, `gbrain sync unblock --source --apply` does it now with a receipt per file, and `gbrain repair content --source ` previews every lane kind (its printed apply command runs with no extra consent). A hold the lane marks `needs_human` (a manual fence edit, a recommended page merge, an exposed tail on a world page) is listed in `gbrain sync status --source --json` with its paragraph: relay it, make or approve the edit it names, commit, `gbrain sync --source --no-pull`. Raising spend (`fences.repair.max_usd_per_day`, `fences.repair.llm true`) is the user's call ([the lane](docs/guides/repair.md#content-lane), [fence holds](docs/guides/write-refusals.md#invalid_fence)). A hold with code `preparation_stalled` (or a managed catch-up that stops `preparation_abandoned` / `preparation_systemic`, or a write receipt with that code) means the write owner stalled, not the file: no repair applies. Run `gbrain sources writer status --source --json` (read-only: the step, what it waited on, the owner and its version), fix that or upgrade the owner, then `gbrain sources retry-held ` and the sync it prints with the same options (`--no-embed` stays). Runbook: [catch-up stuck](docs/guides/troubleshooting.md#catch-up-stuck). - **Keep a managed catch-up moving without a human** (a live checkout where other agents commit while `gbrain sync` drains thousands of pages): a page that moves under the run is held (`concurrent_write`, `worktree_dirty`), a dropped connection is retried, and a relaunch resumes the frozen manifest. The operator loop is `gbrain sync status --source --json` (cursor, `committed_last_10m`, each hold and the last error with `class` / `safe_actions` / `needs_human`), then, when nothing moved and `needs_human` is false, `gbrain sync unblock --source --apply` and the sync it prints; when `needs_human` is true, relay `next.user_message` with the slug. Decision table: [`docs/guides/sync-unblock-runbook.md`](./docs/guides/sync-unblock-runbook.md). - **Migrate / upgrade:** `gbrain upgrade` (binary self-update + schema migrations + post-upgrade prompts), [`docs/UPGRADING_DOWNSTREAM_AGENTS.md`](./docs/UPGRADING_DOWNSTREAM_AGENTS.md), [`skills/migrations/`](./skills/migrations/), `gbrain apply-migrations --yes --no-autopilot-install` (manual migration orchestration without service installation). - **Eval retrieval changes:** capture is off by default. To benchmark a retrieval change against real captured queries, set `GBRAIN_CONTRIBUTOR_MODE=1`, then `gbrain eval export --since 7d > base.ndjson` and `gbrain eval replay --against base.ndjson`. For public benchmark coverage (LongMemEval, ground-truth scoring), `gbrain eval longmemeval ` runs against an isolated in-memory PGLite per question — your `~/.gbrain` is never opened. Full guide: [`docs/eval-bench.md`](./docs/eval-bench.md). - **Drive the brain to a target health score:** preview, then agree. `gbrain doctor --remediation-plan --json` previews job steps and the PROTECTED repair steps (each marked "requires user agreement", with its exact command and the `plan_hash` the approval binds); after the user agrees, `gbrain doctor --remediate --yes --include-repairs --expect --target-score 90 --max-usd 5` (`` from that `--remediation-plan --json` output; a changed plan refuses with `preview_changed`, so preview and ask again) runs the repairs (even when the score target is unreachable) and walks the dependency-ordered job plan, re-checking score between steps. The cap is cumulative across `--resume`; a paid step that would exceed it is not started while free steps still run. Without `--include-repairs`, repair steps are listed as skipped. `--json` classifies each finding `cleared`, `pending`, `consent_required`, `operator_required`, `explicit_kind_required` or `unsupported`. Stale extraction uses source-scoped database pages, including DB-only pages; it does not require a repository sync first. Empty brains (no entity pages) or unconfigured embedding keys hit a `max_reachable_score` ceiling: job steps stop with what's missing, while included repair steps still run. Three phase handlers (synthesize / patterns / consolidate) are PROTECTED — only trusted local callers can submit them; MCP cannot. Reference: [`docs/architecture/topologies.md`](./docs/architecture/topologies.md). - **Track a founder/company over time:** when an entity has typed metric claims in its `## Facts` fence (`metric: mrr`, `value: 50000`, `unit: USD`, `period: monthly` columns), run `gbrain eval trajectory ` for the chronological history with regressions auto-flagged, or `gbrain founder scorecard ` for a four-signal JSON rollup (claim_accuracy / consistency / growth_trajectory / red_flags). MCP op `find_trajectory` exposes the same data — read scope, visibility-filtered for remote callers. `gbrain think` uses this substrate automatically on temporal / knowledge_update intent (default ON; flip `think.trajectory_enabled=false` to opt out). Non-metric event rows (`meeting`, `job_change`, `location_change`) ride through the same pipeline via `facts.event_type`; pass `kind: 'event'` or `'all'` to `find_trajectory` to query them. - **Answer "who is waiting on me?":** connect the user's Google account once (`gbrain google setup` — two user interactions; relay the `[SHOW USER]` blocks verbatim), then `gbrain waiting --json` returns the ranked people waiting on the user, what they promised, evidence quotes, and Gmail deep links. Manage loops with `gbrain loops done|drop|mute`. It refuses on stale data and names the exact sync command to run first. Guides: [`docs/guides/google-connect.md`](./docs/guides/google-connect.md) (setup + every error and its fix), [`docs/guides/open-loops.md`](./docs/guides/open-loops.md) (how detection works); the harness protocol lives in [`skills/google-loops/SKILL.md`](./skills/google-loops/SKILL.md). - **Turn on System One decisions (TypeSafe Jev):** every slot is off by default and nothing is sent until the user opts in. With `TYPESAFE_API_KEY` set, `gbrain decide probe` (sends nothing from the brain), then `gbrain decide probe --query ""` to preview on the user's own brain, then `gbrain decide enable --recommended` after showing the user what leaves the machine. `gbrain decide disable --all` is the kill switch. Guide: [`docs/guides/system-one.md`](./docs/guides/system-one.md); key setup: [`docs/ai-providers/typesafe.md`](./docs/ai-providers/typesafe.md). - **Contribute code:** [`CONTRIBUTING.md`, "Where does my change go?"](./CONTRIBUTING.md#where-does-my-change-go) names the files, registry, regenerate command and smallest test for a storage method, schema migration, doctor check, CLI-only command, HTTP route or sync phase. A branch written before refactor wave 1: follow the moved-symbol map in [`docs/architecture/wave-1-porting.md`](./docs/architecture/wave-1-porting.md). - **Everything else:** [`./llms.txt`](./llms.txt) is the full documentation map. [`./llms-full.txt`](./llms-full.txt) is the same map with core docs inlined for single-fetch ingestion. ## Before shipping Easiest path: `bun run ci:local` runs the full CI gate inside Docker (gitleaks, guards + typecheck, then 4-shard parallel unit + E2E against four pgvector containers plus a transaction-mode PgBouncer; unit phase keeps `DATABASE_URL` unset) and tears down. `bun run ci:local:diff` checks a doc-only diff in seconds (gitleaks plus the doc checks) and runs the full gate otherwise. Requires Docker (Docker Desktop / OrbStack / Colima) and `gitleaks` (`brew install gitleaks`). Fastest path, with a Ubicloud token (`UBICLOUD_API_KEY` or `UBICLOUD_API_TOKEN`): `bun run ci:ubicloud` runs the same gate across four ephemeral VMs in about five minutes, uncommitted edits included (`ci:ubicloud:diff` for the doc-only fast path). See "Ubicloud fan-out" in [`docs/TESTING.md`](./docs/TESTING.md). Set `UBI_OWNER` to your thread code. In a multi-lane wave, lanes run `ci:ubicloud:diff` or targeted suites; only the integrator runs the full gate. Manual path: `bun test` plus the E2E lifecycle described in `./CLAUDE.md` (spin up the test Postgres container, run `bun run test:e2e`, tear it down). Ship via the `/ship` skill, not by hand. The full release + contributor process (CHANGELOG voice, version-locations sync, PR conventions, community-PR-wave) lives in [`./docs/RELEASING.md`](./docs/RELEASING.md); read it before shipping. **Always use PATCH without asking**, including the initial release choice; override `/ship`'s MINOR/MAJOR prompts. Auto-allocate past collisions, sync all version stamps and the PR title, then report the number. This changes numbering only: scope, merge, deployment, paid-work and validation approvals still apply. ## Privacy Never commit real names of people, companies, or funds into public artifacts. See the Privacy rule in `./CLAUDE.md`. GBrain pages reference real contacts; public docs must use generic placeholders (`alice-example`, `acme-example`, `fund-a`). ## Forks If you are a fork, regenerate `llms.txt` + `llms-full.txt` with your own URL base before publishing: `LLMS_REPO_BASE=https://raw.githubusercontent.com/your-org/your-fork/main bun run build:llms`.