garrytan/gbrain · 33k stars · Intermediate · 15 min · 2026-11-15

Give your coding agents a shared memory with garrytan/gbrain

GBrain is a self-hosted brain for your notes and company docs that Claude Code, Codex and other agents search before they answer, and a place where facts you ask them to remember survive into the next session.

TL;DR

GBrain gives every agent you use one shared brain: your Markdown notes, your company docs, and facts you told an agent to remember. Install it with Bun, create a keyless local brain, run gbrain setup claude-code (or codex), and new sessions look in the brain before answering. It starts with no API keys; search is by keyword until you add one.

Why this repo matters

The README's pitch is that agents "stop starting from zero". Instead of re-explaining pricing decisions or last week's call, your agents read what you and your team wrote down: a facts page, a decisions log, call transcripts. Facts you ask an agent to remember are still there in the next session, and in every other agent connected to the same brain. It is MIT-licensed and free to self-host; gbrain.io is optional paid hosting.

Best practices

  • Start keyless. The README says GBrain starts with no API keys and searches by keyword until you add one. Add embeddings or synthesis only when you decide to.
  • Always give a memory its source. The remember verb requires provenance (where you learned it, with the date). The connect tutorial verifies the round trip by reading the fact back with its provenance.
  • Tell the agent the brain exists. The README says agents seldom call an MCP server nobody told them about, so gbrain setup <harness> writes a brain-first instruction block into CLAUDE.md or Codex's AGENTS.md.
  • Preview before it writes. gbrain setup shows what it will write first; --dry-run previews and --remove undoes it.
  • Verify recall in a new session. The tutorial says an answer from the current conversation is not evidence of persistent recall.
  • Keep analytics out. The README says GBrain is not a data warehouse; keep ads, analytics, CRM and payment data elsewhere.

How-to

Where do I start?

1. Install the CLI

Where do I get it? Not from npm: the README warns the npm gbrain package is unrelated and can shadow the real binary. You need Bun 1.4.4 or newer.

bun install -g github:garrytan/gbrain#stable
gbrain engine status --json

Next: Create a keyless brain

Try it

Run the remember/recall round trip above with a unique phrase. Open a brand-new agent session without repeating the phrase and ask for it, watching for the actual recall call. Then ask the agent to forget the test fact and confirm it no longer appears in active recall.

Pitfalls

  • npm install -g gbrain or bun add -g gbrain installs an unrelated package. Use the GitHub install only.
  • Two stdio servers on one PGLite brain will fight over the lock. Share one brain across harnesses with a hosted or gbrain mcp expose setup instead.
  • Embedding, reranking and synthesis providers you configure can receive text; the README's memory-boundaries guide says where text goes.
  • Markdown export is not a full database backup.

Next steps