Your AI agent is smart but forgetful. You start each new session from scratch – you don’t remember who you met, what you read, or what you decided last Tuesday. GBrain It is an open source solution for that. Built by Garry Tan (President and CEO of Y Combinator) to power his OpenClaw and Hermes deployments, it is a Postgres-powered knowledge layer that ingests meetings, emails, tweets, and notes, then automatically plugs a typed knowledge graph on top – with zero LLM calls to extract the graph. The production brain behind Gary’s actual clients is currently still there 146,646 pages, 24,585 people, 5,339 companies, 66 freelance kroner jobs. By its own benchmark (BrainBench, a 240-page collection of rich prose), GBrain has achieved great success F@5 49.1% and R@5 97.9%offering +31.4 pips P@5 on the same code base with the chart layer disabled.
This is a hands-on tutorial. You’ll install GBrain locally, import a small notes folder, do real research, see the knowledge graph wire itself, and connect it to Claude Code via MCP. About 20 minutes start and finish. All peripheral outputs below were captured from a live installation of GBrain v0.38.2.0. The repository (licensed by MIT) is located at github.com/garrytan/gbrain.
What you are building
By the end of the tutorial, you will have:
- local
~/.gbrain/brain.pgliteDatabase – built-in PostgreSQL 17 (via WASM) With pgvector, server configuration is zero. - A small “mental repo” of markdown notes about people, companies and concepts.
- A hybrid search CLI that combines the Vector + BM25 + Reciprocal Rank Fusion (RRF) keyword, with ZeroEntropy reranking at the top by default.
- Written knowledge graph (
works_at,founded,invested_in,attended,advises,mentions) is automatically extracted from your notes. - MCP server detection 74 tools So Cloudcode, CoreSurf and Windsurf can read and write to the brain directly.
Basic requirements
- macOS or Linux (Windows users: use WSL2).
- Code editor.
- Bun ≥ 1.3.10 (GBrain is run at runtime; the repo’s
package.jsonIt is declared that this is the minimum for the engine). We will install it in step 1. - API key to embed from one From: ZeroEntropy (default), OpenAI, or Voyage. Without it, you can still install and run keyword research, however
gbrain query(hybrid + vector) will not return any results. - Optional: Anthropic API key to expand multiple queries during search.
Step 1 – Install Bun and GBrain
GBrain is written in TypeScript and runs on Bun. Install it first:
curl -fsSL https://bun.sh/install | bash
exec $SHELL reload shell so `bun` is on PATH
bun --versionNow install GBrain. As of version 0.38, the primary installation path is a single global installation of Bun:
bun install -g github:garrytan/gbrain
gbrain --version
gbrain 0.38.2.0Step 2 – Prepare your mind
gbrain init --pglite Provides a local PGLite database in ~/.gbrain/. PGLite is full Postgres compiled to WASM – no server, no Docker, ready in about 2 seconds.
In this tutorial, we’ll defer the embed provider so you can continue without the API key right away – and we’ll link to it in Step 6 when we run hybrid search:
gbrain init --pglite --no-embedding(If you’d rather configure embeds now, set one.) OPENAI_API_KEY, ZEROENTROPY_API_KEYor VOYAGE_API_KEY in your environment before normal operation gbrain init --pglite.)
Real output captured from a fresh install (truncated for brevity – there are 81 migrations from the v1 → v85 scheme):
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).You now have an empty brain. Verify:
gbrain stats
Pages: 0
Chunks: 0
Embedded: 0
Links: 0
Tags: 0
Timeline: 0Step 3 – Create a small repo for the brain
The brain repository is just a directory of markdown files. Each file is followed by a GBrain file The combined truth + timeline Style: current section for better understanding at the top, and an append-only directory path at the bottom.
important: Wiki links must use the full static path (for example, [[people/alice-chen]]And not only [[alice-chen]]) for the graph extractor to solve it. This is a real problem, I’ve tested both models; The short form silently produces no links.
mkdir -p ~/my-brain/people ~/my-brain/companies ~/my-brain/concepts
cd ~/my-brainCreate a person page:
cat andgt; people/alice-chen.md andlt;andlt;'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 open-source inference router on GitHub.
EOFCompany page:
cat andgt; companies/acme-ai.md andlt;andlt;'EOF'
---
type: company
title: Acme AI
tags: [startup, inference]
---
YC W24 inference-optimization startup. Founded by [[people/alice-chen]].
Building latency-aware routing for sub-7B models.
---
- 2024-09-04: $12M seed, led by Sequoia.
- 2025-01-18: Open-sourced their inference router.
EOFAnd the concept page:
cat andgt; concepts/inference-optimization.md andlt;andlt;'EOF'
---
type: concept
title: Inference Optimization
tags: [ml-systems]
---
Techniques to reduce latency and cost when serving language models:
quantization, speculative decoding, KV-cache reuse, and request batching.
EOFStep 4 – Import the repo
gbrain import Inactive (content fragment deduplicated). We will pass --no-embed So this step is imperative for readers who don’t have an embedding keyset yet – the embeddings are repackaged in step 6. Actual output:
gbrain import ~/my-brain/ --no-embed[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 createdVerify:
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 ChenStep 5 – Connect the Knowledge Graph
For the first import, run the link extractor explicitly to populate the graph from your wiki links. This is regular expression + written inference – Zero LLM calls.
gbrain extract links --source dbReal output:
[extract.links_db] 3/3 (100%) done
Links: created 2 from 3 pages (db source)
Done: 2 links, 0 timeline entries from 3 pagesTwo written edges were inferred from the wiki links: alice-chen --works_at--andgt; acme-ai (From “Founder and CEO…”) and acme-ai --founded--andgt; alice-chen (From “Founded by…”). The chain of reasoning is launched in order: FOUNDED → INVESTED → ADVISES → WORKS_AT → MENTIONS. There is no model in the loop.
Check the chart directly:
gbrain graph-query people/alice-chen --depth 1
[depth 0] people/alice-chen
--works_at-andgt; 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 is the difference between vector search and structured retrieval. “Who works at Acme AI?” It is now a one-hop scripted edge traversal, rather than a similarity score. This structural channel is what is driving the +31.4 pips P@5 lift above the disrupted variant charted on BrainBench.
Step 6 – Do a search
GBrain sends two search actions. gbrain search It is just a keyword (BM25 in Postgres tsvector) and works without including:
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 It is the complete hybrid pipeline: Vector (HNSW on pgvector) + BM25 + Reciprocal Rank Fusion + Optional Multi-Query Expansion (Anthropic Haiku) + Optional ZeroEntropy reranking tool. It needs embeds, which we postponed in step 2 – connect them now:
Set 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 against your embedding provider
gbrain query "who works on small-model inference?" Set 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 against your embedding provider
gbrain query "who works on small-model inference?"Three search modes shipped out of the box – conservative, balanced, tokenmax – Group cost/quality handles into one configuration key. The default is balanced With the ZeroEntropy Reorder tool running. Quick response format: score = sum(1 / (60 + rank)).
Step 7 – Connect to Claude Code via MCP
The brain is most useful when an AI agent can read and write directly to it. GBrain reveals 74 tools Via the Model Context Protocol via stdio. The basic setup is one command (not a manually edited JSON file):
claude mcp add gbrain -- gbrain serveInstallation verification:
claude mcp list
gbrain stdio gbrain serveNow ask Claude something like this “Brain research to improve reasoning” It will be forwarded via search The tool returns indexed results. The actual MCP tool names are simple snake case: get_page, put_page, delete_page, list_pages, search, query, add_link, get_backlinks, add_tagand 65 others.
Index and surfing Use standard MCP JSON configuration in their settings UIs. Server specifications are the same:
{
"mcpServers": {
"gbrain": { "command": "gbrain", "args": ["serve"] }
}
}Cloud Desktop Uses claude_desktop_config.json to Local studio MCP servers with the same JSON specifications. far HTTP MCP servers must be added through Settings → Integrations with Bearer Token. See docs/mcp/CLAUDE_DESKTOP.md In the repo for the GUI walkthrough.
If you want remote access from any device, replace stdio with HTTP:
gbrain serve --http --port 8787
Bearer auth, default-deny CORS, two-bucket rate limit, per-request audit log.
Postgres-only by design (PGLite is local-only).Step 8 – Let the brain manage itself
GBrain charges the autopilot loop. As of version 0.36.4, one command calculates a treatment plan sorted by dependency, submits each step as a Minion task, rechecks the brain’s health score between steps, and rejects spending beyond the maximum cost:
gbrain doctor --remediate --yes --target-score 90 --max-usd 5Or run it as a daemon:
gbrain autopilot --install cron-driven, 5-minute tickHealthy brains sleep for 60 minutes between ticks. Unhealthy people get a full cycle overnight: synchronization, extraction, inclusion, combination, and synthesis. three stages (synthesize, patterns, consolidate) is protected so that the agent connected to the MCP cannot silently copy API credits.
For working in a custom background,… Minions The queue takes shell functions and LLM subagent functions side by side:
gbrain jobs submit sync --params '{}' --follow
gbrain jobs stats
gbrain jobs work --queue defaultOne caveat for PGLite: gbrain jobs supervisor (Working daemon for auto restart). PostgreSQL only. PGLite’s exclusive file lock blocks the separate worker process – the CLI rejects with an apparent error if config.engine === 'pglite'. If you’re using PGLite, stick with the built-in font --follow Functions for tutorial, or playback gbrain migrate --to supabase Before he became a diligent worker.
Routing rule: Imperative work (pulling tweets, parsing JSON, writing a page) goes to Minions; The adjudication work (sorting incoming mail, evaluating priority) goes to the LLM sub-agents.
What just happened, in one graph
markdown files ──andgt; PGLite + pgvector andlt;──andgt; 43 skills
(your repo, (hybrid retrieval + (HOW to use the brain;
source of truth) typed graph) RESOLVER.md routes intent)
▲ │
└────────────── agent reads/writes ──────────┘The markdown repo is a system of record. GBrain is the retrieval layer + the graph above it. The proxy reads and writes through both, and humans can always open either .md file and edit it directly – gbrain sync Captures change.
Where do you go next?
- Capture one line (New in version 0.38):
gbrain capture "the thought I want to remember"Lands directly ininbox/YYYY-MM-DD-. Also accepts--file,--stdinand accommodate webhook viagbrain serve --http /ingest. - Migrate to Supabase When your brain excels locally (PGLite is good for ~50k pages):
gbrain migrate --to supabase. - Understanding real data Using one of the recipes: Voice (Twilio + OpenAI Realtime), Email + Calendar, 16 embed providers, and Credential Gateway.
- Running standards In the gbrain-evals sibling repo: BrainBench (synthetic) and
gbrain eval longmemeval(General LongMemEval standard). - Create your own skills. A skill is a large reduction file that encodes the workflow – triggers, checks and quality gate.
gbrain check-resolvableValidate skill tree for ACCESSIBILITY/MECE/DRY.
The deeper bet behind GBrain is just that Harness thin, fat skills It excels at the subtle skills behind the fat factor. Run time remains small; The intelligence lives in markdown files that the agent reads at decision time. Every commit you make in your brain’s repository is a permanent context that your agent inherits the next time it wakes up. The longer it runs, the smarter it becomes.
Visual explanation of Marktechpost
Key takeaways
- GBrain (version 0.38.2.0) provides AI clients with a reduced, persistent memory layer first – created by Garry Tan to power his OpenClaw/Hermes deployments containing 146,646 pages and 24,585 people.
- Installation runs locally in about 30 minutes on PGLite (Postgres 17 compiled to WASM, serverless) and scales to Supabase or self-hosted Postgres when needed.
- Each wiki link is parsed by a regex inference chain (
FOUNDED → INVESTED → ADVISES → WORKS_AT) which writes written graph edges without LLM calls. - The hybrid search (vector + BM25 + RRF + ZeroEntropy reranker) reaches P@5 49.1% / R@5 97.9% on BrainBench – a +31.4 points higher P@5 compared to the disabled variant of the chart.
- Shows 74 widgets via MCP – connect them to Claude Code with one widget
claude mcp add gbrain -- gbrain serveAnd your agent can read/write the brain directly.
verify github Repo and Implementation codes. Also, feel free to follow us on twitter Don’t forget to join us 150k+ mil SubReddit And subscribe to Our newsletter. I am waiting! Are you on telegram? Now you can join us on Telegram too.
Do you need to partner with us to promote your GitHub Repo page, face hug page, product release, webinar, etc.? Contact us
