Markdown is truth.
Postgres is a cache.

This isn't aspirational. scripts/check-system-of-record.sh runs in CI and bans direct calls to insertFact, addLink, addTimelineEntry, upsertTake anywhere outside a designated reconciler. Code that writes a derived table without going through markdown first fails the build.

Two consequences you feel immediately:

# Disaster recovery is boring — there is no "restore backup" step
psql -c 'DELETE FROM facts; DELETE FROM links; DELETE FROM takes;'
gbrain sync          # re-read markdown from the repo
gbrain extract all   # rebuild every derived table, byte-identically

# Multi-machine sync is git. That is the entire mechanism.
git push        # laptop
git pull        # desktop — its DB rebuilds on next sync

Every table sits in exactly one of three buckets:

┌──────────────────────────────────────────────────────────────────┐
│  BRAIN REPO   git · markdown · the system of record                │
│  ~/brain/{people, companies, concepts, ideas, projects, media}   │
└───────────────────────────┬──────────────────────────────────────┘
                            │  gbrain sync — walks the git diff,
                            │  parses frontmatter + fences
                            ▼
┌──────────────────────────────────────────────────────────────────┐
│  POSTGRES / PGLITE   derived index · ~45 tables               │
│  pages · content_chunks (pgvector HNSW) · links · facts · takes  │
│  timeline_entries · tags · sources · minion_jobs                 │
└───────┬───────────────┬───────────────┬──────────────┬───────────┘
        ▼               ▼               ▼              ▼
    CLI             MCP           MINIONS       DREAM CYCLE
  gbrain …        gbrain serve      job queue      gbrain dream
  142 verbs       106 ops as        crash-safe     23 phases
                  MCP tools         subagents      nightly cron

The retrieval pipeline

query
  → intent-aware rewrite
  → ┌ pgvector HNSW  — max-pool: best chunk per page, so a page
    │                   surfaces on its strongest evidence
    └ BM25          — websearch_to_tsquery, GBRAIN_FTS_LANGUAGE
  → reciprocal rank fusion
  → source-tier boost        ← weight your own writing above saved articles
  → graph signals            ← adjacency · cross-source · session demote
  → title / alias boost
  → ZeroEntropy reranker
  → results tagged evidence (why it matched)
              and create_safety (exists / probable / unknown)

gbrain search "…" --explain prints per-stage attribution: base score, every boost that fired, what it multiplied by. gbrain search diagnose traces which layer surfaced — or missed — a specific page.

gbrain search returns pages. gbrain think runs the same retrieval, then composes a cited answer plus gap analysis — what's stale, what's uncited, where two pages contradict each other, what hole you should go fill. That second verb is the whole reason to run this.

Storage and addressing

Structure carried by a page

The two knowledge layers — do not conflate these

This is the distinction the codebase calls out by name as the category error. Both are claims. They differ in who said it, when it was captured, and how long it lives.

Landing zones and boundaries

1 — The brain repo (your knowledge)

Governed by gbrain.yml at the repo root. The split here is the useful lever:

storage:
  db_tracked:        # version-controlled, human-curated
    - people/
    - companies/
    - concepts/
    - ideas/
    - projects/

  db_only:           # on disk + in the DB, auto-gitignored by sync
    - media/articles/  # searchable, but never bloats the repo
    - media/x/         # restore with: gbrain export --restore-only
    - meetings/transcripts/

The directory names come from the active schema pack. gbrain-base-v2 is the default: 15 types, each declaring path_prefixes, whether facts get extracted from it, and whether it participates in expertise routing.

Plus tweet, social-digest, analysis, source, deal, email, slack, event — and typed edges: works_at, founded, invested_in, mentions, discusses, derived_from, supersedes, redirects_to.

2 — ~/.gbrain/ (machine-local runtime)

Never contains your knowledge. Wipe it and rebuild from the repo.

~/.gbrain/
├── config.json              brain registry, embedding model, search mode
├── brain/                   PGLite data dir, if using PGLite
├── inbox/                   drop files here → ingested automatically
├── autopilot.lock
├── advisor-history.jsonl
└── audit/                   ~25 weekly-rotated JSONL streams
    ├── dream-budget-YYYY-Www.jsonl
    ├── batch-retry-YYYY-Www.jsonl
    ├── db-disconnect-YYYY-Www.jsonl
    ├── schema-mutations-YYYY-Www.jsonl
    ├── rerank-failures-YYYY-Www.jsonl
    └── … quality-probe, phantoms, shell-jobs, lock-renewal

