GBrain

Your AI agent is smart but forgetful. GBrain gives it a brain.

Built by the President and CEO of Y Combinator to run his actual AI agents. The production brain powering his OpenClaw and Hermes deployments: 17,888 pages, 4,383 people, 723 companies, 21 cron jobs running autonomously, built in 12 days. The agent ingests meetings, emails, tweets, voice calls, and original ideas while you sleep. It enriches every person and company it encounters. It fixes its own citations and consolidates memory overnight. You wake up and the brain is smarter than when you went to bed.

The brain wires itself. Every page write extracts entity references and creates typed links (attended, works_at, invested_in, founded, advises) with zero LLM calls. Hybrid search. Self-wiring knowledge graph. Structured timeline. Backlink-boosted ranking. Ask "who works at Acme AI?" or "what did Bob invest in this quarter?" and get answers vector search alone can't reach. Benchmarked side-by-side against the category: gbrain lands P@5 49.1%, R@5 97.9% on a 240-page Opus-generated rich-prose corpus, beating its own graph-disabled variant by +31.4 points P@5 and ripgrep-BM25 + vector-only RAG by a similar margin. The graph layer plus v0.12 extract quality together carry the gap. Full BrainBench scorecards + corpus live in the sibling gbrain-evals repo.

GBrain is those patterns, generalized. 34 skills. Install in 30 minutes. Your agent does the work. As Garry's personal agent gets smarter, so does yours.

New in v0.25.0 — BrainBench-Real (session capture, contributor opt-in): with GBRAIN_CONTRIBUTOR_MODE=1 set in your shell, every real query + search call through MCP, CLI, or the subagent tool-bridge gets captured (PII-scrubbed) into an eval_candidates table. Snapshot with gbrain eval export, replay against your code change with gbrain eval replay. Three numbers come back: mean Jaccard@k between captured and current retrieved slugs, top-1 stability, and latency Δ. Off by default for production users — no surprise data accumulation. Walkthrough: docs/eval-bench.md. NDJSON wire format: docs/eval-capture.md.

New in v0.28.8 — LongMemEval in the box: gbrain eval longmemeval <dataset.jsonl> runs the public LongMemEval benchmark against gbrain's hybrid retrieval. One in-memory PGLite per run, TRUNCATE between questions (runtime-enumerated tables, schema-migration-safe), 25.9ms p50 per question on Apple Silicon. Your ~/.gbrain brain is never touched. Retrieved chat content is sanitized with the same INJECTION_PATTERNS that protect takes — one source of truth for prompt-injection defense. Hand the JSONL output to LongMemEval's evaluate_qa.py to score.

~30 minutes to a fully working brain. Database ready in 2 seconds (PGLite, no server). You just answer questions about API keys.

