How to Set Up GBrain: A Simple Tutorial for AI Agent Memory

AI agents (Like OpenClaw/Hermes Agent) are getting smarter fast. But most of them still have one big problem: they forget.

You can ask an AI tool to write code, summarize notes, or help with research. It works well in the moment. Then tomorrow, you ask a follow-up question, and the agent acts like it has never met you before.

That is the gap GBrain tries to fix.

GBrain is an open-source tool that gives AI agents a long-term memory layer. Think of it as a private brain for your notes, docs, ideas, projects, and team knowledge. It can import Markdown files, index them, search them, and expose that knowledge to AI agents through the CLI or MCP (Model Context Protocol).

In simple words: GBrain helps your AI agent remember your work.

This guide walks through what GBrain is, why it matters, and how to set it up from scratch.

What Is GBrain?

GBrain is a memory and knowledge system for AI agents (OpenClaw/Hermes Agent).

It can:

Store your Markdown notes and docs
Import an existing folder or knowledge base
Search your content with keyword search and vector search
Connect to AI coding tools through MCP
Build links between related pages
Run local-first with PGLite
Scale to Postgres and pgvector for bigger setups

The basic idea is simple: your agent should not depend only on chat history. It should have a real knowledge base it can query when it needs context.

That makes GBrain useful for:

Developers using AI coding agents
Startup teams building shared knowledge bases
Researchers with large notes collections
Content creators managing ideas and scripts
Solo builders who want a personal AI memory system

Why GBrain Matters

The AI agent market is moving toward longer workflows.

People no longer want a chatbot that only answers one question. They want an assistant that can understand a project, remember decisions, track files, and help over many weeks.

That needs memory.

Without memory, AI agents waste time. They ask the same questions. They repeat old mistakes. They miss context hidden in notes or docs.

GBrain gives the agent a structured place to look before it answers.

A simple example: You have a folder with product notes, meeting summaries, customer feedback, and technical docs. Instead of pasting all of that into ChatGPT, you import the folder into GBrain. Then your AI agent can search the brain when needed.

It is not magic. It is a practical memory layer.

What You Need Before Installing GBrain

Before starting, make sure you have:

Requirement	Why it matters
Git	For cloning and managing projects
Bun	GBrain runs on Bun and TypeScript
Terminal access	To run install commands
Markdown files	Your notes, docs, or knowledge base
API key for embeddings	Optional, but useful for vector search

GBrain works without an embedding provider. In that case, keyword search still works. For better semantic search, you can add providers like ZeroEntropy, OpenAI, Voyage, or Anthropic depending on your setup.

Step 1: Install Bun

GBrain uses Bun as its runtime.

Run this command:

curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"

Then check Bun:

bun --version

If the command is not found, restart your terminal or add Bun to your shell profile.

Step 2: Install GBrain

Install GBrain globally from GitHub:

bun install -g github:garrytan/gbrain

Check the install:

gbrain --version

If you see a version number, the CLI is ready.

If the install fails or gbrain doctor later shows schema_version: 0, run:

gbrain apply-migrations --yes

If that still fails, use the deterministic install path:

git clone https://github.com/garrytan/gbrain.git ~/gbrain
cd ~/gbrain
bun install
bun link

Step 3: Create Your Brain

Now initialize GBrain:

gbrain init --pglite

PGLite means you can run GBrain locally without setting up a full database server. For most personal setups, this is enough.

Then run:

gbrain doctor --json

This checks your setup and reports what is working or missing.

If something is yellow or red, read the output. GBrain usually tells you the exact fix command.

Step 4: Add API Keys

API keys are optional for basic keyword search, but recommended for better retrieval.

You can set keys as environment variables:

export ZEROENTROPY_API_KEY=ze-...
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

Or save them through GBrain config:

gbrain config set zeroentropy_api_key sk-...
gbrain config set anthropic_api_key sk-ant-...

GBrain uses ZeroEntropy as a default embedding and reranking option in recent versions because it is designed for fast, lower-cost retrieval. You can still use other providers if that fits your stack better.

Step 5: Pick a Search Mode

After init, GBrain may ask you to choose a search mode. This matters because search mode controls how much context GBrain sends downstream to your AI model.

Mode	Best for	Notes
Conservative	Low-cost setups	Tight context budget, fewer chunks
Balanced	Everyday use	Good middle ground
Tokenmax	Frontier models	More context, higher cost

For most solo users, balanced is a safe starting point.

To set it:

gbrain config set search.mode balanced

Check available modes:

gbrain search modes

If you are running high-volume agent loops, be careful with tokenmax. More context can mean better answers, but also higher model cost.

Step 6: Import Your Notes or Docs

Now point GBrain at your knowledge folder.

Example:

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

This imports Markdown files without generating embeddings yet.

Then run:

gbrain embed --stale

This creates or refreshes embeddings for content that needs it.

Test with a query:

gbrain query "What are the key themes in my notes?"

If you do not have embedding keys configured, keyword search can still work. Semantic results will improve after embeddings are enabled.

Step 7: Sync Your Brain Over Time

Your notes will change. GBrain can keep up.

For manual sync:

gbrain sync --repo ~/my-knowledge

For live sync:

gbrain sync --watch

For a more automated setup, install autopilot:

gbrain autopilot --install

This can help with background maintenance and enrichment.

Step 8: Connect GBrain to an AI Agent

GBrain can run as an MCP server.

For local stdio MCP:

gbrain serve

Some coding agents can connect directly. Example commands from the GBrain docs:

claude mcp add gbrain -- gbrain serve
codex mcp add gbrain -- gbrain serve

For HTTP MCP:

gbrain serve --http

HTTP mode is more useful for shared or remote setups. It can support auth, admin tools, scopes, and dashboards. For a solo local workflow, stdio is simpler.

Step 9: Check Health

Use these commands often:

gbrain doctor
gbrain doctor --json
gbrain models
gbrain models doctor

These help you see:

Which models are configured
Whether API keys are working
Whether the database is healthy
Whether migrations are needed
Whether search is ready

A clean doctor result means your brain is in good shape.

Common GBrain Commands

Here is a quick command list:

Command	What it does
`gbrain --version`	Check installed version
`gbrain init --pglite`	Create a local brain
`gbrain doctor`	Check system health
`gbrain import ~/folder`	Import notes or docs
`gbrain embed --stale`	Embed new or changed content
`gbrain query "question"`	Ask the brain a question
`gbrain sync --watch`	Watch files and sync changes
`gbrain serve`	Start MCP stdio server
`gbrain serve --http`	Start HTTP MCP server
`gbrain upgrade`	Upgrade GBrain and run migrations

PGLite vs Postgres: Which One Should You Use?

For most people, start with PGLite.

Option	Best for	Setup
PGLite	Solo users, small projects	Simple, local, no server
Postgres + pgvector	Teams, large brains, shared agents	More setup, better scale

If your brain has more than 1,000 Markdown files or needs multi-user access, GBrain may suggest Postgres with pgvector, often through Supabase. Do not overbuild early. Start local. Upgrade when the brain grows.

Practical Use Cases

GBrain is useful when the same knowledge needs to be reused many times.

Examples:

1. Personal AI Memory

Import your notes, ideas, bookmarks, and project docs. Your agent can search them before answering.

2. Coding Agent Context

Connect GBrain to a coding agent. It can remember architecture notes, decisions, bugs, and conventions.

3. Startup Knowledge Base

A team can store company docs, meeting notes, customer insights, and product decisions in one brain.

4. Research Assistant

Researchers can use GBrain to search large Markdown collections and surface related ideas.

5. Content Creation System

Creators can store scripts, outlines, topic ideas, and brand rules. The AI assistant can write with better context.

Best Practices

Keep your brain clean.

A few simple rules help:

Use Markdown files
Name files clearly
Group notes by topic
Avoid dumping random text without structure
Run gbrain doctor after upgrades
Use balanced search mode unless you know you need more
Keep API keys private
Back up your brain folder

GBrain gets more useful as your knowledge base becomes more organized. Garbage in, garbage out still applies.

Troubleshooting

GBrain command not found

Restart your terminal or add Bun to PATH:

export PATH="$HOME/.bun/bin:$PATH"

Schema version is 0

Run migrations:

gbrain apply-migrations --yes

Search quality is weak

Check API keys and embeddings:

gbrain models doctor
gbrain embed --stale

Large import feels slow

Start with a smaller folder first. For bigger brains, consider Postgres + pgvector.

Agent cannot access GBrain

Make sure the MCP server is running:

gbrain serve

Then check the agent MCP config.

Final Thoughts

GBrain is part of a larger shift in AI tools.

The next wave of agents will not just answer prompts. They will remember projects, follow context, and work across time. For that, they need a brain.

GBrain gives builders a practical way to start today. It is local-first, open-source, and flexible enough for both solo users and teams.

If you already keep your work in Markdown, GBrain is especially interesting. You can turn an existing notes folder into a searchable AI memory layer without moving everything into a closed platform.

Start small. Import a folder. Run a few queries. Connect it to your agent when ready.

That is the real promise: less copy-pasting, less repeated context, and an AI assistant that finally remembers what matters.

FAQ

Is GBrain free?

GBrain is open-source. You may still pay for API usage, embeddings, hosting, or database services depending on your setup.

Do I need embeddings to use GBrain?

No. Keyword search can work without embeddings. But embeddings improve semantic search and retrieval quality.

Can I use GBrain locally?

Yes. The easiest setup is local with PGLite. No full database server is required.

Is GBrain only for developers?

No. Developers may benefit first, but writers, researchers, founders, and creators can use it too if they work with Markdown notes.

What is the best search mode for beginners?

Balanced. It gives a good mix of quality and cost control.

Resource: https://github.com/garrytan/gbrain

Teknoding Fathurrahman is a writer and blogger at Teknoding.com. He has written many articles about technology for 5 years. Fathurrahman is driven by a desire to help others understand technology. He makes complex concepts easy to understand, making technology accessible to a wider audience. His articles are engaging narratives that help readers understand the digital world. Fathurrahman is also an active member of the tech community, sharing knowledge and insights with other enthusiasts and experts.

Teknoding EN