git:20260921.6ebc629 to git:20261007.48e90ed

109 added, 26 removed. Audit B to B.

# 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), using the isolated [in-agent setup](docs/guides/in-agent-setup.md) entry point. 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.

+ > **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). Provision on the host; install the private handoff inside the intended harness. A URL or ordinary OAuth token is not administration authority.

+ > **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` to recover, or fall back to the

- deterministic install: `git clone https://github.com/garrytan/gbrain.git ~/gbrain && cd ~/gbrain && bun install && bun link`.

- 2. Init the brain: `gbrain init` (defaults to PGLite, zero-config). For 1000+ files or

+ 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. Same banner fires on `gbrain post-upgrade`

- for existing users (search modes were added in v0.32.3).

+ 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:** [`docs/GBRAIN_VERIFY.md`](./docs/GBRAIN_VERIFY.md),

- [`docs/guides/minions-fix.md`](./docs/guides/minions-fix.md), `gbrain doctor --fix`.

- Database unreachable — or any `GBRAIN_DB_ACCESS <reason>` marker in gbrain

- output: `gbrain engine status --probe` (which engine, where its URL comes from,

- classified reachability), then `gbrain db-repair` to diagnose and

- `gbrain db-repair --yes` to apply safe fixes. All three are engine-free — they

- work while the database is down. Full loop:

- [`docs/ENGINES.md`](./docs/ENGINES.md#engine-detection-and-access-repair).

+ - **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 <code>` 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 <path>: 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 <id>`,

+ preview the fix with `gbrain repair frontmatter --source <id>` (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 <id> --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 <p>`. Walkthrough:

+ [held files](docs/guides/repair.md#held-files). A hold with code

+ `invalid_fence` is a facts or takes table, not frontmatter: read the page

+ (`gbrain get --source <id> -- <slug>`), edit only the fence the hold names,

+ commit, then `gbrain sync --source <id> --no-pull`

+ ([fence holds](docs/guides/write-refusals.md#invalid_fence)).

- **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` (manual schema-only).

+ [`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

<dataset.jsonl>` 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:** the one-command

- loop. `gbrain doctor --remediation-plan --json` previews what would be

- fixed; `gbrain doctor --remediate --yes --target-score 90 --max-usd 5`

- walks a dependency-ordered plan, re-checking score between every step and

- refusing to spend past the cost cap. 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 and bail with what's missing.

+ - **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 <plan_hash> --target-score 90 --max-usd 5`

+ (`<plan_hash>` 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 <entity-slug>` for the chronological history

with regressions auto-flagged, or `gbrain founder scorecard <entity-slug>`

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 "<q>"` 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. Use `bun run ci:local:diff` for the

- diff-aware subset during fast iteration on a focused branch. Requires Docker

+ 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`.