GBrain: a Postgres-backed memory layer for OpenClaw, Hermes, Claude Code and Codex

The problem GBrain targets: agents that forget everything that is not code

Coding agents are good at the repository in front of them and bad at everything else. A meeting note, a pricing thread, a call transcript: none of it survives the session unless you paste it back in. GBrain is the memory layer for that gap, and the README frames the target audience narrowly: people running OpenClaw, Hermes Agent, Claude Code or Codex who want earlier work retrievable later. The author, Garry Tan, describes it as the production brain behind his own OpenClaw and Hermes deployments, with 155,795 pages, 24,589 people, 5,340 companies and 66 cron jobs running autonomously. Those are the author's own deployment numbers, not an independent benchmark, and they describe scale rather than quality.

The sharper claim is about output shape. The README contrasts a conventional retrieval result (a ranked list of five pages you still have to read) with a synthesized answer that carries citations and an explicit statement of what the brain does not know. That gap analysis is the part worth evaluating, because it is the piece most retrieval tools skip.

How the retrieval stack works: hybrid search, typed edges, synthesis

The package description in package.json calls it a "Postgres-native personal knowledge brain with hybrid RAG search." The repository layout supports that: src/core/search/hybrid.ts and src/core/search/expansion.ts sit alongside src/core/think/, src/core/embedding.ts and src/core/link-extraction.ts. Search is hybrid rather than vector-only, and there is a separate expansion stage before results reach the model.

The graph is the second mechanism. The README states that every page write extracts entity references and creates typed edges (attended, works_at, invested_in, founded, advises) with zero LLM calls. That last detail matters: edge creation is deterministic extraction, so graph growth does not multiply your token bill. Queries like "who works at Acme AI?" are answered by traversal, which the README argues vector search alone cannot reach.

Storage is Postgres, with PGLite as the embedded option. The README claims the database is ready in 2 seconds either way, with no server. The engine is swappable: package.json exports ./pglite-engine and ./engine-factory as separate entry points, and src/core/pglite-lock.ts suggests single-writer locking is a real concern in the embedded mode. On benchmarks, the README reports P@5 49.1% and R@5 97.9% on a 240-page Opus-generated rich-prose corpus, described as +31.4 points P@5 over the graph-disabled variant. Those figures come from the author's own BrainBench scorecards, published in the sibling gbrain-evals repository, so treat them as vendor-reported until you reproduce them on your own corpus.

Installing GBrain and wiring it into Claude Code

GBrain is not on npm. The README carries a warning that the npm package named gbrain is unrelated and can shadow the real binary on your PATH. Install from GitHub instead, using the documented command:

bun install -g github:garrytan/gbrain

The alternative documented path is a clone plus a local link:

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

If you already ran the npm install by mistake, the README gives the recovery sequence: npm uninstall -g gbrain or bun remove -g gbrain, then reinstall from GitHub. After installation, verify the environment:

gbrain doctor

The README states that gbrain doctor detects a shadowing npm install and prints the fix. That is the first command worth running, before you ingest anything. The repository also ships AGENTS.md, CLAUDE.md and llms.txt so that an agent can read its own setup instructions; the README says to start with AGENTS.md, or CLAUDE.md if you are on Claude Code. The README estimates roughly 15 minutes to a working personal agent on the Codex or Claude Code path, mostly a short interview, and about 30 minutes for the always-on OpenClaw or Hermes setup. Client wiring is documented in an MCP table in the README, and there is a CLI standalone route if you would rather not involve an agent at all.

Where GBrain stops being the right tool

The install warning is a real operational hazard, not a footnote. A globally installed package with the same name can take precedence on PATH, and the failure mode is silent: you get a different program. The project mitigates it with gbrain doctor, but the mitigation depends on you running that command.

Cost is the second boundary. The README is explicit that the always-on OpenClaw or Hermes configuration carries real server and API cost, while the Codex and Claude Code paths deploy nothing. If your goal is continuous overnight ingestion and enrichment, you are paying for that, and the README does not publish a cost estimate. The 66 cron jobs in the author's deployment are not a free baseline.

The third boundary is scope. GBrain is built for personal and small-team institutional memory. If your actual problem is retrieving chunks from a large static document corpus, a conventional RAG pipeline over a vector store is simpler, and the graph traversal and synthesis layers are overhead you will not exercise. The README's own comparison is against "ripgrep-BM25 + vector-only RAG," which tells you what the author considers the baseline, not what every reader needs. The README does not document rollback or uninstall procedures for an ingested brain, so plan your data layout before you start loading it.

GBrain vs Hermes and OpenClaw: a layer, not a replacement

Search data around this project mixes up two different things. Hermes Agent and OpenClaw are the agent runtimes; GBrain is the memory layer underneath them. The README describes GBrain as the production brain behind the author's OpenClaw and Hermes deployments, and gives OpenClaw or Hermes as the always-on path. Installing GBrain does not give you an agent, and installing an agent does not give you a brain.

The comparison that matters is against the retrieval you already have. Claude Code and Codex both have built-in context handling and file search; those work on the repository and on files you point them at. GBrain adds a persistent store that survives across sessions and across projects, plus entity edges and synthesis. The README positions the Codex path as the recommended first step precisely because it adds the brain without the deployment.

Against a general note-taking system with a search plugin, the difference is the answer layer. A note tool returns matching notes. GBrain returns prose with citations and a note about what is missing. Whether that is better depends on whether you want to read your notes or be briefed by them.

Maintenance, licensing and what the repository tells you

The last push to the default branch was on 2026-08-29, and the most recent release listed is v0.47.5.0 on the same date, following v0.47.4.0 and v0.47.3.0 within the preceding two days. The version numbering is four-part and the cadence in that window was rapid. The repository is not archived. Whether that pace continues is not something the material can tell you; the release history shows what happened through late August 2026 and nothing after it.

GBrain is MIT licensed, per the LICENSE file at the repository root. MIT is permissive: it allows commercial use and modification, and it comes without warranty. That last part is worth stating plainly rather than as boilerplate, because GBrain is designed to ingest meetings, emails, tweets and voice calls into a database you operate. The licence does not govern your obligations to the people whose data you are loading. If you deploy the company-brain shape the README describes, where each person gets a slice scoped by login, the compliance question is about your own data handling, not about MIT.

Upgrade cost is partly structural. The README says to upgrade only through the documented GitHub paths, so an upgrade is a reinstall from the same source rather than a package-manager version bump. The repository ships docker-compose.ci.yml and docker-compose.test.yml, and the package.json build scripts produce compiled binaries for darwin-arm64 and linux-x64, which suggests the project tests and ships across those targets.

Editorial conclusion

Adopt GBrain if you already run Claude Code, Codex, OpenClaw or Hermes and keep losing context between sessions, and start on the Codex path because it deploys nothing. Skip it if you want a hosted product, if you cannot run Postgres or PGLite locally, or if keyword search over your notes is genuinely enough. Before trusting it with anything sensitive, run gbrain doctor to confirm no npm-installed binary is shadowing the real one, and read docs/tutorials/company-brain.md to see how the per-login scoping is meant to be configured.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes