setup

Setup GBrain

Set up GBrain from scratch. Target: working brain in under 2 minutes.

Contract

• Setup completes with a working brain verified by gbrain doctor --json (all checks OK).
• The brain-first lookup protocol is injected into the project's AGENTS.md or equivalent.
• Schema state is tracked in ~/.gbrain/update-state.json so future upgrades know what the user adopted or declined.
• No external database or API key is required for core operations.

Install (if not already installed)

bun add github:sixtycat2000-ctrl/gbrain-qmd

How GBrain Works

GBrain is fully local. All data lives on your machine -- no cloud database required.

• QMD handles search, indexing, and embedding (local Qwen3-Embedding-0.6B model)
• SQLite stores domain data (pages, links, tags, timeline, versions)
• Filesystem stores content files (~/.gbrain/data/content/) and attachments (~/.gbrain/data/files/)

No DATABASE_URL, no Supabase, no OpenAI API key for core operations. Search works offline.

Optional: configure an Expander API key (Anthropic or OpenAI) for enhanced query expansion via gbrain query.

Prerequisites

• Bun runtime (for running gbrain)
• ~1GB disk space for QMD embedding model (downloaded automatically on first embed)
• A git-backed markdown knowledge base (or start fresh)
• Optional: Anthropic or OpenAI API key for Expander-enhanced search

Available init options

• gbrain init -- interactive setup (creates data directory, initializes SQLite + QMD)
• gbrain doctor --json -- health check after init

Phase A: Initialize Data Directory

1. Run init to create the data directory and initialize everything:

   gbrain init
   

   This creates:

   • ~/.gbrain/data/brain.db (SQLite database)
   • ~/.gbrain/data/content/ (markdown content files)
   • ~/.gbrain/data/files/ (attachments)
   • ~/.gbrain/data/qmd-index.sqlite (QMD search index)

2. Verify setup:

   gbrain doctor --json
   

Phase B: Configure Expander (Optional)

For enhanced search with query expansion, set environment variables:

# Choose provider: anthropic (default), openai, openrouter, or custom
export GBRAIN_EXPAND_PROVIDER=anthropic
export GBRAIN_EXPAND_MODEL=claude-haiku-4-5-20251001

# Set the API key for your chosen provider
export ANTHROPIC_API_KEY=sk-ant-...
# or for OpenAI: export OPENAI_API_KEY=sk-...

Without an API key, gbrain uses the QMD local expansion model (1.7B GGUF, auto-downloaded) -- search works with full lex/vec/hyde expansion, no cloud dependency.

Phase C: First Import

1. Discover markdown repos. Scan the environment for git repos with markdown content.

