AGENTS.md git:20261007.d5b7e25B

Immutable. This exact content never changes and is served at /api/v1/blob/c21618dc48b3475f.

# 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)

<!-- npm-trap + #218 recovery: canonical copy lives in README.md ("Install" warning) — sync edits. -->
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:

<!-- BEGIN GENERATED agent-protocol:quick-contract (copied from docs/protocol/AGENT_OPERATOR_v1.md by bun run build:agent-protocol) -->
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".
<!-- END GENERATED agent-protocol:quick-contract -->

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 <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, and clears
  automatically on the next maintenance run. `gbrain repair fences --source <id>`
  previews the repair and its printed apply command runs it now, with no
  extra consent; a `manual` reason needs the edit the hold names (read the
  page with `gbrain get --source <id> -- <slug>`, edit only that fence,
  commit, `gbrain sync --source <id> --no-pull`). Raising spend
  (`fences.repair.max_usd_per_day`, `fences.repair.llm true`) is the user's
  call ([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 --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:** 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. `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`.