gbrain/docs/GBRAIN_SKILLPACK.md

GBrain Skillpack: Reference Architecture for AI Agents

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.

---

Core Patterns

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

Data Pipelines

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

Operations

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.

Architecture

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

Integrations

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

Administration

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

Getting Started

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.

---

Appendix: GBrain CLI Quick Reference

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.

---

Architecture & Philosophy

• 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