Turning a 1,076‑note archive into something you can ask a question.

Adopt it, scoped — and keep a kill criterion

gbrain is a retrieval-and-synthesis daemon over a markdown corpus, exposed to agents over MCP. Markdown in git is the system of record; Postgres is a derived cache that can be dropped and rebuilt. The two things it adds that nothing in the current stack does are gbrain think — a cited answer plus an explicit note on what the brain doesn't know — and a knowledge graph that wires itself on every write.

The recommendation is phases 0–1 only: stand up Postgres, migrate the vault layout, index it, wire the MCP server into Claude Code. Roughly four hours, and the only real bill is embeddings — chat runs on the Claude subscription. Everything beyond that — the entity backfill, the takes-and-calibration subsystem — is a separate decision made after the first one has proven itself.

The four phases

Phases 0–1 are the recommendation. They are one evening plus a week of living with the result, and the only real bill is the one-time embedding run. Phases 2 and 3 are separate decisions with their own gates — 2 costs a few hours of agent time, 3 is the part with genuine recurring draw on your Claude quota.

One honest note on the boundary: PATCH-001 sits in Phase 1 because you decided you want event extraction, but it is the weakest-paying item there — it mines 3,436 words of real diary content. It is a bet on future volume once WhatsApp capture is frictionless, not on what exists today. Deferring it to Phase 3 would be equally defensible.

What we are explicitly not doing

Not the full INSTALL_FOR_AGENTS.md path — 53 skills, the whole dream cycle, OpenClaw/Hermes as designed. That is built for a 146,000‑page brain holding 24,585 people and 5,339 companies. This corpus is a thousand pages of essays, saved articles and project notes with almost no person‑entities in it. Most of that machinery — person dedup, expert routing, deal tracking — would have nothing to operate on.

The vault has a capture verb and no read verb

Measured against the live vault on 2026‑08‑08:

This reframes the problem. It is not a discipline failure — it is structural. The noto-notes skill has four intents (daily capture, append, route, answer) and none of them create structure. Routing appends to an existing note but never adds a link or a tag. So the vault grows monotonically with zero connective tissue, and the only way in is lexical search plus memory of what you saved.

1.57 million words of your own thinking that you cannot ask a question of. That gap is precisely and only what gbrain closes.

iCloud is the transport. One Mac runs everything.

The requirement that drove the design: Noto stays a reader and a writer across all four devices, and the vault itself is where gbrain's markdown lives — not a copy of it.

   ALL FOUR DEVICES                        MacBook Pro — runs nonstop

   iPhone ─┐
   iPad  ──┤                               Postgres 17 + pgvector
   Air   ──┼── Noto ──► iCloud vault ──►   gbrain sync · dream · autopilot
   Pro   ──┘                  │            Hermes (co-located)
                              │            ▲
                              │            │  git --separate-git-dir
                              │            │  (objects live OUTSIDE iCloud)
                              └────────────┘
                                 atoms/ · wiki/ · reports/ · life/events/

Three lifetimes, kept apart

Everything machine-local is derived and disposable except git history, which exists only on this Mac and has no upstream. Since the object store sits inside the otherwise-disposable ~/.gbrain, the fix is to give history an upstream: push to a private remote on the same cron as the sync. One line, and ~/.gbrain becomes genuinely safe to delete again.

Why git's objects leave iCloud

git init --separate-git-dir splits the two halves of a repo. The working tree — your notes, the thing git actually tracks — stays in iCloud where every device sees it. The git directory — thousands of tiny loose objects, independently synced, subject to placeholder eviction — moves to local disk. What remains in the vault is a one-line .git pointer file that never changes.

Most of what gbrain produces never touches a file

The middle row matters more than it looks. propose_takes writes to a database queue, not to markdown — the only thing that ever edits a takes fence in the vault is you running gbrain takes propose --accept N. Grading, calibration profiles, contradiction verdicts and job state are all DB-only.

Facts and Takes are literal sections in your notes

Not separate files. The entity's own markdown gets a ## Facts and a ## Takes heading, each wrapping an HTML-comment-fenced table. The markers render as nothing, so in Noto you see a heading and a table. Row numbers are append-only, so cross-page references of the form slug#N stay valid forever. Facts land on the entity's page, not on the page where you said them.

Where the vault writes actually land

There is no global "write everything under one folder" setting — output paths are mostly hardcoded in the phases, not driven by the schema pack:

The vault moves to the pack, not the other way round

Rather than author a custom schema pack pointing at existing folder names, the vault adopts gbrain-base-v2's conventions. Most of it is a rename.

Migrating does not automatically buy the tuned retrieval

gbrain's boost and decay maps key on an older path convention than the pack's own prefixes — they come from Garry's brain layout, not from gbrain-base-v2. A concept page at the pack's wiki/concepts/ gets no 1.3× boost; a diary at life/diary/ gets no demote. Both maps are overridable (GBRAIN_SOURCE_BOOST, gbrain.yml recency:) and must be set explicitly whichever layout you pick.