LLMs: fetch llms.txt for the documentation map, or llms-full.txt for the same map with core docs inlined in one fetch. Agents: start with AGENTS.md (or CLAUDE.md if you're Claude Code).

Embedding providers: OpenAI is the default, but gbrain ships with 14 recipes covering Voyage, Google Gemini, Azure OpenAI, MiniMax, Alibaba DashScope, Zhipu, Ollama (local), llama.cpp llama-server (local), LiteLLM proxy (universal), and 5 more. Run gbrain providers list to see them, or read docs/integrations/embedding-providers.md for setup, pricing, and a decision tree. gbrain doctor will surface alternative providers whose env vars you already have set.

New in v0.32.3.0 — compress your AGENTS.md without losing accuracy: if your downstream agent fork has grown a 25KB+ AGENTS.md / RESOLVER.md, the new functional-area-resolver skill ships a two-layer dispatch pattern that compresses 25KB → 13KB (48% the size) while beating the verbose baseline by +13 to +17pp across Opus 4.7, Sonnet 4.6, and Haiku 4.5. A/B eval harness, cross-model receipts, and reproduction instructions live at evals/functional-area-resolver/. The static-prompt analog of AnyTool / RAG-MCP / Anthropic Agent Skills progressive disclosure — single-LLM-pass dispatch, no second routing call.

Install

On an agent platform (recommended)

GBrain is designed to be installed and operated by an AI agent. If you don't have one running yet:

• OpenClaw ... Deploy AlphaClaw on Render (one click, 8GB+ RAM)
• Hermes Agent ... Deploy on Railway (one click)

Paste this into your agent:

Retrieve and follow the instructions at:
https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md

That's it. The agent clones the repo, installs GBrain, sets up the brain, loads 34 skills, and configures recurring jobs. You answer a few questions about API keys. ~30 minutes.

If your agent doesn't auto-read AGENTS.md, point it at that file first: https://raw.githubusercontent.com/garrytan/gbrain/master/AGENTS.md is the non-Claude agent operating protocol (install, read order, trust boundary, common tasks). For the full doc map, use llms.txt at the same URL root.

Standalone CLI (no agent)

git clone https://github.com/garrytan/gbrain.git && cd gbrain && bun install && bun link
gbrain init                     # local brain, ready in 2 seconds
                                # picks a search mode (conservative / balanced / tokenmax)
gbrain import ~/notes/          # index your markdown
gbrain query "what themes show up across my notes?"
gbrain search modes             # see the active search mode + per-knob attribution
gbrain search stats             # cache hit rate + intent mix after some real usage

v0.32.3 — named search modes. gbrain init asks once which mode fits your workload. The cost spread depends on BOTH the mode AND your downstream model — 25x corner-to-corner. Per-query cost @ 10K queries/month (typical single-user volume; multiply by 10 for heavy / multi-user fleets):

Natural pairings (corner-diagonal) span ~4x at realistic single-user volume. Auto-suggests based on your configured models.tier.subagent. Non-TTY installs auto-pick balanced and print a hint pointing at gbrain config set search.mode <m>. After some real usage, run gbrain search stats for observability and gbrain search tune for data-driven recommendations. Methodology + eval results live at docs/eval/SEARCH_MODE_METHODOLOGY.md.

Do NOT use bun install -g github:garrytan/gbrain. Bun blocks the top-level postinstall hook on global installs, so schema migrations never run and the CLI aborts with Aborted() the first time it opens PGLite. Use git clone + bun install && bun link as shown above. See #218.

Do NOT use bun add -g gbrain or npm install -g gbrain. The npm registry has an unrelated package squatting that name (gbrain@1.3.x) — you'd silently install the wrong binary and overwrite the canonical one. v0.28.5+ detects this and prints a recovery message on gbrain upgrade, but the git clone + bun link path above is the only reliable install method until we publish under @garrytan/gbrain (tracked v0.29 follow-up). See #658.

3 results (hybrid search, 0.12s):

1. concepts/do-things-that-dont-scale (score: 0.94)
   PG's argument that unscalable effort teaches you what users want.
   [Source: paulgraham.com, 2013-07-01]

2. originals/founder-mode-observation (score: 0.87)
   Deep involvement isn't micromanagement if it expands the team's thinking.

3. concepts/build-something-people-want (score: 0.81)
   The YC motto. Connected to 12 other brain pages.

MCP server (Claude Code, Cursor, Windsurf)

GBrain exposes 30+ MCP tools via stdio:

{
  "mcpServers": {
    "gbrain": { "command": "gbrain", "args": ["serve"] }
  }
}

Add to ~/.claude/server.json (Claude Code), Settings > MCP Servers (Cursor), or your client's MCP config.

Remote MCP with OAuth 2.1 (ChatGPT, Claude Desktop, Cowork, Perplexity)

gbrain serve --http starts a production-grade OAuth 2.1 server with an embedded admin dashboard. Zero external infrastructure. Every major AI client connects, every request is scoped, every action is logged.

# Start the HTTP server (prints admin bootstrap token on first start)
gbrain serve --http --port 3131

# Open the admin dashboard, paste the bootstrap token, register a client
open http://localhost:3131/admin

# Expose publicly (set --public-url so the OAuth issuer matches)
ngrok http 3131 --url your-brain.ngrok.app
gbrain serve --http --port 3131 --public-url https://your-brain.ngrok.app

# ChatGPT and other OAuth-aware clients can also connect:
claude mcp add gbrain -t http https://your-brain.ngrok.app/mcp -H "Authorization: Bearer TOKEN"

Register OAuth clients from the /admin dashboard — click Register client, pick scopes, save the credentials shown once in the reveal modal. Programmatic registration via oauthProvider.registerClientManual(...) and the gbrain auth register-client CLI are also available.

• OAuth 2.1 via the MCP SDK — client credentials (machine-to-machine: Perplexity, Claude), authorization code + PKCE (browser-based: ChatGPT), refresh token rotation, revocation, protected resource metadata. PKCE-only public clients (token_endpoint_auth_method: "none") register without a secret per RFC 7591 §3.2.1 (v0.34). Optional Dynamic Client Registration behind --enable-dcr (DCR redirect_uris must be https:// or loopback per RFC 6749 §3.1.2.1).
• Source-scoped OAuth clients (v0.34) — gbrain auth register-client my-agent --source dept-x ties the client's write authority to one source; read paths only return rows matching that source. --federated-read S1,S2,S3 adds an orthogonal read-scope axis for shared brains (departments writing to one canon while reading the union). Pre-v0.34 clients are backfilled to source_id='default' on upgrade.
• Loopback default for serve --http (v0.34) — listens on 127.0.0.1 unless --bind 0.0.0.0 (or a specific interface IP). Personal-laptop installs no longer publish the brain to the LAN by accident. A stderr WARN fires when --public-url is set without --bind so the operator sees the binding before the first request.
• Scoped operations — 30 operations tagged read | write | admin. sync_brain and file_upload are localOnly, rejected over HTTP.
• React admin dashboard — 7 screens baked into the binary (~65KB gzip). Live SSE activity feed, agents table, credential reveal, filterable request log, per-client config export.
• Legacy bearer tokens still work — pre-v0.26 gbrain auth create tokens continue to authenticate as read+write+admin. v0.22.7's simpler src/mcp/http-transport.ts path stays compiled in for backward compat callers; v0.26+ deployments use the OAuth-aware serve-http.ts.

Per-client guides: docs/mcp/. Hardening defaults, env vars, and threat model: SECURITY.md.

Using gbrain with GStack

If your engineering agent runs on GStack, point it at gbrain for code lookup instead of grep+read. Cathedral II (v0.21.0) ships call-graph edges and two-pass retrieval — /investigate, /review, /plan-eng-review, and /office-hours all benefit when the agent walks the symbol graph instead of scanning files line by line.

The five magical-moment commands:

gbrain code-callers searchKeyword           # who calls this symbol?
gbrain code-callees searchKeyword           # what does this symbol call?
gbrain code-def BrainEngine                 # where is X defined?
gbrain code-refs BrainEngine                # all reference sites
gbrain query "how does N+1 handling work" --near-symbol BrainEngine.searchKeyword --walk-depth 2

All five auto-emit JSON on non-TTY (gh-CLI convention) so a GStack subagent shelling out via bash gets a clean parseable response. Run gbrain sources add <repo> --strategy code to index a repo, then your agent's brain-first lookup covers code, not just markdown. (Cathedral II release notes)

The 34 Skills

GBrain ships 34 skills organized by skills/RESOLVER.md (or your OpenClaw's AGENTS.md — both filenames are supported as of v0.19). The resolver tells your agent which skill to read for any task. v0.25.1 added 9 research-flavored skills (book-mirror flagship plus 8 pairings); see the new "Research and synthesis" section below.

Skill files are code. They're the most powerful way to get knowledge work done. A skill file is a fat markdown document that encodes an entire workflow: when to fire, what to check, how to chain with other skills, what quality bar to enforce. The agent reads the skill and executes it. Skills can also call deterministic TypeScript code bundled in GBrain (search, import, embed, sync) for the parts that shouldn't be left to LLM judgment. Thin harness, fat skills: the intelligence lives in the skills, not the runtime.

Always-on

| Skill | What it d