Your AI agent is smart but forgetful. Every new session starts from zero — no memory of who you met, what you read, what you decided last Tuesday. **[GBrain](https://github.com/garrytan/gbrain)** is an open-source fix for that. Built by Garry Tan (President and CEO of Y Combinator) to power his own OpenClaw and Hermes deployments, it’s a markdown-first, Postgres-backed knowledge layer that ingests meetings, emails, tweets, and notes, then auto-wires a typed knowledge graph on top — with zero LLM calls for the graph extraction. The production brain behind Garry’s actual agents currently holds **146,646 pages, 24,585 people, 5,339 companies, and 66 autonomous cron jobs**. On its own benchmark (BrainBench, a 240-page rich-prose corpus), GBrain hits **P@5 49.1% and R@5 97.9%**, a +31.4-point P@5 lead over the same codebase with the graph layer disabled. This is a hands-on tutorial. You’ll install GBrain locally, import a small notes folder, run a real search, watch the knowledge graph wire itself, and connect it to Claude Code via MCP. About 20 minutes start to finish. All terminal outputs below were captured from a live install of **GBrain v0.38.2.0**. The repository (MIT-licensed) lives at [github.com/garrytan/gbrain](https://github.com/garrytan/gbrain). ## **What you’re building** By the end of the tutorial, you’ll have: - A local `~/.gbrain/brain.pglite` database — embedded **Postgres 17 (via WASM)** with pgvector, zero server config. - A small “brain repo” of markdown notes about people, companies, and concepts. - A working hybrid-search CLI that combines vector + BM25 keyword + Reciprocal Rank Fusion (RRF), with a ZeroEntropy reranker on top by default. - A typed knowledge graph (`works_at`, `founded`, `invested_in`, `attended`, `advises`, `mentions`) auto-extracted from your notes. - An MCP server exposing **74 tools** so Claude Code, Cursor, and Windsurf can read and write to the brain directly. ## **Prerequisites** - macOS or Linux (Windows users: use WSL2). - A code editor. - Bun ≥ 1.3.10 (the runtime GBrain ships on; the repo’s `package.json` declares this as the minimum engine). We’ll install it in Step 1. - An embedding API key from **one** of: ZeroEntropy (default), OpenAI, or Voyage. Without one, you can still install and run keyword search, but `gbrain query` (hybrid + vector) will return no results. - Optional: an Anthropic API key for multi-query expansion during search. ## **Step 1 — Install Bun and GBrain** GBrain is written in TypeScript and runs on Bun. Install it first: ```bash # Install Bun curl -fsSL https://bun.sh/install | bash exec $SHELL # Install GBrain bun install -g github:garrytan/gbrain gbrain --version gbrain 0.38.2.0 ``` ## **Step 2 — Initialize your brain** `gbrain init --pglite` provisions a local PGLite database in `~/.gbrain/`. PGLite is full Postgres compiled to WASM — no server, no Docker, ready in roughly two seconds. For this tutorial we’ll defer the embedding provider so you can follow along without an API key right away — we’ll wire it up in Step 6 when we run hybrid search: ```bash gbrain init --pglite ``` (If you’d rather configure embeddings now, set one of `OPENAI_API_KEY`, `ZEROENTROPY_API_KEY`, or `VOYAGE_API_KEY` in your environment before running plain `gbrain init --pglite`.) ## **Step 3 — Create a tiny brain repo** The brain repo is just a directory of markdown files. Each file follows GBrain’s **compiled truth + timeline** pattern: a current best-understanding section on top, an append-only evidence trail below. **Important:** wikilinks must use the full slug path (e.g., `[[people/alice-chen]]`, not just `[[alice-chen]]`) for the graph extractor to resolve them. ```bash --- people/alice-chen.md --- type: person title: Alice Chen tags: [founder, ai-infra] ——— Founder/CEO of [[companies/acme-ai]]. Previously staff engineer at Google Brain. ——— - 2024-09-04: $12M seed, Sequoia led - 2025-01-18: Open-sourced router ``` ## **Step 4 — Import the repo** `gbrain import` is idempotent (content-hash deduplicated). We’ll pass `--no-embed` so this step is deterministic for readers who don’t have an embedding key set yet — embeddings get backfilled in Step 6. Real output: ```bash gbrain import ~/my-brain/ --no-embed Found 3 markdown files [import.files] 3/3 (100%) imported=3 skipped=0 errors=0 Import complete (0.3s): 3 pages imported 3 chunks created ``` ## **Step 5 — Wire the knowledge graph** For a first-time import, run the link extractor explicitly to backfill the graph from your wikilinks. This is pure regex + typed inference — **zero LLM calls**. ```bash gbrain extract links --source db Links: created 2 from 3 pages Done: 2 links, 0 timeline entries # Inspect the graph directly gbrain graph-query people/alice-chen --depth 1 [depth 0] people/alice-chen --works_at-> companies/acme-ai (depth 1) ``` ## **Step 6 — Run a search** GBrain ships two search verbs. `gbrain search` is keyword-only (BM25 on Postgres `tsvector`) and works without embeddings: ```bash gbrain search "inference" ``` `gbrain query` is the full hybrid pipeline: vector (HNSW on pgvector) + BM25 + Reciprocal Rank Fusion + optional multi-query expansion (Anthropic Haiku) + an optional ZeroEntropy reranker. It needs embeddings, which we deferred in Step 2 — wire them up now: ```bash gbrain query "who works on small-model inference?" ``` ## **Step 7 — Connect to Claude Code via MCP** The brain is more useful when an AI agent can read and write to it directly. GBrain exposes **74 tools** over the Model Context Protocol via stdio. The canonical setup is one command (not a hand-edited JSON file): ```bash claude mcp add gbrain -- gbrain serve ``` ## **Key Takeaways** GBrain (v0.38.2.0) gives AI agents a persistent, markdown-first memory layer — built by Garry Tan to power his own OpenClaw/Hermes deployments holding 146,646 pages and 24,585 people. - Install runs locally in ~30 minutes on PGLite (Postgres 17 compiled to WASM, zero server) and scales to Supabase or self-hosted Postgres when needed. - Every wikilink is parsed by a regex inference cascade (`FOUNDED → INVESTED → ADVISES → WORKS_AT`) that writes typed graph edges with zero LLM calls. - Hybrid search (vector + BM25 + RRF + ZeroEntropy reranker) hits P@5 49.1% / R@5 97.9% on BrainBench — a +31.4-point P@5 lift over the graph-disabled variant. - Exposes 74 tools over MCP — wire it into Claude Code with a single `claude mcp add gbrain -- gbrain serve` and your agent can read/write the brain directly. * * * Check out the [**GitHub Repo**](https://github.com/garrytan/gbrain) and **[Implementation Codes](https://github.com/Marktechpost/AI-Agents-Projects-Tutorials/blob/main/Agentic%20AI%20Codes/gbrain-tutorial.ipynb).