Imported from garrytan/gbrain (AGENTS.md). Install upstream with npx skills add garrytan/gbrain. Copyright stays with the author.

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 or Muse, using the isolated in-agent setup 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.

Existing hosted brain: follow hosted harness access. Provision on the host; install the private handoff inside the intended harness. A URL or ordinary OAuth token is not administration authority.

Creating a new personal agent, explicitly requested by the user: follow BOOTSTRAP_FOR_AGENTS.md, then return here for the operating protocol.

Install (5 min)

1. Install gbrain via Bun (the canonical path):

   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. 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 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 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).
4. Read ./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.

Read this order

1. ./AGENTS.md (this file) — install + operating protocol.
2. ./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 (per-file index — read a file's entry before editing it), ./docs/TESTING.md (test tiers + isolation lint + E2E lifecycle), and ./docs/architecture/thin-client.md (remote-MCP seam).
3. ./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 — 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 — 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/guides/live-sync.md, docs/mcp/DEPLOY.md.
• 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.
• Debug: docs/GBRAIN_VERIFY.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.
• Migrate / upgrade: gbrain upgrade (binary self-update + schema migrations + post-upgrade prompts), docs/UPGRADING_DOWNSTREAM_AGENTS.md, skills/migrations/, gbrain apply-migrations --yes (manual schema-only).
• 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.
• 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. Three phase handlers (synthesize / patterns / consolidate) are PROTECTED — only trusted local callers can submit them; MCP cannot. Reference: 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 (setup + every error and its fix), docs/guides/open-loops.md (how detection works); the harness protocol lives in skills/google-loops/SKILL.md.
• Everything else: ./llms.txt is the full documentation map. ./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 (Docker Desktop / OrbStack / Colima) and gitleaks (brew install gitleaks).

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; read it before shipping.

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.