Repository: garrytan/gbrain

Stars: 8857

CLAUDE.md Copy Chapter

CLAUDE.md

GBrain is a personal knowledge brain and GStack mod for agent platforms. Pluggable
engines: PGLite (embedded Postgres via WASM, zero-config default) or Postgres + pgvector
+ hybrid search in a managed Supabase instance. gbrain init defaults to PGLite;
suggests Supabase for 1000+ files. GStack teaches agents how to code. GBrain teaches
agents everything else: brain ops, signal detection, content ingestion, enrichment,
cron scheduling, reports, identity, and access control.

Architecture Copy Chapter

Contract-first: src/core/operations.ts defines ~30 shared operations. CLI and MCP
server are both generated from this single source. Engine factory (src/core/engine-factory.ts)
dynamically imports the configured engine ('pglite' or 'postgres'). Skills are fat
markdown files (tool-agnostic, work with both CLI and plugin contexts).

Trust boundary: OperationContext.remote distinguishes trusted local CLI callers
(remote: false set by src/cli.ts) from untrusted agent-facing callers
(remote: true set by src/mcp/server.ts). Security-sensitive operations like
file_upload tighten filesystem confinement when remote=true and default to
strict behavior when unset.

Key files Copy Chapter

- src/core/operations.ts — Contract-first operation definitions (the foundation). Also exports upload validators: validateUploadPath, validatePageSlug, validateFilename. OperationContext.remote flags untrusted callers.
- src/core/engine.ts — Pluggable engine interface (BrainEngine). clampSearchLimit(limit, default, cap) takes an explicit cap so per-operation caps can be tighter than MAX_SEARCH_LIMIT.
- src/core/engine-factory.ts — Engine factory with dynamic imports ('pglite' | 'postgres')
- src/core/pglite-engine.ts — PGLite (embedded Postgres 17.5 via WASM) implementation, all 37 BrainEngine methods
- src/core/pglite-schema.ts — PGLite-specific DDL (pgvector, pg_trgm, triggers)
- src/core/postgres-engine.ts — Postgres + pgvector implementation (Supabase / self-hosted)
- src/core/utils.ts — Shared SQL utilities extracted from postgres-engine.ts
- src/core/db.ts — Connection management, schema initialization
- src/commands/migrate-engine.ts — Bidirectional engine migration (gbrain migrate --to supabase/pglite)
- src/core/import-file.ts — importFromFile + importFromContent (chunk + embed + tags)
- src/core/sync.ts — Pure sync functions (manifest parsing, filtering, slug conversion)
- src/core/storage.ts — Pluggable storage interface (S3, Supabase Storage, local)
- src/core/supabase-admin.ts — Supabase admin API (project discovery, pgvector check)
- src/core/file-resolver.ts — File resolution with fallback chain (local -> .redirect.yaml -> .redirect -> .supabase)
- src/core/chunkers/ — 3-tier chunking (recursive, semantic, LLM-guided)
- src/core/search/ — Hybrid search: vector + keyword + RRF + multi-query expansion + dedup
- src/core/search/intent.ts — Query intent classifier (entity/temporal/event/general → auto-selects detail level)
- src/core/search/eval.ts — Retrieval eval harness: P@k, R@k, MRR, nDCG@k metrics + runEval() orchestrator
- src/commands/eval.ts — gbrain eval command: single-run table + A/B config comparison
- src/core/embedding.ts — OpenAI text-embedding-3-large, batch, retry, backoff
- src/core/check-resolvable.ts — Resolver validation: reachability, MECE overlap, DRY checks, structured fix objects
- src/core/backoff.ts — Adaptive load-aware throttling: CPU/memory checks, exponential backoff, active hours multiplier
- src/core/fail-improve.ts — Deterministic-first, LLM-fallback loop with JSONL failure logging and auto-test generation
- src/core/transcription.ts — Audio transcription: Groq Whisper (default), OpenAI fallback, ffmpeg segmentation for >25MB
- src/core/enrichment-service.ts — Global enrichment service: entity slug generation, tier auto-escalation, batch throttling
- src/core/data-research.ts — Recipe validation, field extraction (MRR/ARR regex), dedup, tracker parsing, HTML stripping
- src/commands/extract.ts — gbrain extract links|timeline|all: batch link/timeline extraction from markdown
- src/commands/features.ts — gbrain features --json --auto-fix: usage scan + feature adoption salesman
- src/commands/autopilot.ts — gbrain autopilot --install: self-maintaining brain daemon (sync+extract+embed)
- src/mcp/server.ts — MCP stdio server (generated from operations)
- src/commands/auth.ts — Standalone token management (create/list/revoke/test)
- src/commands/upgrade.ts — Self-update CLI with post-upgrade feature discovery + features hook
- src/core/schema-embedded.ts — AUTO-GENERATED from schema.sql (run bun run build:schema)
- src/schema.sql — Full Postgres + pgvector DDL (source of truth, generates schema-embedded.ts)
- src/commands/integrations.ts — Standalone integration recipe management (no DB needed). Exports getRecipeDirs() (trust-tagged recipe sources), SSRF helpers (isInternalUrl, parseOctet, hostnameToOctets, isPrivateIpv4). Only package-bundled recipes are embedded=true; $GBRAIN_RECIPES_DIR and cwd ./recipes/ are untrusted and cannot run command/http/string health checks.
- src/core/search/expansion.ts — Multi-query expansion via Haiku. Exports sanitizeQueryForPrompt + sanitizeExpansionOutput (prompt-injection defense-in-depth). Sanitized query is only used for the LLM channel; original query still drives search.
- recipes/ — Integration recipe files (YAML frontmatter + markdown setup instructions)
- docs/guides/ — Individual SKILLPACK guides (broken out from monolith)
- docs/integrations/ — "Getting Data In" guides and integration docs
- docs/architecture/infra-layer.md — Shared infrastructure documentation
- docs/ethos/THIN_HARNESS_FAT_SKILLS.md — Architecture philosophy essay
- docs/ethos/MARKDOWN_SKILLS_AS_RECIPES.md — "Homebrew for Personal AI" essay
- docs/guides/repo-architecture.md — Two-repo pattern (agent vs brain)
- docs/guides/sub-agent-routing.md — Model routing table for sub-agents
- docs/guides/skill-development.md — 5-step skill development cycle + MECE
- docs/guides/idea-capture.md — Originality distribution, depth test, cross-linking
- docs/guides/quiet-hours.md — Notification hold + timezone-aware delivery
- docs/guides/diligence-ingestion.md — Data room to brain pages pipeline
- docs/designs/HOMEBREW_FOR_PERSONAL_AI.md — 10-star vision for integration system
- docs/mcp/ — Per-client setup guides (Claude Desktop, Code, Cowork, Perplexity)
- docs/benchmarks/ — Search quality benchmark results (reproducible, fictional data)
- skills/_brain-filing-rules.md — Cross-cutting brain filing rules (referenced by all brain-writing skills)
- skills/RESOLVER.md — Skill routing table (modeled on Wintermute's AGENTS.md)
- skills/conventions/ — Cross-cutting rules (quality, brain-first, model-routing, test-before-bulk, cross-modal)
- skills/_output-rules.md — Output quality standards (deterministic links, no slop, exact phrasing)
- skills/signal-detector/SKILL.md — Always-on idea+entity capture on every message
- skills/brain-ops/SKILL.md — Brain-first lookup, read-enrich-write loop, source attribution
- skills/idea-ingest/SKILL.md — Links/articles/tweets with author people page mandatory
- skills/media-ingest/SKILL.md — Video/audio/PDF/book with entity extraction
- skills/meeting-ingestion/SKILL.md — Transcripts with attendee enrichment chaining
- skills/citation-fixer/SKILL.md — Citation format auditing and fixing
- skills/repo-architecture/SKILL.md — Filing rules by primary subject
- skills/skill-creator/SKILL.md — Create conforming skills with MECE check
- skills/daily-task-manager/SKILL.md — Task lifecycle with priority levels
- skills/daily-task-prep/SKILL.md — Morning prep with calendar context
- skills/cross-modal-review/SKILL.md — Quality gate via second model
- skills/cron-scheduler/SKILL.md — Schedule staggering, quiet hours, idempotency
- skills/reports/SKILL.md — Timestamped reports with keyword routing
- skills/testing/SKILL.md — Skill validation framework
- skills/soul-audit/SKILL.md — 6-phase interview for SOUL.md, USER.md, ACCESS_POLICY.md, HEARTBEAT.md
- skills/webhook-transforms/SKILL.md — External events to brain signals
- skills/data-research/SKILL.md — Structured data research: email-to-tracker pipeline with parameterized YAML recipes
- templates/ — SOUL.md, USER.md, ACCESS_POLICY.md, HEARTBEAT.md templates
- skills/migrations/ — Version migration files with feature_pitch YAML frontmatter
- src/commands/publish.ts — Deterministic brain page publisher (code+skill pair, zero LLM calls)
- src/commands/backlinks.ts — Back-link checker and fixer (enforces Iron Law)
- src/commands/lint.ts — Page quality linter (catches LLM artifacts, placeholder dates)
- src/commands/report.ts — Structured report saver (audit trail for maintenance/enrichment)
- openclaw.plugin.json — ClawHub bundle plugin manifest

Commands Copy Chapter

Run gbrain --help or gbrain --tools-json for full command reference.

Key commands added in v0.7:
- gbrain init — defaults to PGLite (no Supabase needed), scans repo size, suggests Supabase for 1000+ files
- gbrain migrate --to supabase / gbrain migrate --to pglite — bidirectional engine migration

Testing Copy Chapter

bun test runs all tests (47 unit test files + 6 E2E test files). Unit tests run
without a database. E2E tests skip gracefully when DATABASE_URL is not set.

Unit tests: test/markdown.test.ts (frontmatter parsing), test/chunkers/recursive.test.ts
(chunking), test/sync.test.ts (sync logic), test/parity.test.ts (operations contract
parity), test/cli.test.ts (CLI structure), test/config.test.ts (config redaction),
test/files.test.ts (MIME/hash), test/import-file.test.ts (import pipeline),
test/upgrade.test.ts (schema migrations), test/doctor.test.ts (doctor command),
test/file-migration.test.ts (file migration), test/file-resolver.test.ts (file resolution),
test/import-resume.test.ts (import checkpoints), test/migrate.test.ts (migration),
test/setup-branching.test.ts (setup flow), test/slug-validation.test.ts (slug validation),
test/storage.test.ts (storage backends), test/supabase-admin.test.ts (Supabase admin),
test/yaml-lite.test.ts (YAML parsing), test/check-update.test.ts (version check + update CLI),
test/pglite-engine.test.ts (PGLite engine, all 37 BrainEngine methods),
test/utils.test.ts (shared SQL utilities), test/engine-factory.test.ts (engine factory + dynamic imports),
test/integrations.test.ts (recipe parsing, CLI routing, recipe validation),
test/publish.test.ts (content stripping, encryption, password generation, HTML output),
test/backlinks.test.ts (entity extraction, back-link detection, timeline entry generation),
test/lint.test.ts (LLM artifact detection, code fence stripping, frontmatter validation),
test/report.test.ts (report format, directory structure),
test/skills-conformance.test.ts (skill frontmatter + required sections validation),
test/resolver.test.ts (RESOLVER.md coverage, routing validation),
test/search.test.ts (RRF normalization, compiled truth boost, cosine similarity, dedup key),
test/dedup.test.ts (source-aware dedup, compiled truth guarantee, layer interactions),
test/intent.test.ts (query intent classification: entity/temporal/event/general),
test/eval.test.ts (retrieval metrics: precisionAtK, recallAtK, mrr, ndcgAtK, parseQrels),
test/check-resolvable.test.ts (resolver reachability, MECE overlap, gap detection, DRY checks),
test/backoff.test.ts (load-aware throttling, concurrency limits, active hours),
test/fail-improve.test.ts (deterministic/LLM cascade, JSONL logging, test generation, rotation),
test/transcription.test.ts (provider detection, format validation, API key errors),
test/enrichment-service.test.ts (entity slugification, extraction, tier escalation),
test/data-research.test.ts (recipe validation, MRR/ARR extraction, dedup, tracker parsing, HTML stripping),
test/extract.test.ts (link extraction, timeline extraction, frontmatter parsing, directory type inference),
test/features.test.ts (feature scanning, brain_score calculation, CLI routing, persistence),
test/file-upload-security.test.ts (symlink traversal, cwd confinement, slug + filename allowlists, remote vs local trust),
test/query-sanitization.test.ts (prompt-injection stripping, output sanitization, structural boundary),
test/search-limit.test.ts (clampSearchLimit default/cap behavior across list_pages and get_ingest_log).

E2E tests (test/e2e/): Run against real Postgres+pgvector. Require DATABASE_URL.
- bun run test:e2e runs Tier 1 (mechanical, all operations, no API keys)
- test/e2e/search-quality.test.ts runs search quality E2E against PGLite (no API keys, in-memory)
- test/e2e/upgrade.test.ts runs check-update E2E against real GitHub API (network required)
- Tier 2 (skills.test.ts) requires OpenClaw + API keys, runs nightly in CI
- If .env.testing doesn't exist in this directory, check sibling worktrees for one:
find ../ -maxdepth 2 -name .env.testing -print -quit and copy it here if found.
- Always run E2E tests when they exist. Do not skip them just because DATABASE_URL
is not set. Start the test DB, run the tests, then tear it down.

API keys and running ALL tests Copy Section

ALWAYS source the user's shell profile before running tests:

source ~/.zshrc 2>/dev/null || true

This loads OPENAI_API_KEY and ANTHROPIC_API_KEY. Without these, Tier 2 tests
skip silently. Do NOT skip Tier 2 tests just because they require API keys — load
the keys and run them.

When asked to "run all E2E tests" or "run tests", that means ALL tiers:
- Tier 1: bun run test:e2e (mechanical, sync, upgrade — no API keys needed)
- Tier 2: test/e2e/skills.test.ts (requires OpenAI + Anthropic + openclaw CLI)
- Always spin up the test DB, source zshrc, run everything, tear down.

E2E test DB lifecycle (ALWAYS follow this) Copy Section

You are responsible for spinning up and tearing down the test Postgres container.
Do not leave containers running after tests. Do not skip E2E tests.

1. Check for .env.testing — if missing, copy from sibling worktree.
Read it to get the DATABASE_URL (it has the port number).
2. Check if the port is free:
docker ps --filter "publish=PORT" — if another container is on that port,
pick a different port (try 5435, 5436, 5437) and start on that one instead.
3. Start the test DB:

docker run -d --name gbrain-test-pg \
     -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres \
     -e POSTGRES_DB=gbrain_test \
     -p PORT:5432 pgvector/pgvector:pg16

Never leave gbrain-test-pg running. If you find a stale one from a previous run,
stop and remove it before starting a new one.

Skills Copy Chapter

Read the skill files in skills/ before doing brain operations. GBrain ships 25 skills
organized by skills/RESOLVER.md:

Original 8 (conformance-migrated): ingest (thin router), query, maintain, enrich,
briefing, migrate, setup, publish.

Brain skills (from Wintermute): signal-detector, brain-ops, idea-ingest, media-ingest,
meeting-ingestion, citation-fixer, repo-architecture, skill-creator, daily-task-manager.

Operational + identity: daily-task-prep, cross-modal-review, cron-scheduler, reports,
testing, soul-audit, webhook-transforms.

Conventions: skills/conventions/ has cross-cutting rules (quality, brain-first,
model-routing, test-before-bulk, cross-modal). skills/_brain-filing-rules.md and
skills/_output-rules.md are shared references.

Build Copy Chapter

bun build --compile --outfile bin/gbrain src/cli.ts

Pre-ship requirements Copy Chapter

Before shipping (/ship) or reviewing (/review), always run the full test suite:
- bun test — unit tests (no database required)
- Follow the "E2E test DB lifecycle" steps above to spin up the test DB,
run bun run test:e2e, then tear it down.

Both must pass. Do not ship with failing E2E tests. Do not skip E2E tests.

Post-ship requirements (MANDATORY) Copy Chapter

After EVERY /ship, you MUST run /document-release. This is NOT optional. Do NOT
skip it. Do NOT say "docs look fine" without running it. The skill reads every .md
file in the project, cross-references the diff, and updates anything that drifted.

If /ship's Step 8.5 triggers document-release automatically, that counts. But if
it gets skipped for ANY reason (timeout, error, oversight), you MUST run it manually
before considering the ship complete.

Files that MUST be checked on every ship:
- README.md — does it reflect new features, commands, or setup steps?
- CLAUDE.md — does it reflect new files, test files, or architecture changes?
- CHANGELOG.md — does it cover every commit?
- TODOS.md — are completed items marked done?
- docs/ — do any guides need updating?

A ship without updated docs is an incomplete ship. Period.

CHANGELOG voice Copy Chapter

CHANGELOG.md is read by agents during auto-update (Section 17). The agent summarizes
the changelog to convince the user to upgrade. Write changelog entries that sell the
upgrade, not document the implementation.

- Lead with what the user can now DO that they couldn't before
- Frame as benefits and capabilities, not files changed or code written
- Make the user think "hell yeah, I want that"
- Bad: "Added GBRAIN_VERIFY.md installation verification runbook"
- Good: "Your agent now verifies the entire GBrain installation end-to-end, catching
silent sync failures and stale embeddings before they bite you"
- Bad: "Setup skill Phase H and Phase I added"
- Good: "New installs automatically set up live sync so your brain never falls behind"
- Always credit community contributions. When a CHANGELOG entry includes work from
a community PR, name the contributor with Contributed by @username. Contributors
did real work. Thank them publicly every time, no exceptions.

Version migrations Copy Chapter

Create a migration file at skills/migrations/v[version].md when a release
includes changes that existing users need to act on. The auto-update agent
reads these files post-upgrade (Section 17, Step 4) and executes them.

You need a migration file when:
- New setup step that existing installs don't have (e.g., v0.5.0 added live sync,
existing users need to set it up, not just new installs)
- New SKILLPACK section with a MUST ADD setup requirement
- Schema changes that require gbrain init or manual SQL
- Changed defaults that affect existing behavior
- Deprecated commands or flags that need replacement
- New verification steps that should run on existing installs
- New cron jobs or background processes that should be registered

