Give Your Agent a Persistent Memory

GBrain is a persistent knowledge base that gives your Hermes Agent, Claude Code, or Gemini CLI long-term memory across sessions, enhancing their capabilities with searchable data and autonomous learning.

| 7 min read
GBrain is a persistent knowledge base that gives your Hermes Agent, Claude Code, or Gemini CLI long-term memory across sessions, enhancing their capabilities with searchable data and autonomous learning.

🧠 Give Your Hermes Agent a Persistent Memory with GBrain

TL;DR

GBrain is a persistent knowledge base that gives your Hermes Agent (and Claude Code/Gemini CLI) long-term memory across sessions. Install it in ~30 minutes via your agent — it auto-creates a searchable brain of meetings, emails, ideas, and code. Your agent becomes 17,888 pages smarter over time, with hybrid search, auto-linking, cron jobs that run while you sleep, and full MCP integration. MIT licensed, runs locally (PGLite) or on Supabase.

Context

Your Ubuntu system runs:

  • Hermes Agent
  • Claude Code CLI
  • Gemini CLI

The problem: Every session starts fresh. Your agents forget yesterday's decisions, meeting notes, who works where, and what you learned.

Garry Tan (YC President) built GBrain to solve this for his own OpenClaw/Hermes deployment. Production numbers from his personal brain:

  • 17,888 pages, 4,383 people, 723 companies
  • 21 cron jobs running autonomously
  • Built in 12 days
  • Agent ingests meetings, emails, tweets, voice calls while he sleeps
  • Every cycle adds knowledge — the brain compounds daily

GBrain is those patterns, generalized into 29 skills you install in 30 minutes.

The Approach

Step 1: Install GBrain via Your Hermes Agent (30 minutes)

SSH into your Ubuntu VPS and paste this into your Hermes Agent:

Retrieve and follow the instructions at:
https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md

Your agent clones GBrain, sets up the brain, loads 29 skills, and configures recurring jobs. You answer a few questions about API keys.

Alternative (standalone CLI, no agent):

git clone https://github.com/garrytan/gbrain.git && cd gbrain && bun install && bun link
gbrain init                     # local brain, ready in 2 seconds
gbrain import ~/notes/          # index your markdown
gbrain query "what themes show up across my notes?"

Step 2: Connect GBrain to Your Agents

For Hermes Agent / Claude Code (MCP server): Add to your MCP config (e.g., ~/.claude/server.json for Claude Code):

{
  "mcpServers": {
    "gbrain": { "command": "gbrain", "args": ["serve"] }
  }
}

Now your agents have 30+ MCP tools: gbrain search, gbrain get, gbrain put, gbrain query, gbrain graph-query, etc.

For GStack users (you have Claude Code CLI): GBrain integrates with GStack via hosts/gbrain.ts. Run:

gbrain init  # auto-detects GStack, reports mod status

Then GStack's coding skills (/review, /investigate, /plan-eng-review) check the brain before coding.

Step 3: Import Your Existing Data

# Import markdown notes
gbrain import ~/notes/

# Import from Obsidian, Notion, Logseq
gbrain migrate --from obsidian --path ~/obsidian-vault

# Import meeting transcripts (Circleback, etc.)
gbrain meeting-ingest ~/meetings/

# Index code repos (Cathedral II)
gbrain sources add ~/your-repo --strategy code
gbrain code-def functionName    # where is X defined?
gbrain code-callers functionName # who calls this?

Step 4: Set Up Recurring Brain Maintenance

# One maintenance cycle (run via cron)
gbrain dream --dry-run          # preview what would happen
gbrain dream --phase 1          # enrichment only

# Or let your agent schedule it via the cron-scheduler skill
# The brain auto-enriches entities while you sleep

The dream cycle scans every conversation, enriches missing entities, fixes broken citations, and consolidates memory. You wake up and the brain is smarter.

Step 5: Query Your Brain from Any Agent

# Natural language query (hybrid search)
gbrain query "what have I said about founder-market fit?"

# Get a specific page
gbrain get people/alice

# Graph query: who works at Acme AI?
gbrain graph-query companies/acme-ai --type works_at --direction in

# Search code symbols
gbrain code-def HermesAgent
gbrain code-callers searchKeyword

Why It Worked

1. Self-wiring knowledge graph — zero LLM calls

Every page write extracts entity references and creates typed links (attended, works_at, invested_in, founded, advises) with regex patterns, not LLMs. The graph wires itself. Benchmarked on a 240-page corpus:

  • Precision@5: 49.1% (vs 22.1% without graph)
  • Recall@5: 97.9%
  • Beats hybrid search without graph by +31.4 points P@5

2. Compiled truth + timeline pattern

Every page has:

  • Above --- : Compiled truth (current best understanding, gets rewritten when evidence changes)
  • Below --- : Timeline (append-only evidence trail, never edited)

This means your agent can distinguish "what we know now" from "what happened when" — critical for accurate recall.

3. Minions: deterministic work costs $0

The minion-orchestrator skill runs deterministic scripts as Postgres jobs, not LLM sub-agents.

Real production numbers (19 cron jobs, 45,000-page brain):

