Skip to content
Get packs

Guide · Open source

How to use GBrain: install, connect an agent and query memory

Updated · written with AI from the project's own documentation and checked against our catalogue data

GBrain is an open-source (MIT) memory layer for AI agents that you run yourself. It stores explicit facts with their sources, lets you correct or withdraw them, and can share the same memory across several agents. This guide explains what it is good for, how to install it with Bun, how to connect it to an agent, and where its limits are so you can decide whether it fits.

GBraingarrytan/gbrain · ★ 31.4k · MIT

Quick start

  1. 1Check the prerequisite. Install Bun 1.4.4 or newer. GBrain will not run on older versions as described in the README.
  2. 2Install GBrain. Run the global Bun install from GitHub, or clone the repository and link it locally.
  3. 3Avoid the npm package. Do not install the npm gbrain package, because it is unrelated and can shadow the real binary.
  4. 4Connect your agent. Follow the guide for your agent, such as Codex or Claude Code, to save memory inside its environment.
  5. 5Expose the brain if needed. Run gbrain mcp expose to publish the brain over MCP on your tailnet, adding --funnel for cloud agents.
  6. 6Review boundaries. Read the memory boundaries and sharing guides before storing sensitive facts or sharing a brain.

Check whether GBrain fits your setup

GBrain is aimed at people who already use an AI agent such as OpenClaw, Hermes, Codex or Claude Code and want it to remember things across sessions. It is also aimed at developers who are comfortable running a Bun-based TypeScript tool and a local database.

  • Good fit: you want memory you control, with explicit facts and their sources.
  • Good fit: you want to start without paying for embedding or LLM APIs, since retrieval begins with keywords and needs no API keys.
  • Poor fit: you want a simple consumer app. The README points non-technical users to the hosted gbrain.io service instead.
  • Poor fit: you need a guaranteed no-leak access model for shared brains. The README says its authorization tests cover specific paths, not every case.

Install GBrain with Bun

GBrain requires Bun 1.4.4 or newer. The README gives two install routes: a global install from GitHub, or cloning the repository and linking it locally.

  • Global install: run the Bun install command from the README.
  • Local install: clone the repository, then run bun install and bun link from inside it.
  • Do not use npm or a bare bun add -g gbrain. The README says GBrain is not distributed on npm and the npm gbrain package is unrelated.
bun install -g github:garrytan/gbrain

Understand the two install routes

The clone route is the one to use if you want the source in front of you. The README gives the clone command and then the local link step.

  • Clone: git clone https://github.com/garrytan/gbrain
  • Then, inside the cloned folder: bun install && bun link
git clone https://github.com/garrytan/gbrain

Connect GBrain to your agent

The README recommends adding GBrain to an agent you already have. Your agent keeps its identity and saves memory inside its environment. No new personal-agent identity or private repository is required. Guides exist for Grok Bot, Muse, and Codex or Claude Code, and other clients connect over MCP.

To use your brain from other devices, the README describes one command that publishes it over MCP on your Tailscale tailnet and keeps it running. Adding --funnel exposes it for cloud agents.

  • Existing agent: start with the guide for your agent (Codex or Claude Code tutorial in the docs).
  • Remote access over MCP: gbrain mcp expose, with --funnel for cloud agents.
  • Hosted brain: use the hosted harness access guide and the MCP administration guide.
gbrain mcp expose

Know what is stored and what leaves your machine

Durable preferences and facts can be shared across agents, while transient task and harness configuration state stays local. The README warns that configured cloud embedding, reranking, extraction, and synthesis providers can receive text, and that the harness model sees recalled memory even in keyless mode.

Markdown export is not a full database backup, according to the README. Treat it as a readable copy, and keep proper database backups.

  • Keyless start: keyword retrieval needs no API keys.
  • Optional later: semantic search, synthesized answers, and background enrichment.
  • Read the memory boundaries guide before storing anything sensitive.

Share a brain with a team carefully

GBrain supports a shared company brain. Remote clients are constrained by source and operation grants plus visibility filters. Local files and shared database credentials are a different trust boundary, and the README says sources alone do not isolate those callers.

Read the sharing boundaries and company-brain tutorial before setting up shared access.

  • Use explicit grants for each source and operation.
  • Remember that local files and shared database credentials bypass those grants.

What people use it for

  • Giving a coding agent such as Codex or Claude Code memory that persists across sessions.
  • Keeping facts about people, companies and deals with their sources so you can correct them later.
  • Sharing one self-hosted knowledge base across several agents with explicit access grants.
  • Asking a question of your stored notes and getting a cited answer instead of a list of pages.

Frequently asked questions

Is GBrain free?

GBrain is released under the MIT licence, according to the project's listing. Your agent subscription and any separately configured model API usage are separate costs, and always-on enrichment needs its own compute and API setup.

What do I need to run GBrain?

You need Bun 1.4.4 or newer. The README says it is a Bun-based TypeScript tool that uses a local database, so you should be comfortable with that setup.

How do I install GBrain?

Run bun install -g github:garrytan/gbrain, or clone the repository and run bun install and bun link. Do not install the npm gbrain package, which is unrelated.

Does GBrain need API keys?

No. The README says it starts with keyless memory and keyword retrieval. Semantic search, synthesis, and background enrichment are optional additions you can configure later.

Is there an alternative if I don't want to self-host?

The README points users who want a hosted option to gbrain.io, which offers hosted GBrain with nothing to install. The project listing names no comparable projects.

Can I use GBrain as a backup of my data?

No. The README says Markdown export is not a full database backup, so keep proper database backups alongside it.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

GBrain suits developers who already run an AI agent, are comfortable with Bun and a local database, and want memory they control that starts without API keys. Pick the hosted gbrain.io service if you are non-technical, and avoid relying on its shared-brain access controls where a guaranteed no-leak model is required.

Install options & downloads