You do NOT need a migration file when:
- Bug fixes with no behavior changes
- Documentation-only improvements (the agent re-reads docs automatically)
- New optional features that don't affect existing setups
- Performance improvements that are transparent

The key test: if an existing user upgrades and does nothing else, will their
brain work worse than before? If yes, migration file. If no, skip it.

Write migration files as agent instructions, not technical notes. Tell the agent
what to do, step by step, with exact commands. See skills/migrations/v0.5.0.md
for the pattern.

Schema state tracking Copy Chapter

~/.gbrain/update-state.json tracks which recommended schema directories the user
adopted, declined, or added custom. The auto-update agent (SKILLPACK Section 17)
reads this during upgrades to suggest new schema additions without re-suggesting
things the user already declined. The setup skill writes the initial state during
Phase C/E. Never modify a user's custom directories or re-suggest declined ones.

GitHub Actions SHA maintenance Copy Chapter

All GitHub Actions in .github/workflows/ are pinned to commit SHAs. Before shipping
(/ship) or reviewing (/review), check for stale pins and update them:

for action in actions/checkout oven-sh/setup-bun actions/upload-artifact actions/download-artifact softprops/action-gh-release gitleaks/gitleaks-action; do
  tag=$(grep -r "$action@" .github/workflows/ | head -1 | grep -o '#.*' | tr -d '# ')
  [ -n "$tag" ] && echo "$action@$tag: $(gh api repos/$action/git/ref/tags/$tag --jq .object.sha 2>/dev/null)"