Sequence it so it is revertible

Renaming a thousand files inside iCloud — in a vault that already contains conflict copies (2026-08-05.md and 2026-08-05 2.md both exist) — is the riskiest operation in this plan. git init and commit the vault as-is first, then migrate with git mv as a separate commit. git revert undoes it. Doing the rename before git init throws away the only undo you had.

One door, one scoped client per consumer

Three interfaces are wanted: WhatsApp capture through Hermes, vault edits triggering reprocessing, and an API for apps not yet built. Almost none of this needs building — gbrain serve --http already ships it.

• Hermes — co-located on the Pro. /ingest for fire-and-forget capture, /mcp with read for search · think · recall, which makes WhatsApp a read interface too. It does not replace noto-agent: the dividing line is would you want to see this file in Noto?
• Vault edits — gbrain has no file watcher (gbrain watch is a conversation-turn volunteer, despite the name). Autopilot's ~300 s adaptive tick is free and probably fine; gbrain sync trigger --source noto --priority high fired from launchd WatchPaths gets it to seconds. Debounce is mandatory — iCloud rewrites files constantly.
• Future apps — one registered client each, own scopes, own TTL. A reader app gets read and structurally cannot write; a compromised app is revoked without touching the others.

The ledger

The four that carry the most weight

One hunk, one file, and rules to keep it that way

Every deviation from stock gbrain must survive upstream updates. That constraint shapes the install method and the patches themselves.

Install from a source clone (git clone + bun link), not bun install -g. gbrain detects a bun-link install and upgrades by running git pull --ff-only — which fails cleanly on a branch carrying local commits rather than destroying them. That failure is correct behaviour here, not a bug: it is the signal to rebase. Leave self_upgrade.mode unset.

Shaping rules

1. Additive over modifying. A guard in a caller beats editing shared logic.
2. Config-gated, stock default preserved. Makes it upstreamable as a feature and makes conflicts obvious rather than silent.
3. Small stable files over large hot ones. operations.ts is 6,246 lines and changes most releases.
4. One-off work is a script, never a patch. Backfills should not be rebased forever.
5. Upstream aggressively. The cheapest patch is a merged one.

Backfilling the 21 daily notes that hold real content is not part of the patch — the backstop fires on real imports, so forcing a re-import triggers extraction for all of them. A one-off command, per rule 4.

What will go wrong, ranked

Thirteen steps, one gate

Steps 1–8 are one evening. The gate at step 8 is the kill criterion — everything after it is a second decision.

1. Turn off iCloud Optimize Mac Storage; brctl download the vault; confirm other devices idle

   Pro
2. brew install postgresql@17 pgvector, start it, create the database with shared_buffers at 1–2 GB

   Pro
3. Source clone + bun link — not bun install -g. Add upstream remote. Then gbrain init against Postgres and gbrain doctor

   Pro
4. git init --separate-git-dir=~/.gbrain/noto.git in the vault; commit as-is — the restore point; add a private remote

   Pro
5. Migrate folders with git mv per the map. Daily Notes/ stays. Commit as a separate revertible commit

   Pro
6. gbrain sources add noto --path "$VAULT"; gbrain.yml marking media/ as db_only; add daily-notes/ as a diary prefix

   Pro
7. Set GBRAIN_SOURCE_BOOST and recency: explicitly; point chat touchpoints at claude-cli:; facts.extraction_enabled false for the import; auto_chronicle true

   Pro
8. First sync — then the gate. Run the three questions. If think doesn't beat ten minutes of grep, stop here

   Pro · decision point
9. claude mcp add gbrain -- gbrain serve; paste the brain-first protocol into the global CLAUDE.md

   Pro
10. Apply PATCH-001; gbrain config set chronicle.include_diary true; force a re-import of the diary pages to backfill events

    Pro · fork
11. gbrain autopilot --install --max-rss 2048 — the cap is the mitigation for a leak that already froze this machine once

    Pro only
12. Nightly gbrain dream, movements ①–④; weekly gbrain doctor; re-enable facts.extraction_enabled

    Pro
13. gbrain serve --http bound to Tailscale; register scoped clients for Hermes and the Air; confirm agent pages appear in Noto on the phone

    Pro · Air · phone

What it costs, and what we have not decided

Still open

• Whether improvement-log/ belongs in the brain at all, or stays a workflow artifact outside it.
• The self-knowledge pass itself — decided in principle, unbuilt. It needs a prompt, a schedule, and a target shape.
• Whether the entity backfill is worth doing. It is what turns 23 wikilinks into a real graph — a few hours of agent time plus API cost. Decide after a week of vector-only retrieval; the delta is measurable.
• Whether the takes-and-calibration subsystem earns its keep. It reads your prose, extracts gradeable claims, and later scores how your judgment performed. Human-gated, and the one phase with real fuel in this corpus.
• Fixing Noto's structure problem at the source — independent of gbrain, the noto-notes routing intent already reads three candidate notes during its search, so proposing a wikilink costs nothing extra.