Task Sub-agents Minions
Wall time >10,000ms (timeout) 753ms
Token cost ~$0.03/run $0.00
Success rate 0% (couldn't spawn) 100%
Memory/job ~80 MB ~2 MB

4. Hybrid search with 20-layer deterministic pipeline

The brain doesn't rely on one trick. Every query goes through: intent classifier → multi-query expansion → vector search → keyword search → RRF fusion → cosine re-scoring → compiled truth boost → backlink boost → source-aware dedup. Each layer covers what the others miss.

Measured improvement (BrainBench v1, 240 pages):

Metric Before PR #188 After Δ
Precision@5 39.2% 44.7% +5.4 pts
Recall@5 83.1% 94.6% +11.5 pts
Correct in top-5 217 247 +30

5. Skillify: bugs become structurally impossible to repeat

Say "skillify it!" after fixing a bug. GBrain creates a SKILL.md with triggers, a deterministic script with tests, and a routing fixture. The bug can't recur — the fix is now a permanent part of your agent's workflow.

Apply It Yourself

Prerequisites on Your Ubuntu VPS

  • Ubuntu 20.04+ with Bun v1.0+, Git
  • Hermes Agent (or Claude Code CLI / Gemini CLI)
  • (Optional) API keys for enrichment: Anthropic, OpenAI, Groq (Whisper for audio)

Quick Start (30 minutes, via agent)

From your Hermes Agent:

1. Point your agent to: https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md
2. Answer ~5 questions about API keys
3. The agent clones, installs, sets up the brain, loads 29 skills
4. Run: gbrain import ~/Documents/notes/
5. Run: gbrain query "what work have I been doing?"

From CLI (no agent, 2 seconds to working brain):

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

# Initialize (PGLite local, zero config)
gbrain init

# Import your markdown
gbrain import ~/your-notes/

# Search
gbrain query "meeting notes from last week"

# Add a page
echo "# Meeting with Alice\n\nDiscussed Q3 planning" | gbrain put meetings/2026-04-28-alice

# See what you have
gbrain list --type person

Commands You'll Use Daily

When you want to... Command
Ask your brain a question gbrain query "what did I say about X?"
Read a specific page gbrain get people/alice
Write a new page echo "content" | gbrain put slug
Import a folder of notes gbrain import ~/folder/
Find who works somewhere gbrain graph-query companies/acme --type works_at
Find code definitions gbrain code-def functionName
Run one maintenance cycle gbrain dream
Check brain health gbrain doctor
List all skills gbrain skillpack list
Install a curated skill gbrain skillpack install brain-ops

Connect GBrain to Claude Code or Gemini CLI

MCP server (add to your agent's config):

{
  "mcpServers": {
    "gbrain": { "command": "gbrain", "args": ["serve"] }
  }
}

Now your agents can call GBrain tools natively.

For Claude Code specifically:

# Add to ~/.claude/server.json (create if missing)
claude mcp add gbrain -- gbrain serve

Set Up Remote MCP (for Claude Desktop, Cowork, Perplexity)

# Expose via ngrok (requires paid plan for fixed URL)
ngrok http 8787 --url your-brain.ngrok.app

# Create an auth token
bun run src/commands/auth.ts create "claude-desktop"

# Add to Claude Desktop
claude mcp add gbrain -t http https://your-brain.ngrok.app/mcp \
  -H "Authorization: Bearer TOKEN"

Import Real Data from Your Workflows

From email (Gmail):

  • The credential-gateway + email-to-brain recipes auto-set up via gbrain integrations
  • Your agent asks for Gmail OAuth, then every email becomes a brain page with entities

From meetings (Circleback, Google Meet):

# Download transcripts, then:
gbrain meeting-ingest ~/Downloads/meeting-transcripts/
# Every attendee gets enriched, every company gets a timeline entry

From Twitter/X:

# Recipe auto-setup via gbrain integrations
# Your timeline, mentions, and deletions become brain pages

From voice calls:

  • Set up voice-to-brain recipe (Twilio + OpenAI Realtime)
  • Call a phone number, your AI answers with full context from the brain
  • Transcript appears as a brain page automatically

Troubleshooting

gbrain init fails?

# Ensure Bun is installed
curl -fsSL https://bun.sh/install | bash
# Re-run init
gbrain init --force

Skills not loading in Hermes?

# Check resolver
gbrain check-resolvable --verbose
# Auto-fix common issues
gbrain doctor --fix

Search returning poor results?

# Regenerate embeddings
gbrain embed --all --stale
# Re-extract graph links
gbrain extract links --source db

Worker crashes? Use the supervisor:

gbrain jobs supervisor --concurrency 4 --detach
gbrain jobs status --json

Uninstall:

rm -rf ~/.gbrain ~/.config/gbrain
# Remove from MCP config manually

Source

  • GitHub Repository: garrytan/gbrain
  • License: MIT
  • Documentation:
    • AGENTS.md — agent operating protocol
    • llms.txt / llms-full.txt — documentation map for LLMs
    • skills/RESOLVER.md — skill dispatcher (29 skills)
    • docs/ — MCP guides, minions deployment, plugin authoring
  • Benchmarks: gbrain-evals — BrainBench corpus and scorecards
  • Integration with GStack: See hosts/gbrain.ts and USING_GBRAIN_WITH_GSTACK.md in the gstack repo

The bottom line: Your Hermes Agent is smart but forgetful. GBrain gives it a persistent, self-improving memory. Install in 30 minutes, then every session builds on the last. The brain wires itself while you sleep.