[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74748":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":27,"readmeContent":28,"aiSummary":29,"trendingCount":16,"starSnapshotCount":16,"syncStatus":30,"lastSyncTime":31,"discoverSource":32},74748,"gbrain","garrytan\u002Fgbrain","garrytan","Garry's Opinionated OpenClaw\u002FHermes Agent Brain","",null,"TypeScript",22281,3191,105,460,0,210,1332,5216,1054,120,"MIT License",false,"master",true,[],"2026-06-12 04:01:15","# GBrain\n\nYour AI agent is smart but forgetful. GBrain gives it a brain.\n\nBuilt 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.\n\nThe 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](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain-evals) repo.\n\nGBrain 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.\n\n**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\u002Feval-bench.md](docs\u002Feval-bench.md). NDJSON wire format: [docs\u002Feval-capture.md](docs\u002Feval-capture.md).\n\n**New in v0.28.8 — LongMemEval in the box:** `gbrain eval longmemeval \u003Cdataset.jsonl>` runs the public [LongMemEval](https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Fxiaowu0162\u002Flongmemeval) 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 `~\u002F.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.\n\n**New in v0.35.7 — Temporal trajectory + founder scorecard.** Author typed metric assertions in the `## Facts` fence (`mrr=50000`, `arr=2000000`, `team_size=12`) and gbrain stores them as first-class typed columns. `gbrain eval trajectory companies\u002Facme-example` prints the chronological history with regressions auto-flagged inline. `gbrain founder scorecard companies\u002Facme-example` rolls up claim accuracy, consistency, growth direction, and red flags into a stable `schema_version: 1` JSON contract. New MCP op `find_trajectory` exposes the same data to agents (read scope, visibility-filtered for remote callers). The `consolidate` cycle phase now writes `valid_until` on chronologically-superseded facts AND uses semantic upsert on `(page_id, claim, since_date)` — re-running the dream cycle on stable input is now a true no-op (fixed a pre-existing duplicate-takes bug from prior versions).\n\n> **~30 minutes to a fully working brain.** Database ready in 2 seconds (PGLite, no server). You just answer questions about API keys.\n\n> **LLMs:** fetch [`llms.txt`](llms.txt) for the documentation map, or [`llms-full.txt`](llms-full.txt) for the same map with core docs inlined in one fetch. **Agents:** start with [`AGENTS.md`](AGENTS.md) (or [`CLAUDE.md`](CLAUDE.md) if you're Claude Code).\n\n> **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\u002Fintegrations\u002Fembedding-providers.md`](docs\u002Fintegrations\u002Fembedding-providers.md) for setup, pricing, and a decision tree. `gbrain doctor` will surface alternative providers whose env vars you already have set.\n\n> **New in v0.32.3.0 — compress your AGENTS.md without losing accuracy:** if your downstream agent fork has grown a 25KB+ `AGENTS.md` \u002F `RESOLVER.md`, the new [`functional-area-resolver`](skills\u002Ffunctional-area-resolver\u002FSKILL.md) 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\u002FB eval harness, cross-model receipts, and reproduction instructions live at [`evals\u002Ffunctional-area-resolver\u002F`](evals\u002Ffunctional-area-resolver\u002F). The static-prompt analog of AnyTool \u002F RAG-MCP \u002F Anthropic Agent Skills progressive disclosure — single-LLM-pass dispatch, no second routing call.\n\n## Install\n\n### On an agent platform (recommended)\n\nGBrain is designed to be installed and operated by an AI agent. If you don't have one running yet:\n\n- **[OpenClaw](https:\u002F\u002Fopenclaw.ai)** ... Deploy [AlphaClaw on Render](https:\u002F\u002Frender.com\u002Fdeploy?repo=https:\u002F\u002Fgithub.com\u002Fchrysb\u002Falphaclaw) (one click, 8GB+ RAM)\n- **[Hermes Agent](https:\u002F\u002Fgithub.com\u002FNousResearch\u002Fhermes-agent)** ... Deploy on [Railway](https:\u002F\u002Fgithub.com\u002Fpraveen-ks-2001\u002Fhermes-agent-template) (one click)\n\nPaste this into your agent:\n\n```\nRetrieve and follow the instructions at:\nhttps:\u002F\u002Fraw.githubusercontent.com\u002Fgarrytan\u002Fgbrain\u002Fmaster\u002FINSTALL_FOR_AGENTS.md\n```\n\nThat'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.\n\nIf your agent doesn't auto-read `AGENTS.md`, point it at that file first:\n`https:\u002F\u002Fraw.githubusercontent.com\u002Fgarrytan\u002Fgbrain\u002Fmaster\u002FAGENTS.md` is the non-Claude\nagent operating protocol (install, read order, trust boundary, common tasks). For\nthe full doc map, use `llms.txt` at the same URL root.\n\n### Standalone CLI (no agent)\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain.git && cd gbrain && bun install && bun link\ngbrain init                     # local brain, ready in 2 seconds\n                                # picks a search mode (conservative \u002F balanced \u002F tokenmax)\ngbrain import ~\u002Fnotes\u002F          # index your markdown\ngbrain query \"what themes show up across my notes?\"\ngbrain search modes             # see the active search mode + per-knob attribution\ngbrain search stats             # cache hit rate + intent mix after some real usage\n```\n\n**v0.32.3 — named search modes.** `gbrain init` asks once which mode fits\nyour workload. The cost spread depends on BOTH the mode AND your downstream\nmodel — 25x corner-to-corner. Per-query cost @ 10K queries\u002Fmonth (typical\nsingle-user volume; multiply by 10 for heavy \u002F multi-user fleets):\n\n| Mode \\ Downstream | Haiku 4.5 (\\$1\u002FM) | Sonnet 4.6 (\\$3\u002FM) | Opus 4.7 (\\$5\u002FM) |\n|---|---|---|---|\n| `conservative` (~4K) | **\\$40\u002Fmo** | \\$120\u002Fmo | \\$200\u002Fmo |\n| `balanced` (~10K) | \\$100\u002Fmo | \\$300\u002Fmo | \\$500\u002Fmo |\n| `tokenmax` (~20K) | \\$200\u002Fmo | \\$600\u002Fmo | **\\$1,000\u002Fmo** |\n\nNatural pairings (corner-diagonal) span ~4x at realistic single-user\nvolume. Auto-suggests based on your configured `models.tier.subagent`.\nNon-TTY installs auto-pick `balanced` and print a hint pointing at\n`gbrain config set search.mode \u003Cm>`. After some real usage, run\n`gbrain search stats` for observability and `gbrain search tune` for\ndata-driven recommendations. Methodology + eval results live at\n[docs\u002Feval\u002FSEARCH_MODE_METHODOLOGY.md](docs\u002Feval\u002FSEARCH_MODE_METHODOLOGY.md).\n\n**Do NOT use `bun install -g github:garrytan\u002Fgbrain`.** Bun blocks the top-level\npostinstall hook on global installs, so schema migrations never run and the CLI\naborts with `Aborted()` the first time it opens PGLite. Use `git clone + bun install\n&& bun link` as shown above. See [#218](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fissues\u002F218).\n\n**Do NOT use `bun add -g gbrain` or `npm install -g gbrain`.** The npm registry\nhas an unrelated package squatting that name (`gbrain@1.3.x`) — you'd silently\ninstall the wrong binary and overwrite the canonical one. v0.28.5+ detects this\nand prints a recovery message on `gbrain upgrade`, but the `git clone + bun link`\npath above is the only reliable install method until we publish under\n`@garrytan\u002Fgbrain` (tracked v0.29 follow-up). See\n[#658](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fissues\u002F658).\n\n```\n3 results (hybrid search, 0.12s):\n\n1. concepts\u002Fdo-things-that-dont-scale (score: 0.94)\n   PG's argument that unscalable effort teaches you what users want.\n   [Source: paulgraham.com, 2013-07-01]\n\n2. originals\u002Ffounder-mode-observation (score: 0.87)\n   Deep involvement isn't micromanagement if it expands the team's thinking.\n\n3. concepts\u002Fbuild-something-people-want (score: 0.81)\n   The YC motto. Connected to 12 other brain pages.\n```\n\n### MCP server (Claude Code, Cursor, Windsurf)\n\nGBrain exposes 30+ MCP tools via stdio:\n\n```json\n{\n  \"mcpServers\": {\n    \"gbrain\": { \"command\": \"gbrain\", \"args\": [\"serve\"] }\n  }\n}\n```\n\nAdd to `~\u002F.claude\u002Fserver.json` (Claude Code), Settings > MCP Servers (Cursor), or your client's MCP config.\n\n### Remote MCP with OAuth 2.1 (ChatGPT, Claude Desktop, Cowork, Perplexity)\n\n`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.\n\n```bash\n# Start the HTTP server (prints admin bootstrap token on first start)\ngbrain serve --http --port 3131\n\n# Open the admin dashboard, paste the bootstrap token, register a client\nopen http:\u002F\u002Flocalhost:3131\u002Fadmin\n\n# Expose publicly (set --public-url so the OAuth issuer matches)\nngrok http 3131 --url your-brain.ngrok.app\ngbrain serve --http --port 3131 --public-url https:\u002F\u002Fyour-brain.ngrok.app\n\n# ChatGPT and other OAuth-aware clients can also connect:\nclaude mcp add gbrain -t http https:\u002F\u002Fyour-brain.ngrok.app\u002Fmcp -H \"Authorization: Bearer TOKEN\"\n```\n\nRegister OAuth clients from the `\u002Fadmin` dashboard — click **Register client**,\npick scopes, save the credentials shown once in the reveal modal. Programmatic\nregistration via `oauthProvider.registerClientManual(...)` and the\n`gbrain auth register-client` CLI are also available.\n\n- **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:\u002F\u002F` or loopback per RFC 6749 §3.1.2.1).\n- **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.\n- **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.\n- **Scoped operations** — 30 operations tagged `read | write | admin`. `sync_brain` and `file_upload` are `localOnly`, rejected over HTTP.\n- **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.\n- **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\u002Fmcp\u002Fhttp-transport.ts` path stays compiled in for backward compat callers; v0.26+ deployments use the OAuth-aware `serve-http.ts`.\n\nPer-client guides: [`docs\u002Fmcp\u002F`](docs\u002Fmcp\u002FDEPLOY.md). Hardening defaults, env vars, and threat model: [SECURITY.md](SECURITY.md).\n\n### Using gbrain with GStack\n\nIf your engineering agent runs on [GStack](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgstack), point it at gbrain for code lookup instead of grep+read. Cathedral II (v0.21.0) ships call-graph edges and two-pass retrieval — `\u002Finvestigate`, `\u002Freview`, `\u002Fplan-eng-review`, and `\u002Foffice-hours` all benefit when the agent walks the symbol graph instead of scanning files line by line.\n\nThe five magical-moment commands:\n\n```bash\ngbrain code-callers searchKeyword           # who calls this symbol?\ngbrain code-callees searchKeyword           # what does this symbol call?\ngbrain code-def BrainEngine                 # where is X defined?\ngbrain code-refs BrainEngine                # all reference sites\ngbrain query \"how does N+1 handling work\" --near-symbol BrainEngine.searchKeyword --walk-depth 2\n```\n\nAll 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 \u003Crepo> --strategy code` to index a repo, then your agent's brain-first lookup covers code, not just markdown. ([Cathedral II release notes](CHANGELOG.md#0210---2026-04-25))\n\n## The 34 Skills\n\nGBrain ships 34 skills organized by `skills\u002FRESOLVER.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.\n\n[Skill files are code.](https:\u002F\u002Fx.com\u002Fgarrytan\u002Fstatus\u002F2042925773300908103) 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](docs\u002Fethos\u002FTHIN_HARNESS_FAT_SKILLS.md): the intelligence lives in the skills, not the runtime.\n\n### Always-on\n\n| Skill | What it does |\n|-------|-------------|\n| **signal-detector** | Fires on every message. Spawns a cheap model in parallel to capture original thinking and entity mentions. The brain compounds on autopilot. |\n| **brain-ops** | Brain-first lookup before any external API. The read-enrich-write loop that makes every response smarter. |\n\n### Content ingestion\n\n| Skill | What it does |\n|-------|-------------|\n| **ingest** | Thin router. Detects input type and delegates to the right ingestion skill. |\n| **idea-ingest** | Links, articles, tweets become brain pages with analysis, author people pages, and cross-linking. |\n| **media-ingest** | Video, audio, PDF, books, screenshots, GitHub repos. Transcripts, entity extraction, backlink propagation. |\n| **meeting-ingestion** | Transcripts become brain pages. Every attendee gets enriched. Every company gets a timeline entry. |\n| **voice-note-ingest** | Voice notes captured verbatim — exact phrasing preserved, never paraphrased. Routes to originals\u002Fconcepts\u002Fpeople\u002Fcompanies\u002Fideas\u002Fpersonal\u002Fvoice-notes based on content. |\n| **article-enrichment** | Raw article dumps become structured pages with executive summary, verbatim quotes, key insights, and why-it-matters. |\n\n### Research and synthesis (v0.25.1)\n\n| Skill | What it does |\n|-------|-------------|\n| **book-mirror** | Flagship. Hand the agent a book, get a personalized two-column chapter-by-chapter analysis. Left column preserves the chapter's actual content; right column maps every idea to your life using your words from the brain. ~$6 for a 20-chapter book at Opus. Pairs with `gbrain book-mirror` CLI for the trusted runtime. |\n| **strategic-reading** | Read a book \u002F article \u002F case study through ONE specific problem-lens. Output: applied playbook with do \u002F avoid \u002F watch-for and short \u002F medium \u002F long-term recommendations. |\n| **concept-synthesis** | Deduplicate thousands of concept stubs into a tiered intellectual map (T1 Canon to T4 Riff). Trace how ideas evolved across years of notes. |\n| **perplexity-research** | Brain-augmented web research. Sends brain context to Perplexity so the search focuses on what's NEW vs already-known. Output: Executive Summary + Key New Developments + Confirming Signals + Contradictions or Updates + Recommended Brain Updates + Citations. |\n| **archive-crawler** | Universal archivist for personal file archives (Dropbox \u002F Backblaze \u002F Gmail-takeout \u002F hard-drive dumps). REFUSES to run unless `archive-crawler.scan_paths:` is set in `gbrain.yml`. Safe-by-default safety fence. |\n| **academic-verify** | Trace a research claim through publication → methodology → raw data → independent replication. Routes through perplexity-research; produces a verdict (verified \u002F partial \u002F unverifiable \u002F misattributed \u002F retracted). |\n| **brain-pdf** | Render any brain page to publication-quality PDF via the gstack `make-pdf` binary. Strips frontmatter, sanitizes emoji, applies running headers. |\n\n### Brain operations\n\n| Skill | What it does |\n|-------|-------------|\n| **enrich** | Tiered enrichment (Tier 1\u002F2\u002F3). Creates and updates person\u002Fcompany pages with compiled truth and timelines. |\n| **query** | 3-layer search with synthesis and citations. Says \"the brain doesn't have info on X\" instead of hallucinating. |\n| **maintain** | Periodic health: stale pages, orphans, dead links, citation audit, back-link enforcement, tag consistency. v0.23 adds the dream cycle's synthesize + patterns phases ... overnight conversation transcripts become reflections, originals, and 25-year patterns. |\n| **citation-fixer** | Scans pages for missing or malformed citations. Fixes format to match the standard. |\n| **repo-architecture** | Where new brain files go. Decision protocol: primary subject determines directory, not format. |\n| **publish** | Share brain pages as password-protected HTML. Zero LLM calls. |\n| **data-research** | Structured data research with parameterized YAML recipes. Extract investor updates, expenses, company metrics from email. |\n\n### Operational\n\n| Skill | What it does |\n|-------|-------------|\n| **daily-task-manager** | Task lifecycle with priority levels (P0-P3). Stored as searchable brain pages. |\n| **daily-task-prep** | Morning prep: calendar lookahead with brain context per attendee, open threads, task review. |\n| **cron-scheduler** | Schedule staggering (5-min offsets), quiet hours (timezone-aware with wake-up override), idempotency. |\n| **reports** | Timestamped reports with keyword routing. \"What's the latest briefing?\" finds it instantly. |\n| **cross-modal-review** | Quality gate via second model. Refusal routing: if one model refuses, silently switch. |\n| **webhook-transforms** | External events (SMS, meetings, social mentions) converted into brain pages with entity extraction. |\n| **testing** | Validates every skill has SKILL.md with frontmatter, manifest coverage, resolver coverage. |\n| **skill-creator** | Create new skills following the conformance standard. MECE check against existing skills. |\n| **skillify** | The \"skillify it!\" meta-skill. Orchestrates the 10-step loop so failures become durable skills: scaffold the stubs via `gbrain skillify scaffold`, write the real logic, gate with `gbrain skillify check` + `gbrain check-resolvable`. |\n| **skillpack-check** | Agent-readable gbrain health report. Exit code for CI; JSON for debugging. Cron-friendly. |\n| **smoke-test** | 8 post-restart health checks with auto-fix (Bun, CLI, DB, worker, Zod CJS, gateway, API key, brain repo). Drop-in user tests at `~\u002F.gbrain\u002Fsmoke-tests.d\u002F*.sh`. |\n| **minion-orchestrator** | Background work in one skill. Shell jobs via `gbrain jobs submit shell` (operator\u002FCLI, MCP blocks protected names) and LLM subagents via `gbrain agent run`. Parent-child DAGs, `child_done` inbox, durability across worker restarts. |\n\n### Identity and setup\n\n| Skill | What it does |\n|-------|-------------|\n| **soul-audit** | 6-phase interview generating SOUL.md (agent identity), USER.md (user profile), ACCESS_POLICY.md (4-tier privacy), HEARTBEAT.md (operational cadence). |\n| **setup** | Auto-provision PGLite or Supabase. First import. GStack detection. |\n| **migrate** | Universal migration from Obsidian, Notion, Logseq, markdown, CSV, JSON, Roam. |\n| **briefing** | Daily briefing with meeting context, active deals, and citation tracking. |\n\n### Conventions\n\nCross-cutting rules in `skills\u002Fconventions\u002F`:\n- **quality.md** ... citations, back-links, notability gate, source attribution\n- **brain-first.md** ... 5-step lookup before any external API call\n- **model-routing.md** ... which model for which task\n- **test-before-bulk.md** ... test 3-5 items before any batch operation\n- **cross-modal.yaml** ... review pairs and refusal routing chain\n\n## How It Works\n\n```\nSignal arrives (meeting, email, tweet, link)\n  -> Signal detector captures ideas + entities (parallel, never blocks)\n  -> Brain-ops: check the brain first (gbrain search, gbrain get)\n  -> Respond with full context\n  -> Write: update brain pages with new information + citations\n  -> Auto-link: typed relationships extracted on every write (zero LLM calls)\n  -> Sync: gbrain indexes changes for next query\n```\n\nEvery cycle adds knowledge. The agent enriches a person page after a meeting. Next time that person comes up, the agent already has context. The difference compounds daily.\n\nThe system gets smarter on its own. Entity enrichment auto-escalates: a person mentioned once gets a stub page (Tier 3). After 3 mentions across different sources, they get web + social enrichment (Tier 2). After a meeting or 8+ mentions, full pipeline (Tier 1). The brain learns who matters without being told. Deterministic classifiers improve over time via a fail-improve loop that logs every LLM fallback and generates better regex patterns from the failures. `gbrain doctor` shows the trajectory: \"intent classifier: 87% deterministic, up from 40% in week 1.\"\n\n> \"Prep me for my meeting with Jordan in 30 minutes\"\n> ... pulls dossier, shared history, recent activity, open threads\n\n> \"What have I said about the relationship between shame and founder performance?\"\n> ... searches YOUR thinking, not the internet\n\n## Minions: your sub-agents won't drop work anymore\n\nA durable, Postgres-native job queue built into the brain. Every long-running agent task is now a job that survives gateway restarts, streams progress, gets paused \u002F resumed \u002F steered mid-flight, and shows up in `gbrain jobs list`. Zero infra beyond your existing brain.\n\n### The production numbers that matter\n\nHere's my personal OpenClaw deployment: one Render container. Supabase Postgres holding a 45,000-page brain. 19 cron jobs firing on schedule. Real gateway load from real daily work. The task: pull a month of my social posts from an external API and ingest them end-to-end into the brain as a structured page.\n\n|              | Minions   | `sessions_spawn`               |\n|---           |---        |---                             |\n| Wall time    | **753ms** | **>10,000ms** (gateway timeout) |\n| Token cost   | **$0.00** | ~$0.03 per run                 |\n| Success rate | **100%**  | **0%** (couldn't even spawn)   |\n| Memory\u002Fjob   | ~2 MB     | ~80 MB                         |\n\nUnder that 19-cron load, sub-agent spawn couldn't clear the 10-second gateway wall. Minions landed it in under a second for zero tokens. **Scaling:** 19,240 posts across 36 months, single bash loop, ~15 min total, $0.00. Sub-agents: ~9 min best case, ~$1.08 in tokens, ~40% spawn failure. **Lab:** durability ∞ (SIGKILL mid-flight, 10\u002F10 rescued), throughput ~10× faster, fan-out ~21× with no failure wall, memory ~400× less.\n\nFull benchmarks live in [gbrain-evals](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain-evals\u002Ftree\u002Fmain\u002Fdocs\u002Fbenchmarks).\n\n### The routing rule\n\n> **Deterministic** (same input → same steps → same output) → **Minions**\n> **Judgment** (input requires assessment or decision) → **Sub-agents**\n\nPull posts, parse JSON, write a brain page, run a sync — deterministic. $0 tokens, survives restart, millisecond runtime. Triage the inbox, assess meeting priority, decide if a cold email deserves a reply — judgment. What sub-agents are actually good at. `minion_mode: pain_triggered` (the default) automates the routing.\n\n### What's fixed\n\nThe six daily pains — spawn storms, agents that stop responding, forgotten dispatches, gateway crashes mid-run, runaway grandchildren, debugging soup — all belonged to the \"deterministic work through a reasoning model\" mistake. Minions fixes them by not making that mistake: `max_children` cap, `timeout_ms` + AbortSignal, `child_done` inbox, full `parent_job_id`\u002F`depth`\u002Ftranscript per job, Postgres durability with stall detection, cascade cancel via recursive CTE. Plus idempotency keys, attachment validation, `removeOnComplete`, and `gbrain jobs smoke` that proves the install in half a second.\n\n```bash\ngbrain jobs smoke                        # verify install\ngbrain jobs submit sync --params '{}'    # fire a background job\ngbrain jobs stats                        # health dashboard\ngbrain jobs supervisor --concurrency 4   # canonical: auto-restarting worker (Postgres only)\ngbrain jobs work --concurrency 4         # raw worker (no crash recovery — prefer `supervisor`)\n```\n\n`gbrain jobs supervisor` keeps the worker alive across crashes with exponential backoff, atomic PID locking, structured audit events at `~\u002F.gbrain\u002Faudit\u002Fsupervisor-*.jsonl`, and a `start --detach` \u002F `status --json` \u002F `stop` subcommand surface for agents. In containers it runs as PID 1; on systemd hosts it's the child of `gbrain-worker.service`. Full deployment guide: [`docs\u002Fguides\u002Fminions-deployment.md`](docs\u002Fguides\u002Fminions-deployment.md).\n\nRead [`skills\u002Fminion-orchestrator\u002FSKILL.md`](skills\u002Fminion-orchestrator\u002FSKILL.md) for parent-child DAGs, fan-in collection, steering via inbox.\n\n**Minions is not incrementally better than sub-agents for background work. It's categorically different.** 753ms vs gateway timeout. $0 vs tokens. 100% vs couldn't-spawn. If your agent does deterministic work on a schedule, it runs on Minions now.\n\n### Health check and self-heal\n\nMinions is canonical as of v0.11.1 — every `gbrain upgrade` runs the migration automatically (schema → smoke → prefs → host rewrites → env-aware autopilot install). If you ever want to verify manually or wire a cron into your morning briefing:\n\n```bash\ngbrain doctor                    # half-migrated state? prints loud banner + exits non-zero\ngbrain skillpack-check --quiet    # exit 0\u002F1\u002F2 for pipeline gating\ngbrain skillpack-check | jq       # full JSON: {healthy, summary, actions[], doctor, migrations}\n```\n\nIf anything's off, `actions[]` tells you the exact command to run. For deeper troubleshooting: [`docs\u002Fguides\u002Fminions-fix.md`](docs\u002Fguides\u002Fminions-fix.md).\n\nMoving gateway crons to Minions (deterministic scripts, zero LLM tokens per fire): [`docs\u002Fguides\u002Fminions-shell-jobs.md`](docs\u002Fguides\u002Fminions-shell-jobs.md).\n\n## Durable agents: `gbrain agent` (v0.15)\n\nYour subagent runs survive crashes now. OpenClaw died mid-run? The worker re-claims on restart and replays from the last committed turn. Fan-out across 50 shards, one shard crashes — the aggregator still claims after every child reaches a terminal state and writes a mixed-outcome summary. Tool calls persist as a two-phase ledger (`pending` → `complete | failed`) so replay is safe by construction, not by hope.\n\n```bash\n# Submit a single-subagent run\ngbrain agent run \"summarize my last 10 journal pages\"\n\n# Fan out N prompts across N subagent children + 1 aggregator\ngbrain agent run \"analyze every page\" \\\n  --fanout-manifest manifests\u002Fpages.json \\\n  --subagent-def analyzer\n\n# Tail a running job (heartbeat per turn + full transcript on completion)\ngbrain agent logs 1247 --follow --since 5m\n```\n\nDurability is the point: every Anthropic turn commits to `subagent_messages`, every tool call to `subagent_tool_executions`. Worker kills, OpenClaw crashes, timeouts — all resumable. Host repos (your OpenClaw, etc.) ship their own subagent definitions via `GBRAIN_PLUGIN_PATH` + a `gbrain.plugin.json` manifest: see [`docs\u002Fguides\u002Fplugin-authors.md`](docs\u002Fguides\u002Fplugin-authors.md). Requires `ANTHROPIC_API_KEY` on the worker.\n\n## Skillify: say \"skillify it!\" and the bug becomes structurally impossible to repeat\n\nYour OpenClaw hit a new failure. You fix it once in conversation. You say \"skillify it!\"\nAnd now the fix is permanent: a SKILL.md with triggers, a deterministic script with tests, a\nrouting fixture the agent re-evaluates daily, a filing audit that keeps the output from\ndrifting. Ten items. Every one required. The bug can't recur.\n\nHermes and similar agent frameworks auto-create skills as a background behavior. Fine until\nyou don't know what the agent shipped. Checklists decay. Tests drift. Resolver entries get\nstale. Six months later it's an opaque pile nobody has read, nobody has tested, and nobody\nis sure still works. GBrain ships the same capability except the human stays in the loop\nand every step is a command you can run.\n\n### The four verbs you need (v0.19)\n\n```bash\n# 1. Scaffold all 5 stub files for a new skill in one shot.\ngbrain skillify scaffold webhook-verify \\\n  --description \"verify ngrok webhooks\" \\\n  --triggers \"verify the webhook,check tunnel\" \\\n  --writes-pages --writes-to people\u002F,companies\u002F\n\n# 2. Replace the SKILLIFY_STUB sentinels with real logic + real tests.\n$EDITOR skills\u002Fwebhook-verify\u002Fscripts\u002Fwebhook-verify.mjs\n$EDITOR test\u002Fwebhook-verify.test.ts\n\n# 3. Run the 10-item audit: SKILL.md exists, script exists, unit + E2E tests,\n#    LLM evals, resolver entry, trigger eval, check-resolvable gate, brain filing.\ngbrain skillify check skills\u002Fwebhook-verify\u002Fscripts\u002Fwebhook-verify.mjs\n\n# 4. Verify the whole tree: reachability, MECE overlap, DRY, routing gaps,\n#    filing audit, SKILLIFY_STUB sentinels (fails if any skill still has one).\ngbrain check-resolvable              # warnings advisory, errors block\ngbrain check-resolvable --strict     # warnings block too (CI opt-in)\n```\n\nIdempotent re-runs. `--force` regenerates stub files but NEVER duplicates a resolver row.\nScaffold completes in under 2 seconds. The real work (your rule, your script, your tests)\nis what you spend time on. Everything else is boilerplate the CLI writes for you.\n\n### `gbrain routing-eval` — catch the routing gaps your users actually hit\n\nDrop a `routing-eval.jsonl` fixture next to any skill. Each line is `{intent, expected_skill,\nambiguous_with?}`. `gbrain check-resolvable` runs the structural layer by default; `gbrain\nrouting-eval` runs the same structural layer as a dedicated CI verb. The `--llm` flag is\naccepted as a placeholder for a future LLM tie-break layer; in this release it emits a stderr\nnotice and runs structural only. False positives (wrong skill matched), missed routes (no\nskill matched), and tautological fixtures (intent copies trigger verbatim) all surface as\nspecific advisories with the exact file:line to fix.\n\n### Works on your OpenClaw, not just gbrain's repo\n\nv0.19 teaches `gbrain check-resolvable` to accept `AGENTS.md` as a resolver file alongside\n`RESOLVER.md`, at either the skills directory OR one level up (OpenClaw-native workspace-root\nlayout). The skill manifest auto-derives from walking `skills\u002F*\u002FSKILL.md` when `manifest.json`\nis missing. Set `OPENCLAW_WORKSPACE=~\u002Fyour-openclaw\u002Fworkspace` and everything just works:\n\n```bash\nexport OPENCLAW_WORKSPACE=~\u002Fyour-openclaw\u002Fworkspace\ngbrain check-resolvable --verbose\n# Auto-detects: AGENTS.md at workspace root, 107 skills derived from SKILL.md walk,\n# 15 unreachable errors surfaced, 108 advisory warnings for overlaps and gaps.\n```\n\nFirst run on a real OpenClaw deployment found 15 unreachable skills out of 102 — about 15%\nof the tree was dark. The essay's \"skills the agent can never reach\" footgun, now visible.\n\n### `gbrain skillpack install` — drop 25 curated skills into your OpenClaw\n\nThe skills gbrain ships are a curated bundle. Install them into your workspace with\ndependency closure (shared conventions come along), per-file diff protection (your local\nedits are never clobbered without `--overwrite-local`), a file lock that serializes\nconcurrent installers, and an atomic managed-block update to your AGENTS.md so you can\nsee exactly what gbrain wrote.\n\n```bash\ngbrain skillpack list                          # 25 curated skills\ngbrain skillpack install brain-ops             # one skill + its shared conventions\ngbrain skillpack install --all                 # the full bundle\ngbrain skillpack install brain-ops --dry-run   # preview; no writes\ngbrain skillpack diff brain-ops                # compare bundle vs your local copy\n```\n\nRe-running is safe. The managed-block markers in your AGENTS.md let `skillpack install`\naccumulate rows across separate single-skill installs instead of overwriting each other.\nA receipt comment inside the fence (`\u003C!-- gbrain:skillpack:manifest cumulative-slugs=\"...\" -->`)\ntracks what gbrain has installed across runs. `install --all` is the only path that prunes;\nper-skill install never deletes what it didn't install. If you hand-add a row inside the fence,\ngbrain preserves it on reinstall and emits a stderr notice telling your agent to investigate.\n\n**Skillify is the piece that makes the skills tree survive six months of compounding work.**\nRead [`skills\u002Fskillify\u002FSKILL.md`](skills\u002Fskillify\u002FSKILL.md) for the full 10-item checklist\nand the anti-patterns it catches.\n\n## Storage tiering: keep bulk content out of git (v0.22.11)\n\nWhen your brain crosses 100K files and bulk machine-generated content (tweets, articles, transcripts)\nbecomes the size driver, declare which directories belong in git and which live in the database only.\n\n```yaml\n# gbrain.yml at the brain repo root\nstorage:\n  db_tracked:\n    - people\u002F\n    - companies\u002F\n    - deals\u002F\n  db_only:\n    - media\u002Fx\u002F\n    - media\u002Farticles\u002F\n    - meetings\u002Ftranscripts\u002F\n```\n\n`gbrain sync` auto-manages your `.gitignore` for `db_only` paths. `gbrain export --restore-only --repo .`\nrepopulates missing files from the database (container restart, fresh clone, accidental rm).\n`gbrain storage status` shows the tier breakdown.\n\nFull guide: [docs\u002Fstorage-tiering.md](docs\u002Fstorage-tiering.md).\n\n## Getting Data In\n\nGBrain ships integration recipes that your agent sets up for you. Each recipe tells the agent what credentials to ask for, how to validate, and what cron to register.\n\n| Recipe | Requires | What It Does |\n|--------|----------|-------------|\n| [Public Tunnel](recipes\u002Fngrok-tunnel.md) | — | Fixed URL for MCP + voice (ngrok Hobby $8\u002Fmo) |\n| [Credential Gateway](recipes\u002Fcredential-gateway.md) | — | Gmail + Calendar access |\n| [Voice-to-Brain](recipes\u002Ftwilio-voice-brain.md) | ngrok-tunnel | Phone calls to brain pages (Twilio + OpenAI Realtime) |\n| [Email-to-Brain](recipes\u002Femail-to-brain.md) | credential-gateway | Gmail to entity pages |\n| [X-to-Brain](recipes\u002Fx-to-brain.md) | — | Twitter timeline + mentions + deletions |\n| [Calendar-to-Brain](recipes\u002Fcalendar-to-brain.md) | credential-gateway | Google Calendar to searchable daily pages |\n| [Meeting Sync](recipes\u002Fmeeting-sync.md) | — | Circleback transcripts to brain pages with attendees |\n| [Restart Sweep](recipes\u002Frestart-sweep.md) | OpenClaw + Telegram | Detect dropped Telegram messages after OpenClaw gateway restarts |\n\n**Data research recipes** extract structured data from email into tracked brain pages. Built-in recipes for investor updates (MRR, ARR, runway, headcount), expense tracking, and company metrics. Create your own with `gbrain research init`.\n\nRun `gbrain integrations` to see status.\n\n## GBrain + GStack\n\n[GStack](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgstack) is the engine. GBrain is the mod.\n\n- **[GStack](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgstack)** = coding skills (ship, review, QA, investigate, office-hours, retro). 70,000+ stars, 30,000 developers per day. When your agent codes on itself, it uses GStack.\n- **GBrain** = everything-else skills (brain ops, signal detection, ingestion, enrichment, cron, reports, identity). When your agent remembers, thinks, and operates, it uses GBrain.\n- **`hosts\u002Fgbrain.ts`** = the bridge. Tells GStack's coding skills to check the brain before coding.\n\n`gbrain init` detects if GStack is installed and reports mod status. If GStack isn't there, it tells you how to get it.\n\n## Architecture\n\n```\n┌──────────────────┐    ┌───────────────┐    ┌──────────────────┐\n│   Brain Repo     │    │    GBrain     │    │    AI Agent      │\n│   (git)          │    │  (retrieval)  │    │  (read\u002Fwrite)    │\n│                  │    │               │    │                  │\n│  markdown files  │───>│  Postgres +   │\u003C──>│  29 skills       │\n│  = source of     │    │  pgvector     │    │  define HOW to   │\n│    truth         │    │               │    │  use the brain   │\n│                  │\u003C───│  hybrid       │    │                  │\n│  human can       │    │  search       │    │  RESOLVER.md     │\n│  always read     │    │  (vector +    │    │  routes intent   │\n│  & edit          │    │   keyword +   │    │  to skill        │\n│                  │    │   RRF)        │    │                  │\n└──────────────────┘    └───────────────┘    └──────────────────┘\n```\n\nThe repo is the system of record. GBrain is the retrieval layer. The agent reads and writes through both. Human always wins... edit any markdown file and `gbrain sync` picks up the changes.\n\nFor multi-machine setups (cross-machine thin client) and multi-worktree setups (per-worktree code engine + shared remote artifacts), see [`docs\u002Farchitecture\u002Ftopologies.md`](docs\u002Farchitecture\u002Ftopologies.md).\n\n## The Knowledge Model\n\nEvery page follows the compiled truth + timeline pattern:\n\n```markdown\n---\ntype: concept\ntitle: Do Things That Don't Scale\ntags: [startups, growth, pg-essay]\n---\n\nPaul Graham's argument that startups should do unscalable things early on.\nThe key insight: the unscalable effort teaches you what users actually\nwant, which you can't learn any other way.\n\n---\n\n- 2013-07-01: Published on paulgraham.com\n- 2024-11-15: Referenced in batch W25 kickoff talk\n```\n\nAbove the `---`: **compiled truth**. Your current best understanding. Gets rewritten when new evidence changes the picture. Below: **timeline**. Append-only evidence trail. Never edited, only added to.\n\n## Knowledge Graph\n\nPages aren't just text. Every mention of a person, company, or concept becomes a typed link in a structured graph. The brain wires itself.\n\n```\nWrite a meeting page mentioning Alice and Acme AI\n  -> Auto-link extracts entity refs from content (zero LLM calls)\n  -> Infers types: meeting page + person ref => `attended`\n                   \"CEO of X\" pattern        => `works_at`\n                   \"invested in\"             => `invested_in`\n                   \"advises\", \"advisor\"      => `advises`\n                   \"founded\", \"co-founded\"   => `founded`\n  -> Reconciles stale links: edits remove links no longer in content\n  -> Backlinks rank well-connected entities higher in search\n```\n\n```bash\ngbrain graph-query people\u002Falice --type attended --depth 2\n# returns who Alice met with, transitively\n```\n\nThe graph powers questions vector search can't: \"who works at Acme AI?\", \"what has Bob invested in?\", \"find the connection between Alice and Carol\". Backfill an existing brain in one command:\n\n```bash\ngbrain extract links --source db        # wire up the existing 29K pages\ngbrain extract timeline --source db     # extract dated events from markdown timelines\n```\n\nThen ask graph questions or watch the search ranking improve. Benchmarked side-by-side against ripgrep-BM25, vector-only RAG (same embedder), and gbrain-with-graph-disabled: gbrain lands **P@5 49.1%, R@5 97.9%** on a 240-page Opus-generated rich-prose corpus, beating hybrid-nograph by **+31.4 points P@5**. Isolate the contribution: v0.11→v0.12 moved the same gbrain codebase from P@5 22.1% → 49.1% on identical inputs, so typed-link extract quality is load-bearing. Full scorecards + reproducible corpus: [gbrain-evals](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain-evals).\n\n## Search\n\nHybrid search: vector + keyword + RRF fusion + multi-query expansion + 4-layer dedup.\n\n```\nQuery\n  -> Intent classifier (entity? temporal? event? general?)\n  -> Multi-query expansion (Claude Haiku)\n  -> Vector search (HNSW cosine) + Keyword search (tsvector)\n  -> RRF fusion: score = sum(1\u002F(60 + rank))\n  -> Cosine re-scoring + compiled truth boost\n  -> 4-layer dedup + compiled truth guarantee\n  -> Results\n```\n\nKeyword alone misses conceptual matches. Vector alone misses exact phrases. RRF gets both. Search quality is benchmarked and reproducible: `gbrain eval --qrels queries.json` measures P@k, Recall@k, MRR, and nDCG@k. A\u002FB test config changes before deploying them.\n\n## Why it works: many strategies in concert\n\nThe brain isn't one trick. Every retrieval question goes through ~20 deterministic\ntechniques layered together. No single one is magic; the win comes from stacking\nthem so each layer covers what the others miss.\n\n```\nQuestion\n  │\n  ├─ INGESTION (every put_page)\n  │    ├─ Recursive markdown chunking (or semantic \u002F LLM-guided)\n  │    ├─ Embedding cache invalidation on edit\n  │    └─ Idempotent imports (content-hash dedup)\n  │\n  ├─ GRAPH EXTRACTION (auto-link post-hook, zero LLM)\n  │    ├─ Entity-ref regex (markdown links + bare slugs)\n  │    ├─ Code-fence stripping (no false-positive slugs in code blocks)\n  │    ├─ Typed inference cascade (FOUNDED → INVESTED → ADVISES → WORKS_AT)\n  │    ├─ Page-role priors (partner-bio language → invested_in)\n  │    ├─ Within-page dedup (same target collapses to one link)\n  │    ├─ Stale-link reconciliation (edits remove dropped refs)\n  │    └─ Multi-type link constraint (same person can works_at AND advises)\n  │\n  ├─ SEARCH PIPELINE (every query)\n  │    ├─ Intent classifier (entity \u002F temporal \u002F event \u002F general — auto-routes)\n  │    ├─ Multi-query expansion (Haiku rephrases the question 3 ways)\n  │    ├─ Vector search (HNSW cosine over OpenAI embeddings)\n  │    ├─ Keyword search (Postgres tsvector + websearch_to_tsquery)\n  │    ├─ Source-aware ranking (curated dirs outrank chat\u002Fdaily swamp at SQL layer)\n  │    ├─ Hard-exclude (test\u002F archive\u002F attachments\u002F .raw\u002F filtered before retrieval)\n  │    ├─ Reciprocal Rank Fusion (score = sum 1\u002F(60+rank) across both)\n  │    ├─ Cosine re-scoring (re-rank chunks against actual query embedding)\n  │    ├─ Compiled-truth boost (assessments outrank timeline noise)\n  │    ├─ Backlink boost (well-connected entities rank higher)\n  │    └─ Source-aware dedup (one CT chunk per page guaranteed)\n  │\n  ├─ GRAPH TRAVERSAL (relational queries)\n  │    ├─ Recursive CTE with cycle prevention (visited-array check)\n  │    ├─ Type-filtered edges (--type works_at, attended, etc.)\n  │    ├─ Direction control (in \u002F out \u002F both)\n  │    └─ Depth-capped (≤10 for remote MCP; DoS prevention)\n  │\n  └─ AGENT WORKFLOW (graph-confident hybrid)\n       ├─ Graph-query first (high-precision typed answers)\n       ├─ Grep fallback when graph returns nothing\n       └─ Graph hits ranked first in top-K (better P@K and R@K)\n```\n\nEnd-to-end on the BrainBench v1 corpus (240 rich-prose pages, before\u002Fafter PR #188):\n\n| Metric                  | BEFORE PR #188 | AFTER PR #188 | Δ           |\n|-------------------------|----------------|---------------|-------------|\n| **Precision@5**         | 39.2%          | **44.7%**     | **+5.4 pts**|\n| **Recall@5**            | 83.1%          | **94.6%**     | **+11.5 pts**|\n| Correct in top-5        | 217            | 247           | **+30**     |\n| Graph-only F1 (ablation)| 57.8% (grep)   | **86.6%**     | **+28.8 pts**|\n\nPlus 5 orthogonal capability checks (identity resolution, temporal queries,\nperformance at 10K-page scale, robustness to malformed input, MCP operation\ncontract). All pass. Full report: [gbrain-evals](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain-evals).\n\nThe point: each technique handles a class of inputs the others miss. Vector\nsearch misses exact slug refs; keyword catches them. Keyword misses conceptual\nmatches; vector catches them. RRF picks the best of both. Compiled-truth boost\nkeeps assessments above timeline noise. Auto-link extraction wires the graph\nthat lets backlink boost rank well-connected entities higher. Graph traversal\nanswers questions search alone can't reach. The agent picks graph-first for\nprecision and falls back to keyword for recall. **All deterministic, all in\nconcert, all measured.**\n\n## Voice\n\nCall a phone number. Your AI answers. It knows who's calling, pulls their full context from the brain, and responds like someone who actually knows your world. When the call ends, a brain page appears with the transcript, entity detection, and cross-references.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002Fimages\u002Fvoice-client.png\" alt=\"Voice client connected\" width=\"300\" \u002F>\n\u003C\u002Fp>\n\n> [See it in action](https:\u002F\u002Fx.com\u002Fgarrytan\u002Fstatus\u002F2043022208512172263)\n\nThe voice recipe ships with GBrain: [Voice-to-Brain](recipes\u002Ftwilio-voice-brain.md). WebRTC works in a browser tab with zero setup. A real phone number is optional.\n\n## Engine Architecture\n\n```\nCLI \u002F MCP Server\n     (thin wrappers, identical operations)\n              |\n      BrainEngine interface (pluggable)\n              |\n     +--------+--------+\n     |                  |\nPGLiteEngine       PostgresEngine\n  (default)          (Supabase)\n     |                  |\n~\u002F.gbrain\u002F           Supabase Pro ($25\u002Fmo)\nbrain.pglite         Postgres + pgvector\nembedded PG 17.5\n\n     gbrain migrate --to supabase|pglite\n         (bidirectional migration)\n```\n\nPGLite: embedded Postgres, no server, zero config. When your brain outgrows local (1000+ files, multi-device), `gbrain migrate --to supabase` moves everything.\n\n## File Storage\n\nBrain repos accumulate binaries. GBrain has a three-stage migration:\n\n```bash\ngbrain files mirror \u003Cdir>       # copy to cloud, local untouched\ngbrain files redirect \u003Cdir>     # replace local with .redirect pointers\ngbrain files clean \u003Cdir>        # remove pointers, cloud only\ngbrain files restore \u003Cdir>      # download everything back (undo)\n```\n\nStorage backends: S3-compatible (AWS, R2, MinIO), Supabase Storage, or local.\n\n## Commands\n\n```\nSETUP\n  gbrain init [--supabase|--url]        Create brain (PGLite default)\n  gbrain migrate --to supabase|pglite   Bidirectional engine migration\n  gbrain upgrade                        Self-update with feature discovery\n\nPAGES\n  gbrain get \u003Cslug>                     Read a page (fuzzy slug matching)\n  gbrain put \u003Cslug> [\u003C file.md]         Write\u002Fupdate (auto-versions)\n  gbrain delete \u003Cslug>                  Delete a page\n  gbrain list [--type T] [--tag T]      List with filters\n\nSEARCH\n  gbrain search \u003Cquery>                 Keyword search (tsvector)\n  gbrain query \u003Cquestion>              Hybrid search (vector + keyword + RRF)\n\nIMPORT\n  gbrain import \u003Cdir> [--no-embed] [--workers N]\n                                        Import markdown (idempotent)\n  gbrain sync [--repo \u003Cpath>] [--workers N]\n                                        Git-to-brain incremental sync\n                                        (>100-file diffs auto-parallelize 4 workers on Postgres)\n  gbrain export [--dir .\u002Fout\u002F]          Export to markdown\n\nFILES\n  gbrain files list|upload|sync|verify  File storage operations\n\nEMBEDDINGS\n  gbrain embed [\u003Cslug>|--all|--stale]   Generate\u002Frefresh embeddings\n\nLINKS + GRAPH\n  gbrain link|unlink|backlinks          Cross-reference management\n  gbrain extract links|timeline|all     Batch backfill from existing pages\n                                        (--source db|fs, --type, --since, --dry-run)\n  gbrain graph-query \u003Cslug>             Typed traversal (--type T --depth N\n                                        --direction in|out|both)\n\nJOBS (Minions)\n  gbrain jobs submit \u003Cname> [--params JSON] [--follow]  Submit a background job\n  gbrain jobs list [--status S] [--queue Q]             List jobs with filters\n  gbrain jobs get|cancel|retry|delete \u003Cid>              Manage job lifecycle\n  gbrain jobs prune [--older-than 30d]                  Clean completed\u002Fdead jobs\n  gbrain jobs stats                                     Job health dashboard\n  gbrain jobs smoke                                     One-command health check\n  gbrain jobs work [--queue Q] [--concurrency N]        Start worker daemon\n\nSKILLS (v0.19)\n  gbrain skillify scaffold \u003Cname>       Create 5 stub files + idempotent resolver row\n  gbrain skillify check [path]          10-item audit of a skill\n  gbrain skillpack list                 Print the 25 curated skills in the bundle\n  gbrain skillpack install \u003Cname>       Copy one skill + its shared conventions into target\n  gbrain skillpack install --all        Install the full curated bundle\n  gbrain skillpack diff \u003Cname>          Per-file diff: bundle vs target workspace\n  gbrain check-resolvable [--strict]    Resolver audit (reachability, MECE, DRY, routing, filing,\n                                        SKILLIFY_STUB). Accepts RESOLVER.md OR AGENTS.md.\n  gbrain routing-eval [--llm] [--json]  Intent→skill routing accuracy on fixtures\n\nEVAL\n  gbrain eval --qrels \u003Cpath>            Legacy IR-eval (P@k, R@k, MRR, nDCG@k against ground truth)\n  gbrain eval export [--since DUR]      Stream captured eval_candidates as NDJSON (BrainBench-Real)\n  gbrain eval prune --older-than DUR    Retention cleanup for eval_candidates (requires window)\n  gbrain eval replay --against FILE     Replay captured queries vs current build (Jaccard@k, top-1, latency Δ)\n  gbrain eval longmemeval \u003Cdataset>     Run public LongMemEval against gbrain hybrid retrieval (v0.28.8)\n                                        [--limit N] [--retrieval-only] [--keyword-only] [--expansion]\n                                        [--top-k K] [--model M] [--output FILE]\n  gbrain eval suspected-contradictions  Cached contradiction probe (v0.32.6, 6-verdict enum v0.35.3.1)\n                                        [run|trend|review] [--severity S] [--budget-usd N]\n  gbrain eval trajectory \u003Centity>       Chronological typed-claim trajectory + regressions (v0.35.7)\n                                        [--metric M] [--since YYYY-MM-DD] [--until YYYY-MM-DD]\n                                        [--limit N] [--json]\n\nTEMPORAL (v0.35.7)\n  gbrain founder scorecard \u003Centity>     Roll up an entity's typed claims + resolved-take outcomes into\n                                        four signals: claim_accuracy \u002F consistency \u002F growth_trajectory \u002F\n                                        red_flags. Stable JSON contract (schema_version: 1).\n                                        [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--json]\n                                        Backed by the find_trajectory MCP op (read scope, federated\n                                        source-scoped, visibility-filtered for remote callers).\n                                        Override regression threshold:\n                                          export GBRAIN_TRAJECTORY_REGRESSION_THRESHOLD=0.05\n\nADMIN\n  gbrain doctor [--json] [--fast]       Health checks (resolver, skills, DB, embeddings)\n  gbrain doctor --fix [--dry-run]       Auto-fix DRY violations (delegate inlined rules to conventions)\n  gbrain doctor --locks                 List idle-in-tx backends (57014 diagnostic, Postgres only)\n  gbrain stats                          Brain statistics\n  gbrain models                         Show live model routing (tier defaults,\n                                        per-task overrides, alias map, source-of-truth).\n                                        v0.31.12: tier system + recipe-models merge.\n                                        Power-user override:\n                                          gbrain config set models.default opus\n                                          gbrain config set models.tier.deep opus\n  gbrain models doctor                  1-token reachability probe for each configured\n                                        chat\u002Fexpansion model + a zero-token embedding_config\n                                        probe (catches Voyage flexible-dim misconfigs before\n                                        first embed). Catches `model_not_found` before the\n                                        next agent run silently degrades.\n                                        [--skip=\u003Cprovider>] [--json]\n  gbrain serve                          MCP server (stdio)\n  gbrain serve --http [--port 3131]     HTTP MCP server with OAuth 2.1 + admin dashboard\n                                        [--bind HOST] (v0.34: default 127.0.0.1; pass\n                                        --bind 0.0.0.0 for LAN\u002Fremote access)\n                                        [--token-ttl 3600] [--enable-dcr]\n                                        [--public-url URL] [--log-full-params]\n  gbrain auth create|list|revoke|test   Legacy bearer token management\n  gbrain auth register-client \u003Cname>    Register an OAuth 2.1 client\n        --grant-types client_credentials,authorization_code\n        --scopes \"read write admin\"\n        --source \u003Cid>                   v0.34: write authority for source-scoped clients\n        --federated-read \u003CS1,S2,...>    v0.34: read scope across multiple sources\n  gbrain auth revoke-client \u003Cclient_id> Revoke an OAuth 2.1 client (cascade purges\n                                        active tokens + auth codes via FK CASCADE)\n  # OAuth 2.1 clients can also be registered from the \u002Fadmin dashboard or\n  # programmatically via oauthProvider.registerClientManual() for host-repo wrappers.\n  gbrain integrations                   Integration recipe dashboard\n  gbrain sources list|add|remove|...    Multi-source brain management (v0.18)\n                                        v0.28.2: --url \u003Chttps:\u002F\u002F...> registers a federated\n                                        remote git repo; clone is auto-managed under\n                                        $GBRAIN_HOME\u002Fclones\u002F\u003Cid>\u002F and re-cloned on sync if\n                                        it goes missing. Also exposed via MCP for remote\n                                        agent setup (whoami + sources_{add,list,remove,status}).\n  gbrain dream [--dry-run] [--phase N]  11-phase maintenance cycle (lint→backlinks→sync→synthesize\n                                        →extract→patterns→recompute_emotional_weight→consolidate\n                                        →embed→orphans→purge). v0.23 added synthesize + patterns.\n                                        v0.29 added emotional-weight recompute. v0.30.2: synthesize\n                                        chunks fat transcripts. v0.31: consolidate promotes hot facts\n                                        into takes overnight.\n  gbrain dream --input \u003Cfile>           Ad-hoc transcript synthesis (implies --phase synthesize)\n  gbrain dream --date YYYY-MM-DD        Synthesize a single day; --from\u002F--to for backfill ranges\n\n  # v0.31 Hot Memory: cross-session facts queryable in real time.\n  gbrain recall \u003Centity>                List active facts for an entity (newest first)\n  gbrain recall --since \"1h ago\"        Recency-filtered recall\n  gbrain recall --session \u003Cid>          Facts captured in a session id\n  gbrain recall --today                 Markdown render with kind icons (📅🎯🤝💭📌)\n  gbrain recall --supersessions         Audit log of auto-overwritten facts\n  gbrain recall --grep \u003Ctext>           Substring filter (case-insensitive)\n  gbrain recall --as-context            Prompt-injection-ready markdown for headless agents\n  gbrain recall --json                  Structured output with effective_confidence per row\n  gbrain forget \u003Cfact-id>               Expire a fact (soft delete; never hard-DELETE)\n\n  gbrain check-backlinks check|fix      Back-link enforcement\n  gbrain lint [--fix]                   LLM artifact detection\n  gbrain repair-jsonb [--dry-run]       Repair v0.12.0 double-encoded JSONB (Postgres)\n  gbrain orphans [--json] [--count]     Find pages with zero inbound wikilinks\n  gbrain transcribe \u003Caudio>             Transcribe audio (Groq Whisper)\n  gbrain research init \u003Cname>           Scaffold a data-research recipe\n  gbrain research list                  Show available recipes\n```\n\nRun `gbrain --help` for the full reference.\n\n## Origin Story\n\nI was setting up my [OpenClaw](https:\u002F\u002Fopenclaw.ai) agent and started a markdown brain repo. One page per person, one page per company, compiled truth on top, timeline on the bottom. Within a week: 10,000+ files, 3,000+ people, 13 years of calendar data, 280+ meeting transcripts, 300+ captured ideas.\n\nThe agent runs while I sleep. The dream cycle scans every conversation, enriches missing entities, fixes broken citations, consolidates memory. I wake up and the brain is smarter than when I went to sleep.\n\nThe skills in this repo are those patterns, generalized. What took 11 days to build by hand ships as a mod you install in 30 minutes.\n\n## Docs\n\n**For agents:**\n- **[skills\u002FRESOLVER.md](skills\u002FRESOLVER.md)** ... Start here. The skill dispatcher.\n- [Individual skill files](skills\u002F) ... 28 standalone instruction sets (25 ship in the curated `gbrain skillpack install` bundle)\n- [GBRAIN_SKILLPACK.md](docs\u002FGBRAIN_SKILLPACK.md) ... Legacy reference architecture\n- [Getting Data In](docs\u002Fintegrations\u002FREADME.md) ... Integration recipes and data flow\n- [GBRAIN_VERIFY.md](docs\u002FGBRAIN_VERIFY.md) ... Installation verification\n\n**For humans:**\n- [GBRAIN_RECOMMENDED_SCHEMA.md](docs\u002FGBRAIN_RECOMMENDED_SCHEMA.md) ... Brain repo directory structure\n- [Thin Harness, Fat Skills](docs\u002Fethos\u002FTHIN_HARNESS_FAT_SKILLS.md) ... Architecture philosophy\n- [ENGINES.md](docs\u002FENGINES.md) ... Pluggable engine interface\n\n**Reference:**\n- [GBRAIN_V0.md](docs\u002FGBRAIN_V0.md) ... Full product spec\n- [CHANGELOG.md](CHANGELOG.md) ... Version history\n\n**Benchmarks:**\n- [gbrain-evals](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain-evals) ... BrainBench, the sibling repo that holds the eval harness, corpus, scorecards, and 4-adapter comparisons. Depends on gbrain; not installed alongside gbrain.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Run `bun run test` for the parallel unit-test fast loop (~85s on a Mac dev box, 3700+ tests) or `bun run verify` for the pre-push gate (privacy + jsonb + progress + test-isolation + wasm + admin-build + typecheck). For the full local CI gate (gitleaks + unit + all 29 E2E files in Docker, the same checks GH Actions runs), use `bun run ci:local` ... or `bun run ci:local:diff` for the diff-aware subset during fast iteration.\n\nIf you're working on retrieval or any of the search\u002Fembedding\u002Franking surface, set `GBRAIN_CONTRIBUTOR_MODE=1` in your shell rc and use `gbrain eval replay` to gate your changes against a snapshot of real captured queries — the dev loop is documented in [`docs\u002Feval-bench.md`](docs\u002Feval-bench.md). Capture is **off by default** for production users (no surprise data accumulation); the env var is the contributor opt-in.\n\nPRs welcome for: new enrichment APIs, performance optimizations, additional engine backends, new skills following the conformance standard in `skills\u002Fskill-creator\u002FSKILL.md`.\n\n## License\n\nMIT\n","GBrain 是一个为AI代理提供记忆和知识管理功能的系统。它能够自动从会议、邮件、推文、语音通话等信息中提取实体关系，并创建类型链接，无需调用大型语言模型即可实现自组织的知识图谱构建。此外，GBrain 还具备混合搜索能力、结构化时间线展示以及基于反向链接增强的排名算法等功能，显著提升了信息检索的准确性和效率。适用于需要高效管理和利用大量个人或企业相关信息的场景，如个人助理、商业智能分析等。该项目由Y Combinator的总裁兼首席执行官开发并使用于实际生产环境，证明了其稳定性和实用性。",2,"2026-06-11 03:50:39","high_star"]