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 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.

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:

# 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:

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.

--- 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:

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.

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:

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:

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):

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 and **Implementation Codes.