Build Your AI Agent’s Memory: A Step-by-Step Guide to Implementing GBrain — The Self-Wiring Memory Layer from Y Combinator’s Garry Tan

Your AI assistant may be intelligent, but it has no memory. Each conversation begins fresh — it doesn’t recall your previous meetings, articles you’ve consumed, or decisions you made last week. GBrain offers an open-source solution. Created by Garry Tan (President and CEO of Y Combinator) to enhance his own OpenClaw and Hermes systems, it uses markdown files with a Postgres backend to process meetings, emails, tweets, and notes, automatically building an organized knowledge graph — without needing any LLM calls for graph construction. Garry’s personal production brain currently contains 146,646 pages, 24,585 individuals, 5,339 organizations, and 66 automated cron tasks. On its dedicated evaluation (BrainBench, using a 240-page detailed text collection), GBrain achieves P@5 49.1% and R@5 97.9%, outperforming the same system without the graph component by +31.4 points on P@5.

This guide walks you through the setup process. You’ll install GBrain on your machine, import a collection of notes, execute an actual search, observe the knowledge graph form automatically, and link it with Claude Code through MCP. The whole process takes around 20 minutes. All command outputs shown below come from a working installation of GBrain v0.38.2.0. The project (MIT-licensed) is available at github.com/garrytan/gbrain.

What you’ll have by completion

After finishing this guide, you’ll possess:

• A local ~/.gbrain/brain.pglite database — built-in Postgres 17 (WASM-based) with pgvector, requiring no server setup.
• A test “brain repo” containing markdown notes about individuals, companies, and ideas.
• A hybrid search command-line tool merging vector + BM25 keyword + Reciprocal Rank Fusion (RRF), with ZeroEntropy reranking enabled by default.
• An organized knowledge graph (works_at, founded, invested_in, attended, advises, mentions) automatically built from your notes.
• An MCP server providing 74 tools allowing Claude Code, Cursor, and Windsurf to interact with the brain directly.

Requirements

• macOS or Linux (Windows users: use WSL2).
• A text editor.
• Bun ≥ 1.3.10 (the runtime GBrain operates on; the project’s package.json specifies this minimum version). We’ll set it up in Step 1.
• An embedding API key from one of these providers: ZeroEntropy (default), OpenAI, or Voyage. While you can still install and use keyword search without one, gbrain query (hybrid + vector) requires it to return results.
• Optional: an Anthropic API key for expanding search queries.

Step 1 — Set up Bun and GBrain

GBrain is built with TypeScript and runs on Bun. Start by installing Bun:

curl -fsSL  | bash
exec $SHELL                 # restart shell to add `bun` to PATH
bun --version

Next, install GBrain. Starting with v0.38, the standard installation is a single global Bun command:

bun install -g github:garrytan/gbrain
gbrain --version
# gbrain 0.38.2.0

Step 2 — Set up your brain

gbrain init --pglite creates a local PGLite database inside ~/.gbrain/. PGLite is complete Postgres compiled to WebAssembly — no server or Docker needed, ready in about two seconds.

For this guide, we’ll skip the embedding provider setup so you can proceed without an API key initially — we’ll configure it in Step 6 when we execute hybrid search:

gbrain init --pglite --no-embedding

(If you prefer to set up embeddings now, define one of OPENAI_API_KEY, ZEROENTROPY_API_KEY, or VOYAGE_API_KEY in your environment before running plain gbrain init --pglite.)

Actual output from a fresh installation (shortened — there are 81 migrations from schema v1 → v85):

Setting up local brain with PGLite (no server needed)...
  Schema version 1 → 85 (81 migration(s) pending)
  [2] slugify_existing_pages...
  [2] ✓ slugify_existing_pages
  [3] unique_chunk_index...
  [3] ✓ unique_chunk_index
  ...
  Brain ready at /home/you/.gbrain/brain.pglite
  0 pages. Engine: PGLite (local Postgres).

