About garrytan/gbrain
garrytan/gbrain is an open-source project on GitHub, mainly written in TypeScript. Garry's Opinionated OpenClaw/Hermes Agent Brain It currently holds 32,386 stars and 4,821 forks with 811 open issues, and was last pushed on 2026-11-10 (repository created 2026-04-05).
Project Overview
Git Homed tracks it on the Today's Trending board.
GitHub Repository Details
README
One brain for you and your company, read by every agent you use. Put your own notes and your company's docs in one place: a facts page, a decisions log, call transcripts. Claude Code, Codex and your other agents look there before they answer, so they stop starting from zero and work from what you and your team actually wrote down.
GBrain is MIT-licensed and free to self-host, and it starts with no API keys: search is by keyword until you add one. gbrain.io is optional paid hosting.
[!TIP]
Need hosted? First time running an agent? Try gbrain.io, hosted GBrain, for the easiest experience: one brain for you and your team, connected to ChatGPT, Claude and Cursor, with nothing to install or keep online. Stuck? Email support@gbrain.io and a person will set it up with you, free.
A few minutes after you install it:
- Every new Claude Code or Codex session looks in your brain before it answers, without being told to.
- Anything you ask your agent to remember is still there in the next session, in every agent connected to the brain.
- Your notes and your company's docs are searchable, and your agent answers questions like "what did we decide about pricing, and why?" from them.
| How it connects | Agents |
|---|---|
| One command wires memory, hooks and instructions | Claude Code (gbrain setup claude-code), Codex (gbrain setup codex) |
| MCP from its guide, then gbrain setup adds the brain-first instructions | OpenClaw, Hermes, opencode, Cursor |
| MCP from its guide | ChatGPT, Claude Desktop, Claude Cowork, Perplexity, Grok Build, Grok Bot, Muse, Windsurf and other stdio clients |
| Any other coding agent | Paste the install prompt below |
Stability
New releases come out many times a day, but the install command below gives you the stable channel: a release reaches it only after the full test suite and a two-hour, 600,000-page load test pass on that exact release, and only when an important fix is waiting or stable is a week old. Updates are never installed without your say-so unless you turn on automatic upgrades. After an upgrade, gbrain shows a one-time notice listing what changed in behaviour. Stable also comes with a written promise about which commands, flags, tools, config keys and output fields stay the same, and how much warning you get before one changes. docs/STABILITY.md explains that promise, how often stable moves, how to pin a version or go back, and what the faster alpha channel is for.
Install
[!TIP]
Fastest: hosted GBrain at gbrain.io, for any harness. One command launches a GBrain hosted on gbrain.io; Claude Code, Codex, ChatGPT, Cursor and every other AI you use connect to it, with nothing to keep online.
>> curl -sSL https://gbrainio.terminalwire.sh | bash
gbrainio terminal connect # in a new terminal
gbrainio workspace new # pick a plan in the browser
curl -fsSL https://bun.sh/install | bash # skip if Bun 1.4.4+ is installed
export PATH="$HOME/.bun/bin:$PATH"
bun install -g github:garrytan/gbrain#stable # the gbrain CLI only; no local brain
# Claude Code (an existing gbrain entry is kept):
(claude mcp get gbrain >/dev/null 2>&1 || claude mcp add --transport http --scope user gbrain https://gbrain.io/mcp) && gbrain setup claude-code --instructions-only
# Codex (an existing gbrain entry is kept):
(codex mcp get gbrain >/dev/null 2>&1 || codex mcp add gbrain --url https://gbrain.io/mcp) && gbrain setup codex --instructions-only
>gbrain setup --instructions-onlytells the agent the brain is there; agents seldom call an MCP server nobody told them about. It writes the brain-first block into~/.claude/CLAUDE.mdor Codex'sAGENTS.md(a non-emptyAGENTS.override.mdinstead when Codex has one) with a per-turn rule hook, and leaves the MCP entry alone; the same command with--no-instructionsadded takes them out.
> The installer is a shell script for macOS and Linux; read it before you run it.
Here's how to self-host it
GBrain is MIT-licensed and free to self-host. It needs Bun 1.4.4 or newer; existing worker installs read the authorization and queue upgrade guide before restarting on this version.
[!WARNING]
GBrain is NOT distributed on npm. The npm gbrain package is unrelated and
can shadow the real binary, so never run npm install -g gbrain or
bun add -g gbrain. Install only viabun install -g github:garrytan/gbrain#stable
(the soaked stable channel; #latest-stable is the alpha line with every release)
orgit clone --branch stable+bun install && bun link. Installed by mistake?gbrain doctorgives the fix.
Schema not migrated (#218)? Run
gbrain apply-migrations --yes --no-autopilot-install; if it exits 1, rungbrain doctor --json, not another--yes(wedged: relay its fix).
bun install -g github:garrytan/gbrain#stable
gbrain setup claude-code # or: gbrain setup codex
gbrain init --pglite --no-embedding # any other harness, or no agent
gbrain setup shows what it will write first (--dry-run previews, --remove undoes), creates a keyless brain only if none exists, wires MCP, hooks and a brain-first block in the agent's instruction file (--no-instructions skips it), and smoke-tests them (setup guide). For any other coding agent, paste:
Add GBrain memory to this existing agent. Read and follow:
https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md
Keep my current identity and instructions, start keyless, and show me the
search-mode choice. Verify a remember/recall round trip with real GBrain calls.
Postgres, thin clients, API keys and upgrades: docs/INSTALL.md. Agents: INSTALL_FOR_AGENTS.md. Memory-only walkthrough: give your coding agent a memory.
Add your notes and your company's docs
Point GBrain at two folders of Markdown files: your own notes (an Obsidian vault works) and your company's docs. In the company folder, keep facts.md (numbers and statements agents may repeat), decisions.md (each decision with its date, its reason and who made it) and call transcripts saved as .md files.
gbrain sources add notes --path ~/notes --federated --force # your notes
gbrain sources add company --path ~/company --federated --force # company docs
gbrain sync --all # rerun after edits
Then open a new agent session and ask "What did we decide about a free plan, and why?": the answer comes from your decisions log. --federated puts the folder in default search, and --force accepts a folder that isn't a git repository; in a folder that is one, GBrain reads only committed files, so commit your edits before you sync. To see the shape first, gbrain sources demo company-brain runs a fictional company in a few seconds without touching your brain. Before you share a company brain with a team, read the company-brain tutorial.
GBrain is not a data warehouse or analytics store. Keep ads, analytics, CRM and payment data in your warehouse, and connect your agent to it separately.
CLI standalone (no agent)
gbrain init --pglite --no-embedding # keyless; no server, no Docker
gbrain import ~/notes/ --no-embed # index your markdown
gbrain search "a phrase from a note" --json
gbrain doctor # verify health
Optional: a new personal agent
To have GBrain create a new persistent personal agent with identity files and its own private GitHub repo, open Codex (CLI or ChatGPT desktop) or Claude Code in a new, empty folder and paste:
Read and follow every step of:
https://raw.githubusercontent.com/garrytan/gbrain/stable/BOOTSTRAP_FOR_AGENTS.md
Goal: set yourself up as my persistent personal agent in this folder, with gbrain
as your memory. Interview me before writing any identity file — never invent
answers. Ask before anything destructive. You are not done until
gbrain bootstrap verify exits 0.
The repo is not a complete backup; see the bootstrap guide. For the always-on version (24/7 ingestion and the overnight dream cycle on a server with 8GB+ RAM and its own API usage), run GBrain under OpenClaw or Hermes and point it at INSTALL_FOR_AGENTS.md; the personal-brain tutorial walks it end to end.
Connect GBrain to your AI client (MCP)
- Local stdio client:
gbrain setup claude-codeorgbrain setup codexregistersgbrain serve(lists the memory verbs;--surface fulllists every tool) behind gbrain's launcher, so a session opened in a cloned repository never loads that repository'sbunfig.tomlor.env, and adds the brain-first instructions: agents seldom call a brain nobody told them about. Cursor, Windsurf and other stdio clients take"$(command -v gbrain)" serve --surface starter --advertise verbs. - Plugins with curated skills: Codex
codex plugin marketplace add garrytan/gbrain@codex-plugin+codex plugin add gbrain@gbrain; Claude Code/plugin marketplace add garrytan/gbrain+/plugin install gbrain@gbrain. - This brain from anywhere:
gbrain mcp exposepublishes it on your Tailscale tailnet as a user service (--funnelfor cloud agents such as Grok Bot, Muse and ChatGPT). Guide. - A brain on another host:
gbrain connect https://your-host/mcp --token gbrain_xxx --install(add--agent codexfor Codex). Hosted brains use native OAuth or a private handoff; dashboard, clients and permissions live in MCP administration.
Keep skills beside knowledge. New local brains include memory skills in their content root. Agents can join an authorized catalog; only approved editors can publish. Managed coding-agent installs add an owned native router; restart and real-use verification are separate steps. Staged migration preserves sharing choices and personal edits. See shared brain skills.
Choose your setup
1. Add GBrain to my existing agent — recommended. Keep your agent's identity and save memory inside its environment. No new personal-agent identity or private repository is required. Start with the guide for Grok Bot, Muse, or Codex / Claude Code. Other harnesses.
2. Use the brain on my own computer from everywhere. One command publishes it over MCP on your Tailscale tailnet and keeps it running: gbrain mcp expose (add --funnel for cloud agents such as Grok Bot, Muse and ChatGPT). Follow use your brain from anywhere over MCP. Say to your agent: "use my brain over mcp" — "put my brain on tailscale".
3. Connect my existing hosted brain. Follow hosted harness access to choose native OAuth or a private machine connection. For dashboard login, clients, and permissions, use MCP administration with the server's separate owner credential. Delegation is an explicit choice.
Grok Bot and Grok Build are different products. Muse's personal agent and Muse Code are different products too. Muse already has native editable memory; GBrain adds an explicit, portable record with provenance and shared access. See each guide's dated evidence and remaining verification steps.
I'm Garry Tan, President and CEO of Y Combinator. I built GBrain to run my own AI agents. It's the production brain behind my OpenClaw and Hermes deployments: 155,795 pages, 24,589 people, 5,340 companies, 66 cron jobs running autonomously. My agent ingests meetings, emails, tweets, voice calls, and original ideas while I sleep. It enriches every person and company it encounters. It fixes its own citations and consolidates memory overnight. I wake up smarter than when I went to bed — and so will you.
It works as a company brain too. Authenticated remote clients are constrained by source and operation grants plus visibility filters. Local files and shared database credentials are a different trust boundary: sources alone do not isolate those callers. The authorization tests exercise specific access paths, not a universal no-leak guarantee. Read the sharing boundaries and company-brain tutorial before setting up shared access.
Alongside keyword and semantic retrieval, GBrain offers two optional ways to use your stored knowledge:
- A synthesis layer that gives you the actual answer. Synthesized, well-cited prose across people, companies, deals, and ideas. Not "here are 10 chunks that mention your query"; an actual answer with citations and an explicit note on what the brain doesn't know yet. The gap analysis is the part that changes how you use the brain.
- A typed knowledge graph. Trusted local page writes extract supported references without LLM calls when auto-linking is enabled. Remote
put_pageedges arrive later, via sweeps, maintenance oradd_link. Ask "who works at acme-example?": walks are breadth-first, milliseconds on dense clusters (how). On BrainBench relationship questions, relationship retrieval lifts production R@5 from 0.6626 to 0.7241 (benchmark); 0.9791 is thegraph-oracle-parseupper bound, not a product score.
It's easier to ship a daemon that runs 24/7 to ingest, enrich, and consolidate than it is to keep an agent in chat working hard. GBrain is that daemon, generalized. Install in 30 minutes. Your agent does the work. As my personal agent gets smarter, so does yours.
Start keyless. Your harness subscription and any separately configured model API usage are different costs. The optional personal-agent bootstrap takes about 15 minutes; always-on enrichment needs its own compute and API configuration.
Durable preferences and facts can be shared across agents; transient task and harness configuration state stay local. Configured cloud embedding, reranking, extraction, and synthesis providers can receive text, and the harness model sees recalled memory even in keyless mode. Markdown export is not a full database backup. Read memory boundaries.
LLMs: fetchllms.txtfor the documentation map, orllms-full.txtfor the same map with core docs inlined in one fetch. Agents: start withAGENTS.md(orCLAUDE.mdif you're Claude Code).
What this looks like
Say you have a meeting with Alice tomorrow. You want to walk in remembering what she works on, when you last talked, and what's still open between you. Here's what you'd type, and what you'd get back.
You ask:
"What do I need to know before my meeting with Alice tomorrow?"
Most personal-knowledge tools give you back a list of pages. Something like:
1. people/alice — Alice runs engineering at Acme...
2. meetings/2026-03-15-alice-q1 — Q1 product review with Alice...
3. meetings/2026-01-08-acme-kickoff — Kickoff meeting with Acme team...
4. customers/acme — Acme is a series-B fintech we work with...
5. notes/2026-04-22 — Quick chat with Alice about pricing...
Five pages you now have to open and read yourself to actually prepare. The tool found the right material, but it didn't do the work.
GBrain gives you back the answer, with sources:
Alice runs engineering at Acme (a series-B fintech). You last spoke
on April 22 in a quick pricing chat. Three things are still open
from that conversation:
1. She owes you the security review for the new tier
(deadline was May 1; no update since).
2. You committed to pricing for a 500-seat tier
(you sent it April 25; no response yet).
3. She mentioned they're hiring a CISO; you said you'd intro
someone from your network.
Heads up: nothing's been added to the brain about Alice or Acme
since April 22, six weeks ago. She may have replied through email
or Slack DM, channels the brain doesn't see. Worth asking her to
catch up before assuming any of this is still current.
Every claim has a source page behind it. The "heads up" at the end tells you what the brain doesn't know yet, so you can ask Alice about it directly instead of being surprised. The brain just did your meeting prep.
This is the difference between a search engine and a brain. Search finds the pages. The brain reads them for you and writes the answer.
Two ways to query your brain
Raw retrieval (what most personal-knowledge tools ship) and a synthesis layer that gives you an actual answer. They serve different jobs.
# raw retrieval: top pages by hybrid score, no answer-generation call
gbrain search "who's working on AI agents at portfolio companies?"
brain layer: synthesized answer with citations and gap analysis
gbrain think "who's working on AI agents at portfolio companies?"
gbrain search returns the top retrieved pages, ranked by hybrid scoring (vector + keyword + RRF + source-tier boost + reranker). Use it when you want raw material to skim: agent context windows, citation lookups, finding a specific quote.
Configured embedding and reranking providers can still receive text and charge for retrieval. Keyless keyword search needs no model API; synthesis requires a configured chat capability. See memory boundaries.
Search also tells you when its results are incomplete because projections are still rebuilding or a bounded vector scan ran short. Ask your agent *"Check whether my search index is ready"*; see search readiness and recovery before treating an empty result as proof that a page is missing.
gbrain think runs the same retrieval, then composes a synthesized answer across the results with explicit citations to the source pages AND an honest note on what the brain doesn't know yet. The gap analysis is the differentiator: the answer tells you when a page is stale, when a claim is uncited, when two pages contradict each other, when there's a hole you should fill.
Say to your agent: "What do we know about acme-example?" — "Tell me about alice-example before my meeting tomorrow" — "Search for who's working on AI agents." Your agent routes these to the brain automatically; you never type the commands yourself.
Why it compounds. Pair the brain layer with find_trajectory and you get answers like "how have the company's metrics changed AND what does the team look like right now AND what did they promise / share AND when did we last meet AND what's the value-add I can offer here": well-scored, well-cited, in one shot. That's the strategic moat. That's why building a 150K-page brain is worth the effort.
gbrain agent run "..." exposes the same surface to a sub-agent through the Minions queue, with crash-safe two-phase persistence. Same answers, durable.
How to get data in
Start with an explicit fact or a notes folder; opt into connectors, capture, and enrichment separately.
Already have a company knowledge repository? Say to your agent: *“Connect our
existing company brain, preserve its files, and show me the import plan first.”*
Try gbrain sources demo company-brain without keys or private data, then inspect
your committed Markdown with gbrain sources inspect --profile company-brain.
The company-brain ingestion guide covers
explicit destination approval, typed relationships, and resumable verification.
It does not enable embeddings, sharing, schedules, or curation automatically.
Say to your agent: "Remember this with its source" — "What should I import first?"
Data ingestion guide covers files, conversations, connectors, Google data, and capture commands.
Your brain's shape (schema packs)
Most personal-knowledge tools force one fixed layout: their idea of "notes" + "people" + "tags." Drop a Notion export or your own years-old Obsidian vault on top, and the agent doesn't know what a Projects/ folder means or whether Reading/ is people or sources.
gbrain doesn't have a fixed layout. It ships with bundled schema packs and lets you author your own when none fit:
gbrain-base-v2(default) — 15-type DRY/MECE canonical taxonomy (14 canonical +notecatch-all):person,company,media,tweet,social-digest,analysis,atom,concept,source,deal,email,slack,writing,project,note. Subtypes/format/origin pushed to frontmatter.gbrain-base(legacy) — the wider 24-type layout. Stays bundled for back-compat; brains on it can upgrade viagbrain onboard --check --explain→gbrain jobs submit unify-types --params '{"target_pack":"gbrain-base-v2","apply":true}'(omit"apply":truefor a dry-run preview — that is the default).gbrain-recommended— extendsgbrain-basewith the 13 additional directories fromdocs/GBRAIN_RECOMMENDED_SCHEMA.md(source, place, trip, conversation, personal, civic, project, etc.). Activate withgbrain schema use gbrain-recommended.- Your own pack —
gbrain schema detectclusters your actual filesystem into proposed types,gbrain schema suggestruns an LLM pass over them, andgbrain schema review-candidates --applypromotes the ones you like. Three commands and the brain knows your shape. Authoring a successor pack (declaresmigration_from:so existing brains can opt in): seedocs/architecture/pack-upgrade-mechanism.md.