# How GBrain Works, and How to Actually Wire It Into Your Agents
**作者**: AlphaSignal AI
**日期**: 2026-04-10T07:00:15.000Z
**来源**: [https://x.com/AlphaSignalAI/status/2044461541232148986](https://x.com/AlphaSignalAI/status/2044461541232148986)
---
@garrytan open-sourced his production AI infrastructure: 17,888 pages, 4,383 people dossiers, 723 companies. Here's the architecture.
Garry Tan (President & CEO @ycombinator) made public 17,888 pages of his brain. His production system consists of 4,383 people dossiers, 723 companies, 21 autonomous cron jobs created within a span of 12 days. In the first 24 hours this was able to collect over 5,400+ GitHub stars.
It’s a personal knowledge layer for AI agents. By default, all agents are stateless, that is each session begins blank. GBrain provides a structured, searchable long-term memory for each session using an embedded Postgres database and a git-tracked Markdown corpus. The agent uses the brain prior to answering questions and updates the knowledge base with new information following each session. The knowledge grows exponentially.
MIT licensed. TypeScript, runs on Bun. v0.10.1.
## Repo snapshot
https://github.com/garrytan/gbrain
## Three-layer architecture
Brain Repo: A git-backed directory of Markdown files, one per person, company, project, or idea. The repo is the system of record. Edit any file manually and gbrain sync picks up the changes. Tan's own instance includes 13 years of calendar data, 280+ meeting transcripts, and 300+ captured ideas.
Retrieval Layer: Postgres with pgvector. The CLI and MCP server are both generated from a single contract-first interface (src/core/operations.ts, ~30 shared operations). Two pluggable engines: PGLite (embedded Postgres 17.5 via WASM, zero config, boots in 2 seconds) is the default. For corpora over 1,000 files, gbrain migrate --to supabase moves everything to a managed Postgres instance. Migration is bidirectional.
Skills Layer: 25 Markdown skill files organized by RESOLVER.md. The architecture philosophy is "thin harness, fat skills": executable TypeScript handles deterministic operations (search, embed, import, sync). The agent model handles judgment-dependent tasks by reading the skill file and executing it. Skills are plain text and modifiable without touching compiled code.
GBrain is designed as a companion to GStack, Tan's earlier coding-focused agent framework. GStack handles code skills. GBrain handles everything else: memory, enrichment, ingestion, scheduling, and identity.
Generated by Nano Banana
## The knowledge model
Every brain page follows a compiled truth + timeline pattern:
Above the divider: compiled truth, the current best understanding. Gets rewritten when new evidence changes the picture. Below: timeline, append-only evidence trail. Never edited, only extended.
Entity enrichment is tiered and automatic. A person mentioned once gets a stub page (Tier 3). After 3 mentions across different sources, they get web and social enrichment (Tier 2). After a meeting or 8+ mentions, full enrichment pipeline (Tier 1). No manual tagging.
A fail-improve loop runs in the background (src/core/fail-improve.ts): every LLM fallback is logged, and better regex patterns are generated from the failures. gbrain doctor shows the trajectory: "intent classifier: 87% deterministic, up from 40% in week 1."
## The search pipeline
Six steps from query to results:
Intent classifier: zero-latency regex, no LLM call. Detects query type: entity, temporal, event, or general. Routes accordingly.
Multi-query expansion: Claude Haiku generates query variants to improve recall.
Parallel retrieval: vector search (HNSW cosine) runs alongside keyword search (tsvector).
RRF fusion: reciprocal rank fusion merges both result lists into a single ranked set.
Compiled truth boost + cosine re-scoring: entity queries get compiled truth chunks ranked higher. Temporal queries skip the boost to surface timeline dates instead.
4-layer dedup: guarantees at least one compiled truth chunk per page in results.
PR #64 (shipped April 14, 2026) benchmarked the pipeline against a 29-page synthetic corpus running in-memory PGLite:
These numbers are from a 29-page corpus. Tan's production brain is 17,888 pages. Performance at that scale is not publicly benchmarked.
The intent classifier is the critical piece. Running the compiled truth boost without it drops source accuracy to 63.2%, because it forces assessment chunks above timeline entries even when the query is asking for dates. The classifier restores accuracy at zero latency by detecting temporal queries and skipping the boost for them.
An eval harness ships with the repo. gbrain eval --qrels queries.json measures P@k, R@k, MRR, and nDCG@k. A/B config testing is built in.
## How to get started
Agent path (recommended). If you are already on OpenClaw or Hermes, paste one URL into your agent:
The agent clones the repo, installs GBrain, loads the 25 skills, and registers cron jobs. You answer questions about API keys. About 30 minutes.
Standalone CLI path:
MCP path (Claude Code, Cursor, Windsurf):
Add to ~/.claude/server.json for Claude Code, or Settings > MCP Servers in Cursor. GBrain exposes 30+ MCP tools over stdio.
Data ingestion runs through 7 integration recipes: Gmail, Google Calendar, X/Twitter, Twilio voice-to-brain, Circleback meeting transcripts, credential gateway, and ngrok tunnel. Each recipe is a YAML+Markdown document. The agent reads it, requests credentials, and registers the cron. Run gbrain integrations to see current status.
Model requirement: GBrain requires a frontier model. Documented working configurations are Claude Opus 4.6 and GPT-5.4 "Thinking." Weaker models produce unpredictable results on the instruction-driven features.
## Limitations
Dream cycle implementation gap. GBrain ships a real background daemon (gbrain autopilot) that runs sync, link extraction, and embedding on a launchd/cron schedule. What it does not do is compiled truth rewriting, entity enrichment, or dream cycle consolidation. Those features live in Markdown skill files that the connected agent model interprets and executes. Whether they run, and how reliably, depends entirely on how well the model follows multi-step instructions.
Frontier model hard requirement. Claude Opus 4.6 and GPT-5.4 "Thinking" are the documented working paths. Weaker models fail on the instruction-dependent features. This adds API costs before any application logic.
Benchmark scope gap. PR #64's P@1 of 94.7% runs against 29 synthetic pages in-memory. Tan's production corpus is 17,888 pages. The performance curve at scale has not been publicly benchmarked.
Known MCP issues. An independent code review flagged potential race conditions in concurrent MCP writes, and scenarios where NULL embeddings can overwrite valid vectors during write operations.
## Who should clone this
Clone it if you are building long-lived agents on OpenClaw or Hermes, have Claude Opus 4.6 or equivalent API access, and are comfortable with TypeScript. The system also fits investor and founder workflows that track multi-year relationships and deal history at scale.
Skip it if you need production-grade persistent memory today without debugging model-dependent features, are running a weaker model, or are not on OpenClaw or Hermes. The integration path for other agent frameworks is not documented. Multi-device sync requires managing a Supabase instance.
## Practitioner implication
Developers building on OpenClaw or Hermes can now give agents structured, searchable long-term memory backed by a real database, without standing up a separate memory service.
## AlphaSignal Take
Worth Watching.
The storage and retrieval layer is production-engineered: contract-first operations, pluggable engines, a built-in eval harness, 34 unit test files, and 5 E2E test files. The codebase is not a prototype. v0.10.1 shipped April 12, PR #64 closed April 14. Active maintenance.
The headline agentic features sit at the boundary between code and model. Compiled truth rewriting, dream cycles, and entity enrichment are skill files the connected model interprets, not compiled algorithms. That is the "thin harness, fat skills" design choice, but it means reliability scales directly with model quality. With Opus 4.6, the behavior is documented to work. With anything weaker, it degrades.
For this verdict to move to Production Ready: an executable dream cycle scheduler independent of model interpretation, a public benchmark at 10,000+ file scale, and a confirmed fix for the NULL embedding race condition in concurrent MCP writes.
## Links
- GBrain on GitHub (repo, ~30 min setup)
- INSTALL_FOR_AGENTS.md (agent install instructions, ~5 min read)
- Thin Harness, Fat Skills (architecture philosophy, ~8 min read)
Follow @AlphaSignalAI for more content like this.
Check out AlphaSignal.ai to get a daily summary of top models, repos, and papers in AI. Read by 280,000+ devs.
## Questions?
Q: What is GBrain and what does it do? A: GBrain is an open-source personal knowledge layer for AI agents. It stores information in a git-backed Markdown corpus, indexes it in Postgres with pgvector, and exposes it to agents via 30+ MCP tools and 30+ CLI commands. Agents read from the brain before responding and write back after each interaction.
Q: Does GBrain work without OpenClaw or Hermes? A: The standalone CLI and MCP server work with any MCP-compatible client including Claude Code, Cursor, and Windsurf. The 25 skill files and integration recipes are designed around OpenClaw and Hermes. Setup instructions for other agent frameworks are not provided in the repo.
Q: How does GBrain handle large corpora? A: The default PGLite engine is recommended up to ~1,000 files. Above that, gbrain migrate --to supabase moves the database to a managed Postgres instance. Benchmarks in the repo cover a 29-page synthetic corpus; behavior at 10,000+ files has not been publicly benchmarked.
Q: What model does GBrain require? A: Claude Opus 4.6 or GPT-5.4 "Thinking." GBrain's skill files use multi-step instruction-following for compiled truth rewriting, entity enrichment, and dream cycles. Weaker models are documented to produce unpredictable results on these features.
Q: Is GBrain production-ready? A: The retrieval and storage infrastructure is production-grade. The flagship agentic features (dream cycles, compiled truth rewriting) are implemented as model-interpreted instructions rather than executable code, making reliability dependent on model quality. Verify end-to-end behavior with your target model before production deployment.
## 相关链接
- [Garry Tan reposted](https://x.com/garrytan)
- [AlphaSignal AI](https://x.com/AlphaSignalAI)
- [@AlphaSignalAI](https://x.com/AlphaSignalAI)
- [10K](https://x.com/AlphaSignalAI/status/2044461541232148986/analytics)
- [@garrytan](https://x.com/@garrytan)
- [@ycombinator](https://x.com/ycombinator)
- [Apr 10](https://x.com/garrytan/status/2042497872114090069)
- [https://github.com/garrytan/gbrain](https://github.com/garrytan/gbrain)
- [GStack](https://github.com/garrytan/gstack)
- [PR #64](https://github.com/garrytan/gbrain/blob/master/docs/benchmarks/2026-04-14-search-quality.md)
- [GBrain on GitHub](https://github.com/garrytan/gbrain)
- [INSTALL_FOR_AGENTS.md](https://github.com/garrytan/gbrain/blob/master/INSTALL_FOR_AGENTS.md)
- [Thin Harness, Fat Skills](https://github.com/garrytan/gbrain/blob/master/docs/ethos/THIN_HARNESS_FAT_SKILLS.md)
- [@AlphaSignalAI](https://x.com/@AlphaSignalAI)
- [AlphaSignal.ai](https://alphasignal.ai/)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [1:03 AM · Apr 16, 2026](https://x.com/AlphaSignalAI/status/2044461541232148986)
- [10K Views](https://x.com/AlphaSignalAI/status/2044461541232148986/analytics)
---
*导出时间: 2026/4/16 15:49:00*