Your brain is now empty. Verify it:

gbrain stats
# Pages:     0
# Chunks:    0
# Embedded:  0
# Links:     0
# Tags:      0
# Timeline:  0

Step 3 — Build a small brain repo

The brain repo is simply a folder of markdown files. Each file follows GBrain’s compiled truth + timeline format: a current best-knowledge summary at the top, followed by a chronological evidence log below.

Note: wikilinks need the complete slug path (e.g., [[people/alice-chen]], not just [[alice-chen]]) for the graph extractor to recognize them. This is a common pitfall — I tested both formats; the abbreviated form silently creates zero connections.

mkdir -p ~/my-brain/people ~/my-brain/companies ~/my-brain/concepts
cd ~/my-brain

Create a person page:

cat > people/alice-chen.md <<'EOF'
---
type: person
title: Alice Chen
tags: [founder, ai-infra]
---

Founder and CEO of [[companies/acme-ai]]. Previously staff engineer at
Google Brain. Focus area: inference optimization for small language models.

---

- 2024-03-12: Met at AI Engineer Summit. Discussed sparse MoE routing.
- 2024-09-04: Announced $12M seed led by Sequoia.
- 2025-01-18: Shipped

Step 4 — Get Your Knowledge into the System

gbrain import is a smart importer — it won’t duplicate content it has already seen, thanks to content hashing. For readers who don’t have an embedding key configured yet, we’ll use the --no-embed flag so this step runs predictably. Embeddings will be handled later, in Step 6. Here’s what a real interaction looks like:

gbrain import ~/my-brain/ --no-embed

Real output:

[gbrain phase] import.collect_files start dir=/home/you/my-brain/ strategy=markdown
[gbrain phase] import.collect_files done 2ms files=3
Found 3 markdown files
[import.files] 3/3 (100%) imported=3 skipped=0 errors=0

Import complete (0.3s):
  3 pages imported
  0 pages skipped (0 unchanged, 0 errors)
  3 chunks created

Double-check what landed:

gbrain list
# companies/acme-ai                company   2026-05-22  Acme AI
# concepts/inference-optimization  concept   2026-05-22  Inference Optimization
# people/alice-chen                person    2026-05-22  Alice Chen

Step 5 — Connect the Knowledge Graph

After your first import, run the link extractor to populate the graph using your wikilinks. This step uses only regex and type-based inference — no large language model queries whatsoever.

gbrain extract links --source db

Real output:

[extract.links_db] 3/3 (100%) done
Links: created 2 from 3 pages (db source)
Done: 2 links, 0 timeline entries from 3 pages

Two typed relationships were automatically inferred from the wikilinks: alice-chen --works_at→ acme-ai (from the phrase “Founder and CEO of …”) and acme-ai --founded→ alice-chen (from “Founded by …”). The inference chain fires in priority order: FOUNDED → INVESTED → ADVISES → WORKS_AT → MENTIONS. No model is involved in this process.

Explore the graph directly:

gbrain graph-query people/alice-chen --depth 1
# [depth 0] people/alice-chen
#   --works_at→ companies/acme-ai (depth 1)

gbrain backlinks companies/acme-ai
# [
#   {
#     "from_slug": "people/alice-chen",
#     "to_slug": "companies/acme-ai",
#     "link_type": "works_at",
#     "context": "Founder and CEO of [[companies/acme-ai]]...",
#     "link_source": "markdown",
#     ...
#   }
# ]

This highlights the gap between plain vector search and structured retrieval. Asking “Who works at Acme AI?” becomes a single-step typed-edge lookup rather than a fuzzy similarity score. That’s the structural advantage behind the +31.4-point improvement in P@5 on BrainBench compared to the graph-free version.

Step 6 — Search Your Knowledge Base

GBrain offers two search commands. gbrain search performs keyword-only lookups (BM25 against a Postgres tsvector) and works fine without embeddings:

gbrain search "inference"
# [0.3648] companies/acme-ai -- YC W24 inference-optimization startup...
# [0.3648] people/alice-chen -- Founder and CEO of [[companies/acme-ai]]...

gbrain query is the full hybrid pipeline: vector search (HNSW via pgvector) + BM25 + Reciprocal Rank Fusion + optional multi-query expansion (Anthropic Haiku) + an optional ZeroEntropy reranker. It requires embeddings, which we postponed in Step 2 — set them up now:

# Configure one of: ZEROENTROPY_API_KEY (default), OPENAI_API_KEY, or VOYAGE_API_KEY
export OPENAI_API_KEY=sk-...
gbrain config set embedding_model openai:text-embedding-3-large
gbrain embed --all          # one-time backfill with your embedding provider
gbrain query "who works on small-model inference?"

# Same setup as above
export OPENAI_API_KEY=sk-...
gbrain config set embedding_model openai:text-embedding-3-large
gbrain embed --all          # backfill embeddings from your chosen provider
gbrain query "who works on small-model inference?"

Three built-in search modes come ready to use: conservative, balanced, and tokenmax. These options wrap cost and quality settings into a single configuration key. By default, balanced is selected with the ZeroEntropy reranker enabled. The scoring formula is: score = sum(1 / (60 + rank)).

Step 7 — Connect Claude Code through MCP

The system becomes far more powerful when an AI assistant can directly access and modify its contents. GBrain provides 74 tools via the Model Context Protocol (MCP) using standard input/output (stdio). The simplest setup requires just one command:

claude mcp add gbrain -- gbrain serve

To confirm the connection is working:

claude mcp list
# gbrain  stdio  gbrain serve

Now you can ask Claude Code something like “find information about inference optimization” and it will use the search tool to return matching results from your indexed content. The MCP tool names follow standard snake_case formatting: get_page, put_page, delete_page, list_pages, search, query, add_link, get_backlinks, add_tag, along with 56 other functions.

For Cursor and Windsurf users, both tools use standard MCP JSON configuration through their respective settings menus. The server configuration is identical:

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

Claude Desktop requires claude_desktop_config.json for local MCP connections using the same format. For remote HTTP MCP servers, you must add them through Settings → Integrations using a bearer token. Detailed setup instructions can be found in docs/mcp/CLAUDE_DESKTOP.md within the repository.

For remote access from any device, you can switch from stdio to HTTP mode:

gbrain serve --http --port 8787
# Includes bearer authentication, restrictive CORS, rate limiting per bucket, and request logging.
# Uses exclusively with PostgreSQL by design (PGLite is local-only).

Step 8 — Allow the system to manage itself

GBrain features an automated repair system. In version 0.36.4, a single command creates a prioritized fix plan, executes each task as a Minion job, monitors the system’s health between steps, and stops when reaching your budget limit:

gbrain doctor --remediate --yes --target-score 90 --max-usd 5

You can also run it as a background service:

gbrain autopilot --install        # Runs via cron every 5 minutes

Systems functioning properly wait 60 minutes between checks. Systems needing attention get the full maintenance cycle: sync, extract, embed, consolidate, synthesize. Three operations (synthesize, patterns, consolidate) have safeguards preventing connected AI agents from accidentally draining API budgets.

For custom background tasks, the Minions task queue handles both shell commands and AI-assisted work simultaneously:

gbrain jobs submit sync --params '{}' --follow
gbrain jobs stats
gbrain jobs work --queue default

Important PGLite limitation: The gbrain jobs supervisor (the persistent worker service) requires PostgreSQL. PGLite prevents external processes from accessing the same data file — the system will display an error if config.engine === 'pglite'. If using PGLite, use inline execution with --follow for now, or switch to Supabase with gbrain migrate --to supabase before enabling persistent workers.

General guideline: mechanical tasks (fetching tweets, converting formats, writing pages) go to Minions; evaluative tasks (sorting messages, ranking priorities) go to AI sub-agents.