echo "=== GBrain Environment Discovery ==="
for dir in /data/* ~/git/* ~/Documents/* 2>/dev/null; do
  if [ -d "$dir/.git" ]; then
    md_count=$(find "$dir" -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null | wc -l | tr -d ' ')
    if [ "$md_count" -gt 10 ]; then
      total_size=$(du -sh "$dir" 2>/dev/null | cut -f1)
      echo "  $dir ($total_size, $md_count .md files)"
    fi
  fi
done
echo "=== Discovery Complete ==="

2. Import the best candidate. For large imports (>1000 files), use nohup to survive session timeouts:

   nohup gbrain import <dir> --no-embed > /tmp/gbrain-import.log 2>&1 &
   

   Then check progress: tail -1 /tmp/gbrain-import.log

   For smaller imports, run directly:

   gbrain import <dir>
   

3. Prove search works. Pick a keyword query based on what you imported:

   gbrain search "<topic from the imported data>"
   

   This works immediately -- no API keys needed for keyword search.

4. Run embedding. Generate embeddings for semantic search (downloads ~640MB model on first run):

   gbrain embed
   

If no markdown repos are found, create a starter brain with a few template pages (a person page, a company page, a concept page) from docs/GBRAIN_RECOMMENDED_SCHEMA.md.

Phase D: Brain-First Lookup Protocol

Inject the brain-first lookup protocol into the project's AGENTS.md (or equivalent). This replaces grep-based knowledge lookups with structured gbrain queries.

BEFORE (grep) vs AFTER (gbrain)

Task	Before (grep)	After (gbrain)
Find a person	grep -r "Pedro" brain/	gbrain search "Pedro"
Understand a topic	grep -rl "deal" brain/ | head -5 && cat ...	gbrain query "what's the status of the deal"
Read a known page	cat brain/people/pedro.md	gbrain get people/pedro
Find connections	grep -rl "Brex" brain/ | xargs grep "Pedro"	gbrain query "Pedro Brex relationship"

Lookup sequence (MANDATORY for every entity question)

1. gbrain search "name" -- keyword match, fast, works offline
2. gbrain query "what do we know about name" -- Expander-enhanced search (needs API key for full expansion)
3. gbrain get <slug> -- direct page read when you know the slug from steps 1-2
4. grep fallback -- only if gbrain returns zero results AND the file may exist outside the indexed brain

Stop at the first step that gives you what you need. Most lookups resolve at step 1.

Sync-after-write rule

After creating or updating any brain page in the repo, sync immediately so the index stays current:

gbrain sync --no-pull

This indexes new/changed files without pulling from git.

gbrain vs memory_search

Layer	What it stores	When to use
gbrain	World knowledge: people, companies, deals, meetings, concepts, media	"Who is Pedro?", "What happened at the board meeting?"
memory_search	Agent operational state: preferences, decisions, session context	"How does the user like formatting?", "What did we decide about X?"

Both should be checked. gbrain for facts about the world. memory_search for how the agent should behave.

Phase E: Load the Production Agent Guide

Read docs/GBRAIN_SKILLPACK.md. This is the reference architecture for how a production agent uses gbrain: the brain-agent loop, entity detection, enrichment pipeline, meeting ingestion, cron schedules, and the five operational disciplines.

Inject the key patterns into the agent's system context or AGENTS.md:

1. Brain-agent loop (Section 2): read before responding, write after learning
2. Entity detection (Section 3): spawn on every message, capture people/companies/ideas
3. Source attribution (Section 7): every fact needs [Source: ...]
4. Iron law back-linking (Section 15.4): every mention links back to the entity page

Tell the user: "The production agent guide is at docs/GBRAIN_SKILLPACK.md. It covers the brain-agent loop, entity detection, enrichment, meeting ingestion, and cron schedules. Read it when you're ready to go from 'search works' to 'the brain maintains itself.'"

Phase F: Health Check

Run gbrain doctor --json and report the results. Every check should be OK. If any check fails, the doctor output tells you exactly what's wrong and how to fix it.

Error Recovery

If any gbrain command fails, run gbrain doctor --json first. Report the full output. It checks SQLite integrity, QMD index status, content directory, and embedding coverage.

What You See	Why	Fix
SQLite not found	Data directory missing	Run gbrain init
QMD index not found	No content indexed	Import files then run gbrain embed
No pages found	Query before import	Import files into gbrain first
Embedding model download failed	Network issue or disk space	Ensure ~1GB free, re-run gbrain embed

Phase G: Auto-Update Check

If the user's install did NOT include setting up auto-update checks, offer it:

"Would you like daily GBrain update checks? I'll let you know when there's a new version worth upgrading to -- including new skills and schema recommendations. You'll always be asked before anything is installed."

If they agree:

1. Test: gbrain check-update --json
2. Register daily cron (see GBRAIN_SKILLPACK.md Section 17)

If already configured or user declines, skip.

Schema State Tracking

After presenting the recommended directories (Phase C/E) and the user selects which ones to create, write ~/.gbrain/update-state.json recording:

• schema_version_applied: current gbrain version
• skillpack_version_applied: current gbrain version
• schema_choices.adopted: directories the user created
• schema_choices.declined: directories the user explicitly skipped
• schema_choices.custom: directories the user added that aren't in the recommended schema

This file enables future upgrades to suggest new schema additions without re-suggesting things the user already declined.

Anti-Patterns

• Skipping health check. Never declare setup complete without running gbrain doctor --json and confirming all checks pass. A failed check means setup is incomplete.
• Declaring setup without verification. "The command ran" is not the same as "it worked." Search for something you imported to prove the brain is functional.
• Importing without proving search. The magical moment is the user seeing search find things grep couldn't. Don't skip it.
• Ignoring schema state. Without update-state.json, future upgrades cannot distinguish what the user adopted vs declined.

Output Format

SETUP COMPLETE
==============

Engine: QMD + SQLite (local)
Pages imported: N
Embeddings: N/N (keyword search active, semantic improving)
Health check: all OK / [specific failures]

Next steps:
- Read docs/GBRAIN_SKILLPACK.md for production agent patterns
- [any pending items]

Tools Used

• gbrain init -- create local data directory and initialize brain
• gbrain import <dir> [--no-embed] -- import files
• gbrain search <query> -- keyword search brain (offline)
• gbrain query <query> -- Expander-enhanced search
• gbrain doctor --json -- health check
• gbrain check-update --json -- check for updates
• gbrain embed -- generate embeddings via QMD local model
• gbrain reindex -- full re-index of all content
• gbrain stats -- page count + embed coverage
• gbrain sync --no-pull -- index new/changed files