What is GBrain? A memory layer for agents that should not start cold
Your AI agent is smart but forgetful.
That is the opening line of GBrain’s README, and it is the cleanest way to explain the project. Most agent sessions start cold. They do not know your projects, people, companies, conventions, decisions, or recurring mistakes unless you paste everything back in. GBrain is an attempt to give agents a durable personal knowledge brain.
Not a notes app in the usual sense. Not just vector search. A brain.
The distinction matters because a useful agent memory system has to do more than store text. It has to ingest, link, retrieve, route, and explain. It needs to know where a page came from, what entities it mentions, how those entities relate, and which brain or source an agent is supposed to query.
That is the problem GBrain is trying to solve.
who built it
GBrain is built by Garry Tan and open-sourced at:
The README says it is the production brain powering his OpenClaw and Hermes deployments, with thousands of pages, people, companies, and autonomous cron jobs. I would treat those exact numbers as a snapshot from the README rather than a timeless claim, but the broader point is clear: GBrain was not designed as a toy memory demo. It came from a working personal-agent stack.
The relationship to Gstack is explicit in the repo’s CLAUDE.md: GStack teaches agents how to code; GBrain teaches agents everything else — brain operations, signal detection, ingestion, enrichment, scheduling, reports, identity, and access control.
That is a useful split. Gstack is the software factory. GBrain is the institutional memory.
the secret sauce
The secret sauce is hybrid memory: markdown pages, graph links, entity extraction, timeline, search, and skills tied together.
A basic RAG system chunks documents, embeds them, and retrieves nearest neighbors. That is useful, but it misses a lot. If you ask “who works at Acme AI?” pure vector search may find relevant prose if the wording overlaps. A graph can answer through relationships: person -> works_at -> company. GBrain’s README emphasizes typed links like attended, works_at, invested_in, founded, and advises, plus hybrid search and backlink-boosted ranking.
That means the brain is not only a semantic index. It is a living knowledge graph.
The other key idea is routing. GBrain has two axes that agents must not confuse:
- brain = which database
- source = which repo inside that database
A brain might be your personal database. A source might be your wiki, a project repo, a Gstack note collection, or an imported writing folder. This matters because the same slug can exist in different sources, and different brains can have different owners or access policies.
The docs make the rule simple: if the data owner changes, it is a brain boundary. If the owner stays the same but the repo/topic changes, it is a source boundary.
That sounds like an implementation detail, but it is actually core to agent safety. A memory tool that retrieves the wrong source can quietly poison the answer.
why it is useful
The more agents you use, the more painful context fragmentation becomes.
Claude Code may inspect a repo and discover a test convention. Hermes may research a library and write an implementation note. A browser agent may find docs. A cron job may summarize news. A human may make a decision in Obsidian. If all of that stays trapped in separate transcripts, your next session starts cold.
GBrain gives those systems a shared context layer.
Good uses include:
- project briefs
- architecture notes
- coding conventions
- people and company pages
- meeting notes
- investment or industry research
- recurring decisions
- glossary pages
- agent mistakes to avoid
- source banks for future writing
- timelines of what changed
The goal is not to dump everything forever. The goal is to preserve the things that repeatedly reduce future steering.
Research becomes notes. Notes become graph nodes. Graph nodes become retrievable context. Context improves future research. Future research enriches the graph.
how to set it up
The supported install pattern is clone plus Bun link:
git clone https://github.com/garrytan/gbrain.git ~/gbrain
curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"
cd ~/gbrain
bun install
bun link
gbrain --version
Then initialize:
gbrain init
gbrain doctor --json
On a fresh install, warnings are not automatically failure. GBrain defaults to PGLite, an embedded Postgres-via-WASM setup, so the first version can run without standing up a server. The docs also mention Postgres + pgvector / Supabase as a scale path, especially once you have many files.
If you already have markdown content, import and embed it:
gbrain import ~/brain --no-embed
gbrain embed --stale
gbrain query "what are the key themes across these documents?"
For an Obsidian-based Knowledge OS, I would not index the entire vault casually on day one. A better pattern is to start with a curated folder or explicit sources.
using GBrain with Claude Code
Claude Code is strongest inside a repo. It can inspect files, edit code, run tests, and iterate. GBrain makes it better by giving it project memory before it starts.
A good prompt shape:
Use GBrain as project memory.
First read the project brief, architecture notes, commands, and known pitfalls.
Then inspect the repo and propose a plan before editing.
After the task, suggest durable notes that should be written back to GBrain.
That final step is important. The point is not only to retrieve memory. It is to update memory after meaningful work.
If Claude discovers that a test suite depends on a specific environment variable, that should become a note. If it finds that a generated file should not be edited manually, that should become a note. If it learns a deployment gotcha, that should become a note.
The next agent should not have to rediscover it.
using GBrain with Hermes
Hermes and GBrain are a natural pair.
Hermes is good at orchestration: research, cron jobs, web search, tool use, publishing, messaging, and multi-step workflows. GBrain is good at durable retrieval and graph memory.
Example workflow:
- Hermes researches a topic.
- It writes a source bank and distilled notes.
- Those notes go into GBrain or Obsidian.
- Hermes uses the notes to draft a public Knowledge OS post.
- The post is synced and published.
- GBrain indexes the result for future retrieval.
Another workflow:
- Hermes runs a daily industry-analysis cron.
- It stores important people, companies, and claims.
- GBrain links entities automatically.
- Later, you ask: “What has changed about this company over the last month?”
- The answer can use both semantic search and the graph.
That is more powerful than a folder of markdown because the structure becomes queryable.
examples of leverage
The most obvious GBrain use case is project continuity. Every repo gets a small operating manual: how to run it, how to test it, what conventions matter, and what mistakes agents keep making.
The second use case is people and company intelligence. If your work involves investors, founders, startups, public companies, or research labs, entity memory matters. “Who mentioned this company?” and “what did we learn about this founder?” are graph-shaped questions.
The third use case is writing. A blog post is usually the last mile of a longer knowledge chain. GBrain can preserve source notes, claims, caveats, related concepts, and prior arguments, so future writing compounds instead of repeating.
The fourth use case is cron-generated intelligence. A scheduled agent can collect information while you sleep, but without a brain the output is just a daily pile. With GBrain, each run can enrich the long-term map.
the caveat
Memory is dangerous when it is invisible.
If an agent silently remembers wrong facts, stale paths, or outdated decisions, it can become confidently wrong. That is why GBrain’s explicit structure matters. Markdown pages can be inspected. Sources can be scoped. Brains can be separated. Skills can encode routing rules. Bad memory can be edited.
The best memory system is not the one that stores the most. It is the one that stores the right things, retrieves them with the right scope, and lets humans correct the map.
That is why GBrain is interesting. It turns agent memory from vibes into infrastructure.