Here is a visual summary of what was built

markdown files  ──>  PGLite + pgvector  <──>  43 skills
(your repository,      (combines text search    (describes how to use the system;
 master copy)          + relationship graph)   RESOLVER.md directs tasks)
       ▲                                              │
       └──────────────  AI reads and modifies  ────────┘

The markdown collection serves as the primary data source. GBrain adds search and relationship tracking on top. AI assistants interact with both layers, while anyone can still manually edit any .md file — gbrain sync will detect the changes automatically.

What to explore next

• Quick note saving (v0.38 feature): Use gbrain capture "the idea I want to save" to store directly in inbox/YYYY-MM-DD-. Also supports --file, --stdin, and webhook input via gbrain serve --http /ingest.
• Upgrade to Supabase when your content exceeds local capacity (PGLite handles approximately 50K pages): Run gbrain migrate --to supabase.
• Import actual data using preset options: phone integration (Twilio + OpenAI Realtime), email + calendar, 16 embedding services, credential management.
• Run performance tests via the companion gbrain-evals package: BrainBench (test scenarios) and gbrain eval longmemeval (standard LongMemEval evaluation).
• Create your own skills. A skill is a detailed markdown guide defining a process — activation rules, validations, quality checks. Run gbrain check-resolvable

The core philosophy behind GBrain is that a **lean runtime paired with rich, modular skills** outperforms a monolithic, “smart” agent. The runtime itself is kept lightweight, while the intelligence resides in markdown files that the agent consults whenever it needs to make a decision. Every brain repo commit you push becomes a piece of lasting context your agent automatically accesses the next time it runs — meaning it grows sharper over time.

**Marktechpost’s Visual Explainer**

—

### Implementing GBrain: The Self-Wiring Memory Layer for AI Agents

A hands-on walkthrough of **Garry Tan’s open-source agent brain**: install, import, hybrid search, graph wiring, and MCP integration in roughly 20 minutes.

| | | | |
|—|—|—|—|
| **v0.38.2** · Latest release | **43** · Skills shipped | **98%** · TypeScript | **MIT** · License |

—

### The Problem: AI Agents Are Smart but Forgetful

Each new session starts with a blank slate. There is zero recollection of prior meetings, recently consumed material, or decisions reached last week.

– **Vector databases by themselves miss exact-phrase matches and structural queries.**
– **Pure keyword search alone fails to surface conceptually related content.**
– **Most memory layers can’t reliably answer “who works at X?”**
– **Spinning up sub-agents for slow, deterministic tasks burns tokens and time.**

—

### What Is GBrain?

The production brain behind Y Combinator’s CEO. These stats reflect Garry Tan’s personal OpenClaw / Hermes deployment as of v0.38.2.0.

| | |
|—|—|
| **146,646** pages indexed | **24,585** people tracked |
| **5,339** companies | **66** cron jobs |

On BrainBench, hybrid search delivers **P@5 49.1%, R@5 97.9%** — a +31.4-point P@5 boost compared to running the same codebase without the graph layer.

—

### Step 1 — Install Bun, Then GBrain

As of v0.38, the recommended install path is a **single global Bun package**.

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 a Local Brain in Seconds

**PGLite** is a full PostgreSQL 17 engine compiled to WebAssembly — no Docker, no external server needed.

bash
# Defer embedding generation until the search step
gbrain init –pglite –no-embedding

# Setting up local brain with PGLite…
# Schema version 1 → 85 (81 migration(s) pending)
# [2] slugify_existing_pages… ✓
# [3] unique_chunk_index… ✓
# …
# Brain ready at ~/.gbrain/brain.pglite
# 0 pages. Engine: PGLite.

—

### Step 3 — Brain Repo: Compiled Truth + Timeline Pattern

Every page is a single markdown file. **Wikilinks must use the full slug path** — `[[people/alice-chen]]`, not `[[alice-chen]]`.

