gbrain: a memory you control, for agents that forget

Repo: garrytan/gbrain · MIT · TypeScript on Bun

Agents forget. Every new session starts blank unless you give it somewhere to look things up. gbrain is an open-source, self-hosted memory layer built for exactly that — its README's promise is "a memory you control".

What it does

• Stores facts with their sources, and supports corrections and withdrawals, so the memory can change its mind on the record.
• Retrieves with keyword plus semantic search, and can walk a typed knowledge graph.
• Offers an optional synthesis step that returns cited answers and says what the brain doesn't know yet.
• Runs on PGLite (Postgres compiled to WebAssembly) with zero setup, or on full Postgres with pgvector for bigger, shared deployments.

One practical warning from the README: install it as documented. It's not on npm, and an unrelated npm package uses the same name.

How I use it

My scanner pipeline is operated by Hermes Agent. Every night a small script exports new or changed Hermes sessions into a folder gbrain indexes. It tracks what it exported last time, so running it twice does nothing harmful. The result: the agent can answer "why did we add the price filter?" or "what did the last backtest say about options flow?" with a citation instead of a guess.

The one-line fix worth stealing

My server environment sets a DATABASE_URL for the scanner's main Postgres database. gbrain would happily pick that up — and try to use the production signals database as its memory store. The fix is a tiny wrapper script that loads the agent's environment without DATABASE_URL, so gbrain always uses its own PGLite store. Every gbrain call goes through the wrapper.

It's a good general lesson: when two tools read the same environment variable, decide explicitly which one gets it.

When a memory layer is worth it

• Your agent runs unattended and repeatedly, and decisions build on each other.
• You need citations, not vibes, when the agent explains itself.
• You want the memory on your own disk, exportable and correctable.

For a one-off chatbot, skip it. For an agent with a job, memory is the difference between an assistant and a colleague.