Agent Frameworks, ย CLI & DevTooling
Give Your Agent a Persistent Memory
Date Published
# ๐ง 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):**
```bash
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):
```json
{
"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:
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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):**
```bash
# 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):**
```json
{
"mcpServers": {
"gbrain": { "command": "gbrain", "args": ["serve"] }
}
}
```
Now your agents can call GBrain tools natively.
**For Claude Code specifically:**
```bash
# Add to ~/.claude/server.json (create if missing)
claude mcp add gbrain -- gbrain serve
```
### Set Up Remote MCP (for Claude Desktop, Cowork, Perplexity)
```bash
# 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):**
```bash
# Download transcripts, then:
gbrain meeting-ingest ~/Downloads/meeting-transcripts/
# Every attendee gets enriched, every company gets a timeline entry
```
**From Twitter/X:**
```bash
# 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?**
```bash
# Ensure Bun is installed
curl -fsSL https://bun.sh/install | bash
# Re-run init
gbrain init --force
```
**Skills not loading in Hermes?**
```bash
# Check resolver
gbrain check-resolvable --verbose
# Auto-fix common issues
gbrain doctor --fix
```
**Search returning poor results?**
```bash
# Regenerate embeddings
gbrain embed --all --stale
# Re-extract graph links
gbrain extract links --source db
```
**Worker crashes?** Use the supervisor:
```bash
gbrain jobs supervisor --concurrency 4 --detach
gbrain jobs status --json
```
**Uninstall:**
```bash
rm -rf ~/.gbrain ~/.config/gbrain
# Remove from MCP config manually
```
---
## Source
- **GitHub Repository**: [garrytan/gbrain](https://github.com/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](https://github.com/garrytan/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.