done

If any SHA differs from what's in the workflow files, update the pin and version comment.

Community PR wave process Copy Chapter

Never merge external PRs directly into master. Instead, use the "fix wave" workflow:

1. Categorize — group PRs by theme (bug fixes, features, infra, docs)
2. Deduplicate — if two PRs fix the same thing, pick the one that changes fewer
lines. Close the other with a note pointing to the winner.
3. Collector branch — create a feature branch (e.g. garrytan/fix-wave-N), cherry-pick
or manually re-implement the best fixes from each PR. Do NOT merge PR branches directly —
read the diff, understand the fix, and write it yourself if needed.
4. Test the wave — verify with bun test && bun run test:e2e (full E2E lifecycle).
Every fix in the wave must have test coverage.
5. Close with context — every closed PR gets a comment explaining why and what (if
anything) supersedes it. Contributors did real work; respect that with clear communication
and thank them.
6. Ship as one PR — single PR to master with all attributions preserved via
Co-Authored-By: trailers. Include a summary of what merged and what closed.

Community PR guardrails:
- Always AskUserQuestion before accepting commits that touch voice, tone, or
promotional material (README intro, CHANGELOG voice, skill templates).
- Never auto-merge PRs that remove YC references or "neutralize" the founder perspective.
- Preserve contributor attribution in commit messages.

