This is a reference architecture for how a production AI agent uses gbrain as its knowledge backbone. Based on patterns from a real deployment with 14,700+ brain files, 40+ skills, and 20+ cron jobs running continuously.
The memex vision, realized. Vannevar Bush imagined a device where an individual stores everything, mechanized so it may be consulted with exceeding speed. GBrain is that device, except the memex builds itself. The agent detects entities, enriches pages, creates cross-references, and maintains compiled truth automatically.
Each section below is a standalone guide. Click through to the full content.
The foundational read-write loop and data model.
| Guide | What It Covers |
|---|---|
| The Brain-Agent Loop | The read-write cycle that makes the brain compound over time |
| Entity Detection | Run it on every message. Capture original thinking + entity mentions |
| The Originals Folder | Capturing WHAT YOU THINK, not just what you found |
| Brain-First Lookup | Check the brain before calling any external API |
| Compiled Truth + Timeline | Above the line: current synthesis. Below: append-only evidence |
| Source Attribution | Every fact needs a citation. Format and hierarchy |
Getting data in and keeping it current.
| Guide | What It Covers |
|---|---|
| Enrichment Pipeline | 7-step protocol, tier system (Tier 1/2/3 by importance) |
| Meeting Ingestion | Always pull complete transcript, propagate to all entity pages |
| Content & Media Ingestion | YouTube, social media bundles, PDFs/documents |
| Diligence Ingestion | Data room materials: pitch decks, financial models, cap tables |
| Deterministic Collectors | Code for data, LLMs for judgment. The collector pattern |
| Idea Capture & Originals | Depth test, originality distribution, deep cross-linking |
| Getting Data In | Integration recipes: voice, email, X, calendar |
Running a production brain.
| Guide | What It Covers |
|---|---|
| Reference Cron Schedule | 20+ recurring jobs, quiet hours, dream cycle |
| Cron via Minions | Why scheduled work runs as Minion jobs, not agentTurn. Auto-applied by v0.11.0 migration for built-in handlers; host-specific handlers use the plugin contract below. |
| Plugin Handlers | Registering host-specific Minion handlers via code (no data-file exec surface). |
| Minions fix | Repairing a half-migrated v0.11.0 install. |
| Shell jobs (v0.14.0+) | Move deterministic crons (API fetch, token refresh, scrape+write) off the LLM gateway. Zero tokens per fire, ~60% gateway headroom. Follow skills/migrations/v0.14.0.md for the adoption playbook. |
| Quiet Hours & Timezone | Hold notifications during sleep, timezone-aware delivery |
| Executive Assistant Pattern | Email triage, meeting prep, scheduling |
| Operational Disciplines | Signal detection, brain-first, sync-after-write, heartbeat, dream cycle |
| Skill Development Cycle | 5-step cycle: concept, prototype, evaluate, codify, cron |
Subagent routing (v0.11.0+): agents that dispatch background work should route through
skills/conventions/subagent-routing.md — it reads ~/.gbrain/preferences.json#minion_mode
and branches between native subagents and Minion jobs. The v0.11.0 migration auto-injects
a marker into AGENTS.md pointing at this convention.
Cron routing (v0.11.0+): scheduled work goes through Minions, not OpenClaw's agentTurn.
See skills/conventions/cron-via-minions.md for the rewrite pattern. The v0.11.0 migration
auto-rewrites entries whose handler is a gbrain builtin; host-specific handlers (e.g.
ea-inbox-sweep) need a code-level registration per docs/guides/plugin-handlers.md.
How to structure your system.
| Guide | What It Covers |
|---|---|
| Two-Repo Architecture | Agent repo vs brain repo, boundary rules, decision tree |
| Sub-Agent Model Routing | Which model for which task, signal detector pattern, cost optimization |
| The Three Search Modes | Keyword, hybrid, direct. When to use each |
| Brain vs Agent Memory | 3 layers: GBrain (world knowledge), agent memory, session |
Wiring up your life.
| Guide | What It Covers |
|---|---|
| Credential Gateway | ClawVisor / Hermes for Gmail, Calendar, Contacts |
| Meeting & Call Webhooks | Circleback transcripts + Quo/OpenPhone SMS/calls |
| Voice-to-Brain | Phone calls + WebRTC browser calls create brain pages. 25 production patterns: identity separation, bid system, conversation timing, proactive advisor, prompt compression, caller routing, dynamic VAD, real-time logging, belt-and-suspenders post-call |
| Email-to-Brain | Gmail messages flow into entity pages via deterministic collector |
| X-to-Brain | Twitter monitoring with deletion detection + engagement velocity |
| Calendar-to-Brain | Google Calendar events become searchable daily brain pages |
| Meeting Sync | Circleback transcripts auto-import with attendee propagation |
Keeping it running and up to date.
| Guide | What It Covers |
|---|---|
| Upgrades & Auto-Update | check-update, agent notifications, migration files |
| Live Sync | Keep the index current: cron, --watch, webhook approaches |
After setup, the brain is empty. The cold-start skill sequences the highest-leverage data sources to populate it:
| Guide | What It Covers |
|---|---|
| Cold Start | Day-one bootstrapping: contacts, calendar, email, conversations, social, archives. Uses ClawVisor for safe credential handling — agents never hold raw API keys. |
| Ask User | Choice-gate pattern for human input at decision points. Used by cold-start and other skills. |
| Command | Purpose |
|---|---|
gbrain search "term" |
Keyword search across all brain pages |
gbrain query "question" |
Hybrid search (vector + keyword + RRF) |
gbrain get <slug> |
Read a specific brain page by slug |
gbrain sync |
Sync local markdown repo to gbrain index |
gbrain import <path> |
Import files into the brain |
gbrain embed --stale |
Re-embed pages with stale or missing embeddings |
gbrain integrations |
Manage integration recipes (senses + reflexes) |
gbrain stats |
Show brain statistics (page count, last sync, etc.) |
gbrain doctor |
Diagnose brain health issues |
gbrain check-update |
Check for new versions and integration recipes |
Run gbrain --help for the full command reference.
- Infrastructure Layer — Import pipeline, chunking, embedding, search
- Thin Harness, Fat Skills — Architecture philosophy
- Markdown Skills as Recipes — Why markdown is code and your agent is a package manager
- Homebrew for Personal AI — The 10-star vision
- Recommended Schema — Directory structure for your brain repo
- Verification Runbook — End-to-end installation verification