markdown
— people/alice-chen.md —
type: person
title: Alice Chen
tags: [founder, ai-infra]
—

Founder/CEO of [[companies/acme-ai]].
Previously a staff engineer at Google Brain.

—

– 2024-09-04: $12M seed round, led by Sequoia
– 2025-01-18: Open-sourced inference router

—

### Step 4 — Import: Idempotent by SHA-256 Dedup

The import step is safe to re-run. Pass `–no-embed` to postpone embedding creation until later.

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 — Graph: Wire It Up with Zero LLM Calls

A regex-powered inference cascade automatically derives relationship types:
**FOUNDED → INVESTED → ADVISES → WORKS_AT → MENTIONS**.

bash
gbrain extract links –source db
# Links: created 2 from 3 pages
# Done: 2 links, 0 timeline entries

gbrain graph-query people/alice-chen –depth 1
# [depth 0] people/alice-chen
# –works_at–> companies/acme-ai (depth 1)

—

### Step 6 — Search: Hybrid Vector + BM25 + RRF + Reranker

Three preset modes ship by default: **conservative, balanced, tokenmax**. The RRF fusion formula is `score = Σ 1 / (60 + rank)`.

bash
gbrain search “inference”
# [0.3648] companies/acme-ai — YC W24
# inference-optimization startup…
# [0.3648] people/alice-chen — Founder/CEO of
# [[companies/acme-ai]]…

gbrain query “who works on small-model inference?”
# # Hybrid: vector + BM25 + RRF + ZeroEntropy rerank

—

### Step 7 — MCP: Wire Into Claude Code in One Command

GBrain exposes **74 tools** over MCP via stdio. The standard setup requires a single CLI call — no hand-written JSON config needed.

bash
claude mcp add gbrain — gbrain serve

# For Cursor / Windsurf, add to the standard JSON config:
{
“mcpServers”: {
“gbrain”: {
“command”: “gbrain”,
“args”: [“serve”]
}
}
}

Tool names use straightforward snake_case: **get_page, put_page, search, query, add_link, get_backlinks**, plus 68 more.

—

### What You Just Built

– **Markdown-first memory** — the source of truth remains fully readable and editable by humans.
– **Self-wiring graph** — typed edges extracted automatically on every save, at zero LLM cost.
– **Hybrid search** — vector + BM25 + RRF + ZeroEntropy reranker, with three preset configurations.
– **Local Postgres** — PGLite by default (handles up to roughly 50K pages), with Supabase available as you scale.
– **MCP-native** — 74 tools accessible from Claude Code, Cursor, Windsurf, and beyond.

—

## Key Takeaways

– GBrain (v0.38.2.0) gives AI agents a persistent, markdown-first memory layer — the same system Garry Tan built to drive his own OpenClaw / Hermes deployments, now holding 146,646 pages and tracking 24,585 people.
– Installation takes about 30 minutes using PGLite (Postgres 17 compiled to WASM, no server required), and it scales up to Supabase or a self-managed Postgres instance when your needs grow.
– Every wikilink is parsed by a regex inference cascade (`FOUNDED → INVESTED → ADVISES → WORKS_AT`) that writes typed graph edges without a single LLM call.
– Hybrid search (vector + BM25 + RRF + ZeroEntropy reranker) reaches P@5 49.1% / R@5 97.9% on BrainBench — a +31.4-point P@5 gain over the no-graph variant.
– Exposes 74 tools over MCP — connect it to Claude Code with a single `claude mcp add gbrain — gbrain serve` and your agent gains direct read/write access to the brain.

—

Check out the **GitHub Repo** and **Implementation Codes**. Also, feel free to follow us on **Twitter**, join our **150k+ ML SubReddit**, and subscribe to **our Newsletter**. On Telegram too? **Now you can join us there as well.**

Interested in a partnership to promote your GitHub repo, Hugging Face page, product launch, or webinar? **Connect with us.**