Skill routing Copy Chapter

When the user's request matches an available skill, ALWAYS invoke it using the Skill
tool as your FIRST action. Do NOT answer directly, do NOT use other tools first.
The skill has specialized workflows that produce better results than ad-hoc answers.

NEVER hand-roll ship operations. Do not manually run git commit + push + gh pr
create when /ship is available. /ship handles VERSION bump, CHANGELOG, document-release,
pre-landing review, test coverage audit, and adversarial review. Manually creating a PR
skips all of these. If the user says "commit and ship", "push and ship", "bisect and
ship", or any combination that ends with shipping — invoke /ship and let it handle
everything including the commits. If the branch name contains a version (e.g.
v0.5-live-sync), /ship should use that version for the bump.

Key routing rules:
- Product ideas, "is this worth building", brainstorming → invoke office-hours
- Bugs, errors, "why is this broken", 500 errors → invoke investigate
- Ship, deploy, push, create PR, "commit and ship", "push and ship" → invoke ship
- QA, test the site, find bugs → invoke qa
- Code review, check my diff → invoke review
- Update docs after shipping → invoke document-release
- Weekly retro → invoke retro
- Design system, brand → invoke design-consultation
- Visual audit, design polish → invoke design-review
- Architecture review → invoke plan-eng-review
- Save progress, checkpoint, resume → invoke checkpoint
- Code quality, health check → invoke health

README.md Copy Chapter

GBrain

Your AI agent is smart but forgetful. GBrain gives it a brain.

Built by the President and CEO of Y Combinator to run his actual AI agents. The production brain powering his OpenClaw and Hermes deployments: 17,888 pages, 4,383 people, 723 companies, 21 cron jobs running autonomously, built in 12 days. The agent ingests meetings, emails, tweets, voice calls, and original ideas while you sleep. It enriches every person and company it encounters. It fixes its own citations and consolidates memory overnight. You wake up and the brain is smarter than when you went to bed.

GBrain is those patterns, generalized. 25 skills. Install in 30 minutes. Your agent does the work. As Garry's personal agent gets smarter, so does yours.

~30 minutes to a fully working brain. Database ready in 2 seconds (PGLite, no server). You just answer questions about API keys.

Install Copy Chapter

On an agent platform (recommended) Copy Section

GBrain is designed to be installed and operated by an AI agent. If you don't have one running yet:

- OpenClaw ... Deploy AlphaClaw on Render (one click, 8GB+ RAM)
- Hermes Agent ... Deploy on Railway (one click)

Paste this into your agent:

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

That's it. The agent clones the repo, installs GBrain, sets up the brain, loads 25 skills, and configures recurring jobs. You answer a few questions about API keys. ~30 minutes.

Standalone CLI (no agent) Copy Section

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?"

3 results (hybrid search, 0.12s):
1. concepts/do-things-that-dont-scale (score: 0.94)
   PG's argument that unscalable effort teaches you what users want.
   [Source: paulgraham.com, 2013-07-01]
2. originals/founder-mode-observation (score: 0.87)
   Deep involvement isn't micromanagement if it expands the team's thinking.
3. concepts/build-something-people-want (score: 0.81)
   The YC motto. Connected to 12 other brain pages.

MCP server (Claude Code, Cursor, Windsurf) Copy Section

GBrain exposes 30+ MCP tools via stdio:

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

Add to ~/.claude/server.json (Claude Code), Settings > MCP Servers (Cursor), or your client's MCP config.

Remote MCP (Claude Desktop, Cowork, Perplexity) Copy Section

ngrok http 8787 --url your-brain.ngrok.app
bun run src/commands/auth.ts create "claude-desktop"
claude mcp add gbrain -t http https://your-brain.ngrok.app/mcp -H "Authorization: Bearer TOKEN"

Per-client guides: docs/mcp/. ChatGPT requires OAuth 2.1 (not yet implemented).

The 25 Skills Copy Chapter

GBrain ships 25 skills organized by skills/RESOLVER.md. The resolver tells your agent which skill to read for any task.

Skill files are code. They're the most powerful way to get knowledge work done. A skill file is a fat markdown document that encodes an entire workflow: when to fire, what to check, how to chain with other skills, what quality bar to enforce. The agent reads the skill and executes it. Skills can also call deterministic TypeScript code bundled in GBrain (search, import, embed, sync) for the parts that shouldn't be left to LLM judgment. Thin harness, fat skills: the intelligence lives in the skills, not the runtime.

Always-on Copy Section

| Skill | What it does |
|-------|-------------|
| signal-detector | Fires on every message. Spawns a cheap model in parallel to capture original thinking and entity mentions. The brain compounds on autopilot. |
| brain-ops | Brain-first lookup before any external API. The read-enrich-write loop that makes every response smarter. |

Content ingestion Copy Section

| Skill | What it does |
|-------|-------------|
| ingest | Thin router. Detects input type and delegates to the right ingestion skill. |
| idea-ingest | Links, articles, tweets become brain pages with analysis, author people pages, and cross-linking. |
| media-ingest | Video, audio, PDF, books, screenshots, GitHub repos. Transcripts, entity extraction, backlink propagation. |
| meeting-ingestion | Transcripts become brain pages. Every attendee gets enriched. Every company gets a timeline entry. |

Brain operations Copy Section

| Skill | What it does |
|-------|-------------|
| enrich | Tiered enrichment (Tier 1/2/3). Creates and updates person/company pages with compiled truth and timelines. |
| query | 3-layer search with synthesis and citations. Says "the brain doesn't have info on X" instead of hallucinating. |
| maintain | Periodic health: stale pages, orphans, dead links, citation audit, back-link enforcement, tag consistency. |
| citation-fixer | Scans pages for missing or malformed citations. Fixes format to match the standard. |
| repo-architecture | Where new brain files go. Decision protocol: primary subject determines directory, not format. |
| publish | Share brain pages as password-protected HTML. Zero LLM calls. |
| data-research | Structured data research with parameterized YAML recipes. Extract investor updates, expenses, company metrics from email. |

Operational Copy Section

| Skill | What it does |
|-------|-------------|
| daily-task-manager | Task lifecycle with priority levels (P0-P3). Stored as searchable brain pages. |
| daily-task-prep | Morning prep: calendar lookahead with brain context per attendee, open threads, task review. |
| cron-scheduler | Schedule staggering (5-min offsets), quiet hours (timezone-aware with wake-up override), idempotency. |
| reports | Timestamped reports with keyword routing. "What's the latest briefing?" finds it instantly. |
| cross-modal-review | Quality gate via second model. Refusal routing: if one model refuses, silently switch. |
| webhook-transforms | External events (SMS, meetings, social mentions) converted into brain pages with entity extraction. |
| testing | Validates every skill has SKILL.md with frontmatter, manifest coverage, resolver coverage. |
| skill-creator | Create new skills following the conformance standard. MECE check against existing skills. |

Identity and setup Copy Section

| Skill | What it does |
|-------|-------------|
| soul-audit | 6-phase interview generating SOUL.md (agent identity), USER.md (user profile), ACCESS_POLICY.md (4-tier privacy), HEARTBEAT.md (operational cadence). |
| setup | Auto-provision PGLite or Supabase. First import. GStack detection. |
| migrate | Universal migration from Obsidian, Notion, Logseq, markdown, CSV, JSON, Roam. |
| briefing | Daily briefing with meeting context, active deals, and citation tracking. |

Conventions Copy Section

Cross-cutting rules in skills/conventions/:
- quality.md ... citations, back-links, notability gate, source attribution
- brain-first.md ... 5-step lookup before any external API call
- model-routing.md ... which model for which task
- test-before-bulk.md ... test 3-5 items before any batch operation
- cross-modal.yaml ... review pairs and refusal routing chain

How It Works Copy Chapter

Signal arrives (meeting, email, tweet, link)
  -> Signal detector captures ideas + entities (parallel, never blocks)
  -> Brain-ops: check the brain first (gbrain search, gbrain get)
  -> Respond with full context
  -> Write: update brain pages with new information + citations
  -> Sync: gbrain indexes changes for next query

Every cycle adds knowledge. The agent enriches a person page after a meeting. Next time that person comes up, the agent already has context. The difference compounds daily.

The system gets smarter on its own. Entity enrichment auto-escalates: a person mentioned once gets a stub page (Tier 3). After 3 mentions across different sources, they get web + social enrichment (Tier 2). After a meeting or 8+ mentions, full pipeline (Tier 1). The brain learns who matters without being told. Deterministic classifiers improve over time via a fail-improve loop that logs every LLM fallback and generates better regex patterns from the failures. gbrain doctor shows the trajectory: "intent classifier: 87% deterministic, up from 40% in week 1."

"Prep me for my meeting with Jordan in 30 minutes"

... pulls dossier, shared history, recent activity, open threads

"What have I said about the relationship between shame and founder performance?"

... searches YOUR thinking, not the internet

Getting Data In Copy Chapter

GBrain ships integration recipes that your agent sets up for you. Each recipe tells the agent what credentials to ask for, how to validate, and what cron to register.

| Recipe | Requires | What It Does |
|--------|----------|-------------|
| Public Tunnel | — | Fixed URL for MCP + voice (ngrok Hobby $8/mo) |
| Credential Gateway | — | Gmail + Calendar access |
| Voice-to-Brain | ngrok-tunnel | Phone calls to brain pages (Twilio + OpenAI Realtime) |
| Email-to-Brain | credential-gateway | Gmail to entity pages |
| X-to-Brain | — | Twitter timeline + mentions + deletions |
| Calendar-to-Brain | credential-gateway | Google Calendar to searchable daily pages |
| Meeting Sync | — | Circleback transcripts to brain pages with attendees |

Data research recipes extract structured data from email into tracked brain pages. Built-in recipes for investor updates (MRR, ARR, runway, headcount), expense tracking, and company metrics. Create your own with gbrain research init.

Run gbrain integrations to see status.

GBrain + GStack Copy Chapter

GStack is the engine. GBrain is the mod.

- GStack = coding skills (ship, review, QA, investigate, office-hours, retro). 70,000+ stars, 30,000 developers per day. When your agent codes on itself, it uses GStack.
- GBrain = everything-else skills (brain ops, signal detection, ingestion, enrichment, cron, reports, identity). When your agent remembers, thinks, and operates, it uses GBrain.
- hosts/gbrain.ts = the bridge. Tells GStack's coding skills to check the brain before coding.

gbrain init detects if GStack is installed and reports mod status. If GStack isn't there, it tells you how to get it.

Architecture Copy Chapter

┌──────────────────┐    ┌───────────────┐    ┌──────────────────┐
│   Brain Repo     │    │    GBrain     │    │    AI Agent      │
│   (git)          │    │  (retrieval)  │    │  (read/write)    │
│                  │    │               │    │                  │
│  markdown files  │───>│  Postgres +   │<──>│  25 skills       │
│  = source of     │    │  pgvector     │    │  define HOW to   │
│    truth         │    │               │    │  use the brain   │
│                  │<───│  hybrid       │    │                  │
│  human can       │    │  search       │    │  RESOLVER.md     │
│  always read     │    │  (vector +    │    │  routes intent   │
│  & edit          │    │   keyword +   │    │  to skill        │
│                  │    │   RRF)        │    │                  │
└──────────────────┘    └───────────────┘    └──────────────────┘

The repo is the system of record. GBrain is the retrieval layer. The agent reads and writes through both. Human always wins... edit any markdown file and gbrain sync picks up the changes.

The Knowledge Model Copy Chapter

Every page follows the compiled truth + timeline pattern:

---
type: concept
title: Do Things That Don't Scale
tags: [startups, growth, pg-essay]
---
Paul Graham's argument that startups should do unscalable things early on.
The key insight: the unscalable effort teaches you what users actually
want, which you can't learn any other way.
---
- 2013-07-01: Published on paulgraham.com
- 2024-11-15: Referenced in batch W25 kickoff talk

Above the ---: compiled truth. Your current best understanding. Gets rewritten when new evidence changes the picture. Below: timeline. Append-only evidence trail. Never edited, only added to.

Search Copy Chapter

Hybrid search: vector + keyword + RRF fusion + multi-query expansion + 4-layer dedup.

Query
  -> Intent classifier (entity? temporal? event? general?)
  -> Multi-query expansion (Claude Haiku)
  -> Vector search (HNSW cosine) + Keyword search (tsvector)
  -> RRF fusion: score = sum(1/(60 + rank))
  -> Cosine re-scoring + compiled truth boost
  -> 4-layer dedup + compiled truth guarantee
  -> Results

Keyword alone misses conceptual matches. Vector alone misses exact phrases. RRF gets both. Search quality is benchmarked and reproducible: gbrain eval --qrels queries.json measures P@k, Recall@k, MRR, and nDCG@k. A/B test config changes before deploying them.

Voice Copy Chapter

Call a phone number. Your AI answers. It knows who's calling, pulls their full context from the brain, and responds like someone who actually knows your world. When the call ends, a brain page appears with the transcript, entity detection, and cross-references.

<p align="center">
<img src="docs/images/voice-client.png" alt="Voice client connected" width="300" />
</p>

See it in action

The voice recipe ships with GBrain: Voice-to-Brain. WebRTC works in a browser tab with zero setup. A real phone number is optional.

Engine Architecture Copy Chapter

CLI / MCP Server
     (thin wrappers, identical operations)
              |
      BrainEngine interface (pluggable)
              |
     +--------+--------+
     |                  |
PGLiteEngine       PostgresEngine
  (default)          (Supabase)
     |                  |
~/.gbrain/           Supabase Pro ($25/mo)
brain.pglite         Postgres + pgvector
embedded PG 17.5
     gbrain migrate --to supabase|pglite
         (bidirectional migration)

PGLite: embedded Postgres, no server, zero config. When your brain outgrows local (1000+ files, multi-device), gbrain migrate --to supabase moves everything.

File Storage Copy Chapter

Brain repos accumulate binaries. GBrain has a three-stage migration:

gbrain files mirror <dir>       # copy to cloud, local untouched
gbrain files redirect <dir>     # replace local with .redirect pointers
gbrain files clean <dir>        # remove pointers, cloud only
gbrain files restore <dir>      # download everything back (undo)

Storage backends: S3-compatible (AWS, R2, MinIO), Supabase Storage, or local.

Commands Copy Chapter

SETUP
  gbrain init [--supabase|--url]        Create brain (PGLite default)
  gbrain migrate --to supabase|pglite   Bidirectional engine migration
  gbrain upgrade                        Self-update with feature discovery
PAGES
  gbrain get <slug>                     Read a page (fuzzy slug matching)
  gbrain put <slug> [< file.md]         Write/update (auto-versions)
  gbrain delete <slug>                  Delete a page
  gbrain list [--type T] [--tag T]      List with filters
SEARCH
  gbrain search <query>                 Keyword search (tsvector)
  gbrain query <question>              Hybrid search (vector + keyword + RRF)
IMPORT
  gbrain import <dir> [--no-embed]      Import markdown (idempotent)
  gbrain sync [--repo <path>]           Git-to-brain incremental sync
  gbrain export [--dir ./out/]          Export to markdown
FILES
  gbrain files list|upload|sync|verify  File storage operations
EMBEDDINGS
  gbrain embed [<slug>|--all|--stale]   Generate/refresh embeddings
LINKS + GRAPH
  gbrain link|unlink|backlinks|graph    Cross-reference management
ADMIN
  gbrain doctor [--json] [--fast]       Health checks (resolver, skills, DB, embeddings)
  gbrain doctor --fix                   Auto-fix resolver issues
  gbrain stats                          Brain statistics
  gbrain serve                          MCP server (stdio)
  gbrain integrations                   Integration recipe dashboard
  gbrain check-backlinks check|fix      Back-link enforcement
  gbrain lint [--fix]                   LLM artifact detection
  gbrain transcribe <audio>             Transcribe audio (Groq Whisper)
  gbrain research init <name>           Scaffold a data-research recipe
  gbrain research list                  Show available recipes

Run gbrain --help for the full reference.

Origin Story Copy Chapter

I was setting up my OpenClaw agent and started a markdown brain repo. One page per person, one page per company, compiled truth on top, timeline on the bottom. Within a week: 10,000+ files, 3,000+ people, 13 years of calendar data, 280+ meeting transcripts, 300+ captured ideas.

The agent runs while I sleep. The dream cycle scans every conversation, enriches missing entities, fixes broken citations, consolidates memory. I wake up and the brain is smarter than when I went to sleep.

The skills in this repo are those patterns, generalized. What took 11 days to build by hand ships as a mod you install in 30 minutes.

Docs Copy Chapter

For agents:
- skills/RESOLVER.md ... Start here. The skill dispatcher.
- Individual skill files ... 25 standalone instruction sets
- GBRAIN_SKILLPACK.md ... Legacy reference architecture
- Getting Data In ... Integration recipes and data flow
- GBRAIN_VERIFY.md ... Installation verification

For humans:
- GBRAIN_RECOMMENDED_SCHEMA.md ... Brain repo directory structure
- Thin Harness, Fat Skills ... Architecture philosophy
- ENGINES.md ... Pluggable engine interface

Reference:
- GBRAIN_V0.md ... Full product spec
- CHANGELOG.md ... Version history

Contributing Copy Chapter

See CONTRIBUTING.md. Run bun test for unit tests. E2E tests: spin up Postgres with pgvector, run bun run test:e2e, tear down.

PRs welcome for: new enrichment APIs, performance optimizations, additional engine backends, new skills following the conformance standard in skills/skill-creator/SKILL.md.

License Copy Chapter

MIT