gbrain doctor reads those audit streams to produce its health checks — which is why a failure three days ago is still diagnosable today.

3 — Brains ⊥ sources

Two independent axes. A brain is a database. A source is a repo inside it. One brain can hold your notes, a codebase, and an essay collection as separate sources, each with its own sync state and a federated flag controlling cross-source search. A .gbrain-source dotfile pins every command run inside a directory to that source.

Phases hold a database lock, are scoped global or per-source, meter their own budget to ~/.gbrain/audit/dream-budget-*.jsonl, and run singly: gbrain dream --phase extract_facts --once. Six are off by default.

The same twenty-three as a flow

A dependency-ordered table hides what is actually happening. The phases group into six movements, and the ordering is load-bearing — each movement consumes the previous one's output.

① HYGIENE      lint · backlinks
                make the markdown well-formed and the link table symmetric
                before anything reads it
       │
② INGEST       sync
                git diff → DB. Everything downstream reads DB state, so this
                is the barrier between what's on disk and what the brain knows
       │
③ EXTRACT      synthesize · extract · extract_facts · extract_atoms
  structure     · resolve_symbol_edges
                prose → structure: links, timeline entries, the ## Facts fence
                into the facts index, atoms out of transcripts, code symbols
                resolved to chunks. Mostly cheap; extract_atoms is a Haiku pass
       │
④ SYNTHESIZE   patterns · synthesize_concepts
  meaning       · recompute_emotional_weight · consolidate
                cross-session themes, atoms clustered into concept pages,
                salience scoring, ephemeral → durable. Sonnet lives here
       │
⑤ JUDGE        propose_takes → grade_takes → calibration_profile → drift
  opinion       scan prose for gradeable claims → retrieve evidence → judge
                model verdicts them → aggregate into a profile of your
                standing biases. Three of the four default OFF
       │
⑥ MAINTAIN     conversation_facts_backfill · enrich_thin · skillopt
                · embed · orphans · schema-suggest · purge
                backfills, embedding refresh, orphan detection, schema
                proposals, and finally the purge — last, deliberately, so the
                rest of the cycle still sees soft-deleted pages

That gating is the real cost control. gbrain dream with movements ⑤ and ⑥ off is a cheap structural cycle. With them on it is a nightly LLM job over your entire corpus.

gbrain does not own scheduling

Start here, because it explains the shape of everything else. gbrain has no scheduler. A native scheduler loop inside gbrain jobs work "has been on the roadmap since v0.11.1 but has not shipped" — that is the convention doc's own wording. Something else owns when: crontab, launchd, Railway cron, the gateway. gbrain supplies only what the trigger does.

WHEN                          WHAT
────                          ────
crontab / launchd    ──────►  gbrain jobs submit <handler>
(host scheduler)               (Minions queue → durable worker)

The one exception is gbrain autopilot, a long-running daemon with its own internal timer. It replaces the host scheduler for maintenance work, and it is the path worth taking.

Three different cycles, and everyone confuses them

The seven reference flows, and which are actually gbrain

docs/guides/cron-schedule.md presents a seven-job schedule as one system. It is not. Three are gbrain builtins; four are external Node scripts you write, wire, credential and maintain yourself.

Execution discipline — four rules, one of which bites

# Postgres — fire-and-forget, dedup at the DB
gbrain jobs submit <handler> \
  --idempotency-key <handler>:$(date -u +%Y-%m-%dT%H:%M)

# PGLite — run inline instead. The exclusive file lock blocks a
# separate worker daemon, so there is nobody to hand the job to.
gbrain jobs submit <handler> --params '{}' --follow

One more thing about handlers: gbrain only auto-rewrites cron entries whose handler is a builtin — sync, embed, lint, import, extract, backlinks, autopilot-cycle. Anything else is host code you register yourself via MinionWorker.register(). The shell job type is CLI-only and explicitly rejected over MCP, so a remote agent cannot schedule arbitrary shell.

Budget metering, and the hole in it

Before each subagent submit the meter estimates max cost from model + max_output_tokens, accumulates across the cycle, and refuses the next submit once cumulative exceeds the cap. Every submit is appended to ~/.gbrain/audit/dream-budget-YYYY-Www.jsonl with the estimate and the actual usage when reported back. A cap of zero or negative disables the gate.

Autopilot — the daemon worth using

gbrain autopilot --install --max-rss 2048   # launchd on macOS
gbrain autopilot --status

For a single laptop this beats hand-rolled crontab: one install buys supervision, locking and a memory ceiling. Given the 31 GB leak that froze this Mac in August, the RSS cap is not a small detail — set it explicitly rather than trusting the default. And note what autopilot never does: it does not run the dream cycle. That stays a nightly line of its own.

Two sync patterns for 2+ sources

With a noto mirror and an agent source, per-source cron lines are the legacy pattern. One consolidated line replaces them and auto-picks-up future sources without a crontab edit:

*/5 * * * * gbrain sync --all --parallel 4 --workers 4 --skip-failed

Watch the connection budget: parallel × workers × 2 ≈ 32 connections during the wave, since every per-file worker opens its own two-connection pool. Homebrew Postgres defaults to max_connections = 100, so this is comfortable. gbrain doctor surfaces the recommended line as a sync_consolidation check once it sees two active sources.

And the anti-wedge pattern, for when a sync starts timing out:

gbrain sync --break-lock --all --max-age 1800
for src in $(gbrain sources list --json | jq -r '.[].id'); do
  timeout 600 gbrain sync --source "$src" --timeout 540 || true
done

--timeout firing mid-import exits 0 with status partial and leaves last_commit unchanged, so the next run re-walks the same diff and content_hash short-circuits whatever already landed. The outer timeout(1) does the OS-level kill 60s after gbrain's own graceful stop.

What I would actually schedule

Not the reference schedule. Three lines and a daemon.

# Vault → git mirror. One-way; rsync never writes back into iCloud.
*/15 * * * *  rsync -a --delete \
                "$HOME/Library/Mobile Documents/com~apple~CloudDocs/Noto/" \
                "$HOME/brain/sources/noto/" \
              && git -C "$HOME/brain" add -A \
              && git -C "$HOME/brain" commit -q -m "vault sync $(date -u +%FT%TZ)" || true

# Nightly dream — structure only to start. Movements ①–④ on, ⑤–⑥ off.
0 2 * * *     gbrain dream >> ~/.gbrain/logs/dream.log 2>&1

# Weekly health.
0 6 * * 1     gbrain doctor --json >> ~/.gbrain/logs/doctor.log 2>&1

Plus gbrain autopilot --install --max-rss 2048 handling sync, extract, embed and orphans continuously — which is why the */15 line above is only rsync-and-commit. gbrain notices the new commits on its own tick.

What to deliberately not run, and why:

• No email, X, calendar or meeting collectors. Four credentials and four scripts serving entity types this corpus barely has. Revisit only when meeting notes start landing in the vault.
• No morning briefing until there is something to brief on. A briefing over a corpus with no calendar and no deals is a daily email that says nothing — and it drags the entire quiet-hours and held-queue apparatus in with it.
• Movements ⑤–⑥ off for the first month. Turn on propose_takes → grade_takes → calibration_profile deliberately, one at a time, with a budget cap set and an Anthropic subagent model, after watching a week of dream logs. That is the feature most likely to be worth real money on this corpus — which is exactly why it should be a decision, not a default.

The two surfaces are not the same list

src/cli.ts builds the CLI from two disjoint sources. src/mcp/server.ts builds MCP from one.

106 ops  ──┬──►  stdio MCP    all 106 tools
           │                 buildToolDefs(operations) — no filter
           │
           ├──►  HTTP MCP     96 tools
           │                 serve-http.ts:1842 → operations.filter(op => !op.localOnly)
           │
           └──►  CLI          48 verbs  (ops with cliHints.name, not hidden, not shadowed)
                             + 2 aliases (link-add, link-rm)

 92 CLI_ONLY verbs ─────────►  CLI only. No MCP equivalent. Ever.

Of the 106 ops: 51 declare a CLI name, 16 are explicitly hidden from the CLI, and 39 have no CLI name at all — they exist only as MCP tools. Three names (think, salience, anomalies) appear in both lists; CLI_ONLY is checked first, so the CLI runs a richer local handler while MCP callers get the leaner op.

The 106 ops, grouped

By scope: read 60 · admin 26 · write 17 · sources_admin 2 · agent 1. Only 32 are mutating — this is overwhelmingly a read surface.

The 92 CLI-only verbs, grouped

Everything gbrain can do to itself. None of it reachable over MCP.

Note the shape: 48 of the 92 are maintenance and diagnostics. This is a system that spends most of its verb budget keeping its own index honest.

What this costs you in Claude Code