**Give the agent you already use a memory you control.** GBrain stores explicit facts with their sources, supports corrections and withdrawal, and makes the same memory available across your agents. Start with keyless memory and keyword retrieval; add semantic search, synthesis, and background enrichment when you need them.
> [!TIP]
> **Need hosted? First time running an agent?** Try **[gbrain.io](https://gbrain.io/?ref=readme)**, hosted GBrain, for the easiest experience: one brain for you and your team, connected to ChatGPT, Claude and Cursor, with nothing to install or keep online. Stuck? Email support@gbrain.io and a person will set it up with you, free.
**Keep skills beside knowledge.** New local brains include memory skills in their
content root. Agents can join an authorized catalog; only approved editors can
publish. Managed coding-agent installs add an owned native router; restart and
real-use verification are separate steps. Staged migration preserves sharing
choices and personal edits. See [shared brain skills](docs/guides/shared-brain-skills.md).
## Choose your setup
1. **Add GBrain to my existing agent — recommended.** Keep your agent's identity and save memory inside its environment. No new personal-agent identity or private repository is required. Start with the guide for **[Grok Bot](docs/guides/grok-bot.md)**, **[Muse](docs/guides/muse.md)**, or **[Codex / Claude Code](docs/tutorials/connect-coding-agent.md)**. [Other harnesses](#connect-gbrain-to-your-ai-client-mcp).
2. **Use the brain on my own computer from everywhere.** One command publishes it over MCP on your Tailscale tailnet and keeps it running: `gbrain mcp expose` (add `--funnel` for cloud agents such as Grok Bot, Muse and ChatGPT). Follow **[use your brain from anywhere over MCP](docs/guides/remote-mcp.md)**. **Say to your agent:** *"use my brain over mcp"* — *"put my brain on tailscale"*.
3. **Connect my existing hosted brain.** Follow **[hosted harness access](docs/guides/hosted-harness-access.md)** to choose native OAuth or a private machine connection. For dashboard login, clients, and permissions, use **[MCP administration](docs/mcp/ADMIN.md)** with the server's separate owner credential. Delegation is an explicit choice.
Grok **Bot** and Grok **Build** are different products. Muse's personal agent and **Muse Code** are different products too. Muse already has native editable memory; GBrain adds an explicit, portable record with provenance and shared access. See each guide's dated evidence and remaining verification steps.
I'm Garry Tan, President and CEO of Y Combinator. I built GBrain to run my own AI agents. It's the production brain behind my OpenClaw and Hermes deployments: **155,795 pages, 24,589 people, 5,340 companies**, 66 cron jobs running autonomously. My agent ingests meetings, emails, tweets, voice calls, and original ideas while I sleep. It enriches every person and company it encounters. It fixes its own citations and consolidates memory overnight. I wake up smarter than when I went to bed — and so will you.
**It works as a company brain too.** Authenticated remote clients are constrained by source and operation grants plus visibility filters. Local files and shared database credentials are a different trust boundary: sources alone do not isolate those callers. The authorization tests exercise specific access paths, not a universal no-leak guarantee. Read the [sharing boundaries](docs/architecture/brains-and-sources.md#what-confines-remote-callers-and-what-does-not) and [company-brain tutorial](docs/tutorials/company-brain.md) before setting up shared access.
Alongside keyword and semantic retrieval, GBrain offers two optional ways to use your stored knowledge:
- **A synthesis layer that gives you the actual answer.** Synthesized, well-cited prose across people, companies, deals, and ideas. Not "here are 10 chunks that mention your query"; an actual answer with citations and an explicit note on what the brain doesn't know yet. The gap analysis is the part that changes how you use the brain.
- **A typed knowledge graph.** Trusted local page writes extract supported references without LLM calls when auto-linking is enabled. Remote `put_page` edges arrive later, via sweeps, maintenance or `add_link`. Ask "who works at acme-example?": walks are breadth-first, milliseconds on dense clusters ([how](docs/architecture/RETRIEVAL.md#breadth-first-graph-walks)). On BrainBench relationship questions a graph adapter scored **P@5 0.3421, R@5 0.9791** vs 0.1917 / 0.6874 plain hybrid ([2026-09-09 refresh](https://github.com/garrytan/gbrain-evals/blob/main/docs/benchmarks/2026-09-09-retrieval-refresh.md)): whole systems, not a graph-only lift or a general guarantee.
The point of building a 150K-page brain is to use it as a strategic moat. To never lose context. To query what's in your own head without re-reading it. The brain layer is what makes the moat usable. The 24/7 dream cycle is what keeps it sharp. Both run on your hardware, your DB, your keys.
It's easier to ship a daemon that runs 24/7 to ingest, enrich, and consolidate than it is to keep an agent in chat working hard. GBrain is that daemon, generalized. Install in 30 minutes. Your agent does the work. As my personal agent gets smarter, so does yours.
> **Start keyless.** Your harness subscription and any separately configured model API usage are different costs. The optional personal-agent bootstrap takes about 15 minutes; always-on enrichment needs its own compute and API configuration.
Durable preferences and facts can be shared across agents; transient task and
harness configuration state stay local. Configured cloud embedding, reranking,
extraction, and synthesis providers can receive text, and the harness model sees
recalled memory even in keyless mode. Markdown export is not a full database
backup. Read [memory boundaries](docs/guides/memory-boundaries.md).
> **LLMs:** fetch [`llms.txt`](llms.txt) for the documentation map, or [`llms-full.txt`](llms-full.txt) for the same map with core docs inlined in one fetch. **Agents:** start with [`AGENTS.md`](AGENTS.md) (or [`CLAUDE.md`](CLAUDE.md) if you're Claude Code).
## What this looks like
Say you have a meeting with Alice tomorrow. You want to walk in remembering what she works on, when you last talked, and what's still open between you. Here's what you'd type, and what you'd get back.
**You ask:**
> "What do I need to know before my meeting with Alice tomorrow?"
**Most personal-knowledge tools give you back a list of pages.** Something like:
```
1. people/alice — Alice runs engineering at Acme...
2. meetings/2026-03-15-alice-q1 — Q1 product review with Alice...
3. meetings/2026-01-08-acme-kickoff — Kickoff meeting with Acme team...
4. customers/acme — Acme is a series-B fintech we work with...
5. notes/2026-04-22 — Quick chat with Alice about pricing...
```
Five pages you now have to open and read yourself to actually prepare. The tool found the right material, but it didn't do the work.
**GBrain gives you back the answer, with sources:**
```
Alice runs engineering at Acme (a series-B fintech). You last spoke
on April 22 in a quick pricing chat. Three things are still open
from that conversation:
1. She owes you the security review for the new tier
(deadline was May 1; no update since).
2. You committed to pricing for a 500-seat tier
(you sent it April 25; no response yet).
3. She mentioned they're hiring a CISO; you said you'd intro
someone from your network.
Heads up: nothing's been added to the brain about Alice or Acme
since April 22, six weeks ago. She may have replied through email
or Slack DM, channels the brain doesn't see. Worth asking her to
catch up before assuming any of this is still current.
```
Every claim has a source page behind it. The "heads up" at the end tells you what the brain doesn't know yet, so you can ask Alice about it directly instead of being surprised. The brain just did your meeting prep.
This is the difference between a search engine and a brain. Search finds the pages. The brain reads them for you and writes the answer.
## Install
Requires **Bun 1.4.0 or newer**. Existing worker installations should follow the
[authorization and queue upgrade guide](docs/guides/authorization-upgrade.md)
before restarting services with this version.
> [!WARNING]
> **GBrain is NOT distributed on npm.** The npm `gbrain` package is unrelated and
> can shadow the real binary, so never run `npm install gbrain` or
> `bun add -g gbrain`. Install only via `bun install -g github:garrytan/gbrain`
> or `git clone` + `bun install && bun link`.
> Installed it by mistake? `npm uninstall -g gbrain` / `bun remove -g gbrain`, then
> reinstall; `gbrain doctor` detects it.
> Schema not migrated ([#218](https://github.com/garrytan/gbrain/issues/218))?
> Run `gbrain apply-migrations --yes --no-autopilot-install`; exit 1 means it's still
> behind: run `gbrain doctor --json`, not `--yes` (`wedged`: relay its fix).
**Claude Code or Codex, fastest path:**
```bash
bun install -g github:garrytan/gbrain
gbrain setup claude-code # or codex; --dry-run previews, --remove undoes
```
`setup` shows the brain, source, launcher and owner it resolved before writing, runs `gbrain init --pglite --no-embedding` only when no brain exists, writes the stdio MCP entry and read-context hooks (owned by hash, plus Codex hook trust) and smoke-tests them. Capture and providers stay off unless accepted; a hosted brain keeps `gbrain connect --install`. [Setup guide](docs/guides/setup.md).
Start with the agent you already use. For Grok Bot and Muse, the dedicated guides above install an isolated launcher, repairable runtime, and memory in a verified persistent directory. For a coding agent, paste:
```text
Add GBrain memory to this existing agent. Read and follow:
https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md
Keep my current identity and instructions. Start keyless, preserve unrelated
configuration, and use the memory-only path. Do not create a personal-agent
identity or private repository. Show me the required search-mode choice.
Verify a unique remember/recall/correction/withdrawal round trip using observed
GBrain calls, then tell me how to verify recall in a new conversation.
```
[Codex guide](docs/mcp/CODEX.md) · [Claude Code guide](docs/mcp/CLAUDE_CODE.md) · [Memory-only walkthrough](docs/tutorials/connect-coding-agent.md) · [CLI standalone](#cli-standalone-no-agent).
The following bootstrap paths are optional: use them when you want GBrain to help create a **new persistent personal agent**, including identity files and a private repository.
### For Codex — optional personal-agent bootstrap
Turn Codex into your persistent personal agent. (Just want the brain + skills without the full agent? `codex plugin marketplace add garrytan/gbrain@codex-plugin` then `codex plugin add gbrain@gbrain` — see [docs/mcp/CODEX.md](docs/mcp/CODEX.md). The paste block below builds the whole agent.) Works in the **ChatGPT desktop app** (open Codex on a folder) and in the **Codex CLI** (`codex` in a terminal) — same install, same result. Open Codex in a **new, empty folder** (not an existing code project) — that folder becomes your agent's own **private GitHub repo**, which bootstrap creates and privacy-verifies for you. Then paste:
```
Read and follow every step of:
https://raw.githubusercontent.com/garrytan/gbrain/latest-stable/BOOTSTRAP_FOR_AGENTS.md
Goal: set yourself up as my persistent personal agent in this folder, with gbrain
as your memory. Interview me before writing any identity file — never invent
answers. Ask before anything destructive. You are not done until
`gbrain bootstrap verify` exits 0.
```
Bootstrap creates identity files from your answers, a local keyless brain, MCP
registration, and a private repository. Command approvals are normal. Verify a
saved fact in a fresh conversation; identity-file recall alone is not that test.
The repo is not a complete backup. For private-repo adoption, optional providers,
cloud behavior, and uninstall, read the [bootstrap guide](docs/guides/bootstrap.md).
### For Claude Code — optional personal-agent bootstrap
Works in the **desktop app** and in the **CLI** (`claude` in a terminal) — identical harness, identical result. Open Claude Code in a **new, empty folder** (not an existing code project) — that folder becomes your agent's own **private GitHub repo**, created and privacy-verified for you. Then paste the same block:
```
Read and follow every step of:
https://raw.githubusercontent.com/garrytan/gbrain/latest-stable/BOOTSTRAP_FOR_AGENTS.md
Goal: set yourself up as my persistent personal agent in this folder, with gbrain
as your memory. Interview me before writing any identity file — never invent
answers. Ask before anything destructive. You are not done until
`gbrain bootstrap verify` exits 0.
```
Claude Code also supports per-turn context and persistence hooks, with opt-outs.
A fresh-conversation recall test must observe actual GBrain calls, not infer the
source from the answer. See [bootstrap](docs/guides/bootstrap.md) for cloud setup,
private-repo adoption, hooks, recovery, and removal.
### For OpenClaw or Hermes — GBrain as intended, always on
This is GBrain used the way it was designed to be used: a server-hosted agent with 24/7 crons, continuous ingestion, and the overnight dream cycle that enriches your brain while you sleep — your agent works whether your laptop is open or not. It's also the highest-cost path: a deployed server (8GB+ RAM) plus raw API token usage that scales with how hard your agent runs, well beyond a chat subscription. Start here if you want the full experience from day one; start with Codex above if you want to feel it first. If you don't have a platform running yet, both deploy in one click:
- **[OpenClaw](https://github.com/openclaw/openclaw)** — deploy [AlphaClaw on Render](https://render.com/deploy?repo=https://github.com/chrysb/alphaclaw) (one click, 8GB+ RAM)
- **[Hermes](https://github.com/NousResearch/hermes-agent)** — deploy on [Railway](https://github.com/praveen-ks-2001/hermes-agent-template) (one click)
Then paste this into your agent:
```
Retrieve and follow the instructions at:
https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md
```
The agent starts with keyless memory and verifies it. API keys, automatic capture, paid enrichment, and the dream cycle are separate opt-in choices; the install prompt does not authorize all of them.
> **Never set up an AI agent platform before?** The [personal-brain tutorial](docs/tutorials/personal-brain.md) walks the whole path end-to-end — picking OpenClaw vs Hermes, deploying it, pointing it at INSTALL_FOR_AGENTS.md, getting the API keys, and verifying the first query. Start there if any of the above is new. Or skip the platform: [gbrain.io](https://gbrain.io/?ref=readme) is hosted GBrain.
### Lighter ways in
**Just want a memory for your coding agent — no identity, no repo.** On Claude Code or Codex use `gbrain setup` (above). By hand: `gbrain init --pglite --no-embedding`, then `codex mcp add gbrain -- "$(command -v gbrain)" serve --surface full` (`claude mcp add` takes the same argv; `--surface verbs` or `starter` for a harness that caps its tool count). Saved memories are brain-wide by default; pass `visibility: "private"` for local-only facts.
**Already have a brain on a remote host** (OpenClaw, Hermes, or any `gbrain serve --http`)? Point your laptop agents at it with one command each — `--install` wires it up and smoke-tests the token before handoff:
```bash
gbrain connect https://your-host/mcp --token gbrain_xxx --install # Claude Code
gbrain connect https://your-host/mcp --token gbrain_xxx --agent codex --install # Codex
```
Onboarding a whole agent harness onto a shared brain? On the brain host, `gbrain agent register --harness claude-code` mints a scoped OAuth client plus a 30-day token and prints the paste-ready wiring block — presets for daily-driver and write-isolated coding agents. The [onboarding decision table](docs/guides/agent-to-gbrain.md#onboarding-paths--the-decision-table) says which path fits.
**Brain-only install into another coding agent** (Cursor, Claude Cowork, or anything that can fetch a URL and run shell commands) — paste the OpenClaw/Hermes block above (`INSTALL_FOR_AGENTS.md`). It starts with keyless memory without replacing the agent's identity. Skills, automatic capture and the dream cycle are separate choices; verify activation in the intended harness.
**[→ Full walkthrough: give your coding agent a memory](docs/tutorials/connect-coding-agent.md)** — the memory-only paths end to end, plus the brain-first protocol you paste into `CLAUDE.md` / `AGENTS.md` and the four habits that make it actually change how you work.
### CLI standalone (no agent)
```bash
bun install -g github:garrytan/gbrain
gbrain init --pglite --no-embedding # keyless; no server, no Docker
gbrain doctor # verify health
gbrain import ~/notes/ --no-embed # index your markdown
gbrain search "a phrase from a note" --json
```
Postgres-at-scale, Supabase, and thin-client setup paths live in [`docs/INSTALL.md`](docs/INSTALL.md).
For an existing keyless brain, follow the [memory-only upgrade path](docs/INSTALL.md#memory-only-upgrades)
to keep daemon installation and paid reindexing opt-in.
### Connect GBrain to your AI client (MCP)
For a hosted brain, start with the [native OAuth and private machine connection guide](docs/guides/hosted-harness-access.md). To open the dashboard, register clients, edit access, or invalidate tokens, use [MCP administration](docs/mcp/ADMIN.md). A **profile** controls MCP authority; a **surface** controls which granted tools are visible. Neither grants owner dashboard access. New memory profiles use the full surface. `--surface verbs` retains exactly the seven memory verbs, with orientation available through `gbrain://capabilities`. Thin CLI connections use the full surface and remain restricted by their grants.
Choose the connection instructions for your actual product:
**Upgrading a brain indexed before v0.48.3.0?** Rebuild its search chunks first: [upgrade recovery guide](skills/migrations/v0.48.3.0.md). **Say to your agent:** *"Upgrade gbrain and check whether my search index needs rebuilding."*
- **[Claude Code](docs/mcp/CLAUDE_CODE.md)** — plugin: `/plugin marketplace add garrytan/gbrain` + `/plugin install gbrain@gbrain` (MCP + skills; persona variants `gbrain-coding` / `gbrain-daily` install curated subsets; pick one). Marketplace-free skills: `gbrain skillpack scaffold --harness claude-code` copies a persona-curated skill set into your user-scope skills dir. Or local one-liner: `claude mcp add gbrain -- "$(command -v gbrain)" serve`. Remote with just a bearer token: `gbrain connect https://your-host/mcp --token gbrain_xxx` prints a paste-ready block (or `--install` wires it up and smoke-tests the token).
- **[Codex](docs/mcp/CODEX.md)** — plugin (recommended): `codex plugin marketplace add garrytan/gbrain@codex-plugin` + `codex plugin add gbrain@gbrain` installs the MCP server AND the curated skill set. Or connect-only: `gbrain connect https://your-host/mcp --token gbrain_xxx --agent codex` (or `--install`); the token path reads `$GBRAIN_REMOTE_TOKEN` at runtime, while the private-handoff installer writes a private managed HTTP header so the connection survives a new shell.
- **[Cursor / Windsurf / any stdio MCP client](docs/mcp/CLAUDE_CODE.md)** — same shape, add `{"command": "gbrain", "args": ["serve", "--surface", "full"]}` to your MCP config.
- **[Hermes](docs/mcp/HERMES.md)** — `printf 'Y\n' | hermes mcp add gbrain --env GBRAIN_HOME=$HOME --connect-timeout 60 --command $(which gbrain) --args serve --surface full`. Keep `--args` last, and verify with `hermes mcp test gbrain` (the add exits 0 even on failure).
- **[Grok Bot](docs/guides/grok-bot.md)** — recommended: keep the brain on your computer, publish it with `gbrain mcp expose --funnel`, grant the Bot a `memory-writer` client and install the thin CLI at `/workspace/gbrain`; or install memory inside the Bot computer when no machine of yours stays online. Bots share local files and credentials; sources organize memory without isolating Bots. **Say to your agent:** *"connect grok bot to my brain"*.
- **[Muse personal agent](docs/guides/muse.md)** — first verify its durable user-files location; then either connect it to your published brain (`gbrain mcp expose --funnel` + thin CLI) or install the local CLI there. Native MCP configuration and skill activation are not assumed. **Say to your agent:** *"connect muse to my brain"*.
- **[Grok Build](docs/mcp/GROK.md)** — `grok mcp add gbrain -e "GBRAIN_HOME=$HOME" -- "$(command -v gbrain)" serve --surface full`. The add is lazy (exit 0 without connecting) — verify with `grok mcp doctor gbrain`, which spawns the server. Verified against Grok Build v1.0.4.
- **[opencode](docs/mcp/OPENCODE.md)** (opencode.ai / SST — not OpenClaw) — `opencode mcp add gbrain --env GBRAIN_HOME=$HOME -- "$(command -v gbrain)" serve --surface full`, or let `gbrain bootstrap hooks --harness opencode` write the config for you (opencode is a bootstrap-supported harness — it reads AGENTS.md natively). The add is lazy — verify with `opencode mcp list`, which spawns the server (`✓ gbrain connected`). Remote: `gbrain connect https://your-host/mcp --token gbrain_xxx --agent opencode [--install]` — the config stores only the `{env:GBRAIN_REMOTE_TOKEN}` interpolation. Verified against opencode v1.18.18.
- **[OpenClaw](docs/mcp/OPENCLAW.md)** — the ClawHub bundle plugin registers gbrain automatically (`openclaw.plugin.json` ships in this repo), or register the stdio server with `openclaw mcp add gbrain --command "$(command -v gbrain)" --arg serve --env GBRAIN_HOME=$HOME` (absolute path: the launchd gateway PATH lacks `~/.bun/bin`); verify with `openclaw mcp list`.
- **[Claude Desktop (Cowork)](docs/mcp/CLAUDE_DESKTOP.md)** — Settings → Integrations → add the URL of your HTTP server. Remote only; the local `claude_desktop_config.json` does not work for remote servers.
- **[Claude Cowork (team plan)](docs/mcp/CLAUDE_COWORK.md)** — org Owner adds the connector under Organization Settings → Connectors.
- **[Perplexity Computer](docs/mcp/PERPLEXITY.md)** — choose native OAuth or a managed bearer connection according to the actual connector settings. The owner registers the matching client and delivers any confidential credentials privately.
- **[ChatGPT](docs/mcp/CHATGPT.md)** — native OAuth with PKCE. Register the exact callback and token authentication method shown in its MCP settings, then start the connection in ChatGPT and complete owner consent.
For the HTTP server itself:
```bash
gbrain serve # stdio MCP (local subprocess; for Claude Code, Cursor, Windsurf)
gbrain serve --http # HTTP MCP with OAuth 2.1 + admin dashboard at /admin
# (required for Claude Desktop, Cowork, Perplexity, ChatGPT)
gbrain mcp expose # publish serve --http on your Tailscale tailnet with HTTPS + a user service
gbrain mcp expose --funnel # same name, public HTTPS — for agents that run in a vendor's cloud
```
`gbrain mcp expose` is the recommended way to run the server from your own computer: it installs Tailscale if needed (after a consent prompt), signs in, publishes the server on `https://your-machine.your-tailnet.ts.net/mcp`, keeps the admin token in a private file, installs a launchd / systemd user service, and prints separate owner-login, native OAuth, and machine-client next steps (`--status` re-checks, `--remove` undoes only its own changes). Local coding agents on the same machine: `gbrain bootstrap harness --yes --port 3131` on a Postgres brain; on PGLite mint a token before the service runs (`gbrain auth create local-agents --scopes read,write`) and pass `--token`, or grant a scoped client through the running server (`gbrain mcp grant … --admin-token-file ~/.gbrain/serve/admin-token`). Tailnet-only by default; `--funnel` is the explicit opt-in for cloud agents. **Say to your agent:** *"use my brain over mcp"* — *"reach my brain from my phone"*. Guide: [use your brain from anywhere over MCP](docs/guides/remote-mcp.md).
The HTTP server includes optional dynamic client registration, scope-gated access (`read` / `write` / `admin` / `agent`), owner-approved OAuth authorization, and rate limiting. Dynamic registration cannot grant delegation; `admin` implies neither `agent` nor owner administration. Start with the [MCP task guide](docs/mcp/README.md) for deployment, client setup, administration, and alternatives to Tailscale (ngrok, Railway, Fly.io).
Running several brains behind one tool catalog? Give each one an identity with `gbrain config set mcp.instructions ""` so a connected agent can tell them apart ([details](docs/mcp/DEPLOY.md#operations)). **Say to your agent:** *"Tell connected agents which brain this is"*.
## Two ways to query your brain
Raw retrieval (what most personal-knowledge tools ship) and a synthesis layer that gives you an actual answer. They serve different jobs.
```bash
# raw retrieval: top pages by hybrid score, no answer-generation call
gbrain search "who's working on AI agents at portfolio companies?"
# brain layer: synthesized answer with citations and gap analysis
gbrain think "who's working on AI agents at portfolio companies?"
```
**`gbrain search`** returns the top retrieved pages, ranked by hybrid scoring (vector + keyword + RRF + source-tier boost + reranker). Use it when you want raw material to skim: agent context windows, citation lookups, finding a specific quote.
Configured embedding and reranking providers can still receive text and charge
for retrieval. Keyless keyword search needs no model API; synthesis requires a
configured chat capability. See [memory boundaries](docs/guides/memory-boundaries.md#where-text-goes).
Search also tells you when its results are incomplete because projections are
still rebuilding or a bounded vector scan ran short. Ask your agent *"Check
whether my search index is ready"*; see [search readiness and recovery](docs/architecture/RETRIEVAL.md#chunk-rebuilds-after-upgrading)
before treating an empty result as proof that a page is missing.
**`gbrain think`** runs the same retrieval, then composes a synthesized answer across the results with explicit citations to the source pages AND an honest note on what the brain doesn't know yet. The gap analysis is the differentiator: the answer tells you when a page is stale, when a claim is uncited, when two pages contradict each other, when there's a hole you should fill.
**Say to your agent:** *"What do we know about acme-example?"* — *"Tell me about alice-example before my meeting tomorrow"* — *"Search for who's working on AI agents."* Your agent routes these to the brain automatically; you never type the commands yourself.
**Why it compounds.** Pair the brain layer with `find_trajectory` and you get answers like *"how have the company's metrics changed AND what does the team look like right now AND what did they promise / share AND when did we last meet AND what's the value-add I can offer here"*: well-scored, well-cited, in one shot. That's the strategic moat. That's why building a 150K-page brain is worth the effort.
`gbrain agent run "..."` exposes the same surface to a sub-agent through the Minions queue, with crash-safe two-phase persistence. Same answers, durable.
## How to get data in
Start with an explicit fact or a notes folder; opt into connectors, capture, and enrichment separately.
**Already have a company knowledge repository?** Say to your agent: *“Connect our
existing company brain, preserve its files, and show me the import plan first.”*
Try `gbrain sources demo company-brain` without keys or private data, then inspect
your committed Markdown with `gbrain sources inspect --profile company-brain`.
The [company-brain ingestion guide](docs/guides/company-brain-ingestion.md) covers
explicit destination approval, typed relationships, and resumable verification.
It does not enable embeddings, sharing, schedules, or curation automatically.
**Say to your agent:** *"Remember this with its source"* — *"What should I import first?"*
[Data ingestion guide](docs/guides/data-ingestion.md) covers files, conversations, connectors, Google data, and capture commands.
## Your brain's shape (schema packs)
Most personal-knowledge tools force one fixed layout: their idea of "notes" + "people" + "tags." Drop a Notion export or your own years-old Obsidian vault on top, and the agent doesn't know what a `Projects/` folder means or whether `Reading/` is people or sources.
**gbrain doesn't have a fixed layout.** It ships with bundled schema packs and lets you author your own when none fit:
- **`gbrain-base-v2`** (default) — 15-type DRY/MECE canonical taxonomy (14 canonical + `note` catch-all): `person`, `company`, `media`, `tweet`, `social-digest`, `analysis`, `atom`, `concept`, `source`, `deal`, `email`, `slack`, `writing`, `project`, `note`. Subtypes/format/origin pushed to frontmatter.
- **`gbrain-base`** (legacy) — the wider 24-type layout. Stays bundled for back-compat; brains on it can upgrade via `gbrain onboard --check --explain` → `gbrain jobs submit unify-types --params '{"target_pack":"gbrain-base-v2","apply":true}'` (omit `"apply":true` for a dry-run preview — that is the default).
- **`gbrain-recommended`** — extends `gbrain-base` with the 13 additional directories from `docs/GBRAIN_RECOMMENDED_SCHEMA.md` (source, place, trip, conversation, personal, civic, project, etc.). Activate with `gbrain schema use gbrain-recommended`.
- **Your own pack** — `gbrain schema detect` clusters your actual filesystem into proposed types, `gbrain schema suggest` runs an LLM pass over them, and `gbrain schema review-candidates --apply` promotes the ones you like. Three commands and the brain knows your shape. Authoring a successor pack (declares `migration_from:` so existing brains can opt in): see [`docs/architecture/pack-upgrade-mechanism.md`](docs/architecture/pack-upgrade-mechanism.md).
```bash
gbrain schema active # which pack is running, which tier set it
gbrain schema list # bundled + installed packs
gbrain schema detect # propose types matching your filesystem
gbrain schema suggest # LLM-refined proposals on top of detect
gbrain schema review-candidates # human gate: promote / rename / ignore
gbrain schema use my-pack # activate
```
**Say to your agent:** *"My schema isn't matching my notes — propose new types from my corpus"* — *"Add a page type for lab results to my brain's schema."* The schema-author skill runs the detect → suggest → review flow for you.
The active pack threads through every read + write path: `parseMarkdown` infers page type from the pack's path prefixes; `whoknows` scopes expert routing to types declared `expert_routing: true`; `extract_facts` runs only on `extractable: true` types. The retained search-cache key includes the pack name + version, but semantic result reuse is temporarily disabled. Switch packs and the brain re-interprets itself; switch back and nothing's lost.
Seven-tier resolution chain (per-call flag → env var → per-source DB key → brain-wide DB key → `gbrain.yml` → `~/.gbrain/config.json` → `gbrain-base` default). Full reference + authoring guide: [`docs/architecture/schema-packs.md`](docs/architecture/schema-packs.md).
## Tutorials
Step-by-step walkthroughs for getting the most out of GBrain. Each one takes you from zero to a working outcome, with concrete commands and real numbers.
- [**Set up your personal AI agent + brain from zero**](docs/tutorials/personal-brain.md) — the canonical full-stack install. Two GitHub repos, a Telegram bot, AlphaClaw on Render, OpenClaw + GBrain + Supabase. End-to-end in about 2 hours.
- [**Set up GBrain as your company brain**](docs/tutorials/company-brain.md) — federated, multi-user, OAuth-scoped institutional memory for a 10-50 person team. About 90 minutes end-to-end.
- [**Auto-improve a skill with `gbrain skillopt`**](docs/tutorials/improving-skills-with-skillopt.md) — treat a `SKILL.md` as a trainable parameter. Generate a starter benchmark straight from the skill with `--bootstrap-from-skill` (or write your own), strengthen the judges, then watch the optimizer propose edits and keep only the ones that measurably score higher. ~20 minutes, ~$1 in API calls. Flag + cost + safety reference: [`docs/guides/skillopt.md`](docs/guides/skillopt.md).
More walkthroughs in progress: connecting an existing agent (Claude Code, Cursor, OpenClaw, Hermes) to a GBrain memory layer; setting up GBrain for VC dealflow with founder scorecards and meeting prep; migrating an existing Notion or Obsidian vault; indexing a codebase as a queryable code brain. Full tutorial index: [`docs/tutorials/`](docs/tutorials/).
Want to see a tutorial that isn't here yet? [Open an issue](https://github.com/garrytan/gbrain/issues) describing the workflow you want documented.
## What it does (the loop)
```
signal → search → respond → write → auto-link → sync
(every (brain-first (informed (page + (typed edges (cron
message) retrieval) by context) timeline) + backlinks) keeps fresh)
```
- **Signal detector**, after you opt in, captures durable ideas and entity mentions from substantive messages. Explicit remembering works without automatic capture; paid enrichment is a separate choice.
- **Brain-first lookup** before any external API call. The cheapest, fastest, most personal information source you have.
- **Auto-link** extracts graph links for trusted local page writes. No LLM calls; pure pattern matching on page references such as `[[people/alice-example]]`. Unresolved extracted facts keep their provenance without inventing a backing page.
- **Cron-driven enrichment** runs while you sleep: dedup people pages, fix citations, score salience, find contradictions, prep tomorrow's tasks.
The whole loop is described in [`docs/architecture/topologies.md`](docs/architecture/topologies.md) with diagrams.
**Say to your agent:** *"Set up autopilot"* (installs the cron that runs the loop) — *"Run dream"* — *"Did the dream cycle run?"*
## Capabilities
GBrain combines keyword and semantic retrieval, typed graph traversal, optional cited synthesis, background jobs, and curated agent skills.
**Say to your agent:** *"What search mode am I running?"* — *"Who works at acme-example?"* — *"What does my brain know about this project?"*
[Capability reference](docs/guides/capabilities.md) keeps the commands, benchmark scope, cost controls, and feature-specific guides.
## Integrations
Data flowing into the brain. Each integration is a recipe — markdown + setup hints — that ships in `recipes/` and is discoverable via `gbrain integrations list`. **Say to your agent:** *"Set up voice calls into my brain"* — *"Wire my email and calendar into the brain"* — your agent reads the recipe and walks the setup with you.
- **Voice**: Phone calls create brain pages via Twilio + OpenAI Realtime (or DIY STT+LLM+TTS). Setup recipe: [`recipes/twilio-voice-brain.md`](recipes/twilio-voice-brain.md).
- **Gmail + Calendar + Contacts (native)**: the google source kind syncs threads, events, and contacts through your own OAuth client and runs the open-loop engine on top (`gbrain waiting`). Setup: [`docs/guides/google-connect.md`](docs/guides/google-connect.md); recipes: [`recipes/email-to-brain.md`](recipes/email-to-brain.md), [`recipes/calendar-to-brain.md`](recipes/calendar-to-brain.md).
- **Email + calendar (webhooks)**: webhook handlers that route to brain signals. [`docs/integrations/meeting-webhooks.md`](docs/integrations/meeting-webhooks.md).
- **Embedding providers**: Voyage (new-install default: `voyage-4` @ 1024d), OpenAI, OpenRouter, Google Gemini, Azure OpenAI, MiniMax, Alibaba DashScope, Zhipu, Ollama (local), llama.cpp llama-server (local), LM Studio, Together, and LiteLLM proxy. Pricing matrix + decision tree in [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md). Existing vectors are never converted by changing the default; use the explicitly approved [embedding migration](docs/guides/embedding-migration.md).
- **Rerankers**: Voyage `rerank-3-lite` hosted (the default unless `search.reranker.model` is set; on in `balanced` and `tokenmax`, same `VOYAGE_API_KEY` as embeddings; `gbrain config set search.reranker.model voyage:rerank-2.5` restores the previous default), plus the `llama-server-reranker` recipe for fully-local cross-encoder rerank via llama.cpp running Qwen3-Reranker against the same `gateway.rerank()` seam. Setup walkthrough in [`docs/ai-providers/llama-server-reranker.md`](docs/ai-providers/llama-server-reranker.md).
- **Credential vault + gateway**: `gbrain creds` manages OAuth and API credentials in a local vault ([`recipes/credential-gateway.md`](recipes/credential-gateway.md)); agent-side vault-aware secret distribution: [`docs/integrations/credential-gateway.md`](docs/integrations/credential-gateway.md).
- **MCP clients**: every major MCP client is supported. [`docs/mcp/`](docs/mcp/) per-client setup.
- **Memorable (procedural memory)**: optional, off by default. Your brain remembers *what* happened; Memorable makes your agent remember *how* — finished sessions become replayable procedures stored on your machine (in a standalone local store, or inside your brain database if you opt in), recalled when a similar task comes back. See the section below, and [`docs/memorable-agents.md`](docs/memorable-agents.md) for the agent-facing detail.
### Memorable — remember how, not just what (optional)
Memorable stores replayable procedures from coding sessions. Its relay is off by
default and requires an explicit disclosure/consent step; it can send redacted
traces and query text off-machine. Read the [Memorable integration guide](docs/memorable-agents.md)
for installation, data flow, per-harness limitations, and removal.
**Say to your agent:** *"Explain Memorable's data sharing before enabling it."*
## Architecture
```mermaid
flowchart LR
Repo[Markdown brain repos] --> Sync[Sync and parse]
Sync --> Engine{Brain engine}
Engine -->|default| PGLite[(PGLite)]
Engine -->|shared or large| Postgres[(Postgres and pgvector)]
Agent[AI agent or operator] --> Surface[CLI or MCP]
Surface --> Ops[Contract-first operations]
Ops --> Search[Hybrid retrieval]
Ops --> Graph[Typed graph traversal]
PGLite --> Search
Postgres --> Search
PGLite --> Graph
Postgres --> Graph
Search --> Synthesis[Synthesis and gap analysis]
Graph --> Synthesis
Synthesis --> Answer[Cited answer]
```
**Two engines, one contract.** PGLite (Postgres 17 via WASM, zero-config, default) for personal brains up to ~50K pages. Postgres + pgvector (Supabase or self-hosted) for shared / large / multi-machine deployments. The contract-first `BrainEngine` interface in [`src/core/engine.ts`](src/core/engine.ts) defines the 140+ methods both engines implement; CLI and MCP server are generated from one source.
**Canonical files preserve file-backed knowledge.** Your brain repo holds Markdown that GBrain indexes for retrieval; deletes in git become soft-deletes in the database. DB-only pages, unresolved facts, revision history, and operational state need a separate database backup. See the [system-of-record contract](docs/architecture/system-of-record.md). You can publish public subsets, share team mounts, and run thin-client setups pointing at a colleague's brain server. Topologies in [`docs/architecture/topologies.md`](docs/architecture/topologies.md).
**Two organizational axes (brain ⊥ source).** A *brain* is a database (your personal brain, a team mount you joined). A *source* is a repo inside that brain (wiki, gstack, an essay, a knowledge base). Routing lives in `.gbrain-source` dotfiles and resolves via a documented 6-tier precedence chain. Full diagrams in [`docs/architecture/brains-and-sources.md`](docs/architecture/brains-and-sources.md).
**Why the graph matters.** Vector search finds similar text; graph retrieval follows stored relationships. Extracted edges are evidence to inspect, not proof that a relationship is true. Graph freshness depends on the write path and maintenance described in [memory boundaries](docs/guides/memory-boundaries.md#page-writes-and-the-graph-are-separate-outcomes). Deep dive: [retrieval architecture](docs/architecture/RETRIEVAL.md); [entity recall](docs/guides/entity-recall.md).
## Troubleshooting
Start with `gbrain doctor`. For database access failures, use `gbrain engine status --probe` and `gbrain db-repair` before changing configuration.
**Say to your agent:** *"Check my brain health and show me the repair plan before changing anything."*
[Troubleshooting reference](docs/guides/troubleshooting.md) covers installation recovery, PGLite startup, embedding dimensions, locks, import failures, and sync.
## Docs
- [`docs/INSTALL.md`](docs/INSTALL.md) — every install path, end to end
- [`docs/guides/bootstrap.md`](docs/guides/bootstrap.md) — the persistent-personal-agent bootstrap contract (interview, identity files, hooks, private repo, security posture, uninstall), plus local harness mode (`gbrain bootstrap harness`) for wiring framework-spawned Claude Code/Codex sessions to a running serve
- [`docs/what-schemas-unlock.md`](docs/what-schemas-unlock.md) — why schemas matter: 7 killer use cases, the structural argument for typed page kinds, the agent-co-curates pattern
- [`docs/schema-author-tutorial.md`](docs/schema-author-tutorial.md) — 5-minute walkthrough: fork the bundled pack, add a custom type, backfill existing pages, prove the wiring via `gbrain whoknows`
- [`docs/architecture/`](docs/architecture/) — system design, topologies, retrieval theory
- [`docs/guides/`](docs/guides/) — how-to runbooks (google connect, open loops, sub-agent routing, minion deployment, skill development, brain-first lookup, idea capture, diligence ingestion)
- [`docs/integrations/`](docs/integrations/) — connecting external data sources (voice, email, calendar, embedding providers)
- [MCP task guide](docs/mcp/README.md) — deployment and per-client setup (Claude Desktop, Code, Cursor, ChatGPT, Perplexity, Cowork)
- [MCP administration](docs/mcp/ADMIN.md) — owner dashboard access, client registration, OAuth, permissions, and token recovery
- [Evals](docs/eval/) and [research](docs/research/) — methods and results
- [`docs/ethos/`](docs/ethos/) — philosophy (thin harness, fat skills, markdown as recipes, origin story)
- [`AGENTS.md`](AGENTS.md) — entry point for non-Claude agents
- [`CLAUDE.md`](CLAUDE.md) — entry point for Claude Code (deep operating context)
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contributor guide, test discipline, eval-capture mode
- [`SECURITY.md`](SECURITY.md) — install-path trust model, self-update integrity, automated scanning, OAuth threat model, hardening defaults
## Contributing
Run `bun run test` for the fast loop, `bun run verify` for the pre-push gate, `bun run ci:local` to run the full Docker-backed CI stack locally. Detailed test discipline in [`CONTRIBUTING.md`](CONTRIBUTING.md).
Community PRs are batched into release waves rather than merged one-by-one — see the community-PR-wave process in [`docs/RELEASING.md`](docs/RELEASING.md). Contributor attribution stays attached via `Co-Authored-By:` trailers. We credit every accepted contribution in [`CHANGELOG.md`](CHANGELOG.md).
If you find a bug or want a feature: open an issue first. Quick fixes (typo, doc bug, obvious regression) can go straight to a PR. Anything touching schema, retrieval ranking, MCP protocol, or the security boundary needs a design discussion in the issue first.
## License + credit
MIT. I built GBrain to run my OpenClaw and Hermes deployments — the production brain behind my AI agents.
Origin story: [`docs/ethos/ORIGIN.md`](docs/ethos/ORIGIN.md).
Community PR contributors are credited in `CHANGELOG.md` per release. Attribution for the retired provider's historical embedding and reranker integration remains in Git at `6040075c6cb95be5881cc2e1b76ef7d71f4e5d29`. Voyage AI for the asymmetric-encoding recipe template. Ramp Labs for the search quality improvements lineage.
---
### Integrations README (`docs/integrations/README.md`)
# Getting Data Into Your Brain
GBrain is the retrieval layer. But retrieval is only as good as what you put in.
This directory covers how to get data flowing into your brain automatically.
## How Data Flows In
```
Signal arrives (phone call, email, tweet, calendar event)
↓
Collector captures it (deterministic code, reliable)
↓
Agent analyzes it (LLM, judgment, entity detection)
↓
Brain pages created/updated (compiled truth + timeline)
↓
GBrain indexes it (chunking, embedding, search-ready)
↓
Next query is smarter (the compounding effect)
```
## Available Integrations
### Self-Installing Recipes
These are integration recipes your agent can set up for you. Run
`gbrain integrations` to see what's available and their status.
| Recipe | Category | Requires | What It Does | Setup Time |
|--------|----------|----------|-------------|------------|
| [ngrok-tunnel](../../recipes/ngrok-tunnel.md) | Infra | — | Fixed public URL for MCP + voice ($8/mo) | 10 min |
| [credential-gateway](../../recipes/credential-gateway.md) | Infra | — | Gmail + Calendar access (ClawVisor or Google OAuth) | 15 min |
| [voice-to-brain](../../recipes/twilio-voice-brain.md) | Sense | ngrok-tunnel | Phone calls create brain pages via Twilio + OpenAI Realtime | 30 min |
| [email-to-brain](../../recipes/email-to-brain.md) | Sense | credential-gateway | Gmail messages flow into entity pages via deterministic collector | 20 min |
| [x-to-brain](../../recipes/x-to-brain.md) | Sense | — | Twitter timeline, mentions, keyword monitoring with deletion detection | 15 min |
| [calendar-to-brain](../../recipes/calendar-to-brain.md) | Sense | credential-gateway | Google Calendar events become searchable daily brain pages | 20 min |
| [meeting-sync](../../recipes/meeting-sync.md) | Sense | — | Circleback meeting transcripts auto-import with attendee propagation | 15 min |
### Manual Integration Guides
These require manual setup (no self-installing recipe yet):
| Guide | What It Does |
|-------|-------------|
| [Credential Gateway](credential-gateway.md) | Set up ClawVisor or Hermes for Gmail, Calendar, Contacts access |
| [Meeting & Call Webhooks](meeting-webhooks.md) | Circleback meeting transcripts + Quo/OpenPhone SMS/calls |
| [qm Harness](qm-harness.md) | gbrain as the company brain for a qm (multi-user agent harness) deployment — central HTTP MCP, per-scope clients, roster provisioning, write fencing |
Something came in wrong? [Reliability repair](reliability-repair.md) covers what
`gbrain doctor` flags after import (double-encoded JSONB values, truncated
markdown bodies) and the commands that fix each one.
## How to Read a Recipe
Integration recipes are markdown files with YAML frontmatter. Your agent reads
the recipe and walks you through setup.
```yaml
---
id: voice-to-brain # unique identifier
name: Voice-to-Brain # human-readable name
version: 0.7.0 # recipe version
description: Phone calls... # what it does
category: sense # sense (data input) or reflex (automated response)
requires: [] # other recipes that must be set up first
secrets: # API keys and credentials needed
- name: TWILIO_ACCOUNT_SID
description: Twilio account SID
where: https://console.twilio.com # exact URL to get this key
health_checks: # typed DSL to verify the integration is working
- type: http
url: "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID.json"
auth: basic
auth_user: "$TWILIO_ACCOUNT_SID"
auth_token: "$TWILIO_AUTH_TOKEN"
label: "Twilio account"
- type: heartbeat_max_age # staleness gate: FAILS `integrations doctor`
max_age: 48h # when the newest heartbeat event is older.
label: "Data freshness" # The other types are point-in-time and stay
# green even when a sense stops producing data.
output_paths: # repo-relative dirs the collector writes files to;
- daily/voice/ # lets doctor/sync warn if one lands in db_only
setup_time: 30 min # estimated time to complete setup
---
[Setup instructions the agent follows step by step...]
```
**The recipe IS the installer.** Your agent (OpenClaw, Hermes, Claude Code) reads
the markdown body and executes the setup steps. It asks you for API keys, validates
each one, configures the integration, and runs a smoke test.
### Recipe trust boundary
Only recipes shipped inside the gbrain package itself (the `recipes/` directory in
a source install, or the global install copy) are trusted. Recipes discovered at
runtime from `$GBRAIN_RECIPES_DIR` or a cwd-local `./recipes/` are marked untrusted:
they cannot run `command` health checks, cannot run `http` health checks (SSRF
defense), and cannot use the deprecated string health_check form. Untrusted recipes
can still use `env_exists`, `heartbeat_max_age` (reads only the local heartbeat
file — no exec, no network), and `any_of` compositions. To ship a recipe that runs
live checks, contribute it upstream so it becomes package-bundled.
## The Deterministic Collector Pattern
When an LLM keeps failing at a mechanical task despite repeated prompt fixes,
stop fighting the LLM. Move the mechanical work to code.
**Code for data. LLMs for judgment.**
- Email collection: code pulls emails with baked-in links (100% reliable).
LLM reads the digest, classifies, enriches brain entries (judgment).
- Tweet collection: code pulls timeline, detects deletions, tracks engagement
(deterministic). LLM extracts entities, writes brain updates (judgment).
- Calendar sync: code pulls events and attendees (deterministic). LLM enriches
attendee brain pages (judgment).
This pattern prevents the "LLM forgot the links" failure mode. Mechanical work
must be 100% reliable. Judgment work is where LLMs shine.
See [Deterministic Collectors](../guides/deterministic-collectors.md) for the
full pattern.
## Architecture
For details on the shared infrastructure that all integrations build on
(import pipeline, chunking, embedding, search), see the
[Infrastructure Layer](../architecture/infra-layer.md).
For the philosophy behind thin harness + fat skills, see
[Thin Harness, Fat Skills](../ethos/THIN_HARNESS_FAT_SKILLS.md).
---
### Mcp README (`docs/mcp/README.md`)
# Connect and administer GBrain MCP
Choose the task first. Connecting a harness and administering the server use
different credentials.
| Task | Start here | Required access |
| --- | --- | --- |
| Run an HTTP MCP server | [Deployment](DEPLOY.md) | Access to the brain host and its service configuration |
| Open the admin panel or manage clients | [MCP administration](ADMIN.md) | The running server's separate owner bootstrap credential |
| Connect an existing agent | [Hosted harness setup](../guides/hosted-harness-access.md) | Native OAuth/PKCE, or a private machine-client handoff |
| Wire Claude Code to a local brain in one command | [`gbrain setup claude-code`](../guides/setup.md) | A local GBrain installation; setup resolves the brain, writes MCP and read-context hooks, and verifies them |
| Run a local MCP pipe | [Local stdio](DEPLOY.md#local-stdio-zero-setup) | A local GBrain installation; no HTTP admin panel is created |
| Diagnose a failed connection | [Recovery table](ADMIN.md#recover-a-failed-step) | Start with the failed stage and the authority you actually hold |
| A tool call returned an error | [A tool call returned an error](#a-tool-call-returned-an-error) | None: the error says who acts |
**For agents:** read [the MCP access skill](../../skills/mcp-access/SKILL.md).
If skill tools are unavailable, the instructions here and in
[ADMIN.md](ADMIN.md) work directly. A connected harness can also read
`gbrain://capabilities` for its effective permissions and administration guidance.
**Owner administration is separate from MCP `admin` scope.** An OAuth access
token, client secret, or ordinary MCP connection does not authorize dashboard
login, client creation, or client revocation. A public PKCE client has no client
secret. Ask the server-hosting harness or a separately authorized administrator
to perform owner actions.
Say to that administrator: “Open the admin panel for my running GBrain server.
Use its configured endpoint and protected owner credential. Give me a fresh
single-use login link without opening it yourself.”
Say to the connecting agent: “Connect this harness to my hosted GBrain. Use its
native OAuth flow if available; otherwise use a private machine handoff. Follow
the hosted setup guide and report configuration separately from an observed
connection in this harness.”
Tool descriptions are deliberately short (the starter list is pinned at 25,000
characters by `test/mcp-schema-budget.test.ts`); the longer guidance for each
starter tool is in the [MCP tool reference](TOOL_REFERENCE.md).
Client-specific details: [ChatGPT](CHATGPT.md), [Claude Code](CLAUDE_CODE.md),
[Claude Desktop](CLAUDE_DESKTOP.md), [Codex](CODEX.md),
[opencode](OPENCODE.md), [Perplexity](PERPLEXITY.md),
[OpenClaw](OPENCLAW.md), and the [adapter reference](../guides/harness-adapters.md).
## A tool call returned an error
Every gbrain tool error is one content block holding a JSON envelope. Read
`code` (an older server sends only `error`), then follow `fix.next`:
- `run`: call `fix.mcp` (or run `fix.argv` where you have a shell) exactly as given.
- `ask_user`: relay `user_message` and stop; act only after the user agrees.
- `tell_user_to_run`: the fix needs the user or the brain host's operator
(for example a scope grant or a CLI-only repair); give them `fix.command`.
- `wait`: retry after the stated delay with the same request.
- `report`: tell the user what happened; the host operator runs `gbrain doctor --json`.
Then run `fix.verify`, which is always read-only. A mutating call with an
unknown outcome points at its write receipt (`get_write_request`), never at a
blind retry. Successful results can carry extra `[gbrain notice …]` text blocks
after `content[0]`; read them too (a `degraded` notice means an empty result is
not proof the user has no notes). Full contract, including the scope-failure
`error`/`code` pairs: [AGENT_OPERATOR_v1](../protocol/AGENT_OPERATOR_v1.md).
## Search and query result rows
`search` and `query` return their rows as compact JSON in the first content
block. Remote callers get **lean rows** by default: the fields an agent acts
on, without the ranking diagnostics that would make each row several times
longer than its evidence text.
A lean row keeps `slug`, `title`, `type`, `chunk_text`, `score` (4
significant digits), `effective_date`, `source_id`, `chunk_id` (with `slug`
and `source_id`, the `assemble_evidence` hit), `evidence`, `create_safety`
(the duplicate-page guard), `trust_tier` and `origin`. It keeps `id` (the
`fetch` key) only when this connection can call `fetch` at that moment: a
`full` surface, a stdio session `request_tools` widened, or an HTTP client
whose surface and scopes include it (`starter` and `verbs` do not list
`fetch`). After `fetch` becomes callable, re-run `search` for `id` or pass
the row's `slug` to `fetch` (accepted when unambiguous); `fields: "full"`
returns every field. It also keeps every safety or
provenance marker that is present: `injection_suspected`, `injection_p`,
`unverified`, `content_flag`, `status`, `superseded`, `superseded_by`,
`message_id`, `thread_id`, `source_subject`, `modality` when not `text`,
`stale` when true, `provenance: "generated"` on a machine-written page,
and `delivered: {"truncated": true}` when evidence delivery cut the text.
`effective_date` is the page's own date and `effective_date_source` says
which kind: `date`, `published` or `filename` is a document date,
`event_date` an event date, and `created` or `fallback` only when the page
was created or imported. It is never a contract's effective or validity
date; that date is in the text. Every reply with dated rows adds one line
after the rows that says so (`[gbrain dates] ...`).
```json
{"query": "acme-example renewal terms"}
```
```json
[{"slug":"contracts/acme-example-msa","title":"MSA: Acme Example","type":"contract","chunk_text":"Payment terms: Net 45. Renewal is annual.","chunk_id":812,"score":0.91,"source_id":"default","effective_date":"2026-04-02","id":"gbrain-page:v1:WyJkZWZhdWx0IiwiY29udHJhY3RzL2FjbWUtZXhhbXBsZS1tc2EiXQ","evidence":"keyword_exact","create_safety":"probable"}]
```
Pass `fields: "full"` to get every field (`page_id`, `chunk_index`,
`chunk_source`, `keyword_hit`, `cosine`, `base_score`, boosts, rerank and
graph signals, the full `delivered` object):
```json
{"query": "acme-example renewal terms", "fields": "full"}
```
`_meta.retrieval.rows` reports `"lean"` or `"full"` for every remote call.
| Client | Rows by default | How to get full rows |
| --- | --- | --- |
| Any MCP client (stdio or HTTP) | lean | `fields: "full"` per call, or the host sets `gbrain config set mcp.result_rows full` |
| gbrain thin CLI, v0.60.44.0 or later | full (it sends `X-Gbrain-Client`) | nothing to do |
| gbrain thin CLI, older than v0.60.44.0 | lean | upgrade the CLI, or the host sets `mcp.result_rows full` |
| Trusted local CLI (`gbrain search`, `gbrain call`) | full | nothing to do |
The host setting is read per request over OAuth HTTP and at start-up for
`gbrain serve` (stdio), so restart a stdio server after changing it. The
`X-Gbrain-Client` header selects a row shape only; it is not an identity
claim and never grants access.
Say to your agent: *"Search my brain for the acme-example renewal terms and
show me every ranking field for the top result."*
### Fact rows in `query`
`query` can return saved facts as rows of their own, after the page rows and
only in slots and token budget the pages left free. A fact row is not a page.
It has `result_type: "fact"` and `fact_id`, and no `slug`, `id`, `type` or
`chunk_id`, so it can't be passed to `get_page`, `fetch` or
`assemble_evidence`. `follow_up` names the call that returns the fact:
`recall` with the fact's entity, or with a `grep` of its text when it has no
entity. `page_slug` is present only when the caller can read the entity's page;
pass it to `get_page`.
```json
{"result_type":"fact","fact_id":"412","page_slug":"companies/acme-example","follow_up":{"op":"recall","args":{"entity":"companies/acme-example"}},"title":"Saved fact about companies/acme-example","chunk_text":"Saved fact (fact; valid from 2026-09-01; provenance: user update): The billing contact for Acme Example is Bob.","score":0.42,"source_id":"default"}
```
`search.query_facts_arm=false` turns fact rows off.
---
### Research README (`docs/research/README.md`)
# Research records
Completed experiments and decisions, including negative and inconclusive results.
These are historical evidence, not promises about current GBrain behavior.
| Date | Research | Decision |
|---|---|---|
| 2026-09-29 | [PGLite managed-persistence write throughput](pglite-persistence-throughput-2026-09-29.md) | Shipped. PGLite soak 8.9 → 31.7 writes/s in matched 1,000-write runs on `standard-30`; the 10,000-write gate soak drops from 1,417 s to 277–308 s; Postgres 11.2 → 13.5 writes/s; all crash boundaries and full gates pass. |
| 2026-09-24 | [T-Mem validation for GBrain](t-mem-2026-09-24/postmortem.md) | Feature [#5374](https://github.com/garrytan/gbrain/pull/5374) is mothballed, not merged. Preserve the research and evaluator separately: no completed custom feature-on score; a released-code pilot found a small descriptive-trigger retrieval signal but no demonstrated answer-quality gain. |
---
### Tutorials README (`docs/tutorials/README.md`)
# Tutorials
Step-by-step walkthroughs that take you from zero to a working outcome. Concrete commands, real numbers, no abstraction-first jargon. Each tutorial assumes no prior GBrain knowledge.
## Shipped
- [**Set up your personal AI agent + brain from zero**](personal-brain.md) — the canonical solo install. Two GitHub repos, a Telegram bot, AlphaClaw on Render, OpenClaw + GBrain + Supabase. End-to-end in about 2 hours; about $100 to $150 a month sustained. The full-stack install I'd run today.
- [**Set up GBrain as your company brain**](company-brain.md) — federated, multi-user, OAuth-scoped institutional memory for a 10-50 person team. Three sources (shared / customers / internal-only), per-user scope, first synthesized query as a teammate. About 90 minutes end-to-end, about $5 in API calls for the demo, under $100 a month sustained for a 25-person company.
- [**Auto-improve a skill with `gbrain skillopt`**](improving-skills-with-skillopt.md) — treat a `SKILL.md` as the trainable parameter of a frozen agent. Write your first benchmark from scratch (the part everyone gets stuck on), preview the cost, run the optimizer, read accepted vs no_improvement vs aborted, and accept a measurably better skill. About 20 minutes, about $1 in API calls. Reference: [`../guides/skillopt.md`](../guides/skillopt.md).
- [**Give your coding agent a memory: GBrain + Claude Code / Codex**](connect-coding-agent.md) — the two-funnel walkthrough for coding-agent users. Path A: connect Claude Code / Codex to a brain you already run (OpenClaw, Hermes, any `gbrain serve --http`). Path B: start from nothing with a 2-second local PGLite brain. Both end with the brain-first protocol you paste into `CLAUDE.md` / `AGENTS.md` and the four habits (brain-first lookup, ambient capture, briefing-from-your-brain, whoknows) that make it worth it. About 10 minutes.
## In progress
These are the next tutorials on the roadmap. Open an issue if one of them is the one you need most; that's how we'll prioritize.
- **Set up GBrain for VC dealflow** — the operator's recipe. People pages for founders, companies with typed Facts fence carrying ARR / team-size / runway across dates, meetings auto-ingested, deal pages linking everything. Shows `gbrain whoknows`, `gbrain find-trajectory`, and `gbrain founder scorecard` on real workflows.
- **Migrate your existing vault into GBrain** — for Notion / Obsidian / Roam users with a vault that doesn't match GBrain's default layout. Walks through `gbrain schema detect` → `suggest` → `review-candidates` so the brain learns your shape instead of forcing you to learn its.
- **Index your codebase as a code brain** — for developers. Initialize a brain in a code repo, swap to `voyage-code-3` for embeddings, use `gbrain code-def` / `gbrain code-refs` / `gbrain code-callers` to navigate the codebase semantically from any MCP-aware editor.
- **Run GBrain fully local with Ollama or llama.cpp** — for privacy-first deployments. No cloud calls, no API keys, no telemetry. Trades some retrieval quality for full local control. Useful for regulated industries, air-gapped environments, or just paranoia.
- **Set up the dream cycle** — the overnight enrichment daemon that makes the brain self-maintaining. Fixes citations, dedupes people pages, surfaces contradictions, generates founder scorecards on the schedule you configure. The piece that turns a static knowledge base into a brain that gets smarter while you sleep.
## Want to write one?
Tutorials follow the [Diataxis](https://diataxis.fr/) tutorial pattern: learning-oriented, walks a learner from zero to a working result in one session, every step produces a visible change. If you've used GBrain for something interesting and want to write the walkthrough, the existing [`company-brain.md`](company-brain.md) is the model. Open a PR.
## Related documentation
- **Reference:** [`docs/architecture/`](../architecture/) — system design, topologies, retrieval theory
- **How-to:** [`docs/guides/`](../guides/) — task-oriented runbooks (sub-agent routing, minion deployment, skill development, brain-first lookup, idea capture, diligence ingestion). Highlight: [scaling skills past 300](../guides/scaling-skills.md) — the three-tier architecture for agents that have outgrown the always-loaded skill manifest.
- **Integrations:** [`docs/integrations/`](../integrations/) — connecting external data sources (voice, email, calendar, embedding providers)
- **MCP setup:** [`docs/mcp/`](../mcp/) — per-client setup (Claude Desktop, Claude Code, Codex, ChatGPT, Perplexity, Cowork)
- **Install paths:** [`docs/INSTALL.md`](../INSTALL.md) — every install path, end to end
- **Agent bootstrap:** [`docs/guides/bootstrap.md`](../guides/bootstrap.md) — the paste-in path that turns a coding agent into a full agent (identity, per-turn context, schedules, a private repo as its durable body)
---
### Eval System One README (`docs/eval/system-one/README.md`)
# System One v1 evals: verdicts
**ELI10.** Jev helps in two places. It reads a whole chat and decides whether
anything worth remembering is buried in it. It also tells when a new fact
replaces an old one. Everywhere else we tried, the current system did as well
or better:
- **Dream triage (S7) finds what the current triage throws away.** On our test
set it caught every one of 18 buried decisions, commitments and reflections;
the current triage missed 10. The catch: it also sends about a third of
boring chats to the writer. End to end that meant 10/10 buried signals
remembered instead of 3/10, and about 75% more dream spend.
- **The contradiction sweep (S9) notices updated facts.** Today's cosine rule
found none of 97 labelled updates. Jev found 94, with one wrong proposal.
- **Search reranking (S1) was worse than Voyage,** the reranker we use today.
- **The other slots** either didn't change results (S2) or could not pass the
safety gate on our data (S3, S4, S6, S8). S5 was too small a test to call.
`gbrain decide enable --recommended` therefore turns on S7 and S9 only. Both
read private data (conversation windows and facts), so they need
`decide.egress.private=allow`.
Every number below comes from the eval half of a frozen split. Every label was
produced by a corpus generator, an LLM or a benchmark's own annotations;
**none is a human hand label** (see [PROTOCOL.md](PROTOCOL.md)). Total paid
spend: **$24.95 of the $40 cap**, itemised in [ledger.jsonl](ledger.jsonl) and
[ledger-datasets.jsonl](ledger-datasets.jsonl). Provider for every Jev number:
`typesafe:jev-1.13.0`, which always resolved to `jev-1.13.0`.
## Verdict table
Verdicts: **win** (the slot's headline metric improved and nothing it
guards got worse, or the trade is stated in the row); **mixed** (the headline
metric improved and another headline metric got worse); **no measurable
change**; **regression**; **inconclusive** (measured, but too little data or
LLM-only labels to call); **not measured**.
| Slot | Verdict | Headline numbers (eval half) | Qualification (0.90 gate) | Shipped |
|---|---|---|---|---|
| S7 triage | **win, costs more** | Buried-signal misses 10/18 → **0/18**; routine rejected 78/79 → 52/79; triage cost per transcript $0.0046 → $0.0009; triage latency p50/p95 2.2/6.2 s → 1.4/4.2 s. Preset E2E: 10/10 buried signals synthesized vs 3/10, junk pages 2 → 5, dream spend $1.50 → $2.60 | qualified: 39/39 correct rejections, lb 0.910 | reference calibration + `--recommended` |
| S9 conflict | **win** | Supersedes found 0/97 (cosine rule) → **94/97**; wrong supersedes 10 → 1; $0.00002 per swept fact | not a harmful slot (proposals only) | reference calibration + `--recommended` |
| S1 rerank | **regression** | LongMemEval-S (233 answerable): recall_all@5 94.8% (Voyage) vs 94.0 / 91.4 / 92.7% (Jev at top_n_in 30/50/100); R@1 94.4% vs 91.4–91.8%. Answer accuracy (100 q) 91% vs 89%. LongMemEval-M pilot: R@1 87.5% vs 75.0% (100) / 70.8% (300) | n/a (no threshold) | no |
| S2 intent | **no measurable change** | Routing accuracy search 46.5% → 66.9%, think 58.7% → 77.0%, but LongMemEval retrieval 0 wins / 0 losses | n/a (not harmful) | no; `wait_ms` default raised to 250 |
| S3 evidence | **regression** | Calibrated threshold (0.02) never prunes. At the lowest acting threshold (0.08, forced): recall_all@5 94.8% → 91.4% (1 win / 9 losses, p=0.02), sessions in top 5 4.89 → 3.52 | fails: best acting lb 0.869 | no |
| S4 answerable | **regression** | Abstention precision ≤ 34% at any acting threshold (0.20: 13 of 38 abstentions correct) | insufficient_n (15 abstention families in the eval half) | no |
| S6 recall_needed | **mixed** | Reflex-miss corpus: know-to-ask failures 71.3% → **11.3%**; sealed BrainBench: failures 0% → 0%, false fires 0% → 8.5%; turn latency p50 10 ms → 161 ms | insufficient_n: 14/14 correct suppressions, needs 35 | no |
| S8 grounding | **inconclusive** | Real dream-page units: quarantines 25, 22 of them unsupported by LLM label (88%); catches 13% of LLM-flagged unsupported units; 3/206 supported units wrongly quarantined | insufficient_n: 11 page families, 3 with a wrong quarantine | no |
| S5 injection | **inconclusive** | 12 fixtures: at 0.65 flags 3/4 attacks, 0/32 clean; a quoted payload scores 0.56–0.60. On LongMemEval (no attacks) it demoted 0.8% of candidates | not harmful | no |
| S7 on a local `llm:` model | **not measured** | Time budget went to the matched pairs above | — | — |
## Per-slot detail
### S7 triage (win, costs more)
Matched pair on 109 eval-half transcripts (13 Cat 35 + 96 synthetic), through
`runTriagePass`, the function `gbrain dream` calls. Off is today's Haiku 4.5
judge plus the rescue band. On is Jev per-window probabilities at the
calibrated 0.77 threshold; answers in the margin band go to the Haiku judge.
| | off (Haiku) | on (Jev) |
|---|---|---|
| Synthesis-worthy transcripts passed | 20/30 | **30/30** |
| Buried-signal (synthetic) passed | 8/18 | **18/18** |
| Cat 35 real positives passed | 12/12 | 12/12 |
| Routine transcripts rejected | 78/79 | 52/79 |
| Sent to synthesis | 21 | 57 |
| Accuracy | 0.90 | 0.75 |
| Triage cost per transcript | $0.0046 | $0.0009 |
| Latency p50 / p95 / p99 | 2.24 / 6.22 / 7.66 s | 1.44 / 4.16 / 5.15 s |
| Decision flip rate (two runs) | 0.9% | 4.6% |
Paths in the on arm: 57 Jev pass, 37 Jev reject, 15 margin hold (Haiku
decided). McNemar on the discordant pairs favours off on accuracy (11 vs 27,
p=0.014), because the errors differ in kind: off drops real signal, on
synthesizes routine chats. Calibration: recall 1.0 on the calibrate half,
retest_sd 0.014, repack_sd 0.013, ECE 0.46. Jev probabilities are not
calibrated in absolute terms (routine windows score 0.6–0.8); the threshold,
not the raw number, carries the meaning.
**Preset end to end** (`enable --recommended` on a fresh brain, then
`gbrain dream --phase synthesize`, 29 eval-half transcripts, the same corpus
for both arms):
| | all off | preset (S7 + S9) |
|---|---|---|
| Transcripts synthesized | 10 | 19 |
| Synthesis-worthy transcripts synthesized | 9/16 | **16/16** |
| Buried-signal transcripts synthesized | 3/10 | **10/10** |
| Routine transcripts synthesized (junk) | 1 (2 pages) | 3 (5 pages) |
| Pages written | 20 | 38 |
| Dream spend (triage + synthesis estimate) | $1.50 | $2.60 |
| Synthesize phase wall time | 733 s | 1,427 s |
The preset contains no query-path slot, so query latency and answer quality
are unchanged by construction. S9 ran in the cycle but found 0 facts to sweep:
the synthesized pages carry no `## Facts` fence. Its evidence is the labelled
pair eval below, not this run.
### S9 conflict (win)
395 eval-half fact pairs; 97 supersede, 75 duplicate, 223 independent labels.
780 pairs come from a template generator and 6 from repository tests.
| | cosine rule (today) | S9 (dup 0.52, floor 0.65) | S9 (floor 0.50) |
|---|---|---|---|
| Supersedes found | 0/97 | 94/97 | 95/97 |
| Wrong supersedes / proposals | 10/10 | 1/95 | 1/96 |
| Label agreement | 0.565 | 0.939 | 0.942 |
On the 88 pairs the sweep can actually see (cosine ≥ 0.80), S9 finds 29/30
supersedes with 0 wrong proposals. The calibrated proposal floor (0.65, F1 on
supersede labels) performs the same as the 0.50 default. Decision flips 0/395;
latency p50/p95 146/221 ms per fact.
### S1 rerank (regression)
LongMemEval-S cleaned, 248 eval-half questions (233 answerable). Every arm
shares one embedding cache (openai:text-embedding-3-large at 1536 dimensions)
and differs only in the reranker.
| Arm | recall_all@5 | R@1 | Jev top-1 when present | Rerank p50/p95 | Cost/q |
|---|---|---|---|---|---|
| no reranker | 93.6% | 91.8% | — | — | $0 |
| **Voyage rerank-2.5, top_n_in 30 (today)** | **94.8%** | **94.4%** | 220/233 | — | ~$0.001 |
| Voyage, top_n_in 100 | 94.8% | 93.1% | 217/233 | — | ~$0.0015 |
| Jev, top_n_in 30 | 94.0% | 91.8% | 214/233 | 381/521 ms | $0.0008 |
| Jev, top_n_in 50 | 91.4% (p=0.02) | 91.4% | 213/233 | 512/750 ms | $0.0013 |
| Jev, top_n_in 100 | 92.7% | 91.4% | 213/233 | 515/716 ms | $0.0013 |
| Jev, top_n_in 100 (retest) | 92.3% | 91.8% | 214/233 | 494/649 ms | $0.0013 |
| expansion + Jev 100 | 93.6% | 91.8% | — | 248/248 timed out | — |
- **Recall experiment.** On LongMemEval-S the fused pool is the whole haystack
(about 47 sessions), so pool recall is 100% at depth 30. The frozen
28-question LongMemEval-M pilot (500 sessions per question,
text-embedding-3-small) also had every answer session in the fused top 30.
There, Voyage R@1 was 87.5%, Jev@100 75.0% and Jev over a deep 300-candidate
pool 70.8% (n=24; not significant, but no arm beat today's).
- **GBRA-4's 134/134 did not replicate.** Jev put the target first in 213/233
questions where it was present; Voyage did in 220/233.
- **Answers.** 100 questions, Haiku 4.5 reader, gpt-4o judge: 91% with Voyage,
89% with Jev@30 (1 win, 3 losses).
- **Bug found, then fixed.** In this run, with query expansion on, S1 never
reranked: the 1,500 ms per-query decide budget (`decide.query_budget_ms`)
started at request start, and the expansion call used it up. Every row fell
back to fused order, so the "expansion + Jev 100" row above measures fused
order, not Jev. The budget now starts at the first post-retrieval decide
stage (regression test in `test/decide/search-slots.serial.test.ts`); that arm
was not re-measured.
### S2 intent (no measurable change)
Routing accuracy on 424 eval-half queries (the labels map LongMemEval
`question_type` and BrainBench relational cases): search 46.5% → 66.9%
(51 overrides: 41 helped, 6 hurt), think 58.7% → 77.0%. Retrieval did not move:
the S2 arm on LongMemEval-S matched today's on every question.
- **Late rate.** How many answers arrive after the wait bound:
- From a Capy machine: 39–41% after 150 ms, 7–8% after 200 ms, 1–3% after
250 ms, under 1% after 300 ms.
- From the eu-central Ubicloud VM: 27% after 250 ms.
- **Decision.** `decide.slots.intent.wait_ms` now defaults to 250 ms. It keeps
the full routing accuracy on the Capy machine at a p50 cost of about 145 ms.
### S3 evidence (regression)
The recall ≥ 0.98 calibration picks 0.02, which the 0.05 margin turns into
"never prune". About 10% of real answer sessions score at or below 0.06,
because the 6,000-character candidate cap cuts the answer out of long
sessions. Production's `capRerankDoc` applies the same cap. So any acting
threshold prunes real evidence:
- At 0.08 the family-level lower bound is 0.869 on the eval half (fails 0.90).
- Forced on at 0.08, top-5 evidence-complete recall dropped 94.8% → 91.4%, for
28% fewer sessions in the reader's context.
With S5 co-packed, calibration now records the pack shape it sent
(`slots=evidence+injection`) and co-packs S5 questions in calibrate/qualify;
see `test/decide/evidence-copack-calibration.serial.test.ts`.
### S4 answerable (regression)
500 LongMemEval questions, 30 of them abstention. Over the top-5 sessions, Jev
gives many answerable questions a low probability (median 0.64, 10th
percentile 0.13). At 0.20 it would abstain on 38 eval-half questions, 13
correctly. The calibrated threshold (0.05) never abstains. Not run through the
judged reader, because the dataset-level precision already rules it out.
### S6 recall_needed (mixed)
| Eval half | reflex only | S6 on (0.74, suppress below 0.10) |
|---|---|---|
| Reflex-miss corpus (264 turns): know-to-ask failures | 71.3% | **11.3%** |
| Reflex-miss corpus: false fires | 55.7% | 49.7% |
| Sealed BrainBench (79 turns): failures | 0% | 0% |
| Sealed BrainBench: false fires | 0% | **8.5%** |
| Turn latency p50 / p95 (sealed) | 10 / 19 ms | 161 / 258 ms |
- **Reflex-miss corpus.** Lowercase names, surnames and indirect references;
synthetic, labels by construction.
- **Suppression.** 14 suppressions, all correct, but 35 families are needed to
qualify. At the old 0.05 default no turn was ever suppressed (0 of 343), so
the default is now 0.10.
- **Deadline.** 3% of S6 answers missed the 250 ms deadline; the reflex result
stood.
### S8 grounding (inconclusive)
750 claim units from 16 Cat 35 dream pages, labelled by Claude Sonnet 5 (567
real units, 183 perturbation negatives). At the recall ≥ 0.95 calibration
(threshold 0.29):
- **Real units.** 25 quarantined, 22 of them LLM-unsupported; 13% of
LLM-unsupported real units caught; 3 of 206 supported units lost.
- **Perturbations.** 63 of 126 caught, 0 false.
- **Qualification.** Impossible with 16 page families, 11 in the eval half.
- **Owed.** The plan's human-labelled sample.
### S5 injection (inconclusive)
Across 3 repeats, attacks scored 0.50–0.94 and clean candidates 0.02–0.08. The
exception is a legitimate candidate quoting an attack payload (0.56–0.60). At
0.65, S5 flags 3 of 4 attacks and no clean candidate. On LongMemEval, which
has no attacks, it demoted 93 of 11,402 candidates.
### Judge harness (eval-only)
`gbrain decide judge-agreement`:
- **LongMemEval answers:** Cohen's kappa 0.73 (95% CI 0.51–0.96) against the
gpt-4o judge, 95% agreement, n=100.
- **Grounding:** kappa 0.58 (0.52–0.64) against the Sonnet 5 labels, 78.7%
agreement, n=750.
Both compare one judge with another, not with human labels.
## Files
- [PROTOCOL.md](PROTOCOL.md): how pairs were run, thresholds chosen, labels
marked.
- [datasets/](datasets/): frozen datasets, generators, [HASHES.md](datasets/HASHES.md).
- [receipts/](receipts/): calibrate/qualify JSON, recorded Jev answers,
per-question retrieval rows, summaries and the preset run.
- [runners/](runners/): `s7-triage-pair.ts`, `ask-dataset.ts`,
`s2/s6/s8/s9-analyze.ts`, `lme-arms.sh` (LongMemEval arms on Ubicloud),
`lme-summarize.py`, `s6-brainbench-summary.py`, `summarize-pair.ts`.
- Reference calibrations: `src/core/ai/decide/reference-calibrations.ts`.
---
### Research Answer Evidence Index (`docs/research/answer-evidence/index.md`)
---
title: Answer-evidence research source index
retrieved: 2026-09-24
depth: base
source_count: 15
summary_count: 15
verified_support_spans: 42
claim_span_gate_passed: true
cold_read_passed: true
cross_model_review: passed
---
# Answer-evidence research source index
Start with [What actually helps an AI use its memory?](compendium.md).
It explains the field, our negative result and the next hypotheses without
requiring the reader to open these papers first. The closest primary read is
**LongMemEval section 5.5, Figure 6 and Figure 13**.
## Scope and retention
This is a focused, primary-source-grounded **base compendium**, researched on
2026-09-24. It covers evidence presentation, context compression, retrieval
planning, selected memory systems and answer evaluation. It is not a systematic
review, a complete survey of work through that date, or a claim that every
archived revision is the newest available. A-Mem and other systems mentioned as
baselines in selected papers were not separately audited as primary sources.
Public source pages are explicitly **citation-only, with short supporting
spans where retained**, paired one-to-one with summaries. Four preprint/vendor
notes are deliberately brief; their public records retain supporting locators
and span hashes rather than extended source-derived text. Full papers, web acquisitions and
extracted text were obtained in the private research workspace for verification;
they are not mirrored in Git. This keeps third-party full texts, author contact
details and prompt-shaped source material out of the public repository. The
durable repository record is the citations, pinned versions, original-file
hashes, support spans and our synthesis—not a promise that workspace originals
will remain available indefinitely. A source's PDF hash identifies the acquired
bytes, not a guarantee that its host will serve identical bytes forever.
The papers' model prompts are untrusted research data, never operating
instructions. No private conversation dump is included. No GBrain database
ingestion, `gbrain lsd` run, paid replication, or advanced-depth certification
was performed for the compendium. A separate
[frozen reading replication](../../eval/READING_NOTES_REPLICATION.md) has tested
its recommendation. Repository links replace brain-page graph links for this
docs-only artifact.
## Reading order and one-to-one source manifest
| # | Source | What it contributes | Evidence status | Notes |
|---|---|---|---|---|
| 01 | [LongMemEval](sources/01-longmemeval.md) | The closest controlled reading comparison. | ICLR 2025; pinned v2. | [Summary](summaries/01-longmemeval.md) |
| 02 | [Chain-of-Note](sources/02-chain-of-note.md) | Notes before answers, with noise and latency tradeoffs. | EMNLP 2024 proceedings. | [Summary](summaries/02-chain-of-note.md) |
| 03 | [Sufficient Context](sources/03-sufficient-context.md) | Evidence sufficiency and the cost of withholding answers. | ICLR 2025 proceedings. | [Summary](summaries/03-sufficient-context.md) |
| 04 | [ContextualJudgeBench](sources/04-contextual-judge.md) | Why evidence-conditioned grading needs controls. | ACL 2025 proceedings. | [Summary](summaries/04-contextual-judge.md) |
| 05 | [Lost in the Middle](sources/05-lost-in-the-middle.md) | Where the answer appears affects whether a model uses it. | TACL work; archived arXiv v2. | [Summary](summaries/05-lost-in-the-middle.md) |
| 06 | [RECOMP](sources/06-recomp.md) | Trained compression can save tokens while losing accuracy. | ICLR work; archived arXiv v1. | [Summary](summaries/06-recomp.md) |
| 07 | [LongLLMLingua](sources/07-longllmlingua.md) | Query-aware compression plus reordering can help. | ACL work; archived arXiv v2. | [Summary](summaries/07-longllmlingua.md) |
| 08 | [LLMLingua-2](sources/08-llmlingua-2.md) | Learned token preservation has task-dependent tradeoffs. | ACL Findings work; archived arXiv v2. | [Summary](summaries/08-llmlingua-2.md) |
| 09 | [RULER](sources/09-ruler.md) | A context-window size is not a reasoning guarantee. | COLM work; archived arXiv v3. | [Summary](summaries/09-ruler.md) |
| 10 | [IRCoT](sources/10-ircot.md) | Later search queries can follow intermediate findings. | ACL work; archived arXiv v2. | [Summary](summaries/10-ircot.md) |
| 11 | [CRAG](sources/11-crag.md) | Selective retrieval repair adds assumptions and cost. | Archived arXiv v3 preprint. | [Summary](summaries/11-crag.md) |
| 12 | [Contextual Retrieval](sources/12-contextual-retrieval.md) | Add context to search keys instead of deleting reader evidence. | Vendor engineering report. | [Summary](summaries/12-contextual-retrieval.md) |
| 13 | [Mem0](sources/13-mem0.md) | Graph memory is not uniformly better; abstention omitted. | Archived arXiv v1 preprint. | [Summary](summaries/13-mem0.md) |
| 14 | [Hindsight](sources/14-hindsight.md) | Whole-system memory results need matched judging. | Archived arXiv v1 preprint. | [Summary](summaries/14-hindsight.md) |
| 15 | [SimpleMem](sources/15-simplemem.md) | Component removal suggests narrow follow-up hypotheses. | Archived arXiv v3 preprint. | [Summary](summaries/15-simplemem.md) |
The machine-readable [sources.json](sources.json) holds the same pairings, URLs,
versions, original-file hashes and claim support (quotations or private-span
hashes with locators). Published venues and
the actually archived arXiv revisions are distinguished: this collection does
not claim every archived PDF is the final proceedings version.
## How to read the numbers
- **Answer accuracy** counts answers judged correct; the judge and rubric matter.
- **Exact match (EM)** requires an answer to match an accepted reference after
the study's normalization. It is not identical to a human correctness judgment.
- **Answer F1** measures answer/reference word overlap in these QA evaluations,
not the fraction of questions answered correctly.
- **Retrieval recall** measures supporting material found. Recall at 20 results
is not answer accuracy; IRCoT additionally uses a different budgeted metric.
- **Selective accuracy** counts correct answers among attempted answers. Always
report **coverage**, the fraction of questions attempted, alongside it.
- **Percentage points** subtract two percentages; a relative percentage change
divides by the baseline. Do not interchange them or compare unlike metrics.
## Verification and unresolved limits
All 15 original acquisition hashes were independently recomputed. All 42 ledger
support quotations matched their archived extracted text after whitespace
normalization. Numeric tables and experimental conditions used in the synthesis
were also inspected; LongMemEval Figure 6 was checked in the rendered PDF, not
inferred from a search snippet. PDF reading-order extraction was used where
two-column layouts interleaved unrelated text.
The claim-span check establishes that quoted support exists. It does not
independently reproduce a paper's experiment or make every headline causal.
An independent cold-read and factual-characterization review passed after the
public-retention edits; its seven quality dimensions scored 8–9 out of 10.
Known caveats remain on the source pages: Chain-of-Note's Table 4/prose numeric
disagreement, compression losses, retrieval gains without answer gains,
unanswerable-question exclusions, imported baselines, and unlike judge metrics.
The compendium's recommendation is our synthesis, not a claim made by all papers.
For GBrain's own measured outcomes, read
[Answer-evidence packets: did not help](../../eval/ANSWER_PACKET_RESULTS.md)
and the subsequent [intact-evidence reading results](../../eval/READING_NOTES_RESULTS.md).
The broader [evaluation guide](../../eval-bench.md) links this collection.
---
### Test Audit 2026 09 29 README (`docs/test-audit/2026-09-29/README.md`)
# Test audit evidence, 2026-09-29
Read-only discovery records from the 2026-09-29 test audit of gbrain at
`2ede415` (v0.59.11.0). Five lanes looked for tests that protect no shipped
behavior, the production code only those tests keep alive, and the coverage
holes that must be filled before anything is removed. Every candidate carries a
mutation probe: a behavior-breaking edit the test missed, or a
behavior-preserving edit it failed on.
These files are a historical research record. They describe the tree as it was
at `2ede415`; line numbers and counts drift as master moves, so re-verify a
reference against the current checkout before acting on it. They are not part of
the `llms.txt` bundles (`scripts/llms-config.ts` lists its sources explicitly
and does not include `docs/test-audit/`). The scanner scripts that produced the
inventories are not committed.
How a test is retired, and the evidence each deletion needs, is described in
[docs/TESTING.md](../../TESTING.md) ("Coverage responsibilities before
consolidation").
## Lanes
| Lane | Report | What it establishes | Consumed by |
|---|---|---|---|
| source-grep | [lane-source-grep/source-grep.md](lane-source-grep/source-grep.md) | Tests that read `src/**` as text: which are blind to behavior changes (probe edits they miss), which pin real contracts, and which need a routing fix before they can go | Blind/duplicate deletions; the source-grep rewrites; the `postgres-engine.ts` E2E map entry |
| doc-pins | [lane-doc-pins/doc-pins.md](lane-doc-pins/doc-pins.md) | Tests that assert on committed docs, skills, templates and recipes: prose-only pins versus generated-artifact freshness, link integrity and shipped prompt contracts | Doc-pin deletions; the resolver fixture tests; the doc-claims consolidation |
| e2e | [lane-e2e/e2e.md](lane-e2e/e2e.md) | How `test/e2e` files are routed in CI, which files run only PGLite, which wrappers double-run scenarios, and where selected E2E spends time | E2E lane corrections; the PGLite-only lane-move pilot |
| patterns | [lane-patterns/patterns.md](lane-patterns/patterns.md) | Cross-cutting low-value shapes over `test/**`: typeof probes, placeholder assertions, copied-function tests, near-duplicate files | Placeholder and typeof-probe cleanup; the `gbrain features` behavioral tests |
| seams | [lane-seams/seams.md](lane-seams/seams.md) | Test-only exports in `src/`, seams with no callers, and `src/` modules unreachable from every runtime entry (static walk, orphan guard, poison probe) | Seam cleanup; the dead-module cluster removals and their disposition gate |
## Inventories and probe logs
| File | Contents |
|---|---|
| [lane-source-grep/inventory.tsv](lane-source-grep/inventory.tsv) | Per test file: lane, test count, source reads, source imports, spawns, weight (ms), LOC |
| [lane-source-grep/pertest.json](lane-source-grep/pertest.json) | The same inventory with each file's test names |
| [lane-source-grep/struct_src.json](lane-source-grep/struct_src.json) | Files whose source reads look structural (counts, weight, LOC) |
| [lane-source-grep/probes.log](lane-source-grep/probes.log) | Raw mutation-probe results for the source-grep lane |
| [lane-e2e/e2e-files.json](lane-e2e/e2e-files.json) | Every `test/e2e` file classified by engine, key gating, spawning and weight |
| [lane-e2e/pglite-files.txt](lane-e2e/pglite-files.txt) | PGLite-only `test/e2e` files by weight (lane-move candidates) |
| [lane-e2e/attendance-retrieval-postgres.log](lane-e2e/attendance-retrieval-postgres.log), [lane-e2e/attendance-repair-postgres.log](lane-e2e/attendance-repair-postgres.log) | Measured runs showing the attendance wrappers execute both engine arms in the E2E lane |
| [lane-patterns/scan.json](lane-patterns/scan.json), [lane-patterns/scan2.json](lane-patterns/scan2.json) | Raw pattern-scan output (assertion shapes per file and per test) |
| [lane-patterns/neardup.txt](lane-patterns/neardup.txt) | Near-duplicate test file pairs by similarity |
| [lane-patterns/probes.log](lane-patterns/probes.log) | Raw mutation-probe results for the patterns lane |
| [lane-seams/test-only-exports.tsv](lane-seams/test-only-exports.tsv) | Exported `src/` symbols with no production caller, and the tests that use them |
| [lane-seams/seam-callers.tsv](lane-seams/seam-callers.tsv) | Test-named exports with their caller counts |
| [lane-seams/unreachable.tsv](lane-seams/unreachable.tsv), [lane-seams/dead-modules.txt](lane-seams/dead-modules.txt) | `src/` modules unreachable from any runtime entry, with LOC and the tests that import them |
| [lane-seams/dead-tests.txt](lane-seams/dead-tests.txt) | Test files that exist only to test those modules |
| [lane-seams/bundled-src.txt](lane-seams/bundled-src.txt) | `src/` files reached by a `bun build` of every runtime entry and package export |
The doc-pins lane recorded its probe results inline in its report; it has no
separate probe log.
## Implementation evidence
`implementation/` holds the per-slice evidence tables from the fix wave that
acted on these reports (v0.59.20.0): each deleted test's probe and surviving
owner, each new test's mutation, and each dead module's disposition.
| File | Slice |
| --- | --- |
| `implementation/security.md` | Source-config secret surfaces |
| `implementation/holes.md` | Coverage holes filled |
| `implementation/e2e-lanes.md` | E2E lane corrections |
| `implementation/deletions-guards.md` | Blind/duplicate test deletions, placeholder guard, source-read policy, docs |
| `implementation/dead-modules.md` | Dead-module clusters and the orphan permitted list |
| `implementation/pending-deletions.md` | Deletions that waited on new owners; process-cleanup fix |
| `implementation/lane-pilot.md` | Lane-move pilot and measurements |
| `implementation/rewrites.md` | Behavior rewrites, doc claims, docs-CLI truth check |
---
### Eval Decisions C2 Interleave Dev README (`docs/eval/decisions/c2-interleave-dev/README.md`)
# Interleaved supersession candidates: dev verdict
`facts.candidate_fusion = interleave` (candidate) against `rrf_free`, the single cosine arm (baseline), on
gbrain 91081f319, through an offline PGLite replay of a seeded fixture. Interleave adds no measurable benefit,
so the default stays `rrf_free`. Interleave never improved twin recall@5 and lost 1 to 2 twins out of 280.
False supersession and preserved distinct claims were identical in both arms at every threshold. The verdict
is `dev`, so it cannot set a default.
| Threshold | Twin recall@5 | False supersession | Preserved distinct claims | Correct decisions |
|---|---|---|---|---|
| 0.85 | 99.6% → 98.9% (CI −1.8 to 0 pts) | 19.5% → 19.5% | 93.3% → 93.3% | 64.5% → 64.5% |
| 0.90 | 99.6% → 98.9% (CI −1.8 to 0 pts) | 9.8% → 9.8% | 96.7% → 96.7% | 49.0% → 49.0% |
| 0.95 (product) | 99.3% → 98.9% (CI −1.1 to 0 pts) | 0.75% → 0.75% | 99.75% → 99.75% | 39.0% → 39.0% |
The overall result is `inconclusive` under the decision-kit gates, because the twin-recall superiority gate
neither passed nor failed. Both guards pass.
## What was measured
The fixture has 40 synthetic companies, 1,148 seeded rows and 400 probes. The seeded rows are:
- Single-valued claims, such as revenue, headcount, runway, headquarters, CEO, price, customers, launch date,
churn and NPS.
- Coexisting similar claims that differ only in numbers or dates: funding rounds, quarterly revenue, office
openings and board meeting dates.
- Private rows for world claims (a private copy and a private note) and one private-only claim per company.
Every fourth company is dense. It has all four coexisting families with up to 8 members each and three more
private notes per claim, so its cosine top 5 is crowded.
The probes are applied in order, as explicit-lane writes:
- 120 corrections with a changed number, date or name.
- 40 restatements.
- 80 back-to-back corrections of one claim. This is the state a concurrent pair reaches after the publication
guard's retry.
- 40 private corrections.
- 80 new members of coexisting claims, such as the next funding round or quarter.
- 40 new claims.
Every row carries its claim key, so each probe's expected twin is known by construction.
Each arm replays the fixture on a fresh in-memory brain through the product's `listSupersessionCandidates`.
The arms run the same decision rule as `decideSingleFact`: an exact fingerprint duplicate, or else the
highest-cosine eligible candidate at or above the threshold. The threshold is swept because it is calibrated
for the production embedding model, and this run uses a free local model (`BAAI/bge-small-en-v1.5`, 384
dimensions). At 0.95, the product's explicit-lane threshold, the real `decideSingleFact` ran beside the replay
and agreed on all 800 decisions. Statistics are paired by probe and clustered by company: a cluster bootstrap
CI and a cluster sign-flip p, using `pairedClusterStatistics`.
## Why interleave doesn't help here
The decision takes the highest-cosine eligible candidate, so a keyword-arm row can only change a decision in two
cases:
- Every row in the cosine top 5 is ineligible, for example a private row for a world write.
- The cut to 5 drops a cosine row that would have won.
In 341 to 348 probes the fused set held a row that the cosine arm did not. Still, the first case never occurred:
the cosine arm found 99.3 to 99.6% of twins, including in the dense slice (69 of 70). The second case cost
interleave 1 to 2 twins. No decision changed in either direction.
The dense slice was added after a first run showed no crowding in the standard slice. It is the keyword arm's
best case on this fixture, and it still did not help.
## What dominates instead
The decision threshold and the embedding model matter far more than candidate fusion. Both arms behave the
same way:
- At 0.95, the local model misses 116 of 120 corrections. Those corrections are inserted beside the old value,
which leaves 166 single-valued claims with two active values at the end.
- At 0.85, the local model falsely supersedes 70 of 80 coexisting claims. A Series B replaces the Series A, and
one quarter's revenue replaces another's.
These rates belong to this model and are not product numbers. They mean the supersession gate needs to be
checked against the production embedding model. This fixture can do that check with real embeddings for a
fraction of a cent once paid embedding calls are approved.
## Production embeddings
The [supersession-threshold-dev](../supersession-threshold-dev/README.md) follow-up re-embedded this fixture with
`voyage:voyage-4` (the default) and `openai:text-embedding-3-large`, and swept thresholds 0.80 to 0.97 for both
arms. Interleave never helped. With voyage-4 it lost one twin out of 280 to the cut to 5, so at thresholds
0.80 to 0.89 one more correction was missed than with `rrf_free`. From 0.90 up the two arms decided the same.
With 3-large both arms found every twin and decided the same at every threshold. The verdict stands: keep `rrf_free`.
## Reproduce
```bash
bun scripts/eval-c2-candidate-fusion.ts texts > /tmp/c2-texts.json
pip install fastembed==0.8.1
python3 scripts/eval-c2-embed.py /tmp/c2-texts.json /tmp/c2-embeddings.json.gz
bun scripts/eval-c2-candidate-fusion.ts run --embeddings /tmp/c2-embeddings.json.gz --out docs/eval/decisions/c2-interleave-dev
```
`verdict.json` records the sha256 of the fixture texts (`821285709d…`) and of the embeddings file
(`35723141e7…`). Dev spend was $0.
---
### Eval Decisions C4 Pinned Questions README (`docs/eval/decisions/c4-pinned-questions/README.md`)
# Pinned questions: B5 verdict
Pinned questions ship **opt-in**. The win is the anchored retrieval, not the maintained answer. Run 3 used
embeddings and three seeds. A plain reader handed the same entity-anchored evidence that pinned refresh uses,
at the same token budget, was as accurate as a pinned answer: 96.8% of reads against 98.1%, and pinned did not
beat it in seed 42. Handed all of that evidence, the reader was right on every read. The same anchoring lifts
query plus a reader from 88.4% to 96.8% at equal tokens and removes its stale-wrong answers (11.6% to 0%). The
safety gate passes with zero leakage, including 144 restricted-grant probes in run 3.
Pinned answers stay available for owners who want them. They are the cheapest way to serve an entity question
read many times: at 100 reads per write, a correct pinned answer costs $0.00057, against $0.00152 for the
anchored reader at equal tokens and $0.00284 at full evidence. Opt-in means gbrain creates no pin by itself.
Pinning a question is the owner's consent for its paid refresh (plan C1), and a brain with no pins makes no
model call. The refresh phase and `context_pack` delivery stay on for pins that exist, so no setting changed.
The anchored retrieval ships in pinned refresh (`retrieveEvidence` in `src/core/questions/refresh.ts`). Where
else it should apply is under "Where anchored retrieval applies" below.
Measured build: gbrain 1384a0db (the `capy/mpw-integration` branch). Stage: dev.
## Benefit gate
Run 3 decides. Its rule was written into this README and pushed (e17258eb) before any run-3 cell ran. Run 2's
rule compared pinned with query plus a reader on a keyword-only brain, which left the retrieval question open.
### Run 3: maintained answer against anchored retrieval (preregistered 2026-10-05, before any run-3 cell)
Run 2 left one open question. Pinned refresh retrieves evidence anchored on the pin's entity, newest first, and
the other arms did not, so run 2 cannot say whether the win comes from the maintained answer or from that
retrieval. Run 3 is designed to separate the two. It reuses run 2's workload generator unchanged.
- **Control arm, anchored retrieval + reader.** For each state it calls the exact retrieval pinned refresh uses
(`retrieveEvidence` in `src/core/questions/refresh.ts`: the entity page, then pages that link to it or name
it, newest first, then hybrid hits, facts, timeline and takes). It hands that evidence to the same reader
(`anthropic:claude-sonnet-5-5`) at the same token budget as query + reader: the pinned answer's delivered
tokens, with a floor of 200. No answer is maintained between batches.
- **Sensitivity arms, reported but not decisive.** The anchored control and query + reader each also run at
full evidence: every item pinned refresh sees, or the top 16 hybrid hits, with no token budget.
- **Embeddings on for every arm.** Pages are embedded with `voyage:voyage-4` (1024 dimensions, gbrain's default)
after every write batch, and search runs in gbrain's default mode (balanced: hybrid keyword + vector with the
default reranker). Pinned refresh, query + reader, the anchored control and `think` all search the same
embedded brain.
- **Three seeds:** 42, 7 and 1234. Results report each seed, the mean and the spread (min and max).
- **Arms otherwise as run 2:** pinned with the default refresh model (`anthropic:claude-opus-4-7`), pinned with
`anthropic:claude-sonnet-5-5` refresh (model-matched to the reader), query + reader and `think`. Reads per
write are 1, 10 and 100. Leakage is probed for every seed. The cap is $15.
**Decision rule.** Pinned with the default model beats the anchored control if, in every seed, either its
accuracy is higher or its mean freshness lag is lower, and if there are zero leaks across all seeds.
- If pinned beats the control, pinned questions stay default-on.
- If pinned only ties the control (the rule above fails without a leak), the anchored retrieval is the win. It
ships, along with a recommendation for where else it applies (such as query for entity-scoped questions),
and pinned questions go back to opt-in.
- Any leak means opt-in, whatever the accuracy.
#### Run 3 results
Every arm ran on 3 seeds with `voyage:voyage-4` embeddings and gbrain's default balanced search. Each cell is
the mean across seeds, with the min and max in brackets. The reads-per-write ratio does not change accuracy or
freshness.
| Arm | Accuracy | Stale-wrong | Freshness lag (batches) | Correct at change |
|---|---|---|---|---|
| pinned, default model (Opus 4.7) | 0.981 [0.972, 1.000] | 0.000 | 0.022 [0.000, 0.033] | 0.978 [0.967, 1.000] |
| pinned, Sonnet 5.5 refresh | 0.995 [0.986, 1.000] | 0.000 | 0.006 [0.000, 0.017] | 0.994 [0.983, 1.000] |
| **anchored retrieval + reader (control)** | 0.968 [0.944, 0.986] | 0.000 | 0.039 [0.017, 0.067] | 0.961 [0.933, 0.983] |
| anchored retrieval + reader, full evidence | 1.000 | 0.000 | 0.000 | 1.000 |
| query + reader | 0.884 [0.875, 0.903] | 0.116 [0.097, 0.125] | 0.139 [0.117, 0.150] | 0.861 [0.850, 0.883] |
| query + reader, full evidence | 0.991 [0.972, 1.000] | 0.009 [0.000, 0.028] | 0.011 [0.000, 0.033] | 0.989 [0.967, 1.000] |
| think | 1.000 | 0.000 | 0.000 | 1.000 |
Per seed, against the control:
| Seed | Pinned accuracy | Control accuracy | Pinned lag | Control lag | Pinned beats control |
|---|---|---|---|---|---|
| 42 | 0.972 | 0.986 | 0.033 | 0.017 | no |
| 7 | 1.000 | 0.972 | 0.000 | 0.033 | yes |
| 1234 | 0.972 | 0.944 | 0.033 | 0.067 | yes |
**Outcome: tie.** Pinned beats the control in two seeds out of three, and in seed 42 the control is ahead on
both accuracy and freshness, so the preregistered rule fails. There were zero leaks in 144 probes. Under the
rule, the anchored retrieval is the win and pinned questions go back to opt-in.
- Most of run 2's gap was keyword-only search and a tight token budget. With embeddings on, query plus a
reader at full evidence reaches 0.991, and `think` reaches 1.000.
- At equal tokens, the anchoring itself is worth about 8 accuracy points over plain query (0.968 against
0.884). It also takes stale-wrong answers from 11.6% to 0%, because it puts the newest notes about the
entity first.
- Pinned with Sonnet refresh (0.995) is the arm model-matched to the reader. It stays within a seed's
variation of the full-evidence anchored reader (1.000), so a maintained answer adds no accuracy over
handing the same evidence to the same model.
- No refresh failed in 432 attempts. The refresh path now parses tolerantly and retries once (see "Malformed
refresh output" below).
Dollars per correct answer (mean across seeds):
| Reads per write | Pinned (Opus 4.7) | Pinned (Sonnet 5.5) | Anchored, equal tokens | Anchored, full | Query + reader | Query, full | Think |
|---|---|---|---|---|---|---|---|
| 1 | 0.00966 | 0.00683 | 0.00152 | 0.00284 | 0.00133 | 0.00231 | 0.02665 |
| 10 | 0.00139 | 0.00139 | 0.00152 | 0.00284 | 0.00133 | 0.00231 | 0.02665 |
| 100 | 0.00057 | 0.00084 | 0.00152 | 0.00284 | 0.00133 | 0.00231 | 0.02665 |
A pinned read costs about $0.00047, because the reader sees one short answer instead of the evidence. Keeping
a pin current costs about $0.108 per pin over the 12 batches with Opus, or $0.072 with Sonnet. Pinned overtakes
the anchored reader at equal tokens after about 110 reads per pin, and the full-evidence anchored reader after
about 46. That makes pinning a cost choice for questions read often. It is not an accuracy choice.
Metered spend for run 3: $11.80 of the $15 cap. That is $10.95 for the run, $0.38 for a one-entity smoke run
and $0.48 for a Sonnet refresh replay that looked for the malformed output. Voyage embedding and rerank calls
are not metered and were small.
#### Where anchored retrieval applies
Anchoring helps whenever a question names one entity and asks for its current state. It puts the entity page
first, then pages that link to it or name it, newest first. Keyword and vector ranking both treat older and
newer notes about the entity alike.
- **query / search, for entity-scoped questions** (the largest measured effect: +8 accuracy points and no
stale-wrong answers at equal tokens). When the query resolves to one entity and asks for its latest or
current state, the newest anchored pages can be blended into the candidate pool ahead of fusion.
- **think's gather** for "now" or "current" questions about one entity. With embeddings, `think` already reaches
1.000 here at 17 times the anchored reader's cost, so anchoring is the cheaper route to the same answer.
- **context_pack's entity cards**, which choose which pages about a packed entity to show.
Each of these needs its own measured gate before it becomes a default; this run measured only the reader
arms.
#### Malformed refresh output
Run 2's Sonnet refresh failed twice with `model_output_not_json`. A 72-refresh replay on seed 42 did not
reproduce it, so the raw reply was never seen. The parser had two gaps that fit the symptom: it only tried the
span from the first `{` to the last `}`, so prose with braces around the JSON or a draft object followed by a
corrected one broke it, and one bad reply failed the whole refresh. 1384a0db fixes both. The parser now tries
every balanced top-level object and takes the last one shaped like an answer. A reply with no answer object
is retried once with a JSON-only reminder; both calls are charged. Tests are in
`test/pinned-questions-refresh-parse.test.ts`, and 6 of the 7 fail without the fix.
### Run 2: corrections appended as new evidence
The workload is seeded (seed 42) and has 6 entities and 12 write batches, which is 13 writes per entity. Each
entity has a widget-factory city, and corrections arrive as dated notes while the older notes stay as written.
Batch 4 adds two conflicting notes in one week, and the later note corrects the earlier one. Batch 6 delivers
the update through `remember`. Batch 7 withdraws it with `forget`, and the answer reverts. Batch 10 makes the
newest note private. After each batch every question is read 1, 10 or 100 times, depending on the frozen
reads-per-write ratio. The cost counted is total lifecycle dollars: the first answer, every refresh attempt,
delivered read tokens and every model call.
| Arm | Accuracy | Stale-wrong | Freshness lag (batches) | Correct at change | Lifecycle $ |
|---|---|---|---|---|---|
| pinned, default model (Opus 4.7) | 0.986 | 0.000 | 0.017 | 0.983 | 0.649 |
| pinned, Sonnet 5.5 refresh | 0.958 | 0.014 | 0.050 | 0.950 | 0.415 |
| query + reader | 0.514 | 0.486 | 0.583 | 0.483 | — |
| think | 0.792 | 0.208 | 0.250 | 0.783 | — |
Freshness lag is the mean number of write batches before an answer reflects one of the 60 value changes.
Correct at change is the share of those changes answered correctly in the batch they happened.
Dollars per correct answer:
| Reads per write | Pinned (Opus 4.7) | Pinned (Sonnet 5.5) | Query + reader | Think |
|---|---|---|---|---|
| 1 | 0.00961 | 0.00681 | 0.00234 | 0.03061 |
| 10 | 0.00138 | 0.00141 | 0.00234 | 0.03061 |
| 100 | 0.00056 | 0.00087 | 0.00234 | 0.03061 |
- Pinned spends more total dollars than query plus a reader until about 147 reads per pin (163 with the Sonnet
refresh model). Because it is right twice as often, it is already cheaper per correct answer at 10 reads per
write, and at 100 it costs a quarter as much.
- Pinned is 3.2 times cheaper than `think` per correct answer at 1 read per write, 22 times at 10 and 55 times
at 100, and it is also more accurate.
- The Sonnet refresh model cuts lifecycle cost by 36% ($0.415 against $0.649) for 2.8 points of accuracy.
It returned non-JSON on 2 of 72 refreshes; each time the pin kept its previous answer, which counts against
it.
- Withdrawal is the weakest event. After `forget` in batch 7, 1 of 6 default-model answers and 2 of 6 Sonnet
answers missed the revert.
- Leakage: 48 probes through a restricted MCP grant that cannot read private pages, covering search,
`get_page`, `context_pack` and `questions_status`, found 0 leaks.
**Retrieval asymmetry.** Pinned refresh anchors retrieval on the pin's scope: the entity page first, then
pages that link to it or name it, newest first, with question and synthesis pages excluded. Query plus a
reader uses ordinary keyword retrieval, and `think` uses its own gather. Every arm is keyword-only because the
harness brain has no embedding key. Query plus a reader fails here the way it does in real use: once notes
pile up, keyword ranking treats every note that mentions the entity's city alike and often misses the newest.
**Diagnostic attempt before the fix.** The first run-2 attempt, on 183fee7f, found pinned no better than query
plus a reader (0.528 and 0.542 accuracy against 0.514). Pinned refresh retrieval had the same newest-note
blind spot. baadfc04 fixed it in `src/core/questions/refresh.ts` with a regression test. The attempt is
recorded in `verdict.json` as a diagnostic and was not a decision input.
#### Models
- Answer and refresh model: `anthropic:claude-opus-4-7`, gbrain's default for questions
(`models.standing_questions`, which resolves to the deep tier). The cost-lever arm refreshes with
`anthropic:claude-sonnet-5-5`.
- `think` arm: the same default model.
- Reader for the pinned and query arms: `anthropic:claude-sonnet-5-5`, the fixed reader of the B suites.
Metered spend for run 2: $5.92 of the $10 cap ($2.98 for the run and $2.93 for the diagnostic
attempt).
### Run 1: corrections rewrite the evidence page
Measured build: gbrain a4267eed7. Verdict at the time: opt-in. Run 1 found that the benefit gate did not pass
against query plus a reader. Accuracy was at the ceiling for every arm, and pinned answers did not cost less
per correct answer until a pin had been read about 240 times.
The cost counted is total lifecycle dollars per correct, fresh answer: the first answer, every refresh
attempt, delivered read tokens and every model call. The workload is seeded and has 6 entities and
4 write batches. Each entity has a widget-factory city, and later batches correct some of those cities.
After each batch, every question is read 1 or 10 times, depending on the frozen reads-per-write ratio.
| Reads per write | Arm | Reads | Correct | Stale-wrong | Dollars | Dollars per correct |
|---|---|---|---|---|---|---|
| 1 | pinned | 24 | 24 | 0 | 0.0559 | 0.00233 |
| 1 | query + reader | 24 | 24 | 0 | 0.0127 | 0.00053 |
| 1 | think | 24 | 24 | 0 | 0.1828 | 0.00762 |
| 10 | pinned | 240 | 240 | 0 | 0.1262 | 0.00053 |
| 10 | query + reader | 240 | 240 | 0 | 0.1270 | 0.00053 |
| 10 | think | 240 | 240 | 0 | 1.8355 | 0.00765 |
- Pinned lifecycle split: $0.048 went to the first answers and 14 refresh attempts, and $0.0079 (1 read per
write) or $0.078 (10 reads per write) went to reader tokens over the fresh sentences.
- Break-even: pinned overtakes query + reader after about 240 reads per pin (242 and 237 in the two runs).
Both arms hand the reader about the same number of tokens per read, so a pin saves little at read time.
The cost of keeping the answer current is repaid slowly.
- Against on-demand `think`, pinned is cheaper at both ratios: 3.3 times at 1 read per write and 14.5 times
at 10.
**Ceiling.** Every arm answered every read correctly. The workload rewrites the evidence page when a city is
corrected, so no arm had a superseded value to repeat (stale-wrong is 0 everywhere). This run cannot show an
accuracy or freshness advantage. It decides on cost alone.
#### Models
- Answer and refresh model: `anthropic:claude-opus-4-7`. This is gbrain's default for questions
(`models.standing_questions`, which resolves to the deep tier).
- `think` arm: the same default model.
- Reader for the pinned and query arms: `anthropic:claude-sonnet-5-5`, the fixed reader of the B suites.
- Retrieval is keyword-only for all three arms, because the harness brain has no embedding key.
Metered spend: $2.34 of the $40 cap.
## Safety gate
`test/helpers/pinned-questions-scenarios.ts` passes 33 of 33 scenarios on PGLite
(`test/pinned-questions-safety.test.ts`) and 33 of 33 on live Postgres
(`test/e2e/pinned-questions-postgres.test.ts`). The full `bun run ci:ubicloud` gate passes on the integrated
tree at 170422f4 (merged with master c9ba7782). The suite covers:
- Zero leakage to restricted grants on search, query, list_pages, get_page, get_versions, context_pack and
recall.
- No answer text in pages, chunks, versions, history or export.
- Read-time staleness for edits, soft and hard deletes, forget, clock expiry, supersession, visibility changes,
takes, timeline entries and owner edits.
- Refresh that never publishes over a concurrent edit, a duplicate worker, a crash between publication stages
or a failure.
- The consent, keyless, budget and no-worker states, and the operator journeys over MCP.
## Reproduce
```bash
# Run 3 (deciding)
bun evals/pinned-questions/appended-gate.ts --plan --json --seeds 42,7,1234 --entities 6 \
--reader-model anthropic:claude-sonnet-5-5 --refresh-models anthropic:claude-opus-4-7,anthropic:claude-sonnet-5-5 \
--embeddings voyage:voyage-4
bun evals/pinned-questions/appended-gate.ts --run --yes --max-usd 14.1 --seeds 42,7,1234 --entities 6 \
--reader-model anthropic:claude-sonnet-5-5 --refresh-models anthropic:claude-opus-4-7,anthropic:claude-sonnet-5-5 \
--embeddings voyage:voyage-4 --partial run3-partial.json --json
# Run 2
bun evals/pinned-questions/appended-gate.ts --plan --json --entities 6 --seed 42 \
--reader-model anthropic:claude-sonnet-5-5 --refresh-models anthropic:claude-opus-4-7,anthropic:claude-sonnet-5-5
bun evals/pinned-questions/appended-gate.ts --run --yes --max-usd 7 --entities 6 --seed 42 \
--reader-model anthropic:claude-sonnet-5-5 --refresh-models anthropic:claude-opus-4-7,anthropic:claude-sonnet-5-5 --json
# Run 1
bun evals/pinned-questions/benefit-gate.ts --run --yes --max-usd 40 --entities 6 --batches 4 --seed 42 \
--reader-model anthropic:claude-sonnet-5-5 --json
```
`verdict.json` carries all three run reports and the run-2 diagnostic attempt, and `decision.json` records the arms,
models, workloads, decision rule and budget.
## Changelog
- 2026-10-05, run 3: anchored-retrieval control, embeddings on, 3 seeds, on 1384a0db. Pinned ties the anchored
control (it loses seed 42), so the anchored retrieval is the win and the verdict returns to opt-in. The
refresh parser now handles malformed replies and retries once.
- 2026-10-05, run 2: appended-corrections workload on baadfc04. Pinned beats query plus a reader on accuracy
and freshness with zero leakage, so the verdict moves from opt-in to default-on.
- 2026-10-05, run 1: rewrite workload on a4267eed7. Every arm hit the accuracy ceiling and pinned did not win
on cost against query plus a reader, so pinned questions shipped opt-in.
---
### Eval Decisions Entity Anchoring Query README (`docs/eval/decisions/entity-anchoring-query/README.md`)
# Entity-anchored retrieval in query and search: verdict
Entity anchoring passes gates 1 and 2 here. `search.entity_anchoring` stays off until the harness lane's gate 3
(dev slices, then validation) passes, and that run has not happened. On the seeded appended-corrections
workload (3 seeds, embeddings on), turning the key on lifted `query` + reader at equal tokens from 88.4% to
100% accuracy, from 11.6% to 0% stale-wrong answers, and from 0.139 to 0 batches of freshness lag. Turning it on
lowered no question's recall in the existing evals that cover `query`, but on their as-written questions it
never fired, so that pass shows only that nothing else moves.
Measured build: gbrain 2fa44f149 (the `capy/mpw-integration` branch). c4add4176 moves the op seam into
`entity-anchor.ts` with no change in behavior. Stage: dev.
## The change
Some questions name one entity and ask for its current state: "Which city does acme-example build widgets in
now?" For these, `query` and `search` put the entity page first, then pages that link to it or name it,
newest first, ahead of the organic rows. The row count and the token budget stay what the caller asked for.
The code is `src/core/search/entity-anchor.ts`. Pinned-question refresh already used this anchoring, and both
callers now share it (`entityAnchoredPages`).
- **Detection is deterministic and makes no model call.** It needs a current-state cue in the query ("now",
"currently", "latest", "these days" and similar) and exactly one entity page whose title the query mentions
as a token run. That page must be a person, company, organization, fund, project, deal or concept, and the
caller must be able to read it. With no entity or several entities, nothing changes.
- **Read safety.** Every row the change adds comes from `getChunkWindows`, which re-authorizes each page under
the caller's scope: source, deleted, projection, archived source, quarantine, private pages and safe chunks.
A page in the organic set keeps its row and moves up.
- **Scope.** Anchoring applies to plain queries only. It is skipped with `offset`, `types`, `since`, `until`,
`lang`, `symbol_kind` or `near_symbol`, and on the keyword-only `search` path. Anchored rows take at most
half the rows.
- **Touch points.** The change is additive in the op layer, and `hybridSearch` ranking is untouched:
- `src/core/ops/search.ts`: one guarded call each in `search` (after the declared-name fan-out) and in
`query` (after the fan-out, before the CRAG grade).
- `src/core/search/entity-anchor.ts` (new).
- `src/core/questions/refresh.ts`: `anchoredSlugs` now calls the shared function with the same SQL.
- `src/core/types.ts`: the optional `SearchResult.entity_anchored` field.
- `src/core/config.ts`: the key registration.
## Results
### Gate 1: seeded workload (pass)
Every state of every seed triggered anchoring (216 of 216). Each cell is the mean across seeds 42, 7 and 1234,
with the min and max in brackets.
| Arm | Accuracy | Stale-wrong | Freshness lag (batches) | Correct at change | $ per correct |
|---|---|---|---|---|---|
| **key on, equal tokens** | 1.000 [1.000, 1.000] | 0.000 | 0.000 | 1.000 | 0.00127 |
| key off, equal tokens | 0.884 [0.875, 0.903] | 0.116 [0.097, 0.125] | 0.139 [0.117, 0.150] | 0.861 [0.850, 0.883] | 0.00133 |
| key on, full evidence | 1.000 | 0.000 | 0.000 | 1.000 | 0.00230 |
| key off, full evidence | 0.981 [0.972, 0.986] | 0.009 [0.000, 0.028] | 0.022 [0.017, 0.033] | 0.978 [0.967, 0.983] | 0.00235 |
| Seed | Accuracy on / off | Lag on / off | Wins | Accuracy lower |
|---|---|---|---|---|
| 42 | 1.000 / 0.875 | 0.000 / 0.150 | yes | no |
| 7 | 1.000 / 0.903 | 0.000 / 0.117 | yes | no |
| 1234 | 1.000 / 0.875 | 0.000 / 0.150 | yes | no |
- The key-off arm reproduces run 3's query + reader arm (0.884), so the comparison sits on a known baseline.
- At equal tokens, anchoring puts the newest note about the entity inside the budget. Off, keyword and vector
ranking often surface an older note first, and the reader repeats the superseded city.
- Cost per correct answer falls slightly (0.00127 against 0.00133), because the reader reads the same tokens
and is right more often.
- **Caveat.** This workload was built around exactly this failure mode, so every question is an entity-scoped
current-state question. It shows the mechanism works; it cannot say how often real questions take this shape.
Gate 3 measures that.
Metered spend: $1.52 of the $10 cap. Voyage embedding and rerank calls are not metered.
### Gate 2: existing retrieval evals (pass)
All corpora were run through the `query` op, keyword-only and hermetic. Recall@10 and MRR are shown key on /
key off.
| Corpus | Questions | Anchoring fired | Recall@10 lower | Recall@10 higher | Recall@10 on / off | MRR on / off |
|---|---|---|---|---|---|---|
| namedthing | 12 | 0 | 0 | 0 | 0.917 / 0.917 | 1.000 / 1.000 |
| namedthing+now | 12 | 0 | 0 | 0 | 0.833 / 0.833 | 0.917 / 0.917 |
| relational | 38 | 0 | 0 | 0 | 1.000 / 1.000 | 0.289 / 0.289 |
| relational+now | 38 | 24 | 0 | 8 | 0.136 / 0.000 | 0.096 / 0.000 |
| longmemeval-nightly | 10 | 0 | 0 | 0 | 1.000 / 1.000 | 1.000 / 1.000 |
| longmemeval-nightly+now | 10 | 0 | 0 | 0 | 1.000 / 1.000 | 1.000 / 1.000 |
- The `+now` rows are a diagnostic, not the gate: each question has " now" appended so anchoring can fire.
On the relational fixture it fired on 24 of 38 questions. 8 gained recall and none lost.
NamedThingBench titles are not entity pages, and the LongMemEval nightly fixture has none either, so
anchoring never fires there.
- No hard-negative question lost its clean top 3.
- **Key off matches the build without the change.** Every key-off response in this script, 120 rows across the
corpora, matches the same script run on the pre-change code. The only differences are fields that vary
between any two runs: scores carry a recency term computed from the clock, and page revisions are random
UUIDs.
- Reproduce: `bun evals/entity-anchoring/regression.ts --json`.
## Where else this applies
The pinned-questions run 3 also recommended think's gather for current-state questions about one entity, and
context_pack's entity cards. Neither is built. Each needs its own gate.
## Gates (preregistered)
1. **Seeded workload.** This is the appended-corrections workload from
`docs/eval/decisions/c4-pinned-questions/` (run 3).
- Setup: seeds 42, 7 and 1234; 6 entities; 12 write batches; `voyage:voyage-4` embeddings after every
batch; balanced search.
- Arms: the `query` op (expansion off) with `search.entity_anchoring` on and off, read by the B-suite
reader `anthropic:claude-sonnet-5-5` at equal tokens. The budget is 200 tokens of rows in rank order,
the same as run 3's query + reader arm.
- Sensitivity arms, reported but not decisive: the same two arms at full evidence (16 rows).
- Metrics, as in run 3: accuracy, stale-wrong rate, freshness lag in batches, correct at change and
dollars per correct answer.
- **Rule:** the key-on arm wins gate 1 if, in every seed, its accuracy is higher or its mean freshness lag
is lower, and its accuracy is lower in no seed.
2. **No regression on the existing evals that cover `query`**, each run through the `query` op with the key
on and off. Each reports how many questions triggered anchoring, because a corpus where it never fires
proves nothing:
- NamedThingBench and the relational retrieval-quality fixture (`test/fixtures/retrieval-quality/`),
hermetic and keyword-only.
- The LongMemEval nightly fixture (`test/fixtures/longmemeval-nightly.jsonl`), ingested the way
`gbrain eval longmemeval` ingests it.
- **Rule:** with the key on, no question's top-10 recall is lower than with the key off.
- The `gbrain eval longmemeval` command itself calls `hybridSearch` directly, so the key cannot change it.
3. **Harness lane.** This is run by the harness lane, not here: dev slices (LongMemEval knowledge-update,
PersonaMem, BEAM dev), then confirmation on validation. The harness must retrieve through the `query` op
(or `gbrain query`) with `search.entity_anchoring=true` for the change to apply.
**Decision.** The key becomes default-on only if gates 1 and 2 pass here and gate 3 passes in the harness
lane. Until then it stays off. The cap for gates 1 and 2 is $10.
## Reproduce
```bash
bun evals/entity-anchoring/query-gate.ts --plan --seeds 42,7,1234 --embeddings voyage:voyage-4
bun evals/entity-anchoring/query-gate.ts --run --yes --max-usd 4 --seeds 42,7,1234 --entities 6 \
--reader-model anthropic:claude-sonnet-5-5 --embeddings voyage:voyage-4 --json
bun evals/entity-anchoring/regression.ts --json
```
## Changelog
- 2026-10-05: gates 1 and 2 pass on 2fa44f149. The key stays off pending gate 3.
- 2026-10-05: gates preregistered before any gated run.
---
### Eval Decisions P1 Dev 2026 10 04 R2 README (`docs/eval/decisions/p1-dev-2026-10-04-r2/README.md`)
# P1 temporal typed edges, round 2: development verdict and held-out preregistration
**Held-out E1 (set C, seeds 11/13/17, custodian): pass.** `graph.edge_validity` stays on.
Results are below, under "Held-out verdicts".
Round 2 replaces [round 1](../p1-dev-2026-10-04/README.md), whose held-out run on
phrasing set B failed. `decision.json` is the decision-kit spec and `verdict.json` the
dev verdict. Dev verdicts never set a default; the custodian's held-out verdict does.
## Builds
- Baseline: `6622a119e` (master merge base).
- Candidate: `feb077ef9`, frozen. It also carries pack-declared relation semantics
(`link_types[].temporal`).
## What failed on set B, and the fix
The set B run (custodian, seeds 11/13/17) failed the traps gate: 101 of 115 trap items
were correct (87.8% against a 99% bar). Advisor traps were 35/35, investment-after-exit
37/43, alumni meetings 29/37. Current-employer recall fell 0.049 and live-edge recall
0.062 below the baseline. Set A, the only phrasing the build had been tuned on, showed
traps at 1.0 and no recall change, so the build had overfit set A.
Three development phrasing sets written after the verdict without sight of set B (A2,
A3) reproduced both failure kinds on the round-1 build: recall 0.44–0.47 against a
baseline of 0.67–0.87, traps 0.69–0.85. The causes were general rules, not wording:
1. **Cues outside the relationship.** A start or end cue anywhere before a reference
moved employment even when the line was about investing, a meeting or an event
("Joined [X]'s Series B", "Joined the [X] alumni dinner"). Natural cues now never
move a state relationship on investing, meeting or event lines, or when the
reference is qualified by what follows ("[X]'s …", "[X] alumni"); "[X]'s advisory
board" is the one qualified form that dates `advises`. Event relations never close.
2. **Past prose closing a dated start.** A dated start with past-tense prose and no
dated end was closed at an unknown date, and present perfect and promotions ("has
worked at", "was promoted to CTO at") read as past. A dated start now stays open
until a dated end, and those forms read as present.
3. **Missed transitions.** "Started at [X]" was taken for the explicit grammar with a
relation named `at`, so the line was ignored; the grammar now needs a relation
token. "Moved from [A] to [B]" and "Left [A] for [B]" did not start B; they do,
for the relation that ended. Frontmatter `since`/`until` stored as UTC-midnight
timestamps were not read; they are. Common leave and join verbs were added
("moved on from", "stepped away from", "was hired by", "accepted an offer from").
Unit tests for each rule are in `test/link-temporal-evidence.test.ts` and
`test/link-validity.test.ts`.
## Development results (all temporal-edges gates pass on A, A2 and A3)
Source: gbrain-evals branch `p1-temporal-edges-dev-a2` (`a257cab`, on P0's
`p0-heldout-harness`), `eval/runner/temporal-edges.ts --phrasing A|A2|A3`, seeds 3 and 5.
| Metric | A base → cand | A2 base → cand | A3 base → cand |
|---|---|---|---|
| Current-employer precision | 0.343 → 1.000 | 0.356 → 1.000 | 0.327 → 0.889 |
| As-of exact | 0.212 → 0.900 | 0.217 → 0.913 | 0.194 → 0.694 |
| During-year F1 | 0.594 → 0.896 | 0.601 → 0.909 | 0.472 → 0.690 |
| Stale summary flagged | 0.000 → 0.867 | 0.000 → 0.700 | 0.000 → 0.533 |
| Current-employer recall | 0.842 → 0.842 | 0.870 → 0.870 | 0.670 → 0.670 |
| Live-edge recall | 0.842 → 0.842 | 0.871 → 0.871 | 0.662 → 0.662 |
| Traps | 0.446 → 1.000 | 0.446 → 1.000 | 0.541 → 1.000 |
| Write-order invariance | 1 → 1 | 1 → 1 | 1 → 1 |
Recall equals the baseline on every set, so the remaining recall gap is link typing,
which both builds share: a timeline-only "Joined [X]" or "is an advisor to [X]" can
type the edge as something other than `works_at`. That also caps A3's precision and
as-of numbers.
Guardrails: LoCoMo dev recall-all@5 0.7543 → 0.7543 (pass); N3 513/513 in both builds
(pass, no regression); N4 0.6176 → 0.6176 with no new wrong merge (pass); N1 contracts
pass in both; BEAM-100k 0.4537 → 0.4537, inconclusive (6 clusters, below the kit's
minimum of 10), which makes the overall kit verdict `inconclusive`.
## Held-out preregistration (custodian only)
1. **E1 on a fresh phrasing set C** (set B is spent), seeds 11, 13 and 17. Gates as in
round 1: now-precision +0.10, as-of +0.15, during-F1 +0.15, stale-summary correction
+0.20 (superiority, cluster-bootstrap interval above zero); current-employer and
live-edge recall non-inferior within 0.02; traps ≥ 0.99; order invariance 1 on every
item; no guardrail failing. `graph.edge_validity` stays on only if E1 passes.
2. **E2 and E3** as preregistered in round 1, run on this frozen build after E1. E2
passed for all five models: [p1-e2-2026-10-05](../p1-e2-2026-10-05/README.md).
## Held-out verdicts
**E1, set C (custodian; baseline `6622a119e`, candidate `feb077ef9`): pass.**
| Gate | Baseline → candidate | Result |
|---|---|---|
| Current-employer precision | 0.376 → 0.943 | pass |
| As-of exact | 0.208 → 0.678 | pass |
| During-year F1 | 0.455 → 0.653 | pass |
| Stale-summary correction | 0.000 → 0.364 | pass |
| Current-employer recall | 0.616 → 0.612 | non-inferior, pass |
| Live-edge recall | 0.608 → 0.603 | non-inferior, pass |
| Traps | 115 / 115 | pass |
| Write-order invariance | 240 / 240 | pass |
**E3, ingestion to answer (report only).** After a correction is written, `entity`,
`context_pack` and compiled context show it for 0.277 of people and ambient turn context
for 0.239; the baseline shows it for none. The ceiling is link typing shared by both
builds: a line such as "Signed on with [X] as CTO" is not typed `works_at`, so there is
no relationship for the correction to date.
---
### Eval Decisions P1 Dev 2026 10 04 README (`docs/eval/decisions/p1-dev-2026-10-04/README.md`)
# P1 temporal typed edges: development verdict and held-out preregistration
**Held-out verdict (set B): fail** on the traps gate (101 of 115) and recall
non-inferiority. Round 2, with the fixes and a new preregistration, is in
[p1-dev-2026-10-04-r2](../p1-dev-2026-10-04-r2/README.md).
This folder holds the development comparison for temporal typed edges and the
plan for the held-out run. `decision.json` is the decision-kit spec and
`verdict.json` is the kit's dev verdict. Dev verdicts never set a default; the
held-out verdict from the custodian does.
## Builds
- Baseline: `5bd9e8497` (master merge base).
- Candidate: `bc6723c85`. Later branch commits change only CLI help, exit
codes, tests and goldens (`git diff bc6723c85..HEAD -- src/` touches
`src/cli.ts` and `src/commands/edge-proposals.ts`), none of which the
sources below call.
## Development results (kit verdict `blocked`: two guardrail sources have kit-template errors, below)
Primary source `temporal-edges` (gbrain-evals branch `p1-temporal-edges-dev` at `7323f2f`, `eval/runner/temporal-edges.ts`,
development phrasing set A, seeds 3 and 5, zero LLM):
| Metric | Baseline | Candidate | Gate | Result |
|---|---|---|---|---|
| "Who works at C now" precision | 0.343 | 1.000 | superiority +0.10 | pass, Δ 0.657 [0.604, 0.707] |
| Employer set on a date (as-of exact) | 0.212 | 0.900 | superiority +0.15 | pass, Δ 0.688 [0.621, 0.752] |
| Employers during a year (set-F1) | 0.594 | 0.896 | superiority +0.15 | pass, Δ 0.302 [0.259, 0.345] |
| Stale summary flagged in `context_pack` | 0.000 | 0.867 | superiority +0.20 | pass, Δ 0.867 [0.733, 0.967] |
| Current-employer recall (`now`, live reads) | 0.842 | 0.842 | non-inferiority 0.02 | pass |
| Traps (advisor stays live; investments, alumni meetings do not reopen) | 0.446 | 1.000 | candidate ≥ 0.99 | pass |
| Write-order invariance | 1.000 | 1.000 | every item 1 | pass |
| `context_pack` names the current employer (exploratory) | 0.100 | 0.333 | report only | |
Recall is 0.842 in both builds because link typing misses some employers
before temporal state applies: a timeline line "Joined [X] as engineer" on a
page whose prose never names X types X as `mentions`, and "works at [A] …
also advises [B]" can type A as `advises`. That is link typing, shared by both
builds; it also caps as-of at 0.90 and current-employer naming at 0.33.
Guardrails:
- LoCoMo dev recall-all@5: 0.7543 → 0.7543, pass.
- BEAM-100k dev recall-all@5: 0.4537 → 0.4537, inconclusive (6 clusters, below the family minimum of 10).
- N1 knowledge-update contracts: pass in both builds.
- N3 temporal as-of: the kit blocked the comparison (rows without a `scenario`
cluster). Read from the receipts: 513 of 513 probes pass in both builds.
- N4 entity resolution: the kit blocked the comparison (no eligible rows).
Read from the receipts: identical headline (B³-F1 0.771, accuracy 0.706, 0
wrong merges) and identical rows apart from one result ordering.
- Link type accuracy was not compared: its runner reads the installed gbrain
package rather than the build under test.
## Held-out preregistration (for the custodian)
Run by the custodian only; the implementer never sees held-out text or seeds.
1. **E1 temporal edges (decides `graph.edge_validity` stays on).** Phrasing set B
(cue verbs and templates absent from set A, frozen by the custodian), seeds
11, 13 and 17. Pass: now-precision +0.10, as-of +0.15, during-F1 +0.15,
stale-summary correction +0.20 (each a superiority gate with a
cluster-bootstrap interval above zero); recall non-inferior within 0.02;
traps ≥ 0.99; order invariance 1 on every item; no guardrail failing.
2. **E2 contradiction phase (decides `dream.edge_contradictions.mode` per model).**
Same ledger with only dated "joined" lines, undated and out-of-order
sub-ledgers; `apply` arms for `claude-haiku-4-5` (utility default) and the
newest frontier models `claude-opus-5-5`, `claude-sonnet-5-5`,
`gpt-6.1-sol` and `claude-fable-5-1`; 3 runs each. A model is certified for
`apply` when wrong closures stay at or below 1% in all 3 runs and as-of
improves at least 10 points over the E1 arm; undated pairs must yield only
`undated_unresolved`. Budget cap $20 LLM; the custodian asks before the
frontier arms run past it. Needs the E2 runner mode (not in the kit yet).
3. **E3 ingestion to answer.** A correction written through stdio `put_page`
(HTTP after remote bulk writes land), then `entity`, `context_pack`,
ambient turn context, compiled context and `query` checked by string. Needs
the receipt mode (not in the kit yet).
Defaults follow the verdicts: `graph.edge_validity` stays on only if E1 passes
with no guardrail failing; `apply` is enabled per model only for E2-certified
models (the certified list in `src/core/cycle/edge-contradictions.ts` is empty
until then).
---
### Eval Decisions P1 E2 2026 10 05 README (`docs/eval/decisions/p1-e2-2026-10-05/README.md`)
# P1 temporal typed edges, E2: per-model certification of `apply` mode
**Held-out verdict: pass for all five models.** Each is in `CERTIFIED_APPLY_MODELS`
(`src/core/cycle/edge-contradictions.ts`), so with no explicit
`dream.edge_contradictions.mode` the nightly relationship check applies its closures
with any of them. Every other chat model proposes.
## Run
Custodian (P0), phrasing set C, 3 runs per model, frozen build `feb077ef9`. The ledger
holds only dated "joined" lines (as an employment history usually reads), so every
closure comes from the contradiction phase; undated and out-of-order sub-ledgers check
that undated pairs are never closed and that late-recorded evidence is born closed.
Preregistered bar ([round 1](../p1-dev-2026-10-04/README.md)): wrong closures ≤ 1% in
every run, and as-of exact at least 10 points above the deterministic E1 arm.
Models: claude-haiku-4-5 (the utility default), claude-sonnet-5-5, gpt-6.1-sol,
claude-opus-5-5 and claude-fable-5-1.
| Check (all five models, every run) | Result |
|---|---|
| Wrong closures | 0 |
| As-of exact vs the E1 arm | +0.111 to +0.115 (bar +0.10) |
| Undated pairs closed | 0 |
Each run applied 65–66 closures. Judge output errors: claude-sonnet-5-5 returned 3 and 6
malformed outputs in two runs and claude-fable-5-1 6 in one; those pairs were not
proposed, which is the designed behavior for a malformed answer.
## What the result does not show
1. **No model is better than another here.** The model only flags that two current
relationships cannot both hold; date arithmetic picks which one ended and when. All
five sit at the same ceiling, so the pass certifies that `apply` is safe with each of
them, not a ranking.
2. **Closures are often late.** 41 of the 66 closures are dated after the real end: with only "joined" lines, a gap between jobs closes the earlier job on the next
start date. That is late, not wrong, and it is why as-of clears the bar by about 1.5
points. Follow-up: close at the gap when an explicit end date exists, and otherwise
record the end date as an upper bound.
3. **Proposals go stale within a cycle.** 51 proposals per model went stale in the same
cycle and are judged again the next night.
---
### Eval Decisions P2 Attribution Dev README (`docs/eval/decisions/p2-attribution-dev/README.md`)
# Speaker attribution: dev verdict
This compares `facts.attribution` on (candidate) and off (baseline) on the same build, 5d5375d43, which carries the
extractor's speaker rule. The storage work that followed (`facts.attributed_to`, migration v204) also adds an
`attributed_to` field to the extractor schema; that change was not part of this run. Both arms ran on the
LongMemEval-S development questions through the decision kit's memory-qa facts lane. gbrain's conversation-facts
extractor runs on the dated conversation pages, and a fixed reader answers from the saved facts of the top five
retrieved sessions. This is a `dev` verdict, so it cannot set a default.
| Questions | Off | On | Δ (95% CI) |
|---|---|---|---|
| single-session-assistant (30) | 23.3% | 60.0% | +36.7 pts (+20.0 to +53.3), superiority pass |
| single-session-user (19, guard) | 73.7% | 73.7% | 0 (no question changed), non-inferiority pass |
On the baseline, the extractor keeps the user's side of each conversation and drops what the assistant said (see
`../p2-attribution-gate-dev/`). With the speaker rule on, assistant answers and recommendations are saved as their
own facts ("Assistant recommended …"), so questions about them become answerable from memory.
One question per arm lost its facts: an extractor `malformed_output` error stopped that conversation's extraction.
These rows score 0 and stay in the comparison. The fact-count comparison is left out because those rows have no
count. Dev spend was about $62.
---
### Eval Decisions P2 Attribution Gate Dev README (`docs/eval/decisions/p2-attribution-gate-dev/README.md`)
# Speaker attribution: the facts-lane gate (dev)
This gate decides whether attribution storage is built. Its question: do answers from saved facts trail answers
from pages on questions about what the assistant said? It ran on the baseline extractor (build 5bd9e8497, no
attribution setting) with the 30 LongMemEval-S single-session-assistant questions the decision kit selects with
seed 42 (development split). The same fixed reader (the benchmark's pinned reader and judge) answered twice:
once from the top five retrieved sessions (pages), and once from the saved facts of those sessions. The facts
come from gbrain's conversation-facts extractor on dated conversation pages.
| Answer source | Score | Context |
|---|---|---|
| Pages (raw sessions) | 100.0% | about 13,200 tokens |
| Saved facts | 26.7% | about 27 facts |
The deficit is 73.3 points (95% bootstrap CI −90 to −57). Saved facts lost on 22 questions and won on none.
The deficit far exceeds the 5-point threshold, so attribution storage is in scope.
The cause shows directly in the stored facts. The baseline extractor keeps the user's side of the conversation
and drops what the assistant said. For the questions saved facts answered wrong, the gold sessions held facts
such as "User is interested in budget-friendly hostels in Amsterdam" and no fact about the hostel the assistant
recommended. Of 7,110 saved facts, 53 mention the assistant. Dev spend was $17.76.
---
### Eval Decisions P2 Date Grounding Dev README (`docs/eval/decisions/p2-date-grounding-dev/README.md`)
# Date-grounded extraction: dev verdict
`extraction.date_grounding` on (candidate, build 5d5375d43) against the branch base 5bd9e8497 with the setting
absent (baseline), on development splits only, through the gbrain-evals decision kit's memory-qa facts lane
(gbrain-evals branch `capy/p2-facts-lane`). Each conversation's sessions are imported as dated conversation
pages and gbrain's conversation-facts extractor runs on them; the stored facts are then scored. The
"unresolved" metric is the share of saved facts that still contain a relative time phrase ("yesterday",
"last week", "3 days ago") with no absolute date. A fixed reader answers temporal questions from the saved
facts (fact text and stored date) of the top five retrieved sessions, never from the raw sessions. The
verdict is `dev`, so it cannot set a default. The held-out run is the custodian's.
| Source | Unresolved relative-time facts | QA from saved facts | Guards |
|---|---|---|---|
| LoCoMo temporal (3 conversations, 100 questions) | 6.2% → 1.2% (CI −7.3 to −2.7 pts) | 64.0 → 66.0 (CI −5.9 to +8.3, inconclusive) | recall@5 unchanged; facts per conversation 316 → 314 |
| LoCoMo non-temporal (150 questions) | — | 52.0 → 51.3 (CI −5.6 to +4.7, inconclusive) | recall@5 unchanged |
| LongMemEval-S temporal (11 questions) | 5.5% → 1.7% (CI −4.6 to −2.9 pts) | 54.5 → 54.5 (no question changed) | recall@5 unchanged |
The rule changed once during development. Version 1 kept the phrase beside its date ("two days ago
(2022-09-02)") and stored the event date as `valid_from`. A reader shown the fact under its event date then
applied "two days ago" a second time, so temporal QA from facts fell on LoCoMo (13 questions lost, 4 gained)
although the resolved dates were correct. Version 2 (`date-grounding-v2`) rewrites the phrase as the absolute
date, and the table above measures version 2.
Re-extracting one conversation with the same build moved its temporal QA by up to 9 points between runs, so
extraction variance is as large as the effect being measured. Dev spend was $26.06.
The verdict above counted the extractor's audit rows (one `EXTRACTION_COMPLETE` marker per processed page)
as saved facts. Without them, the pooled unresolved shares are 6.9% → 1.3% on LoCoMo and 6.8% → 2.3% on
LongMemEval-S. The relative drops (−81% and −67%) and every conclusion stand. The held-out run uses the
corrected harness.
---
### Eval Decisions P2 E1 Heldout README (`docs/eval/decisions/p2-e1-heldout/README.md`)
# Hub dampening: held-out verdict (FAIL)
`search.hub_dampening` failed its sealed held-out evaluation, so the search-side mechanism is not part of this release.
The `hubWeight` helper in `src/core/search/hub-dampening.ts` stays, because the multi-hop chain executor
(`relational-chain.ts`) weights intermediate nodes with it.
The candidate was the frozen build af1225d7b with H = 32, the half degree picked on development seed 1
(`../p2-hub-dampening-dev/`). It ran on sealed hub-world seeds 2 and 3 against two rivals:
- remove: the backlink boost set to 0 (31a792c94);
- cap: backlink and graph-signal factors capped at 1.02 (4e2bd760e).
The bar, all four required:
1. concept nDCG@5 at least +1.0 point, with the 95% CI above 0;
2. better than both rivals on concept;
3. hub-as-answer nDCG@5 no lower than −0.5 point;
4. one-hop recall@5 no lower than −0.5 point.
CIs are paired bootstraps over probes (10,000 draws, seed 42), in points.
| Workload | Concept Δ (H = 32) | H = 32 vs remove | H = 32 vs cap | Hub-as-answer Δ | One-hop R@5 Δ | Failed conditions |
|---|---|---|---|---|---|---|
| seed 2, keyword | +3.3 (+2.5, +4.2) | −3.1 (−4.0, −2.3) | −2.6 (−3.3, −1.9) | −30.6 (−45.0, −16.8) | −5.4 (−9.1, −2.0) | 2, 3, 4 |
| seed 3, keyword | +3.6 (+2.8, +4.5) | −2.8 (−3.6, −2.1) | −2.3 (−2.9, −1.7) | −36.2 (−53.0, −19.9) | −1.0 (−3.8, +1.4) | 2, 3, 4 |
| seed 2, hybrid (valid rows only) | +1.0 (+0.3, +1.9) | +0.4 (−1.2, +2.6) | −0.9 (−1.6, −0.3) | −24.5 (−42.6, −8.2) | +0.3 (−4.6, +5.2) | 1, 2, 3 |
| seed 2, hybrid (no-op rows counted as off) | +0.3 (+0.1, +0.6) | +0.6 (−0.3, +1.6) | −0.5 (−1.2, +0.2) | −24.5 (−42.6, −8.2) | +0.2 (−3.0, +3.5) | 1, 2, 3 |
| seed 3, hybrid (valid rows only) | +1.2 (+0.4, +2.1) | +0.7 (−0.4, +2.4) | −0.3 (−0.5, −0.04) | −10.0 (−20.2, −1.2) | +0.8 (−3.6, +5.1) | 2, 3 |
| seed 3, hybrid (no-op rows counted as off) | +0.35 (+0.1, +0.6) | +0.5 (−0.4, +1.5) | −0.1 (−0.8, +0.5) | −10.0 (−20.2, −1.2) | +0.5 (−2.4, +3.5) | 1, 2, 3 |
On the keyword workloads, dampening lifts concept retrieval, but both rivals lift it more. It also costs between a quarter
and a third of hub-as-answer nDCG@5, against a −0.5 guard.
**All 12 cells ran.** All 12 preregistered cells ran. The seed-3 hybrid candidate and cap cells confirm FAIL:
hub-as-answer −10.0 (−20.2, −1.2), and the capped rival still wins on concept. The full table is in gbrain-evals
[`p2.md`](https://github.com/garrytan/gbrain-evals/blob/48dd47bd8/docs/benchmarks/2026-10-05-heldout-program/p2.md)
(merged in gbrain-evals#81, `48dd47bd8`).
**Hybrid telemetry.** In seed-2 hybrid, 346 of 625 H = 32 probe rows (299 concept, 47 one-hop) carried no hub-dampening
stamp. On those queries the lexical metadata-boost gate skipped the backlink and graph-signal stages, so dampening had
nothing to act on and the ranking equals dampening off. The table reports both treatments: those rows dropped, and those
rows counted as off. Neither changes the verdict.
## Consequence
The ranking stage, the `search.hub_dampening` key, its per-call override, the knobs-hash part, the `hub_degree_shape`
doctor check and the per-row hub weights in explain output are removed. Search ranking is unchanged from master.
`verdict.json` is the custodian's aggregate. The sealed seeds stay in owner custody.
---
### Eval Decisions P2 E2 Heldout README (`docs/eval/decisions/p2-e2-heldout/README.md`)
# Date-grounded extraction: held-out verdict (PASS)
Decision `p2-e2-heldout-2026-10-04` ran on the 7 sealed LoCoMo conversations (1,076 questions). The evaluation
custodian ran it under preregistration amendment 1 (gbrain-evals `docs/benchmarks/2026-10-04-p2-ranking-extraction-preregistration.md`).
The candidate was `extraction.date_grounding=true` on the frozen build. The baseline was the same build with the
setting absent. Both arms ran the decision kit's facts lane: gbrain's conversation-facts extractor on dated
conversation pages, two extractions per arm, and a fixed reader that answers from the saved facts with 10
replicates. The gate is correctness first. It decides on the share of saved facts that still hold a relative date
("yesterday", "3 days ago") with no absolute date. QA has to stay non-inferior.
| Gate | Baseline → candidate | 95% CI | Result |
|---|---|---|---|
| Primary: unresolved relative-date share in saved facts | 8.95% → 2.05% (−77% relative; bar ≥ 50%) | [−8.3, −5.5] pts | pass |
| Temporal QA from saved facts (lower bound ≥ −3 pts) | 67.5 → 68.3 | [−1.2, +2.7] | pass |
| Overall QA from saved facts (lower bound ≥ −3 pts) | 53.6 → 54.7 | [+0.6, +1.7] | pass |
| Page recall@5 (lower bound ≥ −1 pt) | unchanged | — | pass |
| Facts per conversation (within ±5%) | −0.3% | — | pass |
All 7 conversations improved individually on the primary metric.
## Default
`extraction.date_grounding` defaults on for fact extraction and for the three other prompts that passed their per-consumer
check. `false`, `off` or `0` turns all of them off. `true` also turns on life chronicle events, the one prompt that did not
pass. `gbrain doctor` (`extraction_date_grounding`) reports which prompts are grounded on a brain.
Facts extracted before the default changed keep their original wording. Re-extracting a source is an explicit,
previewed action that needs the user's consent: `gbrain extract-conversation-facts --source-id --dry-run`.
## Per-consumer checks (preregistration amendment 3)
The held-out verdict measured fact extraction. The four other prompts that know the rule were each checked on 30 invented
dated fixture pages. Each fixture has 3–6 relative time references, a decision, a plan and a prediction, and fixtures were
written by `google:gemini-3.8-flash` before any prompt ran. Each prompt ran twice per fixture through its own product
prompt builder (`anthropic:claude-sonnet-5-5`): as today, and grounded. Two measures:
- unresolved relative phrases in the stored items (the facts lane's check);
- a blind pairwise judge (`openai:gpt-6-sol`, 10 replicates per fixture, A/B order randomized per replicate).
Pass needs (a) fewer unresolved phrases when grounded, and (b) a judge score (grounded win 1, tie 0.5, loss 0) with a 95%
bootstrap lower bound of at least 0.45.
| Prompt | Unresolved phrases, current → grounded | Judge score (95% CI) | Verdicts (grounded / tie / current) | Result | Default |
|---|---|---|---|---|---|
| dream synthesis | 49 → 1 (475 → 615 items) | 0.813 (0.71, 0.92) | 224 / 40 / 36 | pass | on |
| extract_atoms | 5 → 0 (66 → 69 items) | 0.973 (0.94, 0.99) | 292 / 0 / 8 | pass | on |
| propose_takes | 10 → 0 (96 → 99 items) | 0.933 (0.87, 0.99) | 275 / 10 / 15 | pass | on |
| life chronicle events | 0 → 0 (149 → 155 items) | 0.937 (0.86, 0.99) | 281 / 0 / 19 | fail (a) | opt-in (`true`) |
Life chronicle events fails criterion (a) on a floor: its events already carry an absolute `when` field, so neither arm
stored an unresolved phrase (0 → 0). The judge preferred the grounded events in 281 of 300 comparisons. The preregistered
bar is applied as written, so chronicle stays on its current prompt unless the setting is `true`. Changing that would
need a new preregistered check.
The fixtures, outputs, judgments and the script that produced them are in gbrain-evals at
`docs/benchmarks/p2-e2-consumers/` (branch `capy/p2-preregistration`). `per-consumer-report.json` here is the summary.
The budget ledger did not meter this spend, because the calls went to providers directly; the preregistered estimate was $12.
## External development check (report-only)
This check does not change the default. The default follows the preregistered sealed verdict above: correctness was the
primary gate and passed, and QA non-inferiority held on sealed LoCoMo.
GBRA-52 ran date grounding on and off in its BEAM development lane (100k, 500k and 1M; 158 sessions, all dated). The lane
combines retrieval with a 600-token facts block inside 8k tokens of delivered context, with a gemini reader and judge.
| Measure | Grounding on | Grounding off | Paired (W / L / T) |
|---|---|---|---|
| Pooled rubric | 0.653 | 0.663 | 35 / 51 / 274, mean −0.010; losses concentrated at 1M |
| Temporal | 0.438 | 0.493 | 0 / 3 / 33 |
| Event ordering | — | — | 6 / 10 |
With grounding on, 4.9–8.4% of facts carry a `valid_from` that differs from the session date, a median of 3–4 days earlier.
GBRA-52's reading: in this lane the dates rarely reach the reader. Recall returns the newest 100 facts, of which only 3–6%
are dated, and the block holds 600 tokens. So the result says little about correctness, and it shows no QA gain at that
budget. Receipts: gbrain-evals branch `capy/mpw-harness` at 8ec0330,
`docs/benchmarks/2026-10-05-memory-proof-wave-dev/facts-lanes-fix2-date-grounding.md`.
Follow-up: measure date-grounding QA on fixed BEAM with a facts budget large enough for the dates to reach the reader.
Development record: `../p2-date-grounding-dev/`.
---
### Eval Decisions P2 E3 Heldout README (`docs/eval/decisions/p2-e3-heldout/README.md`)
# Speaker attribution: held-out verdict (PASS)
This is the sealed E3 run under preregistration amendment 2 (gbrain-evals `docs/benchmarks/2026-10-04-p2-ranking-extraction-preregistration.md`).
The evaluation custodian ran it on build 6fa1a77b3, using 60 sealed synthetic user–assistant conversations across five
case families: rejection, quotation, correction, repeated suggestion and acceptance.
The candidate was `facts.attribution=true`. The baseline was the same build with the setting absent. Both arms ran
gbrain's conversation-facts extractor through the decision kit's facts lane, with two extractions per arm, and a fixed
reader that answers from the saved facts of the top five sessions with 5 replicates.
| Gate | Baseline → candidate | 95% CI | Result |
|---|---|---|---|
| Primary: assistant-said QA from saved facts | 44.1% → 95.8% (+51.7 pts; 73 wins, 0 losses) | [+42.9, +60.3] | pass |
| Guard 1: user-said QA from saved facts (lower bound ≥ −2 pts) | 97.2% → 98.6% | [−0.4, +3.4] | pass |
| Guard 2: rejected suggestions saved as the user's plan | 0 confirmed | — | pass |
| Guard 3: stored speaker correct (≥ 90% of 200 sampled facts) | 194 / 200 (97%) | — | pass |
**Guard 2 adjudication.** The pinned judge flagged 32 of 1,208 candidate facts in the rejection family. The custodian read
all 32 and confirmed none. Each one was one of these:
- an assistant recommendation that matched the user's own plan;
- a neutral note;
- a choice the user made themselves.
**Reported only.**
- **Facts per conversation: +41%** with attribution on. The extractor now saves what the assistant said (answers,
recommendations, plans) as its own facts, where the baseline dropped it. Storage, extraction output tokens and
hot-memory volume grow by about that much on assistant-heavy conversations.
- **Guard 3 method:** the judge located each fact's source turn itself, because `facts.ndjson` records the session but
not the turn.
## Default
`facts.attribution` defaults on. `false`, `off` or `0` opts out. With it on:
- the extractor phrases assistant claims as their own facts ("Assistant recommended …") and stores
`facts.attributed_to`;
- dedup never merges claims from different known speakers;
- recall and hot memory return the speaker, and context packs render "(assistant said)";
- `consolidate` never promotes an assistant claim into the user's takes.
Facts saved earlier keep `attributed_to` NULL (unknown) and stay compatible with either speaker.
Development records: `../p2-attribution-gate-dev/` (the facts lane trailed pages by 73 pts on assistant-said questions)
and `../p2-attribution-dev/`.
---
### Eval Decisions P2 Hub Dampening Dev README (`docs/eval/decisions/p2-hub-dampening-dev/README.md`)
# Hub dampening: dev result and the frozen held-out configuration
These are the `search.hub_dampening` development arms on hub-world seed 1, the development seed of the preregistered
hub-heavy world. It has 32,652 pages and 77,489 links; inbound degree p50 is 7, p90 is 149 and p99 is 20,008, with four
hubs of 5,000, 10,000, 20,000 and 30,000 inbound links.
The runner is gbrain-evals `eval/runner/hub-world-arms.ts` (branch `capy/p2-hub-world-arms`). It builds one shared index
per gbrain build and runs every read-time arm on it. Each search must report the arm's half degree in its telemetry.
The path is keyword-only, with RELATIONAL_PINS and relational retrieval off.
Families:
- Cat 13 concept probes (the preregistered primary, nDCG@5, 428 probes);
- hub-as-answer probes (20);
- bridge probes (32);
- one-hop relational templates (145).
Bridge probes score 0 in every arm on the keyword path, so they say nothing here.
## Results
Each row is Δ against dampening off, with 95% bootstrap CIs, in nDCG@5 points unless the column says otherwise.
| Arm | Concept (primary) | Hub-as-answer | One-hop recall@5 | One-hop hit@1 |
|---|---|---|---|---|
| H = 32 | +3.0 (+2.3, +3.8) | −78.5 (−89.5, −66.1) | −0.8 (−3.1, +1.5) | −1.4 |
| H = 100 | +2.3 (+1.6, +3.1) | −83.0 (−93.8, −70.4) | −0.1 | +2.1 |
| H = 200 | +1.8 (+1.2, +2.4) | −83.0 | 0.0 | +2.1 |
| H = 600 | +1.4 (+0.9, +1.9) | −83.0 | +0.1 | +3.4 |
| Graph signals off | 0.0 | 0.0 | −4.5 (−7.2, −2.1) | −3.4 |
| Control: backlink boost removed | +6.5 (+5.5, +7.8) | −13.5 (−23.2, −5.0) | −11.0 (−15.3, −6.9) | −10.3 |
| Control: boosts capped at +2% | +6.0 (+4.9, +7.1) | −12.8 (−22.7, −3.8) | −10.5 (−15.0, −6.0) | −7.6 |
Absolute values with dampening off: concept 38.0, hub-as-answer 98.2, one-hop recall@5 74.0.
## What it means against the preregistered gate
The gate passes only if all of these hold:
1. Primary Δ ≥ +1.0 pt with CI > 0.
2. Better than both controls.
3. Hub-as-answer Δ ≥ −0.5 pt.
4. One-hop Δ ≥ −0.5 pt.
Every half degree clears condition 1 and fails conditions 2 and 3. Removing or capping the backlink boost gains about
twice as much concept recall as any dampening setting. Every dampening setting removes most of a hub's boost: for
degrees of 5,000 to 30,000 the weight is below 0.02 even at H = 600. Questions whose answer is the hub page then lose
the page, because the backlink lift is what ranks a hub above its many routine mentions.
Development predicts that hub dampening fails the held-out gate. Under the preregistration, the setting then stays off
and the search-side mechanism is removed. The `hubWeight` helper stays either way, because the multi-hop chain executor
on master (`relational-chain.ts`) imports it.
The sealed held-out run confirmed it: FAIL (`../p2-e1-heldout/`).
The controls show something separate: on a hub-heavy brain the backlink boost costs concept recall (+6.5 pts without it)
but carries one-hop and hub-as-answer recall. No change to it is proposed here.
## Frozen held-out configuration
- **Candidate build:** gbrain#6020 at af1225d7b.
- **Arms:**
- off;
- H = 32, the dev choice with the highest primary;
- graph signals off;
- control "backlink boost removed": branch `p2-e1-rival-remove`, 31a792c94 (af1225d7b plus `BACKLINK_BOOST_COEF = 0`);
- control "boosts capped at +2%": branch `p2-e1-rival-cap`, 4e2bd760e (af1225d7b plus the backlink and graph-signal factors capped at 1.02).
- **Workloads:** sealed seeds 2 and 3, keyword path and hybrid (`text-embedding-3-large`), reranker off.
Runs:
```bash
bun eval/runner/hub-world-arms.ts --corpus-dir --gbrain @af1225d7b --arms off,32,graph-off --output
bun eval/runner/hub-world-arms.ts --corpus-dir --gbrain @31a792c94 --arms off --output
bun eval/runner/hub-world-arms.ts --corpus-dir --gbrain @4e2bd760e --arms off --output
```
Add `--embed openai --paid --budget-run-id ` for the hybrid cells.
Not run on development:
- The hybrid path. The hub-as-answer loss comes from the dampened boost itself, not from retrieval.
- The per-site split (backlink only, graph only), because one knob drives both sites.
- The reranker-on cells.
Dev spend was $0 (keyword path, no model calls).
---
### Eval Decisions P4 Heldout Core 2026 10 06 README (`docs/eval/decisions/p4-heldout-core-2026-10-06/README.md`)
# P4 always-loaded core memory: held-out verdict
The custodian ran the core gate on BEAM-100k sealed (all 14 conversations,
the 56 `preference_following` and `instruction_following` questions) under
the preregistration in
[`docs/eval/CORE_MEMORY_PREREGISTRATION.md`](../../CORE_MEMORY_PREREGISTRATION.md).
Every arm got the same question-blind standing-preferences page; only arm C
marked it core, so C − A′ measures always-loaded delivery against retrieval of
the same page. The sealed receipts stay with the custodian; the eval records
are in garrytan/gbrain-evals#82. Verdict: **fail**, so `memory.core.enabled`
defaults to `false`. Core stays available as an opt-in.
## Gate
The preregistered bar is C − A′ ≥ 0 on every model not at ceiling, and
neither category's CI entirely below −2.0 points. 95% cluster bootstrap
intervals resample whole conversations.
| Model | Questions | A′ | C | C − A′ (points) | 95% CI |
|---|---|---|---|---|---|
| claude-sonnet-5-5 | 56 of 56 | 86.8% | 91.4% | +4.6 | [−0.4, +10.7] |
| gpt-6.1-sol | 56 of 56 | 88.1% | 85.7% | **−2.4** | [−5.4, +0.3] |
| claude-opus-5-5 | 32 of 56 | | | +3.4 | |
| claude-fable-5-1 | 28 of 56 | | | +2.3 | |
gpt-6.1-sol is below zero, so the model-level rule fails. No category's CI
lies entirely below −2.0, so the category guard alone would not have failed.
claude-opus-5-5 and claude-fable-5-1 stopped at their budget caps; their
remaining questions are still running and are recorded here when they land.
They cannot change the outcome, which gpt-6.1-sol already decides.
By category:
- claude-sonnet-5-5, preference following: +8.6 points, CI [+1.8, +17.5].
- gpt-6.1-sol, instruction following: 91.1% → 85.7% (−5.4 points). This is
the drop that fails the gate.
## Cost per correct answer (reported, not gated)
| Model | A′ | C |
|---|---|---|
| claude-sonnet-5-5 | $0.78 | $0.83 |
| gpt-6.1-sol | $0.32 | $0.37 |
| claude-opus-5-5 | $1.19 | $1.39 |
| claude-fable-5-1 | $2.97 | $2.83 |
## Diagnosis lead
The failure is gpt-6.1-sol on instruction following: with the standing
instructions loaded at the top of every session, it followed them less often
than when it found the same page by retrieval. Where to look first is how the
core block reads to that model (its placement before the conversation, its
"always loaded" framing, and whether instructions in a profile block are
treated as context rather than as instructions in force), comparing its C and
A′ answers on the failing instruction questions. A change there needs a new
preregistered run; this verdict stands for this build.
## Defaults
- `memory.core.enabled`: `false`. An owner who wants it turns it on with
`gbrain config set memory.core.enabled true` and marks pages with
`gbrain core init` or `gbrain core add`; `gbrain core` and `gbrain doctor`
say so when pages are marked while it is off.
- `memory.pressure.enabled`: `true`, from its own pass
([pressure verdict](../p4-heldout-pressure-2026-10-05/README.md)).
---
### Eval Decisions P4 Heldout Pressure 2026 10 05 README (`docs/eval/decisions/p4-heldout-pressure-2026-10-05/README.md`)
# P4 pre-compaction save (pressure notice): held-out verdict
The custodian (P0) ran the pressure gate once on BEAM-500K sealed with
claude-sonnet-5-5, under the preregistration in
[`docs/eval/CORE_MEMORY_PREREGISTRATION.md`](../../CORE_MEMORY_PREREGISTRATION.md).
Arms A′ (master with the MCP instructions reorder) and B (this PR's build with
the growth-aware save notice and `remember` with `items`) streamed every
conversation through a 32k-token window. The sealed receipts stay with the
custodian; the eval records are in garrytan/gbrain-evals#82. Verdict:
**pass**, so `memory.pressure.enabled` stays on by default.
## Gate
| Bar | Result |
|---|---|
| B − A′ ≥ +3.0 points, cluster bootstrap CI lower bound above 0 | **+11.3 points**, 95% CI [+8.3, +14.4] (51.7% → 63.0%) |
| No question type's CI entirely below −2.0 points | none |
460 paired questions across 23 conversations: one of the 24 sealed
conversations was dropped at its shard cap, so its 20 questions are not in
either arm.
## Caveat: session dates
The gbrain-evals BEAM loader dated only the first turn group of each batch,
so about 96% of BEAM-500K sessions reached the agent headed "[Conversation on
an unknown date]". Both arms saw identical headers, so the paired B − A′
(+11.3 points) and the verdict stand. The per-type numbers below were measured
with most session dates hidden, which matters most for temporal reasoning and
event ordering: read those two rows as measured under missing dates, not as
the size of the effect with dated sessions. The core gate (preference and
instruction questions, which do not depend on dates) is unaffected. The loader
fix goes into gbrain-evals separately.
## By question type (B − A′, points)
| Type | Δ |
|---|---|
| Temporal reasoning (most session dates hidden) | +24.3 |
| Knowledge update | +20.7 |
| Multi-session reasoning | +20.1 |
| Information extraction | +19.2 |
| Contradiction resolution | +15.5 |
| Event ordering (most session dates hidden) | +10.3 |
| Preference following | +4.6 |
| Summarization, instruction following, abstention | flat |
## Reported (not gated)
| Metric | A′ | B |
|---|---|---|
| Cost per question | $0.679 | $0.870 (+28%) |
| Cost per correct answer | $1.315 | $1.381 (+5%) |
| Evidence saved (a fact saved while a gold session was live) | 39.6% | 60.7% |
The extra cost is the extra saving: B makes more `remember` calls during each
stream. Per correct answer the difference is 5%. The release notes and the
post-upgrade notice state these costs.
309 compaction segments had no notice before the compaction. A session that
arrives in one large turn can jump past the warning point before the next
prompt; those misses are where the notice can improve next.
## Related verdicts
The core gate (BEAM-100k sealed, all four models) failed, so core memory is
off by default and available as an opt-in:
[core verdict](../p4-heldout-core-2026-10-06/README.md). The report-only
slice (claude-opus-5-5, gpt-6.1-sol and claude-fable-5-1 on four BEAM-500K
sealed conversations) decides nothing and is recorded when it lands.
---
### Eval Decisions P4 Stream Dev Pilot README (`docs/eval/decisions/p4-stream-dev-pilot/README.md`)
# P4 streaming dev pilot (development data, sets no default)
The streaming compaction harness (gbrain-evals `capy/p4-streaming-harness` at
`4c98318`, `eval/runner/p4-stream/`) runs LongMemEval-S as a live conversation
with a 32k-token window through gbrain's real Claude Code hooks. These numbers
come from development questions only; they size the sealed run and guide the
work. They never set a default.
## Builds
| Arm | gbrain commit | Config |
|---|---|---|
| A′ | `5c82936a2` (gbrain#6025 head: MCP instructions reordered under the 2,048-char cap) | defaults |
| B | `73bd681cb` (this PR merged with gbrain#6025) | `memory.core.enabled=false`, `memory.pressure.enabled=true`, `memory.pressure.context_window=32000` |
| C | `73bd681cb` | `memory.core.enabled=true`, `memory.pressure.enabled=false`; profile page marked core |
| B (growth trigger) | `cd613d775` (same, plus the growth-aware notice trigger) | as B |
## Results: claude-sonnet-5-5, 20 questions (seed 42, first 20), judge 10x
| Arm | Accuracy | $ per question | Compactions | Notice fired | Segments with no notice before compaction | Facts saved | Evidence-saved |
|---|---|---|---|---|---|---|---|
| A′ | 25.0% | 1.67 | 9.2 | 0% | 100% | 0.1 | 0% |
| B | 21.0% | 2.10 | 10.7 | 95% | 69% | 9.2 | 11% |
| C | 20.0% | 1.72 | 9.6 | 0% | 100% | 0.2 | 6% |
| B (growth trigger) | 75.0% | 2.87 | 13.3 | 100% | 28% | 27.4 | 56% |
Paired differences against A′ (question-level bootstrap):
- B − A′: −4.0 points, 95% CI [−20.0, +12.0], per-question SD 0.398, 20% of questions discordant.
- C − A′: −5.0 points, 95% CI [−25.0, +15.0], per-question SD 0.510, 25% discordant.
- B (growth trigger) − A′: +50.0 points, 95% CI [+20.0, +75.0], per-question SD 0.688, 70% of questions discordant; cost per question +72%.
The first two differences are not distinguishable from zero at n = 20. The pressure notice
fires in 95% of conversations but reaches only 31% of compaction segments: a
whole LongMemEval session (often several thousand tokens) arrives in one turn,
so fill often jumps from under 80% straight past the compaction point. The
growth-aware trigger (warn when two more turns of the size just seen would
reach the automatic compaction point) reaches 72% of segments; the agent saves
three times as many facts, a fact from a gold evidence session in 56% of
questions, and answers 15 of 20 correctly against A′'s 5.
## Two faults that invalidated earlier B results
Every B result above, and the first BEAM B results below, ran with two faults:
- `remember` with `items` still required top-level provenance, so a batch
whose items carried their own provenance was refused (277 of 336 `remember`
calls in one BEAM stream). Fixed in this PR: provenance may be given per
item.
- The harness capped every live reply at 700 output tokens. A batched
`remember` call longer than that is cut off, and the API delivers the tool
call with empty arguments (`fact must be a non-empty string`; 182 of 245
calls after the provenance fix). The harness now reissues a cut-off tool
call with an 8,192-token cap and counts it (gbrain-evals `8cfae29`);
gbrain's error for an argument-less `remember` names that cause.
The LongMemEval-S B numbers above (including the +50.0-point growth-trigger
result) were measured with both faults and are not evidence for or against
the feature.
## BEAM development results (claude-sonnet-5-5, judge `gpt-4.1-mini` 10x)
One stream per conversation; all 20 questions are asked from the same end
state. Only the last two rows of the first table share the corrected harness
and build.
BEAM-500K `500k-10`:
| Arm (build) | Accuracy | $ per question | Compactions | Facts saved | `remember` errors | Cut-off tool calls |
|---|---|---|---|---|---|---|
| A′ (`5c82936a2`) | 60.7% | 0.49 | 33 | 11 | 0 | not counted |
| C (`73bd681cb`) | 57.3% | 0.52 | 37 | 13 | 0 | not counted |
| B, growth trigger (`cd613d775`) | 80.7% | 0.93 | 66 | 162 | not counted | not counted |
| B, compact receipts (`1dab44d69`) | 61.0% | 0.88 | 63 | 148 | 277 | not counted |
| B, provenance fix (`349642275`) | 64.9% | 0.86 | 67 | 170 | 182 | not counted |
| A′, corrected harness (`5c82936a2`) | 46.8% | 0.45 | 33 | 10 | 0 | 1 |
| B, corrected harness (`349642275`) | 58.0% | 0.73 | 62 | 252 | 0 | 57 |
With the corrected harness, B − A′ is +11.2 points (question bootstrap 95% CI
[−2.8, +27.0], per-question SD 0.35, 45% of questions discordant). B costs
62% more per question and $1.26 against $0.97 per correct answer. A′ scored
60.7% and 46.8% on the same conversation in two runs, so one conversation
moves about ±14 points between runs: this sizes the sealed run and shows
plausible signal, nothing more. Core cannot move on this conversation:
A′ already answers every preference question.
BEAM-100k `100k-1` (core check):
| Arm (build) | Accuracy | $ per question | Preference following | Instruction following |
|---|---|---|---|---|
| A′ (`5c82936a2`) | 35.7% | 0.11 | 0.75 | 0.50 |
| C (`349642275`) | 54.4% | 0.10 | 1.00 | 1.00 |
Two questions per category, so this only shows the arm runs as intended and
the signal is plausible.
## Core on LongMemEval-S
The profile page comes from the first session only. In 11 of 500 LongMemEval-S
questions the earliest session is among the gold evidence sessions, and in 1
it is the only one, so C − A′ cannot move on this benchmark. Always-loaded
core needs a workload where a standing fact or preference stated once must be
honored much later: BEAM's `preference_following` and `instruction_following`
questions (40 each per size) test exactly that.
## Cost per cell (one question, one arm, arm A′)
| Model | $ per cell |
|---|---|
| claude-sonnet-5-5 | 1.67 to 2.10 (20-question mean) |
| claude-opus-5-5 | 3.15 (one cell) |
| claude-fable-5-1 | 8.61 (one cell) |
| gpt-6.1-sol | 0.85 (one cell) |
## Power (LongMemEval-S; superseded by the BEAM design in the preregistration)
With the measured per-question SD, a +3.0-point effect at 80% power with the
95% CI excluding zero needs about 1,380 questions per model for B − A′ and
about 2,270 for C − A′ (n = ((1.96 + 0.84) × SD / 0.03)²). LongMemEval-S has
500 questions in total. At about $14.50 per question per arm across the four
newest models, the pressure gate alone (A′ and B) at n = 1,380 costs about
$40,000; on claude-sonnet-5-5 alone about $5,200. The $1,400 cap buys about
28 questions across three arms and four models, where the 95% CI half-width is
about ±15 points.
Development spend through the BEAM runs: about $294 on the streaming harness, plus $14.95 for the LME-S retrieval guardrail in `p4-dev-2026-10-04` (about $310 in total, from the budget ledger). The sealed design and its power are in the [preregistration](../../CORE_MEMORY_PREREGISTRATION.md).
---
### Eval Decisions P6 Fact Keys README (`docs/eval/decisions/p6-fact-keys/README.md`)
# Decision: fact keys in chunk embeddings — killed
- **Plan:** P6, mechanism F2 (fact keys from gbrain's facts extractor merged
into the chunk embedding input).
- **Decided:** 2026-10-05, on development data, under the preregistered kill
gate ([`TIME_AWARE_RETRIEVAL_PREREG.md`](../../TIME_AWARE_RETRIEVAL_PREREG.md),
"Kill gates", amendments 1 and 2).
- **Gate:** F2 must beat `balanced` on its target metric with a paired 95% CI
excluding zero, **and** beat the `tokenmax` contextual-synopsis bundle.
- **Verdict:** **fail.** On the LoCoMo development conversations fact keys
under `balanced` score −1.1 points strict recall_all@5 against `tokenmax`
(95% CI [−2.4, 0.0], 1 win / 6 losses) and +0.4 against `balanced`
(CI [−0.7, +1.7]). `tokenmax` beats `balanced` by +1.5 (CI [+0.2, +2.8]).
- **Context:** on LongMemEval-M development questions fact keys beat
`balanced` by +3.2 points (CI [+1.3, +5.1], 18 wins / 3 losses); M did not
run the `tokenmax` comparison because of cost.
- **Consequence:** no product code, schema, config key or backfill ships. The
eval arms stay (`--fact-keys`, `--fact-extractor paper|production`), as do
the harness's production synopses for `--mode tokenmax` and the LoCoMo
converter.
- **Full build, not shipped:** branch `capy/p6-time-aware-reading` at
`5024ec99f4f591227d12b39b38e304d3255de2c5` (migration v209, publication with
prepare-then-swap, retirement hook, withdrawal discovery, a `fact-keys` CLI
command, doctor `retrieval_enrichment`, and a `--fact-extractor pipeline` arm that
runs that shipping path). Design: [`docs/designs/FACT_KEYS.md`](../../../designs/FACT_KEYS.md).
- **Untested follow-up:** fact keys stacked on `tokenmax`, against `tokenmax`
alone.
Numbers: [`TIME_AWARE_RETRIEVAL_RESULTS.md`](../../TIME_AWARE_RETRIEVAL_RESULTS.md), "Fact keys".
---
### Eval Decisions P6 Think Dates Sealed README (`docs/eval/decisions/p6-think-dates-sealed/README.md`)
# P6 date frame in `think`: held-out verdict
The custodian (P0) ran the preregistered sealed cell once on the frozen build
(candidate `2815a8368cb38d2bbc8bf23bf2c3d2ca34aa6756`, baseline
`67c4ff27bd0a5a8a02ccb66cd663d3aa1daf9969`), harness gbrain-evals
`p0-heldout-harness@cf270c2` (`memory-qa` think lane, `balanced`, reranker off,
autocut off, top 10, official judge prompts; `referenceDate` = question date,
or the conversation's latest session date for LoCoMo). Spec:
[`decision.json`](decision.json); preregistration:
[`TIME_AWARE_RETRIEVAL_PREREG.md`](../../TIME_AWARE_RETRIEVAL_PREREG.md),
amendment 3. The sealed receipts stay with the custodian. Verdict: **pass**.
## LoCoMo sealed (7 conversations, 1,399 paired questions)
| Gate | Result |
|---|---|
| Judged accuracy, paired, clustered by conversation | 74.2% → 88.2%, **+14.0 pts, 95% CI [+11.8, +16.2]**; 229 wins / 33 losses, sign test p = 3 × 10⁻³⁷ |
| Every conversation | improves, +8.7 to +21.0 pts |
| No question category down by more than one question | holds; temporal 27 → 199 of 221 |
| Retrieval | identical in both arms |
| Errors | 0 |
**Disclosure.** The first run hit its $80 ledger cap; the 142 rows the cap
refused were answered in a second run with the same build, harness and
settings. Total spend about $162.
## Latency bar
`think` p95 latency within +20% was preregistered; the sealed lane records
retrieval latency only, so think latency was measured on development data
(latency is not held-out-sensitive): the LongMemEval-S 150-question dev
sample, both frozen builds in parallel processes on one machine, the same
think model (`anthropic:claude-sonnet-5-5`) and questions, wall time around
each `runThink` call (a local timing line on harness `cf270c2`).
| | Baseline | Date frame |
|---|---:|---:|
| p50 | 6.28 s | 6.05 s |
| p95 | 13.67 s | 12.66 s |
p95 ratio 0.93 (bootstrap 95% CI [0.88, 1.03]): **within the bar**; the date
frame adds two short lines to the prompt and no model call. The same run
reproduced the accuracy gain (80.0% → 89.3%). Spend about $26.
## Default
The date frame has no setting: `think` always carries the current-date line
and page content dates, and `reference_date` / `--reference-date` pins
"today". It ships on.
## Pending
LongMemEval-M sealed think runs next as disclosed confirmation; it is
recorded here when it lands.
---
### Eval Decisions P7 Dev 2026 10 04 README (`docs/eval/decisions/p7-dev-2026-10-04/README.md`)
# P7 multi-relation query planner: development verdict and held-out preregistration
This folder holds the development comparison for the multi-relation query
planner (`search.relational_planner`) and points at the plan for the held-out
run. `decision.json` is the decision-kit spec and `verdict.json` is the kit's
dev verdict. Dev verdicts never set a default; the held-out verdict from the
custodian does.
## Builds
- Baseline: `273d2b7e8` (P1 temporal edges head, master `6622a119e` merged in; this branch is stacked on it).
- Candidate: `94bd52e01`, with `search.relational_planner=true`. Later branch
commits change only documentation.
## Development results (kit verdict `pass`)
- LongMemEval-S, all 500 questions, hash embeddings (keyless; the planner needs
no key): recall_all@5 0.5553 → 0.5553 (non-inferiority, pass), nDCG@10
0.6616 → 0.6616, latency Δ −0.15 ms (95% CI −0.66 to +0.35). The planner
plans none of these questions, so the two arms return the same results.
- The composed multi-hop set (`multi-hop-paraphrase`, N9) is this plan's sealed
held-out set, so it is not a dev source here; the custodian runs it.
Further development evidence (oracle reachability, the implementer's world-v1
probe, paraphrase coverage against an LLM planner, false-fire parse checks,
relational-ab one-hop regression, latency on world-v1 and a 100k-link graph) is
recorded in the preregistration.
## Held-out run
Preregistration: gbrain-evals branch `capy/p7-preregistration`,
`docs/benchmarks/2026-10-04-p7-multi-hop-planner-preregistration.md`. It fixes
the arms (feature arm set with `GBRAIN_EVAL_SEARCH_PINS="search.relational_planner=true"`),
cells, metrics, release gates, benefit gates 1-7 and the default rule before
any held-out cell runs.
---
### Eval Decisions P7 Heldout 2026 10 05 README (`docs/eval/decisions/p7-heldout-2026-10-05/README.md`)
# P7 multi-relation query planner: held-out verdict
The custodian (P0) ran the sealed multi-hop set (`multi-hop-paraphrase`, N9 v1)
once on the frozen planner build, under the preregistration in gbrain-evals
(`docs/benchmarks/2026-10-04-p7-multi-hop-planner-preregistration.md`, scored by
`docs/benchmarks/2026-10-04-p7-multi-hop-planner/heldout-verdict.ts`). The
sealed receipts stay with the custodian. Verdict: **pass**, so
`search.relational_planner` defaults on in `balanced` and `tokenmax`.
## Benefit gates
| Gate | Result |
|---|---|
| 1. Sign test, paid paraphrase, cell (a) | 24 questions better, 0 worse, p = 1.2 × 10⁻⁷ |
| 2. Strict all-hit@10 on the five typed families | cell (a) 0 → 27.0%, cell (b, reranker on) 1.1 → 28.1%: +27 points in both |
| 3. Safety | chain answer precision 0.83 (≥ 0.7); edge-evidence correctness 0.85 (≥ 0.8); non-gold pages above the first gold page 3.31 → 0.09; no typed family dropped |
| 4. No hurt | no cell hurts, including the keyless cell |
| 5. One-hop regression (relational-ab) | 0 questions worse |
| 6. False fire | 0 of 500 LongMemEval-S, 0 of 77 BrainBench non-relational, 0 of 50 cat-13 queries |
Custodian notes: N9 v1 has no unanswerable questions, so the abstention part of
gate 3 could not be evaluated; v1 was opened twice, within its three-opening
limit.
## Defaults
- `search.relational_planner`: on in `balanced` and `tokenmax`, off in
`conservative` (that tier has relational retrieval off).
- `search.relational_orient_onehop`: off in every bundle and available opt-in.
The orientation ablation was 1 question better and 0 worse on relational-ab
(p = 1.0), short of the improvement its default rule requires.
## Known gap
The planner planned 70% of the plainly worded (template) questions and 21% of
the reworded (paraphrase) ones. The surface-form vocabulary is the limit, the
same brittleness the one-hop relational parser showed in its own held-out run.
Widening coverage of reworded questions without giving up precision is the
follow-up.
---
### Eval Decisions Query Facts Arm README (`docs/eval/decisions/query-facts-arm/README.md`)
# Facts arm in query: gates and verdict
The facts arm is on by default. It sits behind `search.query_facts_arm`, and `false` turns it off. Gate 1b and
the revised gate 2 passed at garrytan/gbrain@947536f4c, the build where fact rows take only spare capacity. Gate
1 failed at 16288b95c, and that failure is recorded below. With the key set to `false`, `query` returns exactly
what it returned before the arm existed.
## Result: gate 1b and revised gate 2
**Gate 1b passed.** In the B2 corrections suite each correction was dated when it was made. Forget-then-remember
went from 92% correct and 8% stale with the key off to 100% correct and 0% stale with it on, after 1 write and
after 5. The fact row was in the reader's context for all 200 answers after the correction.
Corrected-value accuracy and stale-answer rate per 100 items, reader `claude-sonnet-5-5`, build 947536f4c:
| Arm | Key | Before correction | After 1 write | After 5 writes |
|---|---|---|---|---|
| forget-then-remember | off | 100% / 0% | 92% / 8% | 92% / 8% |
| forget-then-remember | on | 100% / 0% | 100% / 0% | 100% / 0% |
| edit-sync | off and on | 100% / 0% | 100% / 0% | 100% / 0% |
| append | off and on | 100% / 0% | 100% / 0% | 100% / 0% |
Edit-sync and append lose nothing, but the check can't show more than that. Those arms save no facts, so the arm
never added a row there (0 of 600 answers each), and both sit at 100%.
**Revised gate 2 passed.** Fact rows now take only spare capacity, so they never push out a page. No question's
recall@10 is lower with the key on, in any of the five sets:
| Set | Questions | Arm added a row | Recall@10 lower |
|---|---|---|---|
| NamedThingBench | 12 | 0 | 0 |
| Relational retrieval-quality | 38 | 0 | 0 |
| LongMemEval nightly | 10 | 0 | 0 |
| NamedThingBench + one saved fact per question | 12 | 11 | 0 |
| Relational + one saved fact per question | 38 | 38 | 0 (was 2 at 16288b95c) |
The runs are hermetic and keyword-only. The harness reports this rule as `pass_with_facts_diagnostics`.
Spend was $18.05 against a $30 cap. A first attempt that ran out of disk is not in that total. Its records were
lost, but it ran for about two minutes, which by the observed rate cost under $0.50.
**Decision.** `search.query_facts_arm` is on by default. Each `query` now runs up to three extra lookups
on the facts table: terms, embedding and named entity. It makes no model call.
## Result: gate 1 (16288b95c)
**Gate 1 failed.** In the B2 corrections suite's forget-then-remember arm, the key moved the stale-answer rate
from 92% to 4-6%. Corrected-value accuracy went from 0% to 1% after one unrelated write and stayed at 0% after
five. The rule needed it higher at both checkpoints.
The reader named the correction in 158 of the 200 answers after it (0 of 200 with the key off), and still kept the old value. A
remembered fact is dated when it is saved. In this suite that date is the day of the run, after every
question's simulated date. So the reader judged the correction not yet in effect and answered with the old
value. The fixed judge scored those answers wrong rather than stale. A typical answer was "Saltgrass Tacos. The
correction to The Green Fork is only valid from 2026-10-05, which is after the 2025-05-11 question date."
Corrected-value accuracy and stale-answer rate per 100 items, reader `claude-sonnet-5-5`:
| Arm | Key | Before correction | After 1 write | After 5 writes |
|---|---|---|---|---|
| forget-then-remember | off | 100% / 0% | 0% / 92% | 0% / 92% |
| forget-then-remember | on | 100% / 0% | 1% / 4% | 0% / 6% |
| edit-sync | off and on | 100% / 0% | 100% / 0% | 100% / 0% |
| append | off and on | 100% / 0% | 100% / 0% | 100% / 0% |
Edit-sync and append lose nothing with the key on. Both are at 100% with the key off too, so these checks
can only rule out a loss; they cannot show a gain.
**A diagnostic, not a gate.** It was chosen after gate 1's cells ran, so it cannot change the decision. In
these runs `remember` received the correction's own timestamp as `valid_from`, which `remember` accepts on
this branch. That changes the written fact, not the query path. With the fact dated when it took effect, the
key-off arm already answered 92% correctly (8% stale), and the key-on arm answered 100% correctly (0% stale)
at both checkpoints. A future preregistered gate on correction-dated writes would test this directly.
**Gate 2 passed, though the formal gate is close to vacuous.** On NamedThingBench (12 questions), the
relational fixture (38) and the LongMemEval nightly fixture (10), no question's recall@10 is lower with the key
on. These corpora hold no saved facts, so the arm never fired. The runs are hermetic and keyword-only, so the arm
matched by terms and named entity, not by embedding. Two diagnostic copies seed one saved fact per question:
- NamedThingBench: fired 11 of 12 times and lost nothing (recall@10 0.917 both ways).
- Relational: fired 38 of 38 times and lost recall@10 on 2 questions (mean 1.000 off, 0.974 on). Fact rows
take a page slot when the row count is already full.
With the key off, gate-2 output matches garrytan/gbrain@a87c3e2af exactly, apart from wall-clock recency scores
and random revision ids.
Metered spend was $26.05 against a $40 cap:
- Gate 1 runs: $25.56.
- Two 6-probe smokes: $0.14.
- A duplicate run stopped after 30 probes and not used: $0.35.
Records are in `decision.json` (what was tested and how) and `verdict.json` (what happened). The gbrain-evals
mirror carries the two bench flags the gate-1 runs used (`--gbrain-search-config`, `--remember-valid-from`) as a
patch.
**Decision at gate 1.** `search.query_facts_arm` stayed off by default.
## Gate 1b and revised gate 2: preregistered
Written on 2026-10-06, after gate 1's result and before any gate 1b cell or revised gate 2 run. Gate 1 found a
flaw in how the bench was built. B2 simulates past question dates, but `remember` stamped each correction with the
wall-clock save date, so every correction looked like it came after the question. A real agent doesn't see that,
because a real question comes after the correction. Gate 1b keeps everything else the same and dates each
correction when it was made. The diagnostic above used the same writes on the earlier build and was not a gate; gate 1b reruns them as a gate on the new build.
**The change under test.** Fact rows take only spare capacity:
- They fill free slots up to the caller's row count (an explicit `limit`, otherwise the mode's default) and never
displace a page row.
- When the caller sets a token budget, the page rows are budgeted first, and a fact row is added only if it fits
in what remains.
- When there are no free slots or no budget left, `query` returns the page rows unchanged.
Everything else is as in "The change" above: matching, read policy, `superseded_claim` stamps and no model call.
The measured build is the gbrain commit that contains this change. Both gates name it.
**Gate 1b, B2 corrections with correction-dated writes** (gbrain-evals `eval/workload-suites/bench.ts
corrections`, flags from gbrain-evals `d01d3bc`):
- Setup: every arm runs with `--remember-valid-from`, so `remember` receives each item's `correction_timestamp`
as `valid_from`. Arms: forget-then-remember with `search.query_facts_arm` off and on
(`--gbrain-search-config search.query_facts_arm=true`); edit-sync and append, off and on. Same suite
(`corrections-v1`, seed 20261006, 100 items), same reader (`claude-sonnet-5-5`), same fixed judge and same
retrieval budget as gate 1. Answer phase, then score phase.
- Metrics: corrected-value accuracy and stale-answer rate after 1 and after 5 unrelated writes.
- **Rule:** the key-on forget-then-remember arm wins if its corrected-value accuracy is higher than key off at
both checkpoints and its stale-answer rate is not higher at either. Edit-sync and append must not lose more
than 2 points of corrected-value accuracy at either checkpoint with the key on.
**Revised gate 2** (`bun evals/entity-anchoring/regression.ts --json --key search.query_facts_arm`, hermetic):
- The three corpora as written (NamedThingBench, relational retrieval-quality, LongMemEval nightly) and the two
diagnostic copies that seed one saved fact per question (`namedthing+facts`, `relational+facts`).
- Recall@10 over page rows, the key on and off.
- **Rule:** no question's recall@10 is lower with the key on, in any of the five. Each reports how often the arm
added a row, so a pass where the arm never fires is visible as such.
**Decision.** `search.query_facts_arm` becomes default-on only if gate 1b and revised gate 2 both pass.
Otherwise it stays off. Gate 1's failure stands as recorded. Spend cap: $30.
## Preregistration
The sections below were written and pushed in garrytan/gbrain@a87c3e2af, before any code or gated run, and are
unchanged.
## Why
A correction made through `remember` does not win in `query`. In the B2 corrections suite's forget-then-remember
arm (gbrain-evals `eval/workload-suites`, `bun run eval:corrections`), 0 of 100 answers were correct and about
90 repeated the stale value. Two things cause this:
- The remembered fact does not surface when the question is worded differently from the fact.
- The page text that still states the old value ranks first.
`query` reads pages and chunks only. Facts are reachable through `recall`, but `query` never ranks them.
## The change
With the key on, `query` adds a facts arm:
- **Candidates.** Active facts only: not expired, not superseded, and valid now. They are filtered by the
caller's read policy, the same way `recall` filters them: source scope, private facts withheld from remote
callers, and the takes holder allow-list.
- **Matching.** Facts are matched to the query by embedding similarity and keyword, then ordered newest
`valid_from` first among matches.
- **Delivery.** Matched facts are added as fact rows inside the caller's token budget and row count. Facts never
enlarge either.
- **Superseded page claims.** A page row is stamped `superseded_claim` when a newer active fact covers the same
entity and slot. Slot here means the typed claim columns: `claim_metric`, plus `claim_period` when both rows
carry it. Pages without typed claims are never stamped.
- **No model call** is added on the read path.
The touch points will be additive in the `query` op, as with entity anchoring. `hybridSearch` ranking is left
alone.
## Gates
1. **B2 corrections** (gbrain-evals `eval/workload-suites`, `bun run eval:corrections`).
- Setup: the forget-then-remember arm, run at the measured build with `search.query_facts_arm` on and off.
Same seed (`corrections-v1`, seed 20261006, 100 items), same reader and same retrieval budget as the B2
preregistration.
- Metrics: corrected-value accuracy and stale-answer rate after 1 and after 5 unrelated writes.
- **Rule:** the key-on arm wins gate 1 if its corrected-value accuracy is higher at both checkpoints and its
stale-answer rate is not higher at either.
- In the same run, the edit-sync and append arms must not lose more than 2 points of corrected-value accuracy
with the key on.
2. **No regression on the evals that cover `query`.** These are the corpora used for entity anchoring
(`evals/entity-anchoring/regression.ts`): NamedThingBench, the relational retrieval-quality fixture and the
LongMemEval nightly fixture, run through the `query` op with the key on and off.
- Recall@10 is computed over page rows only.
- **Rule:** no question's recall@10 is lower with the key on.
- Each corpus reports how often the facts arm added a row.
3. **Harness lane (optional, recommended).** LongMemEval knowledge-update and PersonaMem dev slices, retrieving
through the `query` op with the key on and off.
**Decision.** The key becomes default-on only if gates 1 and 2 pass, and gate 3 too if it runs. Until then it
stays off. The spend cap is set before the gate 1 run.
## Changelog
- 2026-10-05: gates preregistered before any code or gated run.
- 2026-10-06: built at 16288b95c and gated. Gate 1 failed, gate 2 passed, and the key stays off.
- 2026-10-06: gate 1b (correction-dated writes) and revised gate 2 (fact rows take spare capacity only) preregistered before any of their runs.
- 2026-10-06: gate 1b and revised gate 2 passed at 947536f4c; the key is on by default.
---
### Eval Decisions Supersession Threshold Dev README (`docs/eval/decisions/supersession-threshold-dev/README.md`)
# Fact supersession threshold with production embeddings: dev finding
This replays the C2 supersession fixture (see [c2-interleave-dev](../c2-interleave-dev/README.md)) on gbrain
7d2cc1c70. The fixture was embedded through the product gateway with each production model and swept over
explicit-lane cosine thresholds from 0.80 to 0.97, for both candidate-fusion arms.
For the default model, `voyage:voyage-4`, the product's threshold of 0.95 is already the best guarded
choice, so this finding proposes no change for it. The threshold does depend on the embedding model, though.
With `openai:text-embedding-3-large`, no threshold meets the guard, and at 0.95 it replaces 54% of new
coexisting claims. Even at its best setting on the default model, a cosine threshold alone leaves 47% of
corrections inserted beside the old value. The verdict is `dev`; the per-model table it led to is applied in this wave (see below).
## Results (rrf_free arm; interleave is the same from 0.90 up and one correction worse below)
| Model | Threshold | Corrections missed | Coexisting claims wrongly replaced | All false supersessions | Distinct claims preserved |
|---|---|---|---|---|---|
| voyage-4 (default) | 0.90 | 18.8% | 77.5% | 15.5% | 95.1% |
| voyage-4 | 0.93 | 34.6% | 27.5% | 5.5% | 98.3% |
| voyage-4 | **0.94** (balanced) | 37.1% | 7.5% | 1.5% | 99.5% |
| voyage-4 | **0.95** (product, guarded best) | 46.7% | 3.75% | 0.75% | 99.8% |
| voyage-4 | 0.96 | 55.8% | 1.25% | 0.25% | 99.9% |
| voyage-4 | 0.97 | 73.8% | 0% | 0% | 100% |
| 3-large | 0.90 | 34.6% | 77.5% | 15.5% | 95.1% |
| 3-large | 0.95 (product) | 63.3% | 53.75% | 10.75% | 96.6% |
| 3-large | 0.97 (balanced) | 81.7% | 18.75% | 3.75% | 98.8% |
- "Corrections missed" covers corrections, back-to-back corrections and private corrections: 240 probes,
each with a known old value.
- Restatements are missed more often at higher thresholds: on voyage-4, 0% up to 0.92, 20% at 0.95 and 45%
at 0.97.
- The full 18-threshold sweep for both models is in `verdict.json` under `models.*.threshold_sweep`.
The selection rule was fixed in the script before these runs. It picks the lowest correction miss rate with
false supersession at or under 1% of probes and at least 99.5% of distinct claims preserved. For voyage-4 the
rule selects 0.95, the current value. The balanced point (fewest corrections missed plus coexisting claims
wrongly replaced) is 0.94. Moving there would trade 9.6 points of correction misses for 3.75 points more
coexisting claims wrongly replaced, and would put false supersession at 1.5%, over the guard. That isn't
clearly better, so 0.95 stays.
For 3-large, no threshold meets the guard. Every setting from 0.80 to 0.97 wrongly replaces at least 18.75% of
new coexisting claims. Wrong replacements fall only as the threshold rises, and missed corrections rise just
as fast.
## Why: the cosine distributions
| Model | Correction vs. its old value (p10 / median / p90) | Coexisting claim vs. nearest sibling (p10 / median / p90) |
|---|---|---|
| voyage-4 | 0.871 / 0.949 / 0.978 | 0.874 / 0.924 / 0.937 |
| 3-large | 0.772 / 0.920 / 0.979 | 0.861 / 0.951 / 0.979 |
On voyage-4, a correction is usually closer to the value it replaces than a new coexisting claim is to its
siblings, so a window near 0.94 to 0.95 exists. On 3-large the order reverses. Templated coexisting claims,
such as "revenue in Q3 2025 was $12.4M" next to the Q2 row, sit closer together than a reworded correction
sits to its old value, so no single cosine cutoff separates them.
On both models the two distributions overlap. Cosine alone can't tell "same claim, new value" from "a
similar claim about a different period". That's why about half of corrections stay unreplaced even at the
best threshold on the default model.
## Applied in this wave
Fix 1 below is in the memory proof wave. Fix 2 is not.
- **Calibration table.** `src/core/facts/supersession-threshold.ts` holds one table keyed `provider:model@dims`.
Its only entry is `voyage:voyage-4@1024` at 0.95, so voyage-4 decides exactly as before.
- **Readers.** The fixed 0.95 constants in `capture-dedup.ts`, `write-single.ts` and the classify fast path now
read the table.
- **Uncalibrated models,** including `openai:text-embedding-3-large`, never supersede or deduplicate by
cosine. Each new fact is inserted, and the `conflict` decide sweep judges the pair where it is on.
Exact-text duplicates still collapse: the fingerprint check in `decideSingleFact` and identical text in
`writeSingleFact`.
- **Override.** `facts.supersession_thresholds` takes a JSON map `{"provider:model@dims": number | "off"}`, so an
operator can register a measured value without a release.
- **Doctor.** `supersession_calibration` is an informational check. For an uncalibrated model it names the
model and returns two commands, which need consent because the first one costs money:
`bun scripts/eval-c2-candidate-fusion.ts calibrate ` embeds the fixture (about a
cent), sweeps 0.80 to 0.97 and prints `threshold_pick.guarded`; then
`gbrain config set facts.supersession_thresholds` registers the result.
## Proposed fix
1. **Calibrate per model (applied, see above).** Replace the single `EXPLICIT_DUPLICATE_THRESHOLD = 0.95` (`facts/capture-dedup.ts`,
also hard-coded in `facts/write-single.ts` and the classify fast path) with a per-embedding-model table.
Keep `voyage:voyage-4` at 0.95. A model with no calibrated entry, such as `openai:text-embedding-3-large`,
should not supersede by cosine. Its writes insert the new fact and leave the pair to the existing
conflict review where that is enabled. At 0.95 on 3-large, that gives up the 37% of corrections it
catches today and removes the 54% of wrong replacements. `gbrain doctor` flags a brain whose embedding model has
no calibrated threshold. This fixture calibrates a new model for about a cent with
`bun scripts/eval-c2-candidate-fusion.ts calibrate `.
2. **Make supersession slot-aware.** The remaining misses need more than a threshold. Supersession can use
the claim slot: the typed `claim_metric` and `claim_period` columns when both rows carry them, or the
caller-named target from `remember.replaces` (#6027). Then cosine only nominates candidates, and the slot
decides whether the new fact replaces the old one or coexists with it.
## Caveats
- The fixture is synthetic and templated. Coexisting members reuse one sentence template, which is close to
the worst case for wrong replacements. Real extractor output varies its wording more.
- 3-large ran at 1536 dimensions. Other widths give slightly different cosines.
- The replay used the product's `listSupersessionCandidates`. At 0.95, the real `decideSingleFact` agreed with
the replayed rule on all 800 decisions per model.
## Reproduce
```bash
bun scripts/eval-c2-candidate-fusion.ts embed --model voyage:voyage-4 --dims 1024 --out /tmp/c2-voyage.json.gz # paid, ~$0.002
bun scripts/eval-c2-candidate-fusion.ts run --embeddings /tmp/c2-voyage.json.gz --taus 0.80:0.97:0.01 --decision-id supersession-threshold-dev
```
The same steps with `--model openai:text-embedding-3-large --dims 1536` produce the second model's rows.
Embeddings file sha256: voyage-4 `894ca7a6f8…`, 3-large in `verdict.json`. Spend was about $0.005.
---
### Eval Decisions Temporal Fact Reserve README (`docs/eval/decisions/temporal-fact-reserve/README.md`)
# Temporal fact reserve in query: preregistered gates
Built behind `search.temporal_fact_reserve`, which is off by default. Gate 2 passed, but the reserve never fires on
those sets as written; gate 1 waits on the harness lane. With the key off, and for every query without a temporal
cue, `query` returns exactly what it returned before.
## Gate 2 result
Gate 2 ran on the bounded build (row share 30%), hermetic and keyword-only, with the key on and off. No question's
recall@10 is lower with the key on, in any of the five sets, with or without `token_budget: 8000`. That makes gate 2
a pass.
The pass is close to vacuous. None of the five sets has a temporal cue in its questions, so the reserve fired 0
times in each. A diagnostic outside the gate appends ", and when?" to the questions of the two fact copies:
- NamedThingBench: the reserve fired on 11 of 12 questions with no recall loss (0.833 both ways).
- Relational fixture: the reserve fired on 38 of 38, but the appended words already drop page recall to 0 with the
key off, so this copy shows nothing.
With the key off, `query` output on these sets matches garrytan/gbrain@eb696b3df, apart from wall-clock recency
scores. The facts arm's own gate-2 numbers are unchanged.
Gate 1 (BEAM dev, harness lane) has not run.
## Preregistration
## Why
On BEAM's temporal-reasoning and event-ordering questions, the harness lane's combined arm (pages through `query`
plus `recall`'s facts) scores 0.49, against 0.72 for the comparator. Date grounding (#6020) did not move it, because
dated facts rarely reach the prompt:
- `recall` returns the newest 100 facts, and only 3-6% of those carry a real date.
- The `query` facts arm only uses spare rows, and a `limit: 50` page query leaves none.
## The change
With the key on, a `query` whose text carries a temporal cue gives saved facts a bounded share of the token budget.
- **Temporal cue.** Deterministic, no model call. The query matches, case-insensitively, one of: the words `when`,
`before`, `after`, `since`, `until`, `till`, `during`, `ago`, `earlier`, `later`, `earliest`, `latest`,
`first`, `last`, `previous`, `next`, `date`, `dates`, `day`, `week`, `month`, `year`, `order`, `sequence`; the
phrases `how long`, `how many days`, `how many weeks`, `how many months`, `how many years`, `what time`; an ISO date
(`YYYY-MM-DD`); or a month name.
- **Budget.** The reserve applies only when the call has a token budget: the caller's `token_budget`, or the budget
evidence delivery resolves for `return_unit`. Without one, `query` behaves as today (the facts arm's spare-capacity
rows).
- **Share.** Facts take at most 15% of that budget, counted with the search token estimator, and at most 30% of the
caller's row count (at least 1, at most 20 rows). Pages fill the rest. The row count never grows: a fact row takes
a free row, else the lowest page row.
- **Candidates.** Active facts only, under the same read policy as the facts arm (source scope, world facts only for
remote callers, audit rows excluded): the 50 nearest by the query embedding `query` already computed, plus the 50
best keyword matches, plus the named entity's facts.
- **Ranking by the question.** Each candidate scores its cosine similarity to the query (0 without an embedding) plus
the share of query terms its text contains, plus 0.1 when it carries a real date. A real date means `valid_from`
differs from `created_at` by more than a day, which is true when the writer supplied the date. A candidate is kept
when its cosine is at least 0.5 or its term share at least 0.34. The best-scoring facts fill the reserve.
- **Rendering.** Reserved facts are fact rows (`result_type: "fact"`), each with its date header (`[observed
unknown; valid FROM ...]`), placed after the page rows in date order, oldest first.
- **No model call** is added on the read path.
## Gates
1. **Harness lane, BEAM dev, combined lane, 8k token budget** (gbrain-evals harness provider). The same build, the
same cells and seeds, `search.temporal_fact_reserve` on vs off.
- **Rule:** paired over the same questions, the key-on arm scores higher on temporal reasoning and higher on event
ordering, and its pooled score over all BEAM dev categories is not lower.
2. **No recall loss on the evals that cover `query`** (`evals/entity-anchoring/regression.ts`): NamedThingBench, the
relational retrieval-quality fixture, the LongMemEval nightly fixture, and the one-saved-fact-per-question copies
of the first two. Each runs with the key on and off, once without a token budget and once with `token_budget:
8000`.
- Recall@10 is computed over page rows only.
- **Rule:** no question's recall@10 is lower with the key on, in any set or budget setting. Each set reports how
often the reserve fired.
**Decision.** The key becomes default-on only if both gates pass. Until then it stays off. The lane that runs gate 1
owns its spend. The spend cap for this lane's own runs is $10.
## Changelog
- 2026-10-06: gates preregistered before any code or gated run.
- 2026-10-06: before gate 1 ran, the row bound changed from "at most 20 rows" to "at most 30% of the row count (1-20)".
The first build let reserved facts fill every row of a `limit: 10` call under the default `auto` budget. The gate 2
runs made on that build are void and were rerun on the bounded build. The token share and both gates are
unchanged.
- 2026-10-06: built; gate 2 passed on the bounded build (the reserve never fired on the sets as written).
---
### Eval System One Datasets README (`docs/eval/system-one/datasets/README.md`)
# System One labelled datasets
Labelled inputs for `gbrain decide calibrate` / `qualify` and the matched-pair evals of three slots:
S6 `recall_needed`, S9 `conflict` and S8 `grounding`. Every dataset line is in the
`src/core/ai/decide/dataset.ts` schema, written by `gbrain decide dataset` (which assigns the frozen
calibrate/eval split by a stable hash of the family), then stamped with its label provenance by
`generators/label-source.ts`. That step only adds fields (`label_source`, and per dataset `design`, `case`,
`origin`, `baseline_*`), so the split and `split_hash` are exactly the builder's and `parseDatasetJsonl`
reads the files unchanged. Hashes, item and family counts: [HASHES.md](HASHES.md).
## Label provenance
Every line carries `label_source`:
| Value | Meaning |
|---|---|
| `synthetic-construction` | The label is fixed by the deterministic template that built the item (the generator's intent). No person or model labelled it. |
| `upstream-gold` | The label comes from an existing corpus or test in this repository (BrainBench sealed gold; labelled or verdict-bearing fact pairs in `test/`). |
| `llm:` | A model labelled it (S8: `llm:claude-sonnet-5`). These are not hand labels. |
| `human` | Labelled by a person. **No dataset here contains human labels yet.** |
The design plan asks for a hand-labelled S8 sample for quarantine precision; the S8 set below is an LLM-judged
set and does not satisfy that requirement. A human pass over a sample of it is still owed before any S8
quarantine precision is reported as hand-validated.
## S6 `recall_needed` (know-to-ask)
**Files.** `s6-recall-needed.brainbench.jsonl` (the committed BrainBench corpus),
`s6-recall-needed.extra.jsonl` (the extension corpus below) and `s6-recall-needed.combined.jsonl`
(the two concatenated; ids never collide).
**Source.** `evals/brainbench` (sealed, unchanged) and the new BrainBench-schema corpus
`know-to-ask-extra/{fixtures,gold}` (132 fixtures, 528 gold user turns, suite `know-to-ask`), generated by
`bun docs/eval/system-one/generators/know-to-ask-extra.ts` (Mulberry32, seed 60601, byte-identical reruns,
synthetic name pools only: common first names, invented surnames and company names). `_design.json` records
the designed intent and subtype of every gold turn and is copied into each extra line as `design`.
**Generator commands.**
```bash
bun docs/eval/system-one/generators/know-to-ask-extra.ts
gbrain decide dataset --slot recall_needed --from know-to-ask evals/brainbench --out bb.raw.jsonl
gbrain decide dataset --slot recall_needed --from know-to-ask docs/eval/system-one/datasets/know-to-ask-extra --out extra.raw.jsonl
bun docs/eval/system-one/generators/label-source.ts bb.raw.jsonl docs/eval/system-one/datasets/s6-recall-needed.brainbench.jsonl upstream-gold
bun docs/eval/system-one/generators/label-source.ts extra.raw.jsonl docs/eval/system-one/datasets/s6-recall-needed.extra.jsonl synthetic-construction docs/eval/system-one/datasets/know-to-ask-extra/_design.json
cat docs/eval/system-one/datasets/s6-recall-needed.{brainbench,extra}.jsonl > docs/eval/system-one/datasets/s6-recall-needed.combined.jsonl
```
The builder seeds every fixture into an in-memory brain and replays the shipped reflex
(`assembleTurnContext`, all decide slots off, the hook's 4-turn window, cross-turn dedupe), so `slice`
(`reflex:fired` / `reflex:silent`) and `protected` (alias or exact-title identity hit) record what the
reflex actually did.
**Family.** One item per user turn (`#`, one request each, the production shape); the split
is by fixture, so turns of one conversation never straddle the halves.
**Labels.** BrainBench lines are `upstream-gold` (the corpus's sealed gold, generator-constructed and
validated by the blind double-label pass its README describes). Extra lines are `synthetic-construction`.
Each extra turn targets its own seeded entity, never re-mentioned in the same fixture, so BrainBench's
"re-mentions demote" convention never applies. The categories and why each label is defensible:
| Design | Built so the reflex… | Gold | Why |
|---|---|---|---|
| `fire/*`: no-alias first name, lowercase surname, lowercase full name (no alias), lowercase company, partial company name, indirect person ("my cofounder"), indirect vendor ("the vendor we picked for payroll"), indirect project ("that pricing thing") | stays silent | `should_retrieve: true`, `gold_slugs` = the seeded page | The seeded page holds the fact the question asks for; the prompt does not state it. |
| `suppress/surname-*`: spelling, arithmetic from the prompt, copyedit, general-knowledge question, reformat, translate, letter count, unit conversion | fires on the capitalized surname (title-surname arm, unprotected) | `false` | The request is self-contained: everything needed is in the prompt or is general knowledge. |
| `suppress/alias-name-question`, `full-name-self-contained`, `company-title-self-contained` | fires with an identity hit (protected) | `false` | Same self-contained requests; S6 may never suppress these (identity protection), so they test that the reducer leaves them alone. |
| `keep/surname-needed` | fires on the capitalized surname (unprotected) | `true` | The answer needs the seeded page. These are the turns a wrong suppression would hurt, so suppression precision is measured against real risk. |
| `negative/*`: small talk, generic question, incidental lowercase name (pronunciation, character naming), other-referent name ("Captain X" in a novel, "X Street"), unseeded name | stays silent | `false` | Nothing stored is needed to answer. |
**Reflex replay (actual counts).** Every one of the 528 extra turns came out on the designed reflex slice
and protection flag (0 mismatches against `_design.json`).
| Dataset | fired, needed, protected | fired, needed, unprotected | fired, not needed, protected | fired, not needed, unprotected (suppress opportunity) | silent, needed (fire opportunity) | silent, not needed |
|---|---|---|---|---|---|---|
| BrainBench | 57 | 5 | 0 | 0 | 0 | 87 |
| Extra | 0 | 66 | 44 | 121 | 165 | 132 |
| Combined | 57 | 71 | 44 | 121 | 165 | 219 |
The shipped reflex resolves every BrainBench know-to-ask turn (its baseline failure rate is 0), so BrainBench
alone offers S6 no fire and no suppress opportunity; the extra corpus supplies all of them. Eval half of the
extra corpus: 62 unprotected suppress opportunities (at least 35 of 35 correct are needed for
`action_precision_lb` ≥ 0.90), 21 protected, 33 fired-and-needed unprotected turns, 82 fire opportunities,
66 silent negatives.
## S9 `conflict` (hot-memory contradiction)
**Files.** `s9-conflict/pairs.jsonl` (the `facts-fixtures` input, with baselines),
`s9-conflict/pairs.sweep-eligible.jsonl` (the pairs at cosine ≥ 0.80), and the builder outputs
`s9-conflict.jsonl` (all pairs) and `s9-conflict.sweep-eligible.jsonl`.
**Source.** The repository holds few labelled fact pairs: the hot-memory classifier tests use placeholder
texts (`'x'`, `'new'`), and the suspected-contradictions probe set (`test/fixtures/contradictions-mini.jsonl`)
is five queries, not pairs. Collected as `upstream-gold` (6 pairs, `source_ref` names the test): the three
labelled `facts-fixtures` cases and the proposal accept/undo pair in `test/decide/conflict.test.ts`, the MRR
contradiction in `test/eval-contradictions-judge.test.ts`, and the temporal take supersession in
`test/eval-contradictions-auto-supersession.test.ts` (verdicts mapped to supersede as the tests resolve
them). The five probe queries seed 13 placeholder pairs (`case: probe:*`). The rest is
`synthetic-construction` from `bun docs/eval/system-one/generators/conflict-pairs.ts` (Mulberry32, seed
90909): 12 attributes over invented people and companies (role, city, employer, drink, contact channel,
one-on-one cadence, headcount, customers, stage, pricing, database, headquarters).
- `duplicate`: the candidate restates the new fact's value (`restatement`, `paraphrase-low-overlap`, and
`restates-updated-value`: an older memory that already holds the value an update states).
- `supersede`: the new fact updates the candidate's value with explicit newer framing (`value-update-near`:
same wording plus "as of / since / starting 2026"; `value-update`: narrative "promoted / moved /
switched from … to …"; `negation-update`: "no longer"). Ordered attributes only move forward.
- `independent`: same entity, a different or compatible attribute (`compatible-same-entity`,
`other-attribute`, and `near-independent`: same sentence shape and shared tokens, a different attribute or
referent, e.g. "has N employees" vs "has M paying customers").
**Family.** Pairs sharing a new fact share a family (the production request: the new fact is the state, one
`choice` question per candidate); 408 families, 1 to 3 candidates each.
**Counts.** 786 pairs: duplicate 159, supersede 179, independent 448. `slice` is the choice label on
purpose: the `facts-fixtures` builder keeps only a duplicate boolean as `label`, and `slice` is where the
three-way label survives (hard-case tags are in `case`).
**Baseline (today's rule).** `generators/conflict-baseline.ts` embeds every distinct text with OpenAI
`text-embedding-3-large` at 1536 dimensions and stores per pair `baseline_cosine`, `baseline_decision` (the
`decideSingleFact` rule applied within the family: exact normalized match → duplicate; otherwise only the
family's highest-cosine candidate can match, and at cosine ≥ 0.95 it supersedes when the kinds agree, else
duplicate; everything else is inserted, `independent`), `baseline_model` and `sweep_eligible` (cosine ≥ 0.80,
the S9 sweep's candidate floor). Vectors are cached locally, not committed. Results:
- The cosine rule marks no true supersede (0 of 179; the highest supersede cosine is 0.926), supersedes 12
duplicates of the same kind (cosine ≥ 0.95) and inserts everything else.
- Median cosine: duplicate 0.818, supersede 0.763, independent 0.581. Only 172 pairs clear the sweep floor
(supersede 59, duplicate 96, independent 17); a supersede whose new value is an unseen name or number often
sits below 0.80 with this embedding model, so the floor, not the classifier, bounds what S9 can find.
`s9-conflict.sweep-eligible.jsonl` is the set production would actually ask about (eval half: supersede
30, duplicate 49, independent 9).
## S8 `grounding` (claim support)
**Files.** `s8-grounding/labels.jsonl` (the `grounding-labels` input with provenance),
`s8-grounding/transcripts/` (the 16 Cat 35 transcripts it references) and the builder output
`s8-grounding.jsonl`.
**Source.** Cat 35 transcript-distill corpus in github.com/garrytan/gbrain-evals at
`88d0b1997e4b7fb3bd61e04d6eb637ef166ea6d4` (MIT; a fictional, model-generated corpus with invented people and
companies): dream pages `docs/benchmarks/2026-08-16-brainbench-cat35-transcript-distill/artifacts/*.dream.md`
against `eval/data/transcript-distill-v1/transcripts-txt/*.txt`. The transcripts are copied unchanged so
`transcript_path` resolves from the repository root (`transcripts/SOURCE.md`). Eight of the 24 dream
artifacts are empty (routine transcripts produce no page), so 16 pages contribute.
**Units.** `verifyBody` (`src/core/cycle/synthesize-verify.ts`) against the page's transcript;
`groundingUnits` are exactly the units S8 judges in production (they pass the mechanical checks only because
they carry no quote, number or attribution): 567 units.
**Labels.** `llm:claude-sonnet-5`, one call per page with the transcript and all its units, strict rubric
matching the production question (supported only when the transcript states or directly implies the claim;
added reasons, motives, generalizations or evaluations are unsupported; when unsure, unsupported). The
judge's one-line reason is kept as `judge_reason`. The model's temperature is not settable, so a rerun without
the local response cache can differ.
**Perturbation negatives.** Per page, up to 12 evenly spaced units the judge found supported were rewritten
by the same model into fluent claims the transcript does not support (one key element changed; no numbers,
quotes or speaker attribution). A rewrite is kept only when it still passes the mechanical checks as a
grounding unit and a separate blind judge call labels it unsupported: 183 kept. They carry
`origin: perturbation`, `source_unit` (the unit rewritten) and `label_source: llm:claude-sonnet-5`
(model-written and model-judged, not hand-labelled).
**Counts.** 750 items: dream-page supported 320, dream-page unsupported 247, perturbation unsupported 183.
**Family.** The page (`cat35/`): 16 families, so the frozen split is coarse: 5 pages / 254 items
calibrate, 11 pages / 496 items eval. Family-level qualification over 16 independent families cannot reach
`insufficient_n`'s minimum, so S8 is expected to stay shadow-only with this data, as the plan predicts.
**Builder.** `gbrain decide dataset --slot grounding --from grounding-labels
docs/eval/system-one/datasets/s8-grounding/labels.jsonl` run from the repository root on a brain initialised
with `--no-embedding`: source windows were selected by normalized substring and keyword neighbours only (the
output is byte-identical with the embedding keys unset). `slice` is the coverage the builder found
(`adequate` 571, `weak` 179; weak items are `protected` and can only become `insufficient_context`).
**Generator command.**
```bash
bun docs/eval/system-one/generators/grounding-labels.ts ~/.capy/work/gbrain-evals
gbrain decide dataset --slot grounding --from grounding-labels docs/eval/system-one/datasets/s8-grounding/labels.jsonl --out s8.raw.jsonl
bun docs/eval/system-one/generators/label-source.ts s8.raw.jsonl docs/eval/system-one/datasets/s8-grounding.jsonl llm:claude-sonnet-5 docs/eval/system-one/datasets/s8-grounding/labels.jsonl
```
## S7 `triage` (dream triage)
`s7-triage.jsonl` is built with `gbrain decide dataset --slot triage --from cat35 docs/eval/system-one/datasets/s7-triage`.
The directory holds 254 transcripts in the Cat 35 layout (`gold/.json` + `transcripts-txt/-.txt`):
- 24 Cat 35 transcripts copied unchanged from garrytan/gbrain-evals `eval/data/transcript-distill-v1` at
`88d0b1997e4b7fb3bd61e04d6eb637ef166ea6d4` (MIT; itself a synthetic corpus). Label: the corpus's own
`expected_triage` (`label_source: upstream-gold`).
- 230 synthetic transcripts from `docs/eval/system-one/generators/s7-synthetic-transcripts.ts` (openai:gpt-5.6-luna,
reasoning none, temperature 1, seeded spec list): 180 entirely routine (label false) and 50 mostly routine with
one buried synthesis-worthy passage (label true). Labels are the generator's instructions
(`label_source: synthetic-construction`); nobody read and labelled them. A name check found no planted person or
project name in any routine transcript.
Family = transcript. Eval half: 109 transcripts (79 negative, 30 positive).
## S2 `intent` (query routing)
`s2-intent.jsonl` = `gbrain decide dataset --slot intent --from longmemeval longmemeval_s_cleaned.json` (470
non-abstention questions, search and think call sites, labels from `question_type`) plus `--from brainbench
test/fixtures/retrieval-quality/relational/relational.jsonl` (38 relational queries). Labels are the corpora's own
annotations mapped by the builder (`upstream-gold`). The search label set this produces is only `temporal` and
`general`, so it measures a slice of the search question.
## S5 `injection`
`s5-injection.jsonl` = `gbrain decide dataset --slot injection --from injection-fixtures
test/fixtures/decide/injection-cases.jsonl`: 12 cases, 4 with an attack candidate (`upstream-gold`). Too small to
calibrate or qualify on; used for a detection check only.
## S3 `evidence` and S4 `answerable` (not committed: size)
Both are regenerated from LongMemEval-S cleaned (MIT, sha256 `d6f21ea9d60a0d56…`):
- S3: `gbrain decide dataset --slot evidence --from longmemeval longmemeval_s_cleaned.json` → 10,000 items in 500
families (question), 20 sessions per family, label = the session is an answer session; split_hash
`036999bf920b7039` (57 MB). Candidate text is the session capped at 6,000 characters, the same cap
`capRerankDoc` applies to production candidates.
- S4: `gbrain decide dataset --slot answerable --from longmemeval longmemeval_s_cleaned.json` → 500 items, label
false for the 30 `_abs` questions; split_hash `c2d7aea440b81e88`.
The LongMemEval question lists the retrieval arms ran on are in `longmemeval/`: `s-eval-half.txt` (the 248
eval-half families of the S3 split), `s-eval-judged-100.txt` (85 answerable by hash order + all 15 abstention
questions of the eval half) and `m-pilot-28.txt` (the frozen gbrain-evals LongMemEval-M pilot selection).
## Spend
Paid calls are logged one line per request batch in `../ledger-datasets.jsonl` (tokens from the provider's
reported usage, priced at list: Claude Sonnet 5 $3 / $15 per million input / output tokens, OpenAI
text-embedding-3-large $0.13 per million). Total for these datasets: $2.52 (S8 labelling and perturbation
$2.51, S9 embeddings $0.004 including superseded iterations, two model-id probes $0.0002), under the $3 cap.
The S8 generator refuses to start a call that would take the ledger past $3.
## Regenerating hashes
`bun docs/eval/system-one/generators/hashes.ts` rewrites [HASHES.md](HASHES.md).
---
### ENGINES (`docs/ENGINES.md`)
# Pluggable Engine Architecture
## The idea
Every GBrain operation goes through `BrainEngine`. The engine is the contract between "what the brain can do" and "how it's stored." Swap the engine, keep everything else.
Two engines ship today: `PGLiteEngine` — embedded Postgres via WASM (@electric-sql/pglite), the zero-config default — and `PostgresEngine`, backed by Supabase or any Postgres + pgvector. The interface is designed so a `DuckDBEngine`, `TursoEngine`, or any custom backend could slot in without touching the CLI, MCP server, skills, or any consumer code.
## Why this matters
Different users have different constraints:
| User | Needs | Best engine |
|------|-------|-------------|
| Getting started | Zero-config, no accounts, no server | PGLiteEngine (the default) |
| Power user (you) | World-class search, 7K+ pages, zero-ops | PostgresEngine + Supabase |
| Open source hacker | Single file, no server, git-friendly | PGLiteEngine |
| Team/enterprise | Multi-user, RLS, audit trail | PostgresEngine + self-hosted |
| Researcher | Analytics, bulk exports, embeddings | DuckDBEngine (someday) |
| Edge/mobile | Offline-first, sync later | PGLiteEngine + sync (someday) |
The engine interface means we don't have to choose. PGLite is the zero-friction default. Supabase is the production scale path. `gbrain migrate --to postgres` moves a PGLite brain to Postgres with its history ([guide](guides/move-to-postgres.md)); `gbrain migrate --to pglite` moves a brain without write history the other way.
## The interface
**The single source of truth is `export interface BrainEngine` in
`src/core/engine.ts`.** It is large (100+ methods) and grows with every
feature — do NOT work from any snapshot of it, including an old copy of
this doc. Read the interface itself, and let
`test/e2e/engine-parity.test.ts` + `test/pglite-engine.test.ts` tell you
whether both engines agree. A method in a migrated storage domain has its
SQL once in `src/core/engine-sql/` (see "Storage domains and engine-sql"
below).
The method families, to orient you before opening the file:
- **Lifecycle + identity** — `connect` / `disconnect` / `reconnect`,
`initSchema`, `transaction`, `withReservedConnection`, and the `kind`
discriminator (`'pglite' | 'postgres'`) for the rare engine-specific branch.
- **Pages CRUD** — `getPage`, `putPage`, `deletePage`, `listPages`, slug
resolution.
- **Search** — `searchKeyword`, `searchVector`, chunk-level variants, takes
search (keyword + vector), and `relationalFanout` (the typed-edge recall
arm).
- **Chunks + embeddings** — upsert/get, embedding-bearing variants.
- **Graph** — links (single + batch writers), backlinks, `traverseGraph`,
`traversePaths`.
- **Tags, timeline (single + batch), raw data, versions.**
- **Takes / facts / eval / salience** — the epistemological layer and the
instruments over it.
- **Stats, health, ingest log, config, migrations.**
### Key design choices
**Slug-based API, not ID-based.** Every method takes slugs, not numeric IDs. The engine resolves slugs to IDs internally. This keeps the interface portable... slugs are strings, IDs are database-specific.
**Embedding is NOT in the engine.** The engine stores embeddings and searches by vector, but it doesn't generate embeddings. `src/core/embedding.ts` handles that (a thin delegation to the provider-agnostic AI gateway in `src/core/ai/gateway.ts`). This is intentional: embedding is an external API call (OpenAI, Voyage, a local Ollama — whichever provider you configured), not a storage concern. All engines share the same embedding service.
**Chunking is NOT in the engine.** Same logic. `src/core/chunkers/` handles chunking. The engine stores and retrieves chunks. All engines share the same chunkers.
**Search returns `SearchResult[]`, not raw rows.** The engine is responsible for its own search implementation (tsvector vs FTS5, pgvector vs sqlite-vss) but must return a uniform result type. RRF fusion and dedup happen above the engine, in `src/core/search/hybrid.ts` and its stages under `src/core/search/hybrid/`.
**`traverseGraph` exists but is engine-specific.** Postgres uses recursive CTEs. SQLite would use a loop with depth tracking. The interface is the same: give me a slug and max depth, return the graph.
## Storage domains and engine-sql
Both engines speak the same SQL dialect, so a storage domain's SQL is written
once. `src/core/engine-sql/.ts` holds it; each engine method in that
domain is a one-line delegation. The domains migrated so far are the
`migrated` rows of `scripts/engine-sql-baseline.tsv`; the remaining rows of
that file are the engine members that still carry their own SQL, and the file
only shrinks (`check:engine-sql-ratchet` fails on a new SQL-bearing engine
member).
```
PGLiteEngine / PostgresEngine one-line delegations; RLS scoping per method
| get engineSql() fresh adapter per access, never stored
v
engine-sql/.ts the domain's SQL once; sqlFragment composition;
| ScopedRead / LegacyUnscopedRead brands; row kinds
v
engine-sql/executor.ts SqlExecutor: query / run / executeRaw / unsafe /
| transaction; results as { rows, affectedRows }
+--> dialect-pglite.ts db.query on the engine's checkpoint-admitted handle
+--> dialect-postgres.ts runUnsafe(conn, sql, params, { prepare: true, simple: false })
```
The contract, each part pinned by a test listed in
[docs/TESTING.md, "Engine-sql"](TESTING.md#engine-sql):
- **Lifetime.** `engineSql` reads the engine's current connection on every
access. `transaction()` clones the engine with a swapped connection, so a
stored executor would write outside the transaction.
- **Parameters.** Positional only, composed with `sqlFragment` (placeholders
are numbered at render time). Arrays bind as `= ANY($n::type[])`, JSONB
through `jsonbParam()`, vectors as a text literal with a `::vector` cast.
Only constant text may be spliced (`check:engine-sql-dynamic`).
- **Results and errors.** `{ rows, affectedRows }`; driver errors pass through
unchanged. Columns whose decoding differs between drivers are declared once
per statement with `compileRowNormalizer`.
- **Capabilities.** Real engine differences are capabilities on the executor
(`maxBindParamsPerStatement`, `transactionAdvisoryLocks`,
`probesEmbeddingCast`), never `if (engine === ...)` in domain code.
- **RLS scope.** Every read declares how it is scoped: `ScopedRead` (runs
inside `withScopedReadTransaction` on Postgres, see the RLS section below)
or `LegacyUnscopedRead` (runs on the pool, obtained with
`unscopedExecutor(executor, reason)`). The brands are unforgeable
(`check:engine-sql-brands`).
- **Layering.** Nothing under `engine-sql/` imports an engine façade
(`check:layering`); take the executor as a parameter.
Code that is genuinely dialect-specific stays in the engine or in
`src/core/pglite-engine/` / `src/core/postgres-engine/`, marked
`// engine-sql-ok: `. The forward-reference bootstrap both engines run
before replaying the schema blob is `engine-sql/bootstrap.ts`. A step-by-step
read and write example is in
[CONTRIBUTING.md, "Worked example"](../CONTRIBUTING.md#worked-example-an-engine-sql-read-and-write).
## How search works across engines
```
+-------------------+
| hybrid.ts |
| (RRF fusion + |
| dedup, shared) |
+--------+----------+
|
+------------+------------+
| |
+--------v--------+ +--------v--------+
| engine.search | | engine.search |
| Keyword() | | Vector() |
+-----------------+ +-----------------+
| |
+-----------+-----------+ +---------+---------+
| | | |
+-------v-------+ +-------v---+ +-------v---+ +----v--------+
| Postgres: | | PGLite: | | Postgres: | | PGLite: |
| tsvector + | | tsvector +| | pgvector | | pgvector |
| ts_rank + | | ts_rank | | HNSW | | HNSW |
| websearch_to_ | | (same SQL)| | cosine | | cosine |
| tsquery | | | | | | (same SQL) |
+---------------+ +-----------+ +-----------+ +-------------+
```
RRF fusion, multi-query expansion, and 4-layer dedup are engine-agnostic. They operate on `SearchResult[]` arrays. Only the raw keyword and vector searches are engine-specific.
## PostgresEngine
**Dependencies:** `postgres` (porsager/postgres), `pgvector`
**Postgres-specific features used:**
- `tsvector` + `GIN` index for full-text search with `ts_rank` weighting
- `pgvector` HNSW index for cosine similarity vector search
- `pg_trgm` + `GIN` for fuzzy slug resolution
- Recursive CTEs for graph traversal (breadth-first, each page visited once)
- Trigger-based search_vector (spans pages + timeline_entries)
- JSONB for frontmatter with GIN index
- Connection pooling via Supabase Supavisor (port 6543)
**Hosting:** Supabase Pro ($25/mo, zero-ops, pgvector built in) is the managed path; self-hosted Postgres + pgvector (Docker or Homebrew — see the "Local Postgres" section below) works the same.
Current-projection filters use `(text_projection_revision = knowledge_revision)
IS TRUE` with matching expression statistics, rather than relying on the
planner's fixed column-equality estimate. Migration 160 creates and collects
those statistics; bulk import, sync, reindex and completed projection recovery
refresh them outside page locks. This also matters on PGLite, where an empty
initial schema sample cannot describe later imports. Maintenance needs an
authorized database role; an RLS-hidden statistics view is not evidence that
the object is absent. Highly selective queries may correctly choose an exact
plan. The [retrieval guide](architecture/RETRIEVAL.md#named-thing-retrieval-per-page-pool--title--alias--evidence)
describes bounded candidate recovery and incomplete-result metadata.
On Postgres the same refresh also analyzes the page columns every search
filter reads (`deleted_at`, `source_id`, `type`, `slug`) and
`content_chunks(model, modality, page_id, body_generation)`, and an embed drain that embedded
anything analyzes those chunk columns once at its end (each ANALYZE bounded by
a 30 s statement and 2 s lock timeout). Without those statistics the vector
candidate statement sorts every eligible chunk instead of walking the HNSW
index, and at 1M chunks and above that sort runs past the 8 s vector budget,
so hybrid search falls back to keyword-only results until autovacuum
analyzes the tables. If a refresh is skipped (a lock, or a role that does not
own the tables), run `ANALYZE content_chunks(model, modality, page_id, body_generation)` and
`ANALYZE pages` as the table owner.
### Vector index sizing
The chunk HNSW index stores each vector beside its graph links, so at 1,024
dimensions it takes about 7.6 GiB per million chunks as `vector` (about
9.8 GiB for a 1.28M-chunk brain) and a third of that as `halfvec`. The
deferred ANN build (`gbrain migrate embeddings`, `gbrain reindex --vectors`)
runs `CREATE INDEX CONCURRENTLY` with the server's `maintenance_work_mem`.
When the graph does not fit, pgvector logs `hnsw graph no longer fits into
maintenance_work_mem` and the build slows several-fold: 4.3x at 250k chunks
with 256 MB. Before a large build, raise it on the brain host to the index
size plus about 10% (Supabase: `supabase postgres-config update --config
maintenance_work_mem=12GB --project-ref --experimental`, which reloads
without a restart; self-hosted: `ALTER SYSTEM SET maintenance_work_mem =
'12GB'` and `SELECT pg_reload_conf()`), and give it
`max_parallel_maintenance_workers` of about half the cores: a 1M-chunk build
took 103 s on 16 vCPU with 12 GB and 8 workers. Measured, not shipped:
`halfvec` gives the same recall with an index a third the size, and
`ef_construction` 128 adds about 0.02 to 0.03 unfiltered recall@10 for about
25% more build time. Both need a migration or a rebuild, so the defaults stay
(m 16, ef_construction 64, `vector`). Measurements and method:
[`docs/eval/hnsw-scale-bench.md`](eval/hnsw-scale-bench.md).
### Opt-in RLS source-scope binding (`GBRAIN_RLS_SCOPE_BINDING`)
Defense-in-depth layer for Postgres deployments that want the database itself
to enforce source isolation, in addition to the mandatory app-layer filters
(`sourceScopeOpts` — layer 1, always on).
**Mechanism.** With `GBRAIN_RLS_SCOPE_BINDING=1` (or `true`), the engine's
source-scoped read methods wrap their queries in a transaction that first runs
`SELECT set_config('app.scopes', $1, true)` — the value is a bound parameter
(federated `sourceIds` CSV > scalar `sourceId` > `'*'` for unscoped internal
reads), transaction-local (equivalent to `SET LOCAL`, which itself can't take
bound params). An RLS policy can then filter rows by
`current_setting('app.scopes', true)`.
**Default off.** With the env var unset, reads call through on the shared pool
with no per-read transaction and no pool-slot hold (the search methods keep
their own transaction for `SET LOCAL statement_timeout` and `jit = off`).
**Enabling it** (operator-managed SQL; gbrain ships no DDL for this):
```sql
ALTER TABLE pages ENABLE ROW LEVEL SECURITY;
CREATE POLICY pages_scope_filter ON pages
USING (current_setting('app.scopes', true) = '*'
OR source_id = ANY(string_to_array(current_setting('app.scopes', true), ',')));
-- Required: connections that don't run through the scoped read helper
-- (admin, autopilot, cycle, writes) must default to unscoped, or they
-- see zero rows once the policy exists:
ALTER ROLE SET app.scopes = '*';
-- If the runtime role OWNS the table, RLS is skipped for it unless forced:
ALTER TABLE pages FORCE ROW LEVEL SECURITY;
```
Safe to enable in either order: the env var without a policy is a no-op
setting; a policy without the env var is enforced only via the role default.
**Honest caveat:** only read paths routed through the scoped helper carry a
per-request scope binding — unwrapped paths (writes, admin/maintenance reads)
run under the role default and are not backstopped per caller. This is layer 2;
the app-layer source filters remain layer 1 and stay mandatory. Behavioral pins
live in `test/postgres-engine-rls-scope.test.ts`.
**Segmented page tables.** A page over 1 MiB stored in segments (`pages.segmented_storage`)
keeps its text in `page_segment_texts`, its layout and headings in
`page_body_manifest`, uploads in progress in `page_body_stagings` /
`page_body_staging_parts` (with the segment texts each one holds in
`page_body_staging_texts`), and view sizes in `page_view_digests`. gbrain
enables RLS on all six on every schema replay, as it does on `pages` and
`content_chunks`, so with no policy a role that does not bypass RLS reads no row
of them. Title search, the source-scoped vector scan, the chunk windows search
reads around its hits, `get_chunks` and get_page check a chunk of a page stored
in segments against `page_body_manifest`. A restricted read role that can see
such a chunk (a segmented page of one of its sources) needs `SELECT` on it;
without it those reads fail with `permission_denied` (42501). A role that sees
no such chunk, as every role does while no page is segmented
(`pages.segmented_storage` is off by default), reads as before without the
grant (`test/e2e/segmented-switch-off-rls.test.ts`). Grant it together with
these policies, never with an open one, or the role reads every source's segment
text. A scoped role then sees exactly the segment rows of its sources:
```
/* Detailed source-code truncated for AI context efficiency. */
```
A role whose reads do not run through the scoped helper is scoped by its own
default (`ALTER ROLE SET app.scopes = 'source-a,source-b'`). The
policies read `app.scopes` only; the app-layer source filters stay layer 1.
A write role that does not own the tables needs `SELECT, INSERT, UPDATE, DELETE`
on all six, as on any table a migration adds, even while no page is segmented:
purging soft-deleted pages, fact withdrawal (`forget_fact`, `purge_fact`), the
maintenance sweep's facts pass, doctor's credential check and the segment
storage sweep name them. Its ordinary writes (`put_page`, `remember`, sync
imports, their embedding and the unchanged-file check) do not, while it sees no
segmented chunk (`test/e2e/segmented-switch-off-write-role.test.ts`). With the
policies above it creates segmented pages and sees only its sources' rows
(`test/e2e/segmented-rls-scope.test.ts`).
**In engine-sql.** A read in a migrated domain takes a `ScopedRead` when it
runs through this helper and a `LegacyUnscopedRead` when it runs on the pool
(`src/core/engine-sql/brands.ts`); the engine obtains the branded executor, so
the type system keeps each read's scoping as it is. Moving a read from
unscoped to scoped adds a transaction and a pool hold per read with the flag
on, so it is a deliberate change with its own load test, never a drive-by.
The non-owner `NOBYPASSRLS` isolation test is
`test/e2e/engine-sql-rls-scope.test.ts`.
## Local Postgres
Self-hosted Postgres + pgvector gives you the PostgresEngine without a Supabase
account. Two paths:
**Homebrew (macOS)**:
```bash
brew install postgresql@17
brew services start postgresql@17
createdb gbrain
cd /tmp && git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git
cd pgvector && make && make install
psql gbrain -c "CREATE EXTENSION IF NOT EXISTS vector;"
gbrain init --url postgresql://localhost:5432/gbrain
gbrain doctor
```
`gbrain init --url ` writes the config file and runs the schema setup in
one step. To point an EXISTING brain config at a different database without
re-initializing, use `gbrain config set database_url ` — it routes to the
file plane (`~/.gbrain/config.json`), infers `engine: postgres`, and works even
when the current database is unreachable.
**Ladder-driven (harness installs)** — `gbrain init --prefer-postgres` probes
for a usable Postgres before falling back to PGLite: an env URL, Supabase
Management-API discovery (`SUPABASE_ACCESS_TOKEN` + `SUPABASE_DB_PASSWORD`), a
local server (only when `PGHOST`/`PGPORT`/`PGUSER`/`PGPASSWORD` are set or
`--local-postgres` is passed; `CREATE DATABASE gbrain` needs explicit
`--allow-create-db`), or — with explicit `--allow-docker` — gbrain's own
container `gbrain-postgres` (image `pgvector/pgvector:pg16`, loopback-only
host port 5434, data on the named `gbrain-pgdata` volume,
`--restart unless-stopped`). The ladder REFUSES over an already-configured
brain (re-runs during an outage must never let the PGLite floor overwrite a
healthy Postgres config — that lane is `gbrain db-repair`), and a bare
`DATABASE_URL` is adopted only when the target is already a gbrain brain or
holds no tables at all (`GBRAIN_DATABASE_URL` is always stated intent).
gbrain starts and reuses that container but never stops or removes it; an
existing container is reused with its REAL credentials recovered via
`docker inspect`, never a freshly generated password — and never reused when
its database already holds a brain this home's config doesn't record.
Details in INSTALL_FOR_AGENTS.md ("Engine preference for harness installs").
## PGLiteEngine
**Dependencies:** `@electric-sql/pglite`
**What it is:** Embedded Postgres compiled to WASM via ElectricSQL's PGLite. Runs in-process, no server, no Docker, no accounts. Same SQL as PostgresEngine -- not a separate dialect. Implements the full `BrainEngine` interface; `test/e2e/engine-parity.test.ts` pins that the two engines move in lockstep.
**PGLite-specific details:**
- Uses the generated `pglite-schema.generated.ts` template for DDL (pgvector extension, pg_trgm, triggers, indexes; see "Canonical schema sources" below)
- Parameterized queries throughout (shared utilities in `src/core/utils.ts`)
- `hybridSearch` keyword-only fallback when no embedding provider key is configured
- Data stored at `~/.gbrain/brain.pglite` (configurable)
- pgvector HNSW index for cosine similarity vector search (same as Postgres)
- tsvector + ts_rank for full-text search (same as Postgres)
- pg_trgm for fuzzy slug resolution (same as Postgres)
### PGLite vector index ceiling
PGLite runs Postgres inside WebAssembly, and pglite.wasm caps its memory at
2 GiB. pgvector holds the whole HNSW graph in `maintenance_work_mem` while it
builds, about 4.7 KB per 1,024-dimension chunk (1.16 GB at 250k chunks).
gbrain starts PGLite with `max_parallel_maintenance_workers=0` (PGLite has no
worker processes, and a planned parallel build reserved all of
`maintenance_work_mem` up front) and `max_wal_size=8GB` (a build WAL-logs its
whole index in one statement, and WAL past the automatic checkpoint trigger
wedges PGLite). The deferred ANN build (`gbrain migrate embeddings`) and
`gbrain reindex --vectors` size `maintenance_work_mem` to the graph
(`withHnswBuildMemory` in `src/core/vector-index.ts`): a 248,802-chunk build
takes about 11 minutes and a 1.9 GB index. A graph past the 1.5 GiB budget,
about 300k chunks at 1,024 dimensions, is refused before the build with
`pglite_vector_index_too_large`; vector search keeps working with exact scans,
and the fix is the read-only `gbrain migrate --to postgres --plan --json`.
**When to use PGLite vs Postgres:**
| Factor | PGLite | PostgresEngine + Supabase |
|--------|--------|--------------------------|
| Setup | `gbrain init` (zero-config) | Account + connection string |
| Scale | Good for < 1,000 files | Production-proven at 10K+ |
| Multi-device | Single machine only | Any device via remote MCP |
| Cost | Free | Supabase Pro ($25/mo) |
| Concurrency | Single process | Connection pooling |
| Backups | Manual (file copy) | Managed by Supabase |
| Largest page | 128 MiB, stored in segments (`pages.max_bytes`) | 256 MiB, stored in segments (`pages.max_bytes`) |
**The belief ledger lives only in the database.** `belief_events` and its side tables record what the brain had recorded, and when (`gbrain beliefs status`). Markdown carries only current state, so a rebuild from Markdown, `gbrain reinit-pglite` or a dropped database starts an empty history; back up the database itself. After restoring a Postgres (or PGLite) backup, replay the purges made after the backup was taken: until then content purged later is readable again, and `gbrain doctor --only belief_ledger_coverage` reports a restore whose purge replay was partial, unavailable or unverified. Graduation copies the ledger verbatim (equal event keys and digests); the legacy copier refuses a brain that has one.
**Migration:** on a PGLite brain, `gbrain migrate --to postgres` (alias `--to supabase`) graduates the brain to Postgres. Without `--yes` it prints the plan and exits 3; `--yes --expect ` runs it. Graduation drains pending writes, copies every table verbatim with its primary keys (pages, facts, takes, versions, links, timeline, embeddings, transcripts and paid caches, request history and withdrawals, token and OAuth rows) into a fenced target, verifies row counts and digests, runs `gbrain doctor` on the target, and only then flips routing. It works for brains with write history and for managed brains. The PGLite data dir is retained as `.graduated-` and a tombstone file takes its place. Walkthrough, recovery by error code, rollback and what stays on this computer: [Move a PGLite brain to Postgres](guides/move-to-postgres.md).
**Say to your agent:** *"Upgrade my brain to Postgres. Show me the plan first."*
The legacy copier handles every other direction: `gbrain migrate --to pglite`, PGLite to Postgres when `gbrain config set migrate.graduation false` opts out of graduation, and history-free brains on Windows. It re-creates pages through `putPage` (chunks, embeddings, links, tags, timeline, facts) and copies config rows minus the engine-local denylist (`MIGRATE_CONFIG_ENGINE_LOCAL_KEYS`: the target-owned `engine`/`version` connection + schema ledger and the physical embedding-column registry keys); skipped keys are printed, never silent, and the run ends with a per-table copied-count summary. It forwards the full page row (origin path, kind, provenance, `ingested_at`, aliases, chunk code metadata). Pages the source had sealed are rebuilt on the target before the config flip, without an embedding key, keeping chunk ids and vectors whose input matches. A failed rebuild blocks the flip: the run exits 1 with no error code, prints `The active engine was NOT switched` and the failing pages, and leaves the source engine active; fix them (`gbrain projections drain` on the target) and re-run `gbrain migrate` to resume. Pages the source had not sealed arrive queued, with their verbatim chunks. It does not carry request IDs, withdrawals, attribution or ownership, so it refuses a managed brain and any brain with durable write history, fact withdrawals or canonical worktree ownership (rows in `persistence_requests`, `fact_withdrawals` or `persistence_worktrees`), and a brain with a belief ledger (rows in `belief_events`), which it names.
**Engine migration refused (`writer_coordinator_required`).** The legacy copier's refusal is an agent-contract envelope whose `fix` names the refusing side; every branch verifies with the read-only `gbrain doctor --no-migrate --json`, and nothing has changed in either datastore:
| Refusing side | `fix.next` | Next step |
|---|---|---|
| A PGLite brain with history (or a managed one) moving to Postgres with graduation turned off | `ask_user` (consent `egress`) | Relay `user_message`: turn graduation back on (`fix.argv`: `gbrain config unset migrate.graduation`) and preview the move with the read-only plan (`fix.then`: `gbrain migrate --to postgres --url-env GBRAIN_TARGET_URL --plan --json`, then the [two-command flow](guides/move-to-postgres.md#move-the-brain)), or keep it on PGLite and share it through `gbrain mcp expose`. |
| A Postgres brain moving to PGLite | `report` | The brain stays on Postgres; moving down would drop its history. |
| A target that already holds persistence history | `tell_user_to_run` | Rerun with an empty database the user provides (`--path` for a PGLite target). |
A brain with page versions but no write history gets the same refusal with `reason: page_history` and the number of versions in the message: the legacy copier re-creates pages without their versions, so the copy would discard them. Graduation (PGLite to Postgres) carries them.
On Windows, a PGLite brain with history gets `graduation_unsupported_platform` instead: it stays on PGLite and is shared with `gbrain mcp expose`.
**Graduation refused: the brain is held (`graduation_source_writer_held`).** Graduation needs the PGLite kernel lock. A live stdio `gbrain serve` hands the brain over through the intent marker `.gbrain-graduation.json` and exits; autopilot pauses. When another holder (an HTTP serve, a daemon, another command) does not release the brain within 30 seconds, the run refuses and names it with its pid and transport (`fix.next: tell_user_to_run`). The user stops that process, then the agent reruns the same `gbrain migrate` command. Verify with the read-only `gbrain migrate --status --json`. Nothing has changed in either datastore.
The migration and the autopilot daemon do not race: both graduation and the
legacy copier claim a cooperative pause marker before touching the target. The
marker doubles as a migration mutex — a second concurrent migrate refuses to
run (graduation exits 75 with `graduation_in_progress`), and a marker that
cannot be written refuses the migration outright. Background job workers stop
picking up new work while it is parked. The legacy copier then waits for
in-flight sync/embed/cycle work and running jobs to drain (watching the DB lock
table, capped by `GBRAIN_MIGRATE_QUIESCE_SECONDS` — default 300; `0` skips the
wait). Graduation holds the PGLite kernel lock instead, so no other process has
the brain open: expired run locks and active job leases are orphans it resets
at once, and it waits only for queued write requests, bounded by
`--drain-timeout` (default 60 seconds; exhaustion exits 11 with a
`resume_command`). Cleanup registers the moment the claim lands, so the marker
is released on failure and on catchable signals; a marker orphaned by an
uncleanly killed run is adopted by a later migrate only after a pid-liveness
check (a live migrate's marker is never stolen), and the daemon clears an
orphan whose owning process died on its next poll. `gbrain autopilot --status`
reports `paused` (exit 1) while the marker is parked and prints the marker
path; on a host with no daemon running to self-heal, remove an orphan by hand
only after confirming the pid it names is dead. After a clean flip the daemon
detects the engine change on its next tick and relaunches onto the new engine,
and the migration warns if an exported connection-string env var would
override the new config (graduation lists such a variable as a plan blocker).
### Troubleshooting: startup abort (`RuntimeError: Aborted()`)
**Symptom:** every PGLite-touching command dies at startup with
`PGLite failed to initialize its WASM runtime … Aborted(). Build with
-sASSERTIONS for more info.` — commonly first seen right after a macOS
upgrade.
**Real root cause:** corrupt WAL/checkpoint state in the data dir after an
unclean shutdown (the OS-upgrade reboot kills gbrain mid-write and tears the
write-ahead log; every subsequent open fails WAL replay inside WASM and
Emscripten surfaces only the opaque abort). It is **not** a macOS/WASM
incompatibility — the same signature reproduces across macOS versions and on
Linux, and rebuilding the data dir on the same OS fixes it. No pglite or Bun
version bump changes it.
**Recovery ladder** (top rung first):
1. **Auto-repair (default).** `PGLiteEngine.connect()` detects the abort,
backs up `pg_wal/` + `pg_control` into a sibling
`.wal-repair-backup-/` dir, resets the WAL in place
(pg_resetwal semantics — data files preserved; transactions not
checkpointed before the corruption may be lost), and retries once. The
reset does not rebuild indexes, so a page written just before the crash
can be missing from vector search while keyword search still finds it.
On success it prints a loud stderr notice naming the backup and the next
commands: `gbrain reindex --vectors` (rebuilds every HNSW index from the
stored vectors, no re-embedding) and then `gbrain doctor`. Safety bounds: repair only runs under a cleanly-acquired
data-dir lock (never after reaping another process's lock), skips for a
cooldown window after a failed attempt
(`GBRAIN_PGLITE_WAL_REPAIR_COOLDOWN_SECONDS`, default 3600), reuses one
backup per corruption episode (newest 3 episodes retained), and restores
the original files if the retry still fails. Kill-switch:
`GBRAIN_PGLITE_WAL_REPAIR=off`.
2. **Manual repair.** `gbrain pglite-repair --dry-run` diagnoses the data dir
(read-only); `gbrain pglite-repair --yes` runs the same in-place WAL reset
deliberately. Refuses when another gbrain process holds the brain (a live
`gbrain serve` is named explicitly) and never force-removes `.gbrain-lock`.
3. **Rebuild.** `gbrain reinit-pglite` (embedding model/dimensions default
from your config) wipes and re-creates the brain from your brain repo, or
manually: back up `~/.gbrain`, move `brain.pglite` aside,
`gbrain init --pglite`, re-add sources, `gbrain sync`, `gbrain embed`.
Required for *catalog* corruption (58P01 / pgvector load failure) — WAL
repair cannot fix that class.
4. **Switch engines.** `gbrain init --supabase`, or native Postgres +
pgvector — see the "Local Postgres" section above for the full recipe
(Homebrew or the `gbrain init --prefer-postgres` ladder).
`gbrain doctor` runs a `pglite_data_dir` check whenever a PGLite brain fails
to connect: it diagnoses the dir from disk, names the repair command, reports
retained repair backups, and escalates when repairs keep recurring (that
means the unclean-shutdown genesis is still active — see the ladder's rung 4).
### Legacy PGLite lock (`pglite_busy` reason `legacy_owner_unverified`)
A PGLite brain is owned through the stable sibling kernel lock
`.gbrain-owner.lock`. Brains last opened by an older gbrain may
still hold that release's lock folder, `/.gbrain-lock/`. The first
open by a current gbrain removes it automatically only when it can prove the
old owner is dead: readable metadata with a PID that `kill -0` reports gone
and, on Linux, the same PID namespace and boot id as this process. A live
owner keeps the ordinary `pglite_busy` refusal.
When the folder's metadata is torn or missing, records no PID, or (Linux) does
not prove the PID ran in this namespace since the last boot, waiting never
helps, so the open refuses `pglite_busy` with reason
`legacy_owner_unverified` (class consent, exit 3, not retryable). Its fix
asks the user and starts with the read-only preview; `gbrain doctor` shows
the same reason and fix on its `connection` check.
1. **Preview.** `gbrain pglite-repair --legacy-lock --dry-run --json [--path ]`
never opens the engine and never creates anything. It names the recorded
PID, whether `kill -0` says it is running and its command, the processes
an open-file scan of `/proc` (Linux) saw holding files under the data dir,
and the filesystem type (Linux `statfs`, macOS `df -P` and `mount`), and prints the `plan_hash` and
the apply command. This evidence is advisory: it covers only this host and
PID namespace and cannot see other containers or other hosts that share the
folder.
2. **Apply, after the user agrees.**
`gbrain pglite-repair --legacy-lock --path --yes --expect `
takes the kernel lock (so no current gbrain can be running), inspects
again under it and refuses `legacy_lock_removal_refused` while a process
on this host holds the data dir or the recorded PID runs a command that
could be gbrain (`live_holder`), or when the data dir is on a network or
shared filesystem such as NFS, SMB, 9p, virtiofs or FUSE
(`network_filesystem`), or when it cannot confirm the filesystem is local
(`filesystem_unverified`: Linux reads `statfs`; macOS reads the mount
point from `df -P` and its `mount` line, and counts it local only with
the `local` flag and a local type such as apfs or hfs. Other systems, a
failed probe, an unrecognised type, a macOS network mount such as smbfs or
nfs, and a macOS mount without the `local` flag all refuse). A lock that changed since the preview refuses `preview_changed`.
It inspects again after consent, so a holder or change that appears while
the prompt waits refuses the same way. Otherwise it moves the folder into
`.legacy-lock-removed-/` (nothing is deleted) with a
`receipt.json` and the exact restore command (it also puts back the prior
`.gbrain-owner.json` bytes, kept as `prior-owner-marker.json`,
or removes the new marker when there was none), writes the kernel-v1 marker
`.gbrain-owner.json`, and starts the 10-minute WAL-repair
quarantine (`.lock-reap.json`). The next ordinary open succeeds.
## Canonical schema sources
Schema DDL text has one hand-edited copy. `bun run build:schema`
(`scripts/build-schema.ts`) generates everything else in a fixed order:
```
TS fragment modules (canonical for their tables) ─┐
src/schema.sql (canonical for every other table) ─┴─> src/schema.sql BEGIN/END GENERATED regions
├─> src/core/schema-embedded.generated.ts (Postgres blob)
└─> src/core/pglite-schema.generated.ts (PGLite template)
```
- **Fragments** (`FRAGMENTS` in the generator): `grants/schema.ts`, `facts/withdrawal-schema.ts`,
`lease-schema.ts`, `page-state/schema.ts`, `persistence/schema.ts`,
`page-state/projection-schema.ts`, `persistence/topology-schema.ts`,
`company-brain/receipt-schema.ts`, `shared-skills/schema-all.ts`. Migrations import the same
constants, so a fragment is also the migration text. Each has one region in `src/schema.sql`
whose banner names the file to edit; never edit inside a region.
- **PGLite template**: every `src/schema.sql` statement and fragment, transformed by explicit
capability rules (`PGLITE_RULES`, `PGLITE_DO_BLOCKS`, `PGLITE_ADDITIONS`, each with a reason).
`getPGLiteSchema(dims, model)` fills `__EMBEDDING_DIMS__` / `__EMBEDDING_MODEL__` and applies the
chunk-index and FTS-language policies at runtime. An unknown statement kind, an unclassified
`DO` block, or a rule that no longer matches fails the build.
- **Guards**: `check:schema-fresh` regenerates the whole chain into a temp dir and names the source
to edit on drift; the catalog goldens (`test/schema-catalog-golden.test.ts`,
`test/e2e/schema-catalog-golden.test.ts`) and `test/pglite-upgrade-replay.test.ts` pin the end
state.
Engine differences in the bootstrap (not reconciled; changing them is a schema change):
`file_migration_ledger` is Postgres-only. PGLite gets `code_edges_chunk`, `code_edges_symbol`,
`dream_verdicts`, `sources.chunker_version`, the `content_chunks` code-symbol and `search_vector`
columns (with their indexes and trigger), `pages_generation_idx` and `idx_pages_updated_at_desc`
from migrations. Postgres gets `slug_aliases`, `page_aliases`, the `page_links` view and
`persistence_requests_database_pending` from migrations.
Worked examples:
1. **Add a column or index to a hand-written table** (say `pages.foo`). Scaffold the migration
(`bun run new:migration add_pages_foo`: `ALTER TABLE pages ADD COLUMN IF NOT EXISTS foo TEXT;`,
and for an index on Postgres `CREATE INDEX CONCURRENTLY` with `transaction: false` plus a plain
`sqlFor.pglite`). Add the column to the `pages` `CREATE TABLE` in `src/schema.sql` so fresh
installs get it, then `bun run build:schema`; both blobs follow.
2. **Add a table.** Put its `CREATE TABLE` in `src/schema.sql` and create it in a migration. If
migrations and the blob should share one text, make it a TS fragment instead: export the SQL
constant, import it from the migration, add a `FRAGMENTS` entry and an empty region
(`-- BEGIN GENERATED from (). ...` / `-- END GENERATED from ()`)
where the table belongs, then `bun run build:schema`. A Postgres-only table gets a
`PGLITE_RULES` drop entry with its reason.
3. **When the forward-reference bootstrap changes.** Existing brains replay the blob before
migrations run. If the blob gains an index, FK, trigger or view that references a column an
older brain may lack, add that column's probe and `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`
to the forward-reference bootstrap both engines run (`src/core/engine-sql/bootstrap.ts`:
probe, gap, DDL). A column only defined in a
`CREATE TABLE` needs no bootstrap entry. `test/schema-bootstrap-coverage.test.ts` names any gap.
## Engine detection and access repair
Two engine-free commands answer "which engine is this brain on?" and "why can't
I reach it, and what fixes it?" — both work with the database down, which is the
point. They anchor the runtime availability loop: classified failure →
`GBRAIN_DB_ACCESS ` marker → the bundled `skills/db-repair/` skill →
`gbrain db-repair`.
### `gbrain engine status [--json] [--probe] [--brain ]`
Reports (JSON `schema_version: 1`): the effective engine vs the config-file
engine (they can differ under a transient env URL), `db_url_source`, an
env-shadow note when a cwd-.env `DATABASE_URL` is being excluded by the
cwd-.env guard (gbrain never adopts a `DATABASE_URL` that Bun auto-loaded
from the working directory's `.env` family: `.env`, `.env.local`, and the
`.env.` / `.env..local` variants for `development`,
`production` and `test`; with the precedence note when both `GBRAIN_DATABASE_URL` and
`DATABASE_URL` are set — this `DATABASE_URL` guard matches the file's VALUE; the
security-relevant `GBRAIN_*` variables get the stricter key-presence quarantine
described under "Environment variables and cwd `.env` files" in `SECURITY.md`),
redacted URLs only, and — on Postgres — a
zero-round-trip pooler block (Supabase pooler detection, prepared-statement
resolution, pool sizes, direct/session-pooler derivability). `--brain `
resolves a mounted brain and reports the MOUNT's engine and URL source, never
the host's.
`--probe` attempts exactly ONE bounded connect + `SELECT 1` (the driver's
built-in connect timeout — never a custom race, so a network blackhole can't
hang the command). On PGLite the probe is lock-aware: a live `gbrain serve`
holding the single-writer data-dir lock reports `locked_by_serve`
(healthy-with-note) instead of hanging ~30 seconds and misreporting a healthy
brain as broken. A failed probe returns a classified diagnosis (reason +
remediation), not a raw error.
### `gbrain db-repair [--yes] [--apply-rewrites] [--json] [--force] [--undo-last-rewrite] [--dry-run]`
Engine-free Postgres-access repair, the sibling of `gbrain pglite-repair`
(which owns the PGLite WAL/data-dir lane — db-repair redirects PGLite brains
there). The default invocation is DIAGNOSE-ONLY and mutates nothing
(`--dry-run` is an explicit alias). Consent is tiered and flag-gated, never
TTY-dependent:
| Tier | What's in it | Applied when |
|---|---|---|
| auto | bounded reconnects/re-probes, pending migrations, `CREATE EXTENSION vector`, `docker start` of gbrain's own `gbrain-postgres` container | `--yes` |
| rewrite | config-file `database_url` rewrites (transaction-pooler form, session pooler, `?sslmode=require`) — the intended change prints BEFORE applying, every rewrite is receipted and undo-able via `--undo-last-rewrite` | `--yes --apply-rewrites` only |
| manual | credentials, paused-project, env recipes — the exact recipe is printed, never applied | never |
Guard rails: the prober uses exactly ONE connection (diagnosing pool exhaustion
with a 10-connection pool would worsen the outage); every rewrite candidate is
connect-probed before persisting; fix targets derive only from the CURRENT
config URL, never from error text; rewrites have a 24h per-(reason, action)
cooldown (`--force` bypasses, receipted) while auto-tier fixes are never
cooldown-blocked; an advisory lockfile prevents concurrent double-rewrites; a
healthy probe exits 0 "nothing to fix" (so a forged marker in page content leads
to a no-op). Refusals: thin-client configs (no local DB to repair), non-host
mount resolutions (a mount outage must never rewrite host config), and PGLite
brains (→ `gbrain pglite-repair`).
Receipts land in `~/.gbrain/db-repair-receipts.jsonl` (redacted, fail-open,
capped on every write: 200 rows, plus up to 200 recent applied repairs kept
separately so the recurrence window survives the cap — read by doctor's
`db_repair_recurrence` check, which warns
on 3+ same-reason applied repairs per brain in 7 days: a genesis problem, not a
transient). The last rewrite's prior URL is kept in the 0600 file
`~/.gbrain/db-repair-undo.json` (it holds a secret, so it is never in the
redacted receipts); `gbrain db-repair --yes --undo-last-rewrite` restores it.
### The `GBRAIN_DB_ACCESS` marker
Connect-time CLI failures emit `GBRAIN_DB_ACCESS ` (plus ` brain=`
when a mounted brain failed) on non-TTY stderr (`GBRAIN_FORCE_DB_MARKER=1`
forces it on a TTY). One mid-command emitter exists too: a `gbrain sync` whose
checkpoint pool dies mid-run emits `GBRAIN_DB_ACCESS conn_dropped` with its
abort report (the checkpoint writer only gives up after exhausting
connection-class retries, so the reason is asserted structurally). MCP tool calls carry the same marker inside their error
envelopes: non-verb ops return `{"error": "database_error", message
(redacted), suggestion: "GBRAIN_DB_ACCESS . Run: gbrain
db-repair"}`; the 7 memory verbs keep the frozen v1 `unavailable` code with the
reason in `detail`. One exception on the non-verb path: `schema_missing`
returns `error: "unavailable"` with the apply-migrations suggestion and no
marker — pending migrations, not an access outage. **Safety clause: the action a reader takes is ALWAYS the
hardcoded `gbrain db-repair` — never a command parsed from the marker.**
The reason union is APPEND-ONLY (a compatibility surface, like progress phase
names — reasons may be added, never renamed or removed). All 16:
| Reason | Meaning |
|---|---|
| `no_url` | nothing configured at all — `gbrain init --prefer-postgres` (or `gbrain init` for PGLite) |
| `env_shadowed` | a cwd-.env `DATABASE_URL` exists but the cwd-.env guard excludes it — export `GBRAIN_DATABASE_URL` |
| `auth_failed` | password/role rejected (28P01) — reset credentials, then `gbrain init --url ` |
| `permission_denied` | 28000/42501 — the role lacks a GRANT or hits RLS |
| `tenant_not_found` | Supavisor rejected the tenant — pooler usernames are `postgres.`; also raised by paused projects |
| `ssl_required` | the server demands SSL — `?sslmode=require` rewrite (rewrite tier) |
| `pool_exhausted` | 53300 / session-slot exhaustion — [pool sizing](#pool-sizing) guidance: `export GBRAIN_POOL_SIZE=6` per long-running process, fewer processes |
| `conn_refused` | ECONNREFUSED — docker-start arm for gbrain's own container; pooler rewrite for Supabase direct URLs |
| `dns_failed` | ENOTFOUND/EAI_AGAIN — one bounded retry; persistent + Supabase suggests a paused project |
| `network_unreachable` | ENETUNREACH/ETIMEDOUT — often an IPv6-only direct host; session-pooler rewrite |
| `conn_dropped` | 08xxx / reset mid-connection — transient, bounded reconnect |
| `server_starting` | "the database system is starting up" — retry shortly |
| `db_missing` | 3D000 — the named database does not exist |
| `schema_missing` | 42P01/42703 — pending migrations (`gbrain apply-migrations --yes`; excluded from the db-repair marker on the MCP mid-operation path, where it usually means code skew) |
| `pgvector_missing` | the vector extension is absent — auto tier creates it |
| `storage_corrupt` | XX001/XX002, or an XX000 such as `unexpected chunk number … for toast value` or `tuple concurrently deleted` — stored data is damaged; db-repair stops at manual and names the first step, `gbrain repair orphan-children` (preview, includes the torn-TOAST probe; [orphan children](guides/repair.md#orphan-children)) |
| `unknown` | unclassified — redacted error + `gbrain doctor` |
The classifier lives in `src/core/pg-access-classify.ts`; remediation copy has
exactly one home (that module) — db-repair, doctor, and MCP dispatch all render
its `remediation`, and skills reference the command rather than duplicating
recipe text.
### Degraded-mode serve
When Postgres is unreachable at `gbrain serve` STARTUP, serve does not die:
it boots on a lazy-reconnect engine, each tool call attempts a single reconnect
(minimum ~5s between real attempts — no connect storms), and until one succeeds
tool calls return the classified envelopes above. The call that triggers the
successful reconnect gets a retry-once error rather than a result
(`GBRAIN_RECOVERED_RETRY` — "retry this call"; its source scope was resolved
before recovery); every call after it gets full service, and MCP
`tools/list_changed` tells clients that handshook during degraded mode to
refresh their catalog. Structured
`[gbrain-serve] DEGRADED:` / `[gbrain-serve] RECOVERED:` lines land on stderr
for harness-log forensics. Kill switch: `GBRAIN_SERVE_DEGRADED=0` (or `false`)
restores die-on-startup. Scope: Postgres startup failures only — PGLite startup failures
keep die-on-startup (that lane's repair is `gbrain pglite-repair`), and
mid-session outages ride the engine's own reconnect plus the per-call
classified envelopes.
### Pool sizing
Each gbrain process opens its own ordinary pool of
`GBRAIN_POOL_SIZE` connections (default 10; environment variable only, no
config key). A long-running process (`gbrain serve`, `gbrain autopilot`,
`gbrain jobs work`) needs at least **6**: two for write publication, one for the
idle work probe, one each for the projection and effects workers, and one for
reads and tool calls. Below that, boot or projection draining stalls under
traffic. One-shot CLI commands can use `GBRAIN_POOL_SIZE=2`. With
`GBRAIN_POOL_SIZE=1`, schema setup and maintenance still run (`gbrain init
--db-only`, `apply-migrations`, `repair request-indexes`, `backfill`), but
managed writes need two connections: they stay queued with
`writer_pool_capacity`, so `gbrain init` without `--db-only` stops at its
packaged-skill install. Long holds keep one connection free for reads and
control work; only holds that use nothing but their own connection (migration
DDL, concurrent index builds, backfill batches) may take a single
connection.
Size the pooler for every process at once:
```
long-running processes x GBRAIN_POOL_SIZE
+ processes whose direct route lands on this pooler x their direct pool (see below)
+ one-shot commands running at the same time x their pool (a full `gbrain sync` is one too)
+ parallel import workers x 2 (an unmanaged sync of more than 100 files, `--workers N`, or the sync a serve runs)
<= the pooler's client limit (Supabase Supavisor: the project's pool_size)
```
The direct route lands on the pooler when `GBRAIN_DIRECT_DATABASE_URL` names it,
and also when gbrain derives it from a Supabase pooler URL whose user does not
name the project (`postgres.`): the derived route keeps the pooler host on
port 5432, its session port, even when the main URL uses transaction mode
(6543). Two long-running processes at the
defaults (10 + 3 each) already pass a client limit of 25, so a scheduled
`gbrain sync` next to a `gbrain serve` on the same session port can exhaust it.
`GBRAIN_MAX_CONNECTIONS` caps a sync's worker fan-out to fit a budget.
The direct pool's size follows the command.
`gbrain serve`, `gbrain jobs`, `gbrain autopilot` and `gbrain sync --watch`
open up to 3 direct connections. A command that exits but owns writes or takes
a lease (`sync`, `put`, `import`, `dream`, `cycle`, `sources`, `mcp`,
`migrate-graduation`) and the diagnostics that report the route (`doctor`,
`engine`) open 1. Every other command routes nothing through the direct pool:
its statements use the ordinary pool, as with `GBRAIN_DISABLE_DIRECT_POOL=1`.
Two exceptions keep the direct route for it: applying pending schema
migrations (one connection, for the session advisory lock and the 30-minute
statement timeout), and taking a lease such as an embed or extract lock
(the command then opens 1, so the lease heartbeat keeps its own connection).
`GBRAIN_DIRECT_POOL_SIZE` still sets the size wherever a direct pool opens.
`GBRAIN_DIRECT_POOL_BY_COMMAND=0` restores the earlier behavior: every command
may open the full 3-connection direct pool.
When the sum does not fit, run fewer long-running processes (for example one
shared `gbrain serve --http` instead of one stdio `serve` per agent session),
or raise the pooler's limit. Do not lower a long-running process below 6.
With a direct route configured, the persistence consumer's own tick
statements (idle probe, switch read, recovery and expired-claim scans,
capacity marking) take the direct pool beside the claims, renewals and the
heartbeat, so a transaction-mode pooler never sits between the owner and its
bookkeeping (#6317; `gbrain sources writer status --json` shows
`connection.lane: direct`). `GBRAIN_CONSUMER_DIRECT_LANE=0` keeps those scans
on the ordinary pool when the direct pool is too small for them.
`pool_exhausted` errors (SQLSTATE `53300`) and the
[serve boot timeout](#serve-boot-timeout) print this guidance.
**`serve_boot_timeout`** (stderr, exit 1).
`gbrain serve` made no boot progress for `GBRAIN_SERVE_BOOT_TIMEOUT_SECONDS`
(default 60; 0 disables), so it released the database and exited. The window
restarts at every boot phase, progress note and answered request, so a large
brain whose boot is slow but advancing is never stopped; the line also says how long the
boot had been running. The line
names the boot phase that never finished (`source_preflight`,
`writeback_config`, `mcp_connect`, `source_scope`, `persistence_consumer`,
`resolve_ipc_bind`, `startup_sweep`) and the pool pressure
(`pool=/`). When the pool is below 6 or saturated,
the fix is `export GBRAIN_POOL_SIZE=6` plus pooler sizing as above; otherwise
check the configured provider endpoints for the named phase, or raise the
timeout.
### Pool and transaction diagnostics
These warn lines and errors come from the Postgres engine's connection pools.
Each one names a stable code, its cause, a command and this anchor.
**`pg_connection_poisoned`** (warn).
A pooled connection came back to the pool inside a transaction (ReadyForQuery
status `T`) or a failed one (`E`), usually because a caller released a reserved
connection without `COMMIT` or `ROLLBACK`. The driver terminates that connection
instead of reusing it, so later statements never run inside the leftover
transaction and never fail with SQLSTATE `25P02`. Queued statements move to a
fresh connection. The line names the status byte and the pool (`read` or
`direct`) and carries no query text. `getPoolDiagnostics().poisonedDiscards`
counts discards per engine. There is no opt-out. Nothing needs to be repaired;
if the line repeats, run `gbrain doctor --json` and report the warn lines with
the operations that preceded them. A pool created with `max: 1` keeps the
driver's documented single-connection idiom (`BEGIN` as an ordinary query)
for unreserved statements.
**`schema_lock_blocked`** (error, retryable).
A schema step waited its `lock_timeout` for a table lock another session holds
and stopped instead of hanging (#5227). `gbrain init` and `upgrade` replay
`schema.sql` on the reserved DDL backend; every `ALTER TABLE` there takes an
ACCESS EXCLUSIVE lock even as a no-op, so one open transaction in another
client (idle in transaction, a stuck job) used to park the whole command in
`wait_event_type=Lock` with no output. The replay runs under a session-level
`lock_timeout` on that backend (`GBRAIN_SCHEMA_LOCK_TIMEOUT_SECONDS`, default
60; the value found before is restored on release, so a pooled backend never
leaks it), a transaction-wrapped migration binds the same wait with
`SET LOCAL lock_timeout`, and a `transaction: false` migration sets and
restores it on its own reserved backend. Handler migrations and the
post-migration `verifySchema` run outside the bound: they issue their own
statements (`CREATE INDEX CONCURRENTLY` cannot run in a transaction) and stay
as they were. While the wait is active a separate one-backend connection
samples `pg_blocking_pids()` of the waiting backend once, so the refusal names
the blocking sessions by pid, `application_name`, state and transaction age;
after the cancel the blocker may already be gone, and the message says when the
sample came late. Query text is never read or shown. `detail` names the step
(`replay`, `migration v`). The RLS block skips tables whose
`relrowsecurity` is already set, so a re-run on a live brain no longer takes
ACCESS EXCLUSIVE on them. `init` retries a blocked step a few times with a
short backoff (`init-schema-retry.ts`); a lock that never clears is a bounded
failure, not a hang. Fix: let the named session finish or, with the user's
agreement, end it on the database host with `SELECT pg_terminate_backend()`,
then rerun the same command. Test: `test/e2e/init-schema-lock-blocked.test.ts`.
**`pg_connection_stuck`** (warn). A pooled
statement ran past its in-flight budget, either with nothing coming back from
the server (`reason=idle`) or while bytes kept arriving (`reason=age`, #6543),
so the vendored driver retired that connection:
the statement and every statement queued behind it failed with the driver error
`CONNECTION_STUCK`, the connection left the pool before its socket closed, and
the pool reconnected on its own (#6383). Usually only a wedged connection
reaches the budget: a pipeline the client and server no longer agree on, a
transaction-mode pooler that swallowed a `CancelRequest` and left the backend
in `ClientRead`, or a dead peer. It is not proof: behind a transaction-mode
pooler (port 6543) the startup `statement_timeout` never reaches the backend
(`SHOW statement_timeout` reads `0`; `/health?deep=1` reports it as
`transport.session_timeouts_not_applied`), so a legitimately slow statement can
reach the budget too (#6543). The budget is the pool's own startup `statement_timeout` (5 min on
the read pool, 30 min on the direct pool, `GBRAIN_STATEMENT_TIMEOUT` for the
read pool) plus `GBRAIN_PG_STUCK_GRACE_MS` (default `30000`); it follows the
configured timeout even through a pooler that drops the startup parameter, and
`GBRAIN_PG_STUCK_GRACE_MS=0` or `off` disables the watchdog. Two clocks run
against it: the idle clock restarts on every byte the server sends, the age
clock never does, so a statement that keeps streaming rows or notices past the
budget is retired too. The budget is derived per statement and travels with the
operation: a statement after a `SET [LOCAL] statement_timeout` or
`set_config('statement_timeout', …)` on its connection (inside a transaction,
on a reserved connection, or in the same simple query) gets
`max(budget, that timeout + grace)`, and a declared `0` (an index build, a bulk
copy) has no cap. The driver reads the declaration from the statements it
sends, so it holds behind a transaction-mode pooler that never applies a
session `SET`; a transaction's `SET LOCAL` ends with it, `RESET` restores the
pool's budget. An operation that must run longer declares its own timeout that
way; `GBRAIN_STATEMENT_TIMEOUT` raises it for every read-pool statement. The
line names the pool, `reason`, `age_ms`, `budget_ms` (that statement's own
cap), `queued` (statements that failed with it) and the statement by first
keyword and table (`sql=SELECT_pages`), never its text or parameters. `getPoolDiagnostics().stuckDiscards` counts retirements per
engine; `/health?deep=1` reports them as `stuck_discards`. Retry the failed
call; if the line repeats, run `gbrain doctor --json` and report the warn lines
with the operations that preceded them.
**`pg_connection_desync`** (warn). A statement's
answer (columns, rows, a completion, a parse or bind acknowledgement, or a
statement error) arrived on a pooled connection with no statement waiting for
it, so the client and the server no longer agreed on which answer belonged to
which statement. The vendored driver retired that connection, statements
queued on it failed with a connection error, and the pool reconnected on its
own. The line names the pool, the message type, the driver's connection id and
the last statement written on it by first keyword and table, never its text or
parameters. Notices, notifications and parameter changes never trigger it.
`getPoolDiagnostics().desyncDiscards` counts retirements per engine;
`/health?deep=1` reports them as `desync_discards`.
**`pg_connection_recovery_failed`**
(warn). A connection the driver retired after an incident (stuck, desynced, or
closed under running statements, for example by `pg_terminate_backend` or a
pooler reap) could not reconnect; statements waiting for it failed with the
connect error, and the next statement retries. The line names the pool, the
driver's connection id, the incident (`cause=stuck|desync|closed`) and the
error code. `getPoolDiagnostics()` counts reconnects of retired connections as
`recovered` and failures as `recoveryFailed`; `/health?deep=1` reports them as
`recovered` and `recovery_failed` (#6543). A resident `gbrain serve` writes its
stuck, desync and recovery events to the pool-recovery audit
(`~/.gbrain/audit/pool-recovery-YYYY-Www.jsonl`), so
`gbrain doctor --only pool_reap_health` fails on a recovery failure and warns
on a stuck or desynced connection in the last hour.
Retry the failed call; if the line repeats, run `gbrain doctor --json` and
report the warn lines.
**`pg_statement_build_failed`** (warn). A
statement could not be built from its parameters (`error=UNDEFINED_VALUE`: a
parameter was `undefined`; `error=MAX_PARAMETERS_EXCEEDED`: more than 65534
parameters). It was answered in its place in the pipeline by a query the server
refuses, so only it failed and a transaction it was part of was aborted rather
than committed without it. Before #6383 the same failure, when the statement was
pipelined behind another on its connection, rejected that other statement with
its error, left the culprit queued with nothing on the wire, and delivered every
later reply one statement late until the process restarted (the
`null is not an object (evaluating 'query.statement.types')` line and a backend
stuck `active / ClientRead` were that desync). The line names the pool and the
statement by first keyword and table, and an `UNDEFINED_VALUE` line names the
parameter (`param=$2`, or `param=?` for an array element). Behind a
transaction-mode pooler (port 6543, `?prepare=false`) a build failure usually
means a misrouted answer: the statement bound a value read from a row that
belonged to another statement, so earlier reads on that pool are suspect too.
Check `/health?deep=1` `transport.max_pipeline` (gbrain sends `0` there since
v0.60.187.0; `PGMAX_PIPELINE=0` forces it) and audit the window with
[the pooler misroute audit](guides/pooler-misroute-audit.md). Elsewhere the
call site that bound `undefined` is a gbrain bug, so report the line.
`getPoolDiagnostics().buildFailures` counts them.
**`pg_pool_stalled`** (warn, resident processes).
`gbrain serve` reads its pool every 30 s; when connections are checked out or
statements are waiting for one across two ticks in a row and the pool completed
no statement in between, it logs this line once per tick with `checked_out`,
`max`, `waiters`, `inflight_oldest_ms` and `stalled_ms`, and one
`[gbrain] info code=pg_pool_recovered` line when statements complete again.
One slow statement is one quiet tick and is never reported. With the in-flight
watchdog on, a stall ends within `statement_timeout` plus grace and
`pg_connection_stuck` names the connection; with the watchdog off this line is
the only trace a wedged pool leaves. A line that keeps repeating with no
recovery means the database or pooler is unreachable from the process:
`gbrain doctor --json` from a fresh process, then restart the stalled one.
**`/health?deep=1`** (`gbrain serve --http`). Plain `/health` stays the fast
liveness probe, and it runs its `SELECT 1` on a reserved connection, which the
driver only ever claims from idle connections; a wedged connection sits in the
busy queue where handler statements are routed, so `/health` answered 200
through the whole #6383 incident. `/health?deep=1` runs `SELECT 1` through the
ordinary pooled dispatch (no reservation, 3 s budget) and answers 503 when the
probe does not return in time, when a pooled statement is past its own
in-flight budget (the same per-statement budget the watchdog retires at, so a
transaction that declared a longer `statement_timeout` is measured against it;
the block's `inflight_over_budget_ms`), or when an earlier deep probe is still pending (one
deep probe per engine at a time). Its body carries the pool block:
`{ checked_out, max, waiters, inflight_oldest_ms, completed, poisoned_discards,
stuck_discards, build_failures, desync_discards, recovered, recovery_failed }`. It is cheap enough for a two-minute cron. The
same pool numbers ride the persistence consumer's heartbeat row, so
`gbrain sources writer status --json` shows `pool.inflight_oldest_ms` for the
owner process.
Every 503 body carries a stable `code` with `fix` and `docs` from the error
registry (#6543):
- `persistence_restart_required`: this serve's persistence consumer reports
`restart_required` (an abandoned preparation or a publication past its
deadline), so it claims no write until the process restarts. Restart serve.
- `pool_inflight_over_budget`: a pooled statement has run past its own
in-flight budget without being retired (the watchdog is off, or the serve
runs a driver without per-statement budgets). Restart serve; behind a transaction-mode pooler read
`transport` first and set `PGMAX_PIPELINE=0` if `max_pipeline` is not `0`.
No request id or statement text reaches either body: the endpoint is
unauthenticated.
- `deep_health_probe_failed` with `reason` `pending`, `timeout` or `error`: the
pooled `SELECT 1` did not answer. Retry; if it persists, `gbrain doctor --json`.
Both 200 and 503 bodies carry `transport`, read once at startup through the
read pool and logged as a `[gbrain serve] transport` line:
`{ pooler_mode, prepare, max_pipeline, max_pipeline_reason, statement_timeout,
session_timeouts_not_applied, fix?, application_name? }`. `prepare` and
`max_pipeline` are the live pool's options; `max_pipeline_reason` says why
(`transaction_pooler_port`, `url_prepare_false`, `gbrain_prepare_off`,
`url_max_pipeline`, `env_pgmax_pipeline` or `default`): gbrain builds the read
pools with `max_pipeline: 0` for a transaction-mode URL (port 6543 or
`?prepare=false`) or `GBRAIN_PREPARE=0` since v0.60.187.0, and a URL
`?max_pipeline=` or a non-empty `PGMAX_PIPELINE` always wins.
PgBouncer in transaction mode carries pipelined statements correctly, so a
PgBouncer deployment on port 6543 or with `?prepare=false` can opt back in with
`?max_pipeline=100`: on a 3-connection pool with 8 concurrent workers at about
40 ms round trip, pipelining off measured about 37% fewer statements per second
(1185 vs 1890 in 30 s); at localhost latency there was no measurable cost. Do
not opt back in behind Supavisor.
`application_name: "Supavisor"` appears when the backend names Supavisor.
`session_timeouts_not_applied: true` means gbrain configured a
`statement_timeout` but it reads `0` through the pool (a transaction-mode
pooler drops startup parameters), so no server-side timeout bounds an
autocommit statement; `fix` is the same `ALTER ROLE` the
doctor's `persistence_session_timeouts` check prints
([troubleshooting](guides/troubleshooting.md#session-timeouts-not-applied)).
The endpoint is unauthenticated, so it only reports: it never retires a
connection or restarts anything.
To let a supervisor recover a wedged serve
without a human, set `GBRAIN_SERVE_RESTART_REQUIRED_EXIT_SECONDS=` (off by default;
`n` must be a whole number of at least `120`, and a smaller value refuses to
start with `invalid_params`). When `persistence_restart_required` has held
continuously for `n` seconds (read in-process; the hold restarts whenever the
stuck work settles and the flag clears), serve logs
`[gbrain serve] error code=serve_unhealthy_exit cause=persistence_restart_required`,
disconnects under a 5 s deadline (the consumer's stop waits on the stuck work,
so the exit never depends on it draining) and exits `69`.
`pool_inflight_over_budget` never triggers the exit (the variable is named for
its one trigger): restart serve yourself or from your health check. A loop
guard records each self-exit in `serve-self-exit.json` under the gbrain home;
after 3 self-exits within an hour serve stops exiting, logs
`serve_self_exit_suppressed`, and the deep-health 503 carries
`self_exit_suppressed: true` with a fix that asks for a manual restart and a
look at `gbrain sources writer status --json`.
The service `gbrain mcp expose` installs restarts it (systemd `Restart=always`,
launchd `KeepAlive`), so a fresh serve comes up; the floor keeps a restart loop
under the systemd unit's start limit (10 starts per 300 s). For the installed service put the variable
in `~/.gbrain/env`; for a foreground serve set it in the shell or your own
supervisor's environment. A foreground serve with no supervisor just exits.
**`backfill_rollback_failed`** (error).
A `gbrain backfill` batch failed, and its `ROLLBACK` failed too. The run stops
rather than retrying on a connection whose transaction state is unknown; the
driver discards that connection. Nothing from the batch was committed and the
checkpoint did not advance. The message names both errors (redacted, at most
200 characters each). Fix the cause they name, then run
`gbrain backfill --resume`.
**`backfill_commit_indeterminate`** (error).
A `gbrain backfill` batch sent its `COMMIT` and got no verdict from the
server (for example the connection dropped), so the batch may or may not have
committed. The run stops without bisecting or skipping anything, and the
checkpoint stays before the batch. Run `gbrain backfill --resume`:
rows that did commit no longer match the backfill and are not redone.
**Skipped backfill rows.** A row whose compute
or UPDATE fails on its own (a CHECK or type violation, a compute error) is
isolated by splitting its batch, each part in its own transaction, and recorded
in the config key `backfill..skipped`; the checkpoint moves past it and
the other rows land. `gbrain backfill ` prints each recorded row with
its code and the retry command, and every later run retries it first. A row
that fails with the same content error on 3 consecutive runs (same row, same
gbrain version) is held: it is reported but not retried until the row or the
gbrain version changes; `gbrain backfill --fresh` retries it now. When
most rows of a run fail, the run stops with `item_failures_systemic` and keeps
the skip record and checkpoint it began with.
**`[persistence] phase= reason=`**
(stderr). The resident write consumer could not finish a phase. `reason` is
the SQLSTATE (for example `53300` when a pooler's client limit is reached),
a write-error code, `storage_error`, or `deadline_exceeded` when the phase
overran its five-second budget. `message` is the redacted error text, one line,
at most 200 characters. When an unexpected exception in the owner failed a
write (`storage_error` with a generic public message; the class and frame stay owner-only),
the line also carries `class=`, `errno=` and `frame=` (the top gbrain source
frame, repo-relative, for example `src/core/persistence/page-prepare.ts:120`):
the owner diagnostics the receipt points at. For a database server error it
adds `error_text=`, `statement=` and `position=` (#7112): the server's primary
message with every quoted value replaced by `…` (an object name such as a
column, a relation or the token a syntax error stopped at is kept), the first
line of the failing statement with its literals replaced, never its
parameters, and the error's character position. A PL/pgSQL `RAISE` keeps no
text, because it can carry page values. The stored receipt keeps the same
identifiers (never an application error's message) owner-side in `error_detail`, with the
build that ran the attempt; on the brain host `gbrain write-request --json`
prints that `error_detail`, and names an owner on another build than the CLI
(`owner_build`) and the restart to run. Connection-wait evidence follows on Postgres:
`first_conn_ms` is the time from phase start until the phase obtained a
connection; `checkout=not_observed conn_wait_ms=` means it had not obtained
one after `n` milliseconds (a saturated pool or pooler, not a slow query); and
`loop_lag_ms` is the longest event-loop delay during the phase (a busy or
starved process). The same fields appear in the consumer's status snapshot
under `phase`. Unfinished work stays tracked and is retried; nothing is lost. Run `gbrain sources writer status --json` to see what is waiting.
A `deadline_exceeded` phase is also how a round-trip a transaction-mode pooler
(Supavisor port 6543, PgBouncer) never completed ends: the backend sits in
`ClientRead`, the cancel request the deadline sends may never reach it, so
`GBRAIN_CANCEL_SETTLE_MS` (default 2000) after the cancel the owner discards
that reserved connection, the statement settles client-side, and the next tick
runs. The connection end is not reported as `storage_error`; doctor's
`persistence_session_timeouts` names a transaction-mode URL, and the
session-mode URL of the same pooler (Supabase: port 5432) avoids the class.
`phase=preparation` lines name a write whose preparation ran past its budget:
`reason=deadline_exceeded` (the claim is released with `blocked_reason`
`preparation_deadline` and one attempt is counted; the budget is
`persistence.sync_preparation_ms` for a managed sync member,
`persistence.maintenance_preparation_ms` for every other managed kind and 30 s
for `remember`, `put_page` and `edit_page`), `reason=preparation_stalled` (the
request reached `persistence.max_preparation_attempts` and was finished
`failed` instead of being claimed again) and `reason=ceiling_exceeded` (the
preparation ignored cancellation past `persistence.preparation_ceiling_ms`; the
message names the step and what it waited on, and ends `restart_required` when
this process holds as many such preparations as it tolerates and has stopped
claiming). The runbook is
[catch-up stuck](guides/troubleshooting.md#catch-up-stuck). The
line is rate-limited (one per second, one per phase and code every 30 seconds).
An idle consumer keeps one ordinary-pool connection for its work probe and
never holds a direct or session-pooler connection, so a
`GBRAIN_DIRECT_DATABASE_URL` that points at a session pooler is not pinned by
idle `gbrain serve` processes.
**Claim phases.** Each claim renewal also records the claimed write's phase
(`preparing` or `publishing`); `gbrain sources writer status --json` shows it as
`claim` on running blockers, and doctor `persistence_write_stall` warns past
`persistence.max_claim_ms` (default 600000, 60000 to 86400000). A running
claim also carries the preparation `step`, how long it has been in it, what it
waits on (`git`, `fs`, `db`, `pool` or `unknown`) and the owner process (kind,
pid, gbrain version); past its budget, `claim.stall` reads
`preparation_overdue`. Each request counts the cut-offs of its preparation in
`persistence_requests.preparation_attempts`. See
[troubleshooting](guides/troubleshooting.md#persistence-write-stall).
## JSONB writes: never double-encode
Writing a JS value into a `jsonb` column has exactly two correct forms. Get this
wrong and the write succeeds on PGLite but stores a **jsonb string scalar** on
real Postgres — `col ->> 'k'` returns NULL, `jsonb_array_elements` throws, and a
`jsonb_typeof = 'array'` CHECK rejects the row (which aborts the sync that wrote it).
| Form | Verdict |
|---|---|
| Template tag: `` sql`... ${sql.json(obj)}` `` (postgres-engine only) | ✅ native jsonb serialization |
| Positional raw call, raw object: `executeRawJsonb(engine, sql, scalars, [obj])` | ✅ object reaches the wire as jsonb |
| engine-sql domain code: `` sqlFragment`... ${jsonbParam(obj)}` `` | ✅ bound as `sql.json` on Postgres, serialized for PGLite's native text→jsonb parse |
| Positional raw call, stringified: `executeRaw(\`... $N::text::jsonb\`, [JSON.stringify(x)])` | ✅ binds as text, the cast parses it |
| Positional raw call, BARE cast: `executeRaw(\`... $N::jsonb\`, [JSON.stringify(x)])` | ❌ **double-encodes** under postgres.js `.unsafe()` |
| Template literal interpolation: `` `... ${JSON.stringify(x)}::jsonb` `` | ❌ double-encodes |
**Why:** postgres.js `.unsafe(sql, params)` (the path behind `executeRaw` /
`executeRawDirect`) binds a JS **string** as a text param. A bare `$N::jsonb`
cast then wraps that already-JSON string into a jsonb scalar string instead of
parsing it. Casting through `$N::text::jsonb` forces a text→jsonb parse.
**PGLite's `db.query` parses text→jsonb natively, so it hides the bug** — which is
why the bug only shows up on Postgres (and why the parity test must run there).
**Two CI guards enforce this, both wired into `scripts/check-jsonb-pattern.sh`:**
- the template-tag grep (`${JSON.stringify(x)}::jsonb`), and
- `scripts/check-jsonb-params.mjs`, an AST-lite scanner for the positional
`$N::jsonb` + `JSON.stringify` form the grep misses. Sanctioned escapes:
`$N::text::jsonb`, `$N::text[]`, `executeRawJsonb`, `sql.json`, or an inline
`jsonb-guard-ok` comment.
The real backstop is `test/e2e/op-checkpoint-jsonb-parity.test.ts` +
`test/e2e/jsonb-roundtrip.test.ts`, which round-trip writes through real Postgres
and assert `jsonb_typeof` — the assertion PGLite cannot make.
## Adding a new engine
1. Create `src/core/-engine.ts` implementing `BrainEngine`
2. Add to engine factory in `src/core/engine-factory.ts`:
```typescript
export async function createEngine(config: EngineConfig): Promise {
switch (config.engine || 'postgres') {
case 'pglite': {
const { PGLiteEngine } = await import('./pglite-engine.ts');
return new PGLiteEngine();
}
case 'myengine': {
const { MyEngine } = await import('./my-engine.ts');
return new MyEngine();
}
// ...
}
}
```
The factory uses dynamic imports so an engine's dependencies (e.g. the
PGLite WASM blob) are only loaded when that engine is selected.
3. If the engine speaks the Postgres dialect, add a dialect adapter that
implements `SqlExecutor` (`src/core/engine-sql/executor.ts`) beside
`dialect-pglite.ts` and `dialect-postgres.ts`, expose it through a private
`engineSql` getter over the current connection, and delegate every method
of a migrated domain to `src/core/engine-sql/.ts` the way both
engines do. Declare its capabilities honestly. The binding matrix
(`test/helpers/executor-binding-matrix.ts`) and the engine-sql contract
tests tell you whether the adapter binds, counts, fails and cancels like the
others. A non-SQL engine implements every method itself.
4. Store engine type in `~/.gbrain/config.json`: `{ "engine": "myengine", ... }`
5. Add tests. The test suite should be engine-agnostic where possible... same test cases, different engine constructor.
6. Document in this file + add a design doc in `docs/`
### What you DON'T need to touch
- `src/cli.ts` (dispatches to engine, doesn't know which one)
- `src/mcp/server.ts` (same)
- `src/core/chunkers/*` (shared across engines)
- `src/core/embedding.ts` (shared across engines)
- `src/core/search/hybrid.ts` + `hybrid/`, `expansion.ts`, `dedup.ts` (shared, operate on SearchResult[])
- `src/core/engine-sql/.ts` (shared domain SQL, when your engine has a Postgres-dialect adapter)
- `skills/*` (fat markdown, engine-agnostic)
### What you DO need to implement
Every method in `BrainEngine`. The full interface. No optional methods, no feature flags. If your engine can't do vector search (e.g., a pure-text engine), implement `searchVector` to return `[]` and document the limitation.
## Capability matrix
| Capability | PostgresEngine | PGLiteEngine | Notes |
|-----------|---------------|-------------|-------|
| CRUD | Full | Full | Same SQL |
| Keyword search | tsvector + ts_rank | tsvector + ts_rank | Identical (real Postgres) |
| Vector search | pgvector HNSW | pgvector HNSW | Same operators; bounded fallback/cancellation differs |
| Fuzzy slug | pg_trgm | pg_trgm | Identical (real Postgres) |
| Graph traversal | Breadth-first recursive CTE (one row per layer) | Breadth-first recursive CTE (one row per layer) | Same SQL |
| Transactions | Full ACID | Full ACID | Both support this |
| JSONB queries | GIN index | GIN index | Identical |
| Concurrent access | Connection pooling | Single process | PGLite limitation |
| Hosting | Supabase, self-hosted, Docker | Local file | |
| Migration methods | runMigration, getChunksWithEmbeddings | Same | Identical |
## Future engine ideas
**TursoEngine.** libSQL (SQLite fork) with embedded replicas and HTTP edge access. Would give SQLite's simplicity with cloud sync. Interesting for mobile/edge use cases.
**DuckDBEngine.** Analytical workloads. Bulk exports, embedding analysis, brain-wide statistics. Not for OLTP. Could be a secondary engine for analytics alongside Postgres for operations.
**Custom/Remote.** The interface is clean enough that someone could build an engine backed by any storage: Firestore, DynamoDB, a REST API, even a flat file system. The interface doesn't assume SQL.
Note: there is no SQLite engine. PGLite uses the same SQL as Postgres, so no separate SQLite dialect with FTS5/sqlite-vss translation is needed.
---
### GBRAIN RECOMMENDED SCHEMA (`docs/GBRAIN_RECOMMENDED_SCHEMA.md`)
# Brain: The LLM-Maintained Knowledge Base
A system prompt for any AI agent that wants to build and maintain a personal knowledge base. This describes the pattern, the architecture, and the operational discipline that makes it work.
Drop this into your agent's workspace as a skill or system prompt. Your agent will build the rest.
> **Relationship to schema packs:** this document is the prose, paste-in
> version of the schema pattern. gbrain also ships a machine-enforced
> counterpart — schema packs (`gbrain schema`, typed pages, extraction,
> aliases, lint) — documented in `docs/architecture/schema-packs.md` and
> `docs/schema-author-tutorial.md`. The prose schema here and the active
> schema pack should describe the same brain; when you evolve one, evolve
> the other.
---
## What this is
A personal intelligence system where your AI agent builds and maintains an interlinked wiki of everything you know about your world — people, companies, deals, projects, meetings, ideas — as structured, cross-referenced markdown files. The agent writes and maintains all of it. You direct, curate, and think.
This is Karpathy's LLM wiki pattern, but extended from research notes into a full operational knowledge base — one that integrates with your calendar, email, meetings, social media, and contacts to stay continuously current.
The key insight: **knowledge management has failed for 30 years because maintenance falls on humans. LLM agents change the equation — they don't get bored, don't forget to update cross-references, and can touch 50 files in one pass.** Your wiki stays alive because the cost of maintenance is near zero.
## Three Founding Principles
### 1. Every Piece of Knowledge Has a Primary Home (MECE Directories)
Every piece of knowledge passes through a decision tree and lands in exactly one directory. No duplicated pages, no ambiguity about where something goes.
This is the single most important structural decision. Without it, knowledge bases rot — the same fact lives in three places with three different versions, nobody knows which is current, and the agent (or human) stops trusting the system. MECE directories with explicit resolver rules prevent this.
Every directory has a `README.md` (the resolver) that answers two questions:
1. **What goes here** — a positive definition with a concrete test
2. **What does NOT go here** — the key distinctions from neighboring directories that the agent might confuse
The brain also has a top-level `RESOLVER.md` — a numbered decision tree the agent walks when filing anything. When two directories seem to fit, disambiguation rules break the tie. When nothing fits, the item goes in `inbox/` — which is itself a signal the schema needs to evolve.
**The agent must read the resolver before creating any new page.** This is not optional.
**Important nuance: MECE applies to directories, not to reality.** Real people and entities are multi-faceted — a political founder can also be a friend, donor, media actor, and hiring candidate. The resolver picks the *primary home* for their page (people/), but the page itself uses typed backlinks and cross-references to surface all their facets. The MECE rule prevents duplicate pages, not duplicate relationships. Cross-references are how adjacency is preserved without breaking the one-page-per-entity rule.
### 2. Compiled Truth + Timeline (Two-Layer Pages)
Every brain page has two layers, separated by a horizontal rule (`---`):
**Above the line — Compiled Truth.** Always current, always rewritten when new information arrives. Starts with a one-paragraph executive summary. If you read only this, you know the state of play. Followed by structured State fields, Open Threads (active items — removed when resolved), and See Also (cross-links).
**Below the line — Timeline.** Append-only, never rewritten. Reverse-chronological evidence log. Each entry: date, source, what happened. When an open thread gets resolved, it moves here with its resolution.
If someone asks "what's the current state?" — read above the line. If someone asks "what happened?" — read below the line. The top is the current summary. The bottom is the source log.
This is the Karpathy wiki pattern's killer feature: **the synthesis is pre-computed.** Unlike RAG, where the LLM re-derives knowledge from scratch every query, your brain has already done the work. The cross-references are already there. The contradictions have already been flagged.
### 3. Enrichment Fires on Every Signal
Every time any signal touches a person or company — meeting, email, tweet, calendar event, contact sync, conversation mention — the enrichment pipeline fires. The brain grows as a side effect of normal operations, not as a separate task you remember to do.
This is what distinguishes an operational brain from Karpathy's research wiki. He describes ingesting sources you manually add. An operational brain goes further — every pipeline (meetings, email, social media, contacts) automatically triggers enrichment on every entity it touches. You never have to remember to update someone's page. The system does it because the plumbing is wired correctly.
## Wiring It Into Your Agent
The brain must be referenced in your agent's configuration (AGENTS.md or equivalent) as a hard rule, not a suggestion. Specifically:
1. **Before creating any brain page → read RESOLVER.md.** This should be in your agent's operational rules, not buried in documentation.
2. **Before answering any question about people, companies, deals, or strategy → search the brain first.** Even if the agent thinks it knows the answer. File contents are current; the agent's memory of them goes stale.
3. **The enrich skill fires on every signal.** Every ingest pathway — meeting processing, email triage, social monitoring, contact sync — should call the enrichment pipeline when it encounters a person or company. This is wiring, not discipline. If it depends on the agent remembering, it will eventually be forgotten.
4. **Corrections are the highest-value data.** If the user corrects the agent about a person, company, deal, or decision — it gets written to the brain immediately. No batching, no deferring.
The chain of authority: **Agent config (AGENTS.md) says "read RESOLVER.md" → RESOLVER.md is the decision tree → each directory README.md is the local resolver → schema.md defines page structure → the enrich skill defines the enrichment protocol.**
## Architecture
Three layers:
**Raw sources** — meeting transcripts, emails, tweets, web research, API responses, calendar events, contact data. Immutable. The agent reads from these but never modifies them. Stored in `sources/` and `.raw/` sidecar directories.
**The brain** — a directory of interlinked markdown files. People pages, company pages, deal pages, meeting pages, project pages, concept pages. The agent owns this layer entirely. It creates pages, updates them when new information arrives, maintains cross-references, and keeps everything consistent. You read it; the agent writes it.
**The schema** — a document (this one, plus `schema.md` and `RESOLVER.md`) that tells the agent how the brain is structured, what the conventions are, and what workflows to follow. This is the key configuration file — it makes your agent a disciplined knowledge maintainer rather than a generic chatbot.
## The Database + Markdown Architecture
The markdown wiki is the human-facing layer — the primary interface for humans and LLMs. But it's not the sole source of truth. A structured database layer provides the foundation, and the markdown is generated from it.
### The Four Database Primitives
**Entity registry** — canonical ID, all aliases, all external IDs (LinkedIn member ID, X user ID, email addresses, phone numbers) in one table. This is the single source of truth for "is this the same person?" When you merge two entities, it's a database operation (point both IDs at the same canonical record), not a file-merge operation with cross-reference fixups.
**Event ledger** — every signal that touches the brain is an immutable event: meeting attended, email received, tweet published, enrichment completed, user correction applied. Events have provenance: source, timestamp, confidence, raw payload reference. The timeline section of markdown pages is generated from this ledger. You never lose events because a page rewrite went wrong.
**Fact store** — structured claims with provenance. "Jane Doe is CTO of Acme" with `source=crustdata, confidence=high, observed_at=2026-04-07`. When two sources disagree (LinkedIn says CTO, company website says VP Engineering), the conflict is visible as two facts for the same field with different values. The compiled truth section above the line is generated from the fact store's latest-confident values. Contradictions become data, not bugs.
**Relationship graph** — typed edges between entities. Person→Company (role: CTO, started: 2024-01), Person→Person (relationship: co-founded company together), Company→Deal (type: Series A, date: 2025-03). Enables graph queries that markdown grep can't answer: "who do I know who's invested in AI infrastructure companies?" becomes a traversal, not a prayer.
### Why This Matters
- **Identity resolution** becomes a database operation (merge entity IDs), not a file-merge operation with manual cross-reference fixups
- **Contradictions are structural** (two facts with different values for the same field and different sources) rather than textual (hoping the LLM notices a discrepancy buried in prose)
- **Concurrency is solved** — events append to a ledger, facts upsert to a store, markdown is rebuilt. No more merge conflicts on shared files
- **Graph queries work** — "who do I know at this company?" and "what companies has this investor backed that I also know the founders of?" become database queries, not impossible grep chains
### File-Layer Conventions
The markdown layer uses conventions that map directly to the database primitives:
1. **Use frontmatter for structured metadata** — anything you'd want to filter on (role, company, stage, score, tags) goes in YAML frontmatter, not buried in prose. Frontmatter is metadata for filters and schema-pack rules: it is not written to the fact store, and `gbrain search` / `query` do not index scalar frontmatter values (only the page body is chunked). If a value must be findable by search, also state it in the body, for example `Stage: negotiation` (#5335).
2. **Use `.raw/` for provenance** — save every API response with source and timestamp. These map to provenance records in the fact store.
3. **Treat the timeline as an event stream** — dated, sourced, append-only. These map to the event ledger.
4. **Keep compiled truth conceptually separate from evidence** — above the line is synthesis; below the line is evidence. The synthesis is a generated view; the evidence is queryable records.
5. **Use canonical slugs consistently** — every cross-reference uses the filename slug. These are the entity IDs in the registry.
## Directory Structure
```
/* Detailed source-code truncated for AI context efficiency. */
```
Every directory has a README.md resolver. Adapt directories to your life — add or remove domains as needed. Not everyone needs civic/ or hiring/ or household/. The invariant is: **one directory per knowledge domain, one file per entity, every directory has a resolver, and RESOLVER.md is the master decision tree that guarantees MECE filing.**
## Entity Identity and Deduplication
In a system fed by meetings, email, social media, contacts, and APIs, **entity identity is the first real failure mode.** Without a canonical identity layer, you will end up with subtle split-brain pages — "Jane Smith" from a meeting transcript and "J. Smith" from an email and "jsmith" from Twitter all creating separate pages for the same person.
### Canonical slugs
Every entity gets a canonical slug that serves as its stable ID:
- People: `first-last.md` (all lowercase, hyphens for spaces)
- Companies: `company-name.md`
- If collisions arise, disambiguate: `david-liu-crustdata.md`, `david-liu-meta.md`
The filename IS the identity. All references, cross-links, and .raw/ sidecars use this slug.
### Aliases
People have many names across sources. The frontmatter `aliases` field captures all known variants:
```yaml
aliases: ["Jenny Shao", "Jenny G. Shao", "JennyGShao", "jennifer.shao@company.com"]
```
Aliases include: misspellings from meeting transcripts, maiden names, nicknames, email addresses, social handles, and phonetic variants. When the enrich skill encounters a new name variant for a known entity, it adds the variant to aliases — it does NOT create a new page.
Phone numbers are not aliases. A connector-rendered person page (Google Contacts) carries them under `phones:` in E.164 form, as exact identifiers for a deliberate `entity_identity_link` join; a digit string in `aliases` would match mentions it has nothing to do with.
### Deduplication protocol
Before creating any new page, the agent must:
1. Search existing pages by name (exact and fuzzy)
2. Search aliases across all pages: `grep -rl "NAME_VARIANT" /data/brain/people/ --include="*.md"`
3. Check .raw/ sidecars for matching email addresses or social handles
4. If a match is found → UPDATE the existing page (add alias if the name variant is new)
5. If no match → CREATE a new page
### Merge protocol
When you discover two pages are the same person:
1. Pick the more complete page as the survivor
2. Merge all timeline entries from the duplicate into the survivor (chronological order)
3. Merge all aliases
4. Update all cross-references that pointed to the duplicate
5. Delete the duplicate
6. Commit with message: `merge: [duplicate] into [survivor]`
During weekly lint, actively look for potential duplicates: similar names, same company, same email across different pages.
## Key Disambiguation Rules
The most common filing confusions and how to resolve them:
- **Concept vs. Idea:** Could you *teach* it as a framework? → concept. Could you *build* it? → idea.
- **Concept vs. Personal:** Would you share it in a professional talk? → concept. Is it private reflection? → personal.
- **Idea vs. Project:** Is anyone working on it? Yes → project. No → idea. The graduation moment is when work starts.
- **Writing vs. Media:** Writing is the *artifact* (the essay). Media is the *production and distribution infrastructure* (content pipeline, social monitoring).
- **Writing vs. Concepts:** A concept page is distilled (200 words of compiled truth). An essay is developed prose (argument, narrative, story).
- **Person vs. Company:** Is it about *them as a human*? → people/. Is it about *the organization*? → companies/. Both pages link to each other.
- **Household vs. Personal:** Would a PA execute on it? → household (operational). Is it private reflection? → personal.
- **Sources vs. .raw/ sidecars:** Per-entity enrichment data → .raw/ sidecar. Bulk multi-entity imports → sources/.
When nothing fits, file in inbox/ and flag it. That's a signal the schema needs to evolve.
## Page Types and Templates
### Person
The most important page type. A great person page is a well-researched briefing — not a LinkedIn scrape.
```
/* Detailed source-code truncated for AI context efficiency. */
```
The timeline row grammar is `- **YYYY-MM-DD** | Source — Summary`. The
`Source — Summary` delimiter is a dash with a space on each side: the em dash
(`—`), the en dash (`–`) and the plain hyphen (` - `) are all accepted, so a
house style that never types an em dash writes
`- **2026-01-03** | Meeting - Agreed on the Q2 plan` and gets `source: Meeting`.
A colon is not a delimiter: `- **2026-01-02** | Meeting: Agreed on the Q2 plan`
still parses as a dated entry, but its source is recorded as `markdown` and the
whole `Meeting: Agreed on the Q2 plan` text is the summary, because `Note: …`
and `TODO: …` are ordinary prose. gbrain's own writers (`add_timeline_entry`,
the extractors) keep writing the em dash.
All sections are optional — include what you have, leave empty sections as `[No data yet]` rather than omitting them. **The structure itself is a prompt for future enrichment.** When a section says `[No data yet]`, the agent knows what to look for next time it encounters this person.
The principle: facts are table stakes. Context is the value.
### Epistemic discipline on people pages
The context sections (Beliefs, Motivations, Communication Style, Assessment) are the highest-value parts of the system but also the most prone to hallucination. An agent can over-generalize from sparse evidence or overfit to one recent interaction. Rules:
- **Every claim cites its source.** Not "she's aggressive" but "she pushed back hard on pricing in the March 15 meeting (observed)."
- **Three source types:** `observed` (you saw it happen), `self-described` (they said it about themselves), `inferred` (you're reading between lines). Label each.
- **Confidence tracks interaction count.** One meeting = low confidence. Five meetings = high. Don't write definitive assessments from thin data.
- **Recency matters.** A belief from 2 years ago may not be current. Mark dates.
- **Never generalize from a single data point.** "She seemed frustrated in one meeting" is a timeline entry. Patterns require multiple observations.
- **The user's corrections override everything.** If the user says "that's wrong about her," update immediately — that correction is the highest-confidence signal in the system.
### Company
```markdown
# Company Name
> What they do, stage, why they matter.
## State
- **What:** One-line description
- **Stage:** Seed / Series A / Growth / Public
- **Key people:** Names with links to people pages
- **Key metrics:** Revenue, headcount, funding
- **Connection:** How they relate to your world
## Open Threads
---
## Timeline
```
### Meeting
```markdown
# Meeting Title
> YOUR analysis — not a copy of the AI meeting notes.
> What matters given everything else going on.
> What was decided. What was left unsaid.
## Attendees
## Key Decisions
## Action Items
## Connections to other brain pages
---
## Full Transcript
```
### Deal, Project, Concept — same pattern. Compiled truth on top, timeline on bottom.
## The Enrichment Pipeline
**This is the most important operational pattern.** Every time your agent encounters a person or company — in a meeting, email, tweet, calendar event, contact sync — it should enrich the corresponding brain page.
Enrichment is not just "look up their LinkedIn." It's:
- **What they believe** — positions, worldview, public stances
- **What they're building** — current projects, what's shipping
- **What motivates them** — ambition, career trajectory
- **Their communication style** — how they engage, what energizes them
- **Their relationship to you** — history, context, open threads
- **Hard facts** — role, company, contact info, funding (table stakes)
Facts are table stakes. Context is the value.
### When to enrich
**Any time** a person or company signal appears:
- Someone is mentioned in a meeting transcript → enrich
- Someone emails you → enrich
- Someone interacts with you on social media → enrich
- A new contact appears → enrich
- You mention someone in conversation and their page is thin → enrich
- A company announces funding, ships a product, makes news → enrich
### Enrichment sources (in order of value)
1. **Your own interactions** — what you said about them, what they said to you (highest signal)
2. **Meeting transcripts** — richest context source
3. **Email threads** — tone, urgency, relationship dynamics
4. **Social media** — beliefs, public positioning, who they engage with
5. **Web search** — background, press, talks
6. **People APIs** — structured profile data (career history, education, skills, contact info)
7. **Company APIs** — funding, investors, valuations, headcount, financials
8. **Contact data** — email, phone, location
### Data source skills
Each external data source should be its own named skill with full API documentation, auth patterns, and usage notes. The enrich skill orchestrates them — it decides *which* sources to call based on tier, then delegates to the individual skill for *how* to call the API.
This keeps things DRY: the enrich skill owns the logic (when to enrich, what tier, what to extract), and each data source skill owns the API contract (endpoints, auth, rate limits, gotchas, validation rules).
Recommended data source skills:
- **Web search** — broad keyword search (Brave, Google, etc.). Quick background, press, funding.
- **Semantic search** — better than keyword for finding specific people, LinkedIn URLs, personal writing. (Exa, Perplexity, etc.)
- **Social search** — X/Twitter, Bluesky, etc. for public voice: beliefs, projects, engagement patterns.
- **People enrichment** — structured LinkedIn-like data: career history, education, skills, contact info. (Crustdata, Proxycurl, People Data Labs, etc.)
- **Network search** — search your professional network for warm intros and connections. (Happenstance, Clay, etc.)
- **Company intelligence** — Pitchbook-grade data: funding rounds, investors, valuations, headcount, financials. (Captain API, Crunchbase, etc.)
- **Meeting history** — search past meetings for interactions with this entity. (Circleback, Otter, Fireflies, etc.)
- **Contact data** — email, phone, location from your contacts. (Google Contacts, etc.)
The typical enrichment flow for a new person:
1. **Network search** → find LinkedIn URL, career arc, alternate names
2. **People enrichment** → deep structured data (skills, work history, education, contact info)
3. **Semantic search** → find personal sites, talks, writing that reveal beliefs and perspective
4. **Social search** → their public voice, who they engage with, hobby horses
5. **Web search** → press coverage, recent news, talks
6. **Meeting history** → past interactions with you
For a new company:
1. **Company intelligence** → funding, investors, headcount, financials
2. **Web search** → product, press, traction
3. **Social search** → company's public positioning
4. **People enrichment** → enrich founders/key team members (each triggers person enrichment)
### Enrichment tiers (don't over-enrich)
- **Tier 1 (key people):** Full pipeline — all sources. Inner circle, business partners, important collaborators.
- **Tier 2 (notable):** Web search + social + brain cross-reference. People you interact with occasionally.
- **Tier 3 (minor mentions):** Extract signal from source only, append to timeline. Everyone else worth tracking.
A thin page with real interaction data is better than a fat page stuffed with generic web results. Don't waste 10 API calls on someone with no public presence.
### Raw data sidecars
Every enrichment API response gets saved as a JSON sidecar:
```
people/jane-doe.md ← brain page (curated, readable)
people/.raw/jane-doe.json ← raw API responses
```
The JSON is keyed by source with fetch timestamps:
```json
{
"sources": {
"crustdata": { "fetched_at": "2026-04-05T...", "data": { ... } },
"web_search": { "fetched_at": "...", "data": { ... } }
}
}
```
The brain page is the distilled version. Raw data is the archive.
What goes in the brain page (distilled): location, current title, company, headline, education (one line), career arc (condensed), top skills, social handles, profile picture permalink.
What stays in .raw/ only: full work history with job descriptions, complete skill lists, company descriptions for each employer, platform-specific IDs, follower/connection counts, full API response bodies.
When re-enriching: overwrite the source key with fresh data + new timestamp. Don't append — replace.
### Validation rules
When auto-enriching from people/company APIs:
- **Low connection/follower count (e.g., <20):** Likely wrong person. Save to .raw/ with a `"validation": "low_connections"` flag. Don't auto-write to the brain page.
- **Name mismatch:** If the returned name doesn't share a last name with the entity, skip.
- **Obviously joke profiles:** Career arcs mentioning absurd titles — skip.
- **When in doubt:** Save raw data but don't update the brain page. Wrong data is worse than no data.
### Browser budget
If enrichment involves browser-based lookups (LinkedIn, authenticated pages), set a daily budget (e.g., 20 lookups/day) to avoid account flagging. Prefer API-based enrichment services for bulk work — they don't touch the user's browser session.
## Entry Criteria — Who Gets a Page
Not everyone deserves a brain page. Scale page creation to relationship importance:
**Always create a page for:**
- Anyone you've had a 1:1 or small-group meeting with
- Key colleagues, partners, and direct collaborators
- Anyone with a strong working relationship or better
- Family, close friends, inner circle
**Create if signal exists:**
- People from contacts with recent interaction
- Anyone mentioned by name in conversation with context
- Event contacts with multiple shared events
**Do NOT create:**
- Random names from mass event guest lists with no interaction
- Single-name entries with no identifying context
- Contacts with no relationship signal at all
When in doubt: does the user benefit from this entry existing? If no, skip it.
## The Skill Architecture
Skills are the modular building blocks of the system. There are three types, and understanding how they compose is critical.
### 1. Data source skills (leaf nodes)
Each external API or data source gets its own named skill. The skill owns the API contract: endpoints, authentication, rate limits, error handling, validation rules, and what the response looks like.
Examples:
- **People enrichment** (Crustdata, Proxycurl, People Data Labs) — structured LinkedIn-like data
- **Network search** (Happenstance, Clay) — search professional network, find mutual connections
- **Company intelligence** (Captain API/Pitchbook, Crunchbase) — funding, investors, financials
- **Semantic search** (Exa, Perplexity) — find LinkedIn URLs, personal sites, writing
- **Meeting history** (Circleback, Otter, Fireflies) — past meeting transcripts and notes
- **Calendar/contacts** (Google Calendar, Google Contacts via integration tools) — schedule, contact info
- **Social media** (X API, Bluesky API) — public posts, engagement, follower data
- **Workspace tools** (Gmail, Slack, Drive via integration tools) — email threads, messages, documents
Data source skills are **never called directly by the user.** They're called by orchestration skills (below).
### 2. Orchestration skills (coordinators)
These skills contain the *logic* — they decide what to do, then delegate to data source skills for how to do it.
**The enrich skill** is the most important orchestration skill. It decides:
- Is this a CREATE (new page) or UPDATE (new signal)?
- What tier is this entity? (determines which data sources to call)
- What signal types to extract from the source material?
- Which data source skills to call, in what order?
- How to write the results to the brain?
Other orchestration skills:
- **Meeting ingestion** — pulls meetings from a meeting tool, creates brain meeting pages with analysis, then calls enrich for every attendee and company discussed
- **Email triage / executive assistant** — processes inbox, handles scheduling, then calls enrich when it encounters people or companies
- **Social monitoring** — scans public social media for mentions and engagement, then calls enrich for notable accounts
### 3. Pipeline skills (end-to-end workflows)
These are the user-facing skills that chain multiple orchestration and data source skills together:
- **Morning briefing** — reads calendar + tasks + brain state + recent signals → produces a briefing
- **Person research** — given a name, runs full Tier 1 enrichment and presents the result
- **Weekly brain maintenance** — runs lint, flags stale pages, suggests enrichment targets
### How they compose
```
User says "tell me about Jane Doe"
→ Agent searches brain (grep/index)
→ Page is thin → calls enrich skill (orchestration)
→ enrich determines Tier 1
→ calls happenstance skill (data source) → gets LinkedIn URL
→ calls crustdata skill (data source) → gets full profile
→ calls exa skill (data source) → finds personal writing
→ calls web_search (built-in tool) → gets press coverage
→ calls meeting history (data source) → finds past meetings
→ writes brain page, saves .raw/ sidecar, cross-references
→ Agent presents the enriched page to user
```
```
Cron fires "meeting ingestion" every afternoon
→ meeting-ingestion skill (orchestration) pulls new meetings
→ for each meeting: creates brain meeting page
→ for each attendee: calls enrich skill (orchestration)
→ enrich calls relevant data source skills based on tier
→ for each company discussed: calls enrich skill
→ extracts tasks, commits brain repo
```
The key insight: **data source skills are stateless and reusable.** The enrich skill can call Crustdata whether the trigger was a meeting, an email, a social mention, or a direct user request. The data source skill doesn't care where the request came from.
## How Enrich Wires Into Everything
The enrich skill is the central hub. Every ingest pathway converges on it:
```
Meeting ingestion ───────┬─────────────────────────┬─── people enrichment API
Email triage ────────────┤ ├─── company intelligence API
Social monitoring ───────┤ ENRICH SKILL ├─── network search API
Contact sync ────────────┤ (orchestration) ├─── semantic search API
Manual conversation ─────┤ ├─── social search API
Calendar events ─────────┤ ├─── web search
Webhooks ────────────────┴─────────────────────────┴─── meeting history API
│
▼
BRAIN REPO
(people/, companies/,
meetings/, deals/)
```
Every arrow into the enrich skill carries a **signal** (the raw information from the source) and an **entity** (the person or company to enrich). The enrich skill:
1. **Checks brain state** — does a page exist? Is it thin?
2. **Determines tier** — Tier 1 (full pipeline), Tier 2 (web + social + cross-ref), Tier 3 (source extraction only)
3. **Extracts signal** from the source material (beliefs, motivations, trajectory, facts)
4. **Calls data source skills** based on tier (each skill is a named, documented module)
5. **Writes to brain** — CREATE (via RESOLVER.md) or UPDATE (append timeline, update compiled truth)
6. **Cross-references** — updates all linked entity pages
7. **Saves raw data** to `.raw/` sidecar
8. **Commits** to the brain repo
The critical wiring rule: **every ingest skill must call enrich.** This is not optional or aspirational. It's structural. If a new ingest pathway is added (say, a Slack monitoring skill), its implementation must include "for each person/company mentioned, call the enrich skill." If that line is missing, the brain stops compounding from that source.
## Automated Cron Jobs
The brain doesn't just grow when you're actively using it. Cron jobs make the system autonomous — the brain is maintained, the inbox is triaged, meetings are ingested, and mentions are monitored even while you sleep.
### The cron architecture
Cron jobs run as **isolated agent sessions** — they get their own context, read their own skills, and don't block the main conversation thread. They can post to specific notification channels (Telegram topics, Slack channels, Discord threads) or work silently.
Each cron job is essentially: "wake up, read a skill, do the work, post results (or stay silent if nothing happened), go back to sleep."
### Recommended cron jobs for a brain-powered system
**High frequency (every 10-30 minutes):**
- **Email monitor** — scan inbox, classify by priority, post digest to a notification channel. Handle low-risk items (scheduling, acknowledgments) directly.
- **Message monitor** — check key communication channels for unreplied messages from important contacts. Surface them with suggested responses.
**Medium frequency (every 1-3 hours):**
- **Social radar** — scan public social media for mentions of you or your organization, engagement, emerging narratives. Alert on items that need attention. Call enrich for notable new accounts engaging with you.
- **Heartbeat** — the omnibus check. Calendar lookahead, task review, email scan, brain state review. Post if something needs attention; stay silent if not.
**Daily:**
- **Morning briefing** — calendar + tasks + urgent items + overnight signals → one notification. The "here's your day" message.
- **Task prep** — archive yesterday's completed tasks, build today's list from calendar + backlog + recurring items.
- **Meeting ingestion** — pull all new meetings from your meeting tool, run full ingestion (create meeting pages, propagate to entity pages, extract tasks). This is the heaviest cron job — it touches the most brain pages.
- **Social media collection** — archive your own posts, track engagement velocity, detect deletions. Feed into media/ pages.
**Weekly:**
- **Brain lint** — run the full maintenance pass: contradictions, stale pages, orphans, missing cross-references, MECE filing violations. Post a report.
- **Enrichment sweep** — find brain pages that haven't been enriched in 90+ days, or pages with many `[No data yet]` sections. Queue them for re-enrichment.
- **Contact sync** — pull recent additions from your contacts, cross-reference with brain. Create pages for significant new contacts.
### How crons feed the brain
The key insight: **cron jobs are the autonomous enrichment engine.** Without them, the brain only grows when you're actively talking to the agent. With them:
- The email monitor encounters a person → calls enrich → brain grows
- The meeting ingestion processes a transcript → calls enrich for every attendee → brain grows
- The social radar detects a new notable account → calls enrich → brain grows
- The contact sync finds a new contact → calls enrich → brain grows
- The enrichment sweep finds stale pages → calls enrich with fresh data → brain stays current
The brain compounds 24/7 because the cron jobs are wired to call enrich. The user sleeps; the brain doesn't.
### Cron job design rules
1. **Silent when nothing happens.** If a cron finds nothing new, it should produce no output. No "nothing to report" messages. This is critical — noisy crons get disabled.
2. **Post to specific channels.** Each cron posts to its designated notification channel (e.g., email cron → Emails topic, social radar → Social Alerts topic). Don't mix signals.
3. **Spawn sub-agents for heavy work.** The cron session should stay lightweight. If meeting ingestion needs to process 5 meetings and update 30 entity pages, spawn sub-agents for the entity propagation.
4. **Idempotent and checkpoint-aware.** Every cron should track what it's already processed (in a state file like `meeting-notes-state.json`) so it doesn't redo work on the next run.
5. **Respect quiet hours.** Don't post between 11 PM and 7 AM unless something is genuinely urgent. Crons should check the time before posting.
6. **Every ingest cron must call enrich.** This is the structural rule. A cron that processes meetings but doesn't enrich attendees is a bug, not a feature.
### Example: how it all fits together
A typical afternoon in an autonomous brain system:
1. **3:00 PM** — Email monitor cron fires. Scans inbox. Finds 3 new emails: a scheduling request, a funding announcement, and a founder asking for advice.
- Handles the scheduling request directly (checks calendar, replies with available times)
- Calls enrich on the company in the funding announcement → updates company page with new round
- Posts the founder's email to notification channel for the user to handle
2. **3:15 PM** — Meeting ingestion cron fires. Finds 2 new meetings from today.
- Creates 2 brain meeting pages with analysis
- Calls enrich for 8 attendees across both meetings → updates 8 people pages
- Calls enrich for 3 companies discussed → updates 3 company pages
- Extracts 4 action items → adds to task list
3. **3:30 PM** — Social radar cron fires. Detects a journalist writing a thread about the user's organization.
- Posts alert to Social Alerts channel
- Calls enrich on the journalist → creates/updates their people page with recent activity
4. **4:00 PM** — Heartbeat fires. Calendar shows a meeting in 1 hour. Brain page for the attendee was last enriched 3 months ago.
- Triggers a fresh enrichment pass on the attendee
- Posts a prep note: "Meeting with X in 1 hour. Here's what's changed since you last met."
The user didn't ask for any of this. The brain grew by 12 pages and the user walked into their 4:00 PM meeting fully prepared — because the plumbing is wired correctly.
## Worked Examples From a Production System
These examples show how the architecture operates end-to-end. Names and specifics are genericized, but the skill chains are exact — every skill call, every file write, every cron trigger is how it actually works.
### Example 1: Meeting Ingestion — The Full Chain
A cron job fires at 3:00 PM daily with the prompt: "Read skills/meeting-ingestion/SKILL.md and process today's meetings."
**Step 1: Skill chain loads.** The meeting-ingestion skill's preamble says "Read skills/enrich/SKILL.md" — so the agent loads the enrichment protocol before touching any data. This is critical: it means the agent knows how to handle every person and company it encounters.
**Step 2: Pull new meetings.** The agent calls the meeting history data source skill (in this system, Circleback). It checks a state file (`memory/meeting-notes-state.json`) that tracks the last processed meeting ID. Finds 2 new meetings since last run.
**Step 3: Process Meeting 1 — "Product Review with Sarah Chen and Mike Torres."**
The agent creates `brain/meetings/2026-04-07-product-review.md` with:
- Its own analysis above the line (not a copy of the AI summary — reframed through what the brain already knows about the attendees and the project)
- Key decisions, action items, and connections to other brain pages
- Full transcript below the line
**Step 4: Enrich attendees.**
For **Sarah Chen** — the agent searches the brain: `grep -rl "Sarah Chen" /data/brain/people/`. Finds `people/sarah-chen.md`. Reads it. Page was last enriched 2 weeks ago and has good coverage. → **Tier 3**: extract signal from this meeting only. Appends to her timeline: "2026-04-07 | Meeting — Pushed back on timeline for launch, wants more QA. Concerned about API stability." Updates her Open Threads with the new follow-up item.
For **Mike Torres** — brain search finds `people/mike-torres.md`. Page exists but is thin: just a name, title, and one previous meeting entry. → **Tier 2**: web search + social + brain cross-reference. Agent finds his recent blog posts (feeds into What They Believe), his X activity (feeds into Hobby Horses), and cross-references him with two other brain pages that mention him. Updates compiled truth above the line.
For **"Alex from Meridian Labs"** (mentioned in the meeting but not an attendee) — brain search finds nothing. → **CREATE path**:
1. Reads RESOLVER.md: "a specific named person" → `people/`
2. Creates `people/alex-rivera.md` using the person template from schema.md
3. Runs **Tier 1 enrichment** (full pipeline): network search → finds LinkedIn URL. People enrichment API → full structured profile. Semantic search → finds a conference talk. Web search → finds press coverage of Meridian Labs' recent funding.
4. Saves raw API responses to `people/.raw/alex-rivera.json`
5. Cross-references: updates `companies/meridian-labs.md` to link to Alex's page
**Step 5: Enrich companies discussed.** Meridian Labs was discussed extensively. Agent checks `companies/meridian-labs.md` — exists but funding data is 4 months stale. Calls company intelligence API → gets fresh round data. Updates the page.
**Step 6: Extract action items.** Finds 3 action items in the transcript → appends to `ops/tasks.md`.
**Step 7: Repeat for Meeting 2.** Same flow.
**Step 8: Commit and notify.**
```bash
cd /data/brain && scripts/brain-commit-push.sh "meetings: 2026-04-07 product review, investor sync" \
meetings/ people/alex-rivera.md people/.raw/alex-rivera.json companies/meridian-labs.md ops/tasks.md
```
The helper commits only the files this run touched and pushes; on a non-zero
exit the agent stops and reports the error code instead of posting the
summary ([outcomes](guides/shared-checkout-git.md#outcomes)).
Posts summary to the Meetings notification channel: "Processed 2 meetings. Created 1 new person page (Alex Rivera). Updated 4 entity pages. 5 action items extracted."
**Files touched in this run:**
```
brain/
├── meetings/
│ ├── 2026-04-07-product-review.md (CREATED)
│ └── 2026-04-07-investor-sync.md (CREATED)
├── people/
│ ├── sarah-chen.md (UPDATED — timeline + open threads)
│ ├── mike-torres.md (UPDATED — Tier 2 enrichment)
│ ├── alex-rivera.md (CREATED — Tier 1 enrichment)
│ └── .raw/
│ └── alex-rivera.json (CREATED — raw API responses)
├── companies/
│ └── meridian-labs.md (UPDATED — fresh funding data)
ops/
└── tasks.md (UPDATED — 5 new action items)
memory/
└── meeting-notes-state.json (UPDATED — checkpoint)
```
### Example 2: Email Triage — Resolver + Enrichment in Action
An email monitor cron fires at 12:00 PM. Its prompt: "Read skills/executive-assistant/SKILL.md and skills/gmail/SKILL.md. Triage the inbox."
**Step 1: Pull inbox.** The agent calls the Gmail data source skill via its workspace integration. Gets 8 new emails since last check.
**Step 2: Classify and handle.** Most emails are routine: 2 scheduling confirmations (handled directly — checks calendar, sends confirmations), 3 newsletters (archived), 1 internal FYI (noted). But one stands out:
**An email from "David Park, GP at Ridgeline Ventures"** — subject: "Series A for NovaTech — co-invest opportunity." The agent has never seen this person before.
**Step 3: Enrich the unknown sender.**
The agent calls the enrich skill. Enrich searches the brain:
```bash
grep -rl "David Park" /data/brain/people/ --include="*.md" # no results
grep -rl "Ridgeline" /data/brain/companies/ --include="*.md" # no results
grep -rl "david.park@ridgeline" /data/brain/people/ --include="*.md" # no results (alias search)
```
No match. → **CREATE path.**
1. Reads RESOLVER.md: "a specific named person" → `people/`
2. Runs **Tier 2 enrichment** (this is an unsolicited email, not a key relationship yet):
- Web search: finds David Park's profile on Ridgeline's website. GP, focuses on enterprise SaaS. Previously at two other funds.
- Social search: finds his X account. Recent posts about AI infrastructure, developer tools. Reposted an article about NovaTech last week.
- Brain cross-reference: searches for NovaTech → finds `companies/novatech.md` exists (from a meeting 2 months ago). Cross-links.
3. Creates `people/david-park.md` with what it found — role, fund, investment focus, public voice, connection to NovaTech.
4. Also checks `companies/ridgeline-ventures.md` — doesn't exist. Creates a thin page with what's known from the web search.
**Step 4: Back in the EA skill.** Now the agent has context. It classifies the email:
- Priority: Medium (co-invest opportunity, not urgent)
- Context: David Park is a GP at a fund that focuses on enterprise SaaS. NovaTech is already in the brain from a previous meeting.
- Action needed: User should review
Posts to the Emails notification channel:
> **Co-invest opportunity — NovaTech Series A**
> From: David Park, GP at Ridgeline Ventures
> He's reaching out about co-investing in NovaTech's Series A. Ridgeline focuses on enterprise SaaS.
> NovaTech is already in the brain — you met their founder in February.
> [Open in Gmail](link)
**The email monitor didn't just triage — it grew the brain by two pages** (one person, one company) and cross-linked them to an existing entity.
### Example 3: The Compound Effect — How Context Builds Before a Meeting
This example shows how a completely unknown person becomes a rich brain page across 4 autonomous cron runs over 48 hours, with zero manual intervention. The result: you walk into a meeting fully prepared.
**Hour 0 — Social radar cron (Tuesday, 3:00 PM)**
The social radar cron scans for mentions and engagement on X. It detects a reply to one of the user's posts from an account named `@lena_builds` — a thoughtful, technical response about developer tooling that got 50+ likes.
The agent calls enrich. Brain search: no match for "Lena" or "lena_builds." → **CREATE, Tier 3** (minor mention — just a social interaction, not a relationship yet).
Creates `people/lena-kovac.md` with minimal data: X handle, display name, the reply text, and a note that she seems technical. No API calls — Tier 3 is source-extraction only.
```markdown
# Lena Kovac
> Technical builder. Engaged with a post about developer tooling on X.
## State
- **X:** @lena_builds
- **Relationship:** None yet — social interaction only
- **Confidence:** low (1 interaction)
---
## Timeline
- **2026-04-07** | X reply — Replied to post about developer tools.
Thoughtful technical take on compiler-driven UX. 50+ likes.
```
**Hour 18 — Email monitor cron (Wednesday, 9:00 AM)**
The morning email sweep finds an email from `lena@kovac.dev` — subject: "Loved your talk at the devtools summit — would love to chat about what we're building."
The agent calls enrich. Searches the brain:
```bash
grep -rl "lena" /data/brain/people/ --include="*.md" # finds people/lena-kovac.md
grep -rl "kovac.dev" /data/brain/people/ --include="*.md" # no alias match yet
```
Finds the existing page. Reads it — it's thin (Tier 3, just the X reply). The email adds a new signal AND an email address. → **Upgrade to Tier 2.**
- Adds `lena@kovac.dev` to aliases in frontmatter
- Web search: finds her personal site (`kovac.dev`) — she's building a developer tools startup called Lattice. Previously at a major tech company on their compiler team.
- Social search: deeper X dive. She posts regularly about developer experience, compilers, and Rust. Has 3K followers.
- Brain cross-reference: searches for "Lattice" and "compiler" — finds a concept page about developer tooling that links to 2 companies in the same space.
- Updates `people/lena-kovac.md` with real substance: career history, what she's building, what she believes about developer tooling, her public voice.
**Hour 26 — Executive assistant cron (Wednesday, 5:00 PM)**
The afternoon EA sweep processes scheduling requests. One of the emails it triages is Lena's — she asked to chat. The user's calendar is open Thursday at 2 PM.
But the EA skill also checks: is there a calendar event already scheduled with this person? It searches the calendar — finds that Lena's email (`lena@kovac.dev`) appears in a calendar event for Thursday at 2 PM (she booked through the user's public booking link).
The EA skill sees the meeting is tomorrow. Calls enrich again. Page exists and is now Tier 2 with decent coverage, but there's a meeting tomorrow. → **Upgrade to Tier 1.**
- Network search: finds her LinkedIn URL. She has 2 mutual connections with the user.
- People enrichment API: full structured profile — Stanford CS, 4 years at a major tech company, founded Lattice 8 months ago.
- Semantic search: finds a conference talk she gave on "Why Developer Tools Are Stuck in 2015."
- Saves everything to `people/.raw/lena-kovac.json`
- Updates the brain page with full Tier 1 depth: beliefs, trajectory, what she's building, assessment, network connections.
**Hour 40 — Morning briefing cron (Thursday, 7:30 AM)**
The morning briefing cron builds the daily prep. It reads the calendar: meeting with Lena Kovac at 2 PM. It reads `people/lena-kovac.md` — which is now a rich page.
Produces a prep note in the daily briefing:
> **2:00 PM — Lena Kovac (Lattice)**
> Building a developer tools startup focused on compiler-driven UX. Stanford CS, 4 years on compilers at [major tech co]. Founded Lattice 8 months ago.
> She replied to your devtools post on X last Tuesday (the technical one about compiler-driven UX that got traction). Then emailed the next morning — "loved your talk, want to chat about what we're building."
> Her public writing argues that developer tools are stuck in a 2015 paradigm and that compiler intelligence should drive the entire editing experience. She gave a talk on this at DevTools Summit.
> 2 mutual connections. She's technical, has founder energy, and is building in a space you care about.
**The compound effect:** Lena went from unknown → thin Tier 3 page → substantive Tier 2 page → rich Tier 1 page → meeting prep note. Four cron runs over 48 hours. Zero manual enrichment requests. The user walks into the meeting knowing exactly who Lena is, what she cares about, and why she reached out — because every pipeline is wired to call enrich, and enrich knows how to escalate tier based on relationship signals.
This is the core insight of the brain system: **knowledge compounds autonomously when the plumbing is wired correctly.** Each cron job doesn't just do its own job — it feeds the enrichment pipeline, which feeds every future cron job. The meeting ingestion cron creates pages that the morning briefing cron reads. The email monitor enriches people that the social radar first detected. The whole system is a flywheel.
## Ingest Workflows
These are the specific ingest patterns. Each one calls enrich as its terminal step.
### Meeting ingestion
After every meeting (via Circleback, Otter, Fireflies, or manual notes):
1. Pull meeting notes + full transcript
2. Create a brain meeting page with **your own analysis** (not just regurgitated AI summary) — reframe through what you know about the attendees' world
3. **Propagate to entity pages** — call enrich for every person and company discussed. A meeting is NOT fully ingested until entity pages are updated.
4. Extract action items to task list
5. Commit
### Email ingestion
When processing email:
- Extract people and companies mentioned
- Call enrich with email context (tone, requests, relationship signals)
- Note scheduling, commitments, follow-ups
### Social media ingestion
When monitoring social media:
- Capture what people you track are saying publicly (beliefs, projects, opinions)
- Detect engagement patterns (who's replying to you, who's amplifying you)
- Call enrich for notable accounts → feed into "What They Believe" and "Hobby Horses" sections
### Manual ingestion
When you mention someone or something in conversation:
- Your own comments are the highest-value signal — always capture these
- "Really sharp on the technical side, could be a good advisor for the infra project" → that goes in the person's page immediately
- If the brain page is thin, trigger a full enrichment
## Navigation and Concurrency
**index.md** — content catalog. Every page listed with a one-line summary. Useful for navigation and query routing.
**log.md** — chronological record of ingests and updates. Append-only.
At scale (500+ pages), add search tooling (embeddings, BM25, or tools like gbrain). At moderate scale, grep works well.
### Write hotspots and concurrency
Once you have cron jobs, ingest jobs, and sub-agents all touching the brain repo, **index.md and log.md become merge-conflict magnets.** Every workflow wants to append to log.md and update index.md on every commit.
Practical mitigations:
- **Treat index.md as derived, not hand-maintained.** Instead of updating it in every ingest workflow, rebuild it periodically (daily or on-demand) by scanning the directory tree. This eliminates it as a write hotspot.
- **Make log.md append-safe.** Each entry is a self-contained line with a timestamp prefix. Two machines that append to the end of the file at the same time do conflict; both sides are correct, so keep both lines (resolve with a merged copy: [conflicts](guides/shared-checkout-git.md#conflicts)).
- **Commit in batches, not per-page.** When an ingest job updates 10 entity pages, commit once at the end, not 10 times. This reduces conflict surface.
- **Commit and push through the shared-checkout helper.** Every workflow commits with `scripts/brain-commit-push.sh "" ` (or `gbrain git commit-push`), and pulls with its `--pull` mode. It takes one writer lock per checkout, commits only the named paths and merges remote commits in memory, so it never stashes or rebases files other workflows are writing. With an append-only log and independent entity pages, those merges almost always succeed ([shared-checkout git](guides/shared-checkout-git.md)).
- **Entity pages rarely conflict.** Two workflows updating `people/jane-doe.md` at the same time is rare because they're triggered by different signals about different people. The real conflict hotspots are the shared files (index.md, log.md), which is why those should be append-only or derived.
## Maintenance (Lint)
Periodically (weekly), the agent should:
- **Deduplication scan:** Look for potential duplicate pages — similar names, same company, same email across different pages. Merge when confirmed.
- **Contradictions:** Check for conflicting facts between pages (e.g., two pages listing different roles for the same person at the same company).
- **Staleness:** Flag State sections superseded by newer Timeline entries.
- **Orphans:** Find pages with no inbound links.
- **Open Threads:** Check for items that seem resolved but weren't moved to Timeline.
- **Missing cross-references:** Entity A mentions Entity B but doesn't link to their page.
- **Missing pages:** Entities mentioned frequently but lacking their own page.
- **MECE filing:** Flag any pages that seem to be in the wrong directory.
- **Source audit:** Check people pages for unsourced claims in high-value sections (Beliefs, Motivations, Assessment). Flag claims without source type or date.
- **Alias coverage:** Check if recent meeting transcripts or emails contain name variants not yet in any page's aliases field.
## What makes this different from RAG
RAG re-derives knowledge from scratch on every query. The brain pre-computes synthesis and keeps it current. Specifically:
- **Cross-references are pre-built.** You don't need the LLM to discover that Person A works at Company B and was in Meeting C — that's already linked.
- **Contradictions are pre-flagged.** When new data conflicts with old data, the agent resolves or flags it during ingest, not at query time.
- **The compilation is persistent.** Each source ingested makes the brain richer. Nothing is thrown away or re-derived.
- **The structure itself is a prompt.** Empty sections ("What They Believe: [No data yet]") tell the agent what to look for next.
## Page Lifecycle
Brain pages can have implicit lifecycle states:
- **Active:** Current, recently updated, ongoing relationship or relevance
- **Dormant:** Not updated in 6+ months, relationship cooled, but still potentially relevant
- **Archived:** Moved to `archive/` — dead companies, ended relationships, resolved deals. Historical record only.
- **Graduated:** For ideas that became projects, or projects that became programs — the old page links to the new one
During lint passes, flag pages that haven't been updated in 6+ months for review. Some should be archived; others just need a fresh enrichment pass.
## What makes a great brain
A great brain lets you walk into any meeting, call, or decision already knowing:
1. Who this person is and what they care about (30 seconds of reading)
2. What the company's actual state is (not what they said 6 months ago)
3. What open threads exist between you (promises, follow-ups, deals)
4. What changed recently (latest timeline entries)
5. What to watch for (patterns, concerns, opportunities)
A bad brain is a pile of LinkedIn scrapes and meeting transcripts nobody reads. A good brain is compiled context that makes you more effective in every interaction.
## The Resolver
When creating or filing a new page, walk this decision tree. Every piece of knowledge has exactly one home.
### Decision Tree
**Start here: what is the primary subject?**
1. **A specific named person** → `people/`
2. **A specific organization** (company, fund, nonprofit, government body) → `companies/`
3. **A financial transaction** with terms and a decision to make → `deals/`
4. **A record of a specific meeting/call** that happened at a specific time → `meetings/`
5. **Something being actively built** (has a repo, spec, team, or active work) → `projects/`
6. **A raw possibility** that nobody is building yet → `ideas/`
7. **A reusable mental model or thesis** about how the world works → `concepts/`
8. **A piece of prose** that could be published as a standalone work → `writing/`
9. **Your institution's strategy, org, processes, internal dynamics** → `org/`
10. **Political or civic landscape** — policy, legislation, elections, government → `civic/`
11. **Public narrative or content operations** — social monitoring, content pipeline, published posts → `media/`
12. **A major life program** — an enduring domain of commitment containing multiple projects → `programs/`
13. **Domestic operations** — properties, logistics, household management → `household/`
14. **Private notes** — health, personal reflections, inner life → `personal/`
15. **A hiring pipeline** — candidate evaluations, role specs, interview notes → `hiring/`
16. **A reusable LLM prompt** — templates for getting specific outputs from models → `prompts/`
17. **A raw data import or snapshot** — bulk exports, API dumps, periodic captures → `sources/`
18. **Agent deliverables** — briefings, digests, and research produced by your agent → `agent/`
19. **Unsorted / quick capture** — you don't know where it goes yet → `inbox/`
20. **Dead / no longer relevant** — historical pages with no active references → `archive/`
### Disambiguation Rules
When two directories seem to fit, apply these tiebreakers:
- **Person vs. Company:** If the page is about *them as a human* (beliefs, relationship, trajectory), it's people/. If it's about *the organization they run*, it's companies/. Both pages link to each other.
- **Concept vs. Idea:** Could you *teach* it to someone as a framework? Concept. Could you *build* it? Idea.
- **Concept vs. Personal:** Would you share it in a professional talk? Concept. Is it private reflection? Personal.
- **Idea vs. Project:** Is anyone working on it? If yes, project. If no, idea. The graduation moment is when work starts.
- **Writing vs. Concepts:** Concepts are distilled (200 words of compiled truth). Writing is developed prose (argument, narrative, story).
- **Writing vs. Media:** Writing is the *artifact*. Media is the *production and distribution infrastructure*.
- **Org vs. Programs:** org/ is institutional knowledge *about* your organization. programs/ is about your personal role and priorities within it.
- **Civic vs. People:** Political figures get people/ pages. Their legislative agenda and political positioning as civic actors goes in civic/.
- **Household vs. Personal:** If a PA would execute on it, it's household (operational). If it's private reflection, it's personal (inner life).
- **Sources vs. .raw/ sidecars:** Per-entity enrichment data → .raw/ sidecar next to the entity. Bulk multi-entity imports → sources/.
- **Agent vs. Sources:** Sources feed *into* the brain. Agent deliverables are synthesized output that feeds *into your reading*.
### Special directories (not knowledge)
These exist in the brain repo but aren't knowledge directories:
- **templates/** — page templates for each type (structural, not content)
- **attachments/** — binary attachments (images, PDFs). Managed by your editor, not by the agent.
### MECE Check
Every piece of knowledge should pass through the decision tree above and land in exactly one directory. If you find something that genuinely doesn't fit any category, file it in inbox/ and flag it — that's a signal the schema needs to evolve.
## Getting started
1. Create the directory structure above (or let your agent create it)
2. Write a `RESOLVER.md` decision tree and a `README.md` resolver for each directory
3. Write a `schema.md` with your page conventions and templates
4. Add the brain rules to your agent's config (AGENTS.md or equivalent) as hard rules
5. Start with one meeting transcript or one person you want to track
6. Let the agent build the first few pages, review them, and iterate on the schema
7. Wire up your meeting tool to trigger ingestion
8. Wire up enrichment to fire on every new person/company signal
9. The brain compounds from there
The human's job: curate sources, direct analysis, ask good questions, and think about what it all means. The agent's job: everything else.
---
### GBRAIN SKILLPACK (`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, the 50+ bundled skills (`skills/manifest.json`), 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](guides/brain-agent-loop.md) | The read-write cycle that makes the brain compound over time |
| [Entity Detection](guides/entity-detection.md) | After opt-in, capture original thinking + entity mentions; paid enrichment is separate |
| [The Originals Folder](guides/originals-folder.md) | Capturing WHAT YOU THINK, not just what you found |
| [Brain-First Lookup](guides/brain-first-lookup.md) | Check the brain before calling any external API |
| [Push-Based Context](guides/push-context.md) | volunteer_context: the brain volunteers relevant pages instead of waiting to be asked |
| [Compiled Truth + Timeline](guides/compiled-truth.md) | Above the line: current synthesis. Below: append-only evidence |
| [Source Attribution](guides/source-attribution.md) | Every fact needs a citation. Format and hierarchy |
## Data Pipelines
Getting data in and keeping it current.
| Guide | What It Covers |
|-------|---------------|
| [Enrichment Pipeline](guides/enrichment-pipeline.md) | 7-step protocol, tier system (Tier 1/2/3 by importance) |
| [Meeting Ingestion](guides/meeting-ingestion.md) | Always pull complete transcript, propagate to all entity pages |
| [Content & Media Ingestion](guides/content-media.md) | YouTube, social media bundles, PDFs/documents |
| [Diligence Ingestion](guides/diligence-ingestion.md) | Data room materials: pitch decks, financial models, cap tables |
| [Deterministic Collectors](guides/deterministic-collectors.md) | Code for data, LLMs for judgment. The collector pattern |
| [Idea Capture & Originals](guides/idea-capture.md) | Depth test, originality distribution, deep cross-linking |
| [Getting Data In](integrations/README.md) | Integration recipes: voice, email, X, calendar |
## Operations
Running a production brain.
| Guide | What It Covers |
|-------|---------------|
| [Reference Cron Schedule](guides/cron-schedule.md) | 20+ recurring jobs, quiet hours, dream cycle |
| [Cron via Minions](../skills/conventions/cron-via-minions.md) | Why scheduled work runs as Minion jobs, not `agentTurn`. Built-in handlers are rewritten by the `v0_11_0` migration orchestrator (`gbrain apply-migrations`); host-specific handlers use the plugin contract below. |
| [Plugin Handlers](guides/plugin-handlers.md) | Registering host-specific Minion handlers via code (no data-file exec surface). |
| [Minions fix](guides/minions-fix.md) | Repairing a half-migrated Minions install. |
| [Shell jobs](guides/minions-shell-jobs.md) | 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](guides/quiet-hours.md) | Hold notifications during sleep, timezone-aware delivery |
| [Executive Assistant Pattern](guides/executive-assistant.md) | Email triage, meeting prep, scheduling |
| [Operational Disciplines](guides/operational-disciplines.md) | Signal detection, brain-first, sync-after-write, heartbeat, dream cycle |
| [Skill Development Cycle](guides/skill-development.md) | 5-step cycle: concept, prototype, evaluate, codify, cron |
**Subagent routing:** 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 orchestrator
injects a marker into AGENTS.md pointing at this convention.
**Cron routing:** 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
orchestrator 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](guides/repo-architecture.md) | Agent repo vs brain repo, boundary rules, decision tree |
| [Sub-Agent Model Routing](guides/sub-agent-routing.md) | Which model for which task, signal detector pattern, cost optimization |
| [The Three Search Modes](guides/search-modes.md) | Keyword, hybrid, direct. When to use each |
| [Brain vs Agent Memory](guides/brain-vs-memory.md) | 3 layers: GBrain (world knowledge), agent memory, session |
## Integrations
Wiring up your life.
| Guide | What It Covers |
|-------|---------------|
| [Credential Gateway](integrations/credential-gateway.md) | ClawVisor / Hermes for Gmail, Calendar, Contacts |
| [Meeting & Call Webhooks](integrations/meeting-webhooks.md) | Circleback transcripts + Quo/OpenPhone SMS/calls |
| [Voice-to-Brain](../recipes/twilio-voice-brain.md) | 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](../recipes/email-to-brain.md) | Gmail messages flow into entity pages via deterministic collector |
| [X-to-Brain](../recipes/x-to-brain.md) | Twitter monitoring with deletion detection + engagement velocity |
| [Calendar-to-Brain](../recipes/calendar-to-brain.md) | Google Calendar events become searchable daily brain pages |
| [Meeting Sync](../recipes/meeting-sync.md) | Circleback transcripts auto-import with attendee propagation |
## Administration
Keeping it running and up to date.
| Guide | What It Covers |
|-------|---------------|
| [Agent Bootstrap](guides/bootstrap.md) | The paste-in install: `gbrain bootstrap`, hooks, `bootstrap verify`, keyless mode |
| [Upgrades & Auto-Update](guides/upgrades-auto-update.md) | check-update, agent notifications, migration files |
| [Live Sync](guides/live-sync.md) | 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](../skills/cold-start/SKILL.md) | Day-one bootstrapping: contacts, calendar, email, conversations, social, archives. Uses ClawVisor for safe credential handling — agents never hold raw API keys. |
| [Ask User](../skills/ask-user/SKILL.md) | 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 ` | Read a specific brain page by slug |
| `gbrain sync` | Sync local markdown repo to gbrain index |
| `gbrain import ` | 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](architecture/infra-layer.md) — Import pipeline, chunking, embedding, search
- [Thin Harness, Fat Skills](ethos/THIN_HARNESS_FAT_SKILLS.md) — Architecture philosophy
- [Markdown Skills as Recipes](ethos/MARKDOWN_SKILLS_AS_RECIPES.md) — Why markdown is code and your agent is a package manager
- [Homebrew for Personal AI](designs/HOMEBREW_FOR_PERSONAL_AI.md) — The 10-star vision
- [Recommended Schema](GBRAIN_RECOMMENDED_SCHEMA.md) — Directory structure for your brain repo
- [Verification Runbook](GBRAIN_VERIFY.md) — End-to-end installation verification
---
### GBRAIN V0 (`docs/GBRAIN_V0.md`)
# GBrain v0: Postgres-Native Personal Knowledge Brain
> **Historical design doc.** This is the original v0 spec from before PGLite landed. Several
> forward-looking sections — most notably the SQLite engine plan — were superseded by
> PGLite (embedded Postgres via WASM), which uses the same SQL dialect as Postgres and
> eliminates the need for a separate FTS5/sqlite-vss translation layer. Kept here for
> historical context; see [`ENGINES.md`](ENGINES.md) for the current engine architecture and
> the [`CHANGELOG.md`](../CHANGELOG.md) for the actual implementation history.
> **Do not use the installation commands in this historical spec.** The bare
> npm package named `gbrain` is unrelated to this project. Current installation
> uses `bun install -g github:garrytan/gbrain` or a source clone; follow
> [the current install guide](INSTALL.md). The original design below is retained.
## What this is
GBrain is a compiled intelligence system. Not a note-taking app. Not "chat with your notes."
Every page is an intelligence assessment. Above the line: compiled truth (your current best understanding, rewritten when evidence changes). Below the line: timeline (append-only evidence trail). AI agents maintain the brain. MCP clients query it. The intelligence lives in fat markdown skills, not application code.
The core insight: personal knowledge at scale is an intelligence problem, not a storage problem.
## Why it exists
A 7,471-file / 2.3GB markdown wiki is choking git. Git doesn't scale past ~5K files for wiki-style use. The compiled truth + timeline model (Karpathy-style knowledge pages) is right, but it needs a real database underneath.
There's already a production-grade RAG system (Ruby on Rails, Postgres + pgvector) with 3-tier chunking, hybrid search with RRF, multi-query expansion, and 4-layer dedup. GBrain ports these proven patterns to a standalone Bun + TypeScript tool.
## The knowledge model
```
/* Detailed source-code truncated for AI context efficiency. */
```
## Architecture decisions
### v0 stack
| Layer | Choice | Why |
|-------|--------|-----|
| Database | Postgres + pgvector | Proven RAG patterns, production-tested. World-class hybrid search. |
| Hosting | Supabase Pro ($25/mo) | Zero-ops. Managed Postgres, pgvector, connection pooling. 8GB storage. |
| Runtime | Bun + TypeScript | Consistent with GStack ecosystem. Fast. Compiles to single binary. |
| Embeddings | OpenAI text-embedding-3-large | 1536 dims (reduced from 3072 via dimensions API). ~$0.13/1M tokens. |
| LLM (chunking/expansion) | Claude Haiku | Cheapest model for topic boundary detection and query expansion. |
| Background jobs | Trigger.dev | Serverless. Embed backfill, stale detection, orphan audit, tag consistency. |
| Distribution | npm package + compiled binary + MCP server | Library for OpenClaw, CLI for humans, MCP for agents. |
### What we chose and why
**Postgres over SQLite.** We have 3+ years of proven RAG patterns running on Postgres. tsvector for full-text search, pgvector HNSW for semantic search, pg_trgm for fuzzy slug matching. Porting these to SQLite would mean reimplementing search from scratch. SQLite is a future pluggable engine for lightweight open source users (see `docs/ENGINES.md`).
**Supabase over self-hosted.** Zero maintenance. The brain should be infrastructure that AI agents use, not something you administer. Free tier has pgvector but only 500MB (not enough for 7K+ pages with embeddings, which need ~750MB). Pro tier at $25/mo gives 8GB. No Docker, no self-hosted Postgres in v1.
**Full port over minimal viable.** The patterns are proven. The port is mechanical. Shipping the full 3-tier chunking + hybrid search + 4-layer dedup means world-class RAG from day one. "We'll add that later" means rebuilding everything later.
**Library-first distribution.** gbrain is an npm package. OpenClaw installs it as a dependency (`bun add gbrain`), imports the engine directly. Zero-overhead function calls, shared connection pool, TypeScript types. The CLI and MCP server are thin wrappers over the same engine.
**Trigger-based tsvector (not generated column).** To include timeline_entries content in full-text search, the tsvector needs to span multiple tables. Generated columns can't do cross-table references. A trigger on pages + timeline_entries updates the search_vector.
**Auto-embed during import.** No separate embed step. `gbrain import` chunks and embeds in one pass. Progress bar shows status. `--no-embed` flag for users who want to defer. `embedded_at` column enables `gbrain embed --stale` for backfill.
## Distribution model
```
/* Detailed source-code truncated for AI context efficiency. */
```
package.json exports:
- Library: `src/core/index.ts` (BrainEngine interface, PostgresEngine, types)
- CLI binary: `src/cli.ts`
## First-time experience
### Path 1: OpenClaw user (primary)
OpenClaw is the AI orchestrator that uses gbrain as its knowledge backend. This is the most common install path.
```bash
# 1. Install gbrain as a ClawHub skill
clawhub install gbrain
# 2. The skill runs guided setup on first use:
# - Detects if Supabase CLI is available
# - If yes: auto-provisions a new Supabase project
# - If no: prompts for connection URL
# - Runs schema migration
# - Scans for markdown repos and imports user's content
# - Shows live entity/edge extraction animation
# - Brain is ready
# 3. From OpenClaw, brain tools are now available:
# "Search the brain for [topic from your data]"
# "Ingest my meeting notes from today"
# "How many pages are in the brain?"
```
Behind the scenes, `clawhub install gbrain`:
1. Installs the `gbrain` npm package
2. Ships SKILL.md files (ingest, query, maintain, enrich, briefing, migrate)
3. Registers brain tools with the orchestrator
4. Runs `gbrain init --supabase` on first use (guided wizard)
### Path 2: CLI user (standalone)
```bash
# 1. Install
npm install gbrain
# or: download binary from GitHub Releases
# 2. Initialize with Supabase
gbrain init --supabase
# Guided wizard:
# Try 1: Supabase CLI auto-provision (npx supabase)
# Try 2: If CLI not installed or not logged in, fallback:
# "Enter your Supabase connection URL:"
# Then: runs schema migration, verifies pgvector extension
# Then: verifies database is ready for import
# Output: "Brain ready. Run: gbrain import "
# 3. Import your data
gbrain import /path/to/markdown/wiki/
# Progress bar: 7,471 files, auto-chunk, auto-embed
# ~30s for text import, ~10-15 min for embedding
# 4. Query
gbrain query "what does PG say about doing things that don't scale?"
```
### Path 3: MCP user (Claude Code, Cursor)
```json
// ~/.config/claude/mcp.json
{
"mcpServers": {
"gbrain": {
"command": "gbrain",
"args": ["serve"]
}
}
}
```
Then in Claude Code: "Search my brain for people who know about robotics"
### The init wizard in detail
`gbrain init --supabase` runs through these steps:
```
Step 1: Database Setup
├── Check for Supabase CLI (npx supabase --version)
│ ├── Found + logged in → auto-create project
│ │ ├── Create project via supabase CLI
│ │ ├── Wait for project to be ready
│ │ └── Extract connection string
│ ├── Found + not logged in →
│ │ └── Error: "Supabase CLI found but not logged in."
│ │ Cause: "You need to authenticate first."
│ │ Fix: "Run: npx supabase login"
│ │ Docs: "https://supabase.com/docs/guides/cli"
│ └── Not found → fallback to manual
│ └── Prompt: "Enter your Supabase connection URL:"
│
Step 2: Schema Migration
├── Connect to database
├── CREATE EXTENSION IF NOT EXISTS vector
├── CREATE EXTENSION IF NOT EXISTS pg_trgm
├── Run src/schema.sql (all tables, indexes, triggers)
└── Verify: test insert + vector query
Step 3: Config
├── Write ~/.gbrain/config.json (0600 permissions)
│ { "database_url": "...", "service_role_key": "..." }
└── Verify connection
Step 4: Kindling Import
├── Import 10 bundled PG essays as demo data
├── Chunk + embed each essay
├── Show live entity/edge extraction animation:
│ "Extracting entities... Paul Graham (person), Y Combinator (company)..."
│ "Creating links... Paul Graham → Y Combinator (founded)..."
└── Output: "Brain ready. 10 pages imported."
Step 5: First Query
└── "Try: gbrain query 'what does PG say about doing things that don't scale?'"
```
Every error follows the style guide: problem + cause + fix + docs link.
## CLI commands
```
/* Detailed source-code truncated for AI context efficiency. */
```
CLI and MCP expose identical operations. Drift tests assert identical results for all operations across both interfaces.
## Database schema
9 tables in Postgres + pgvector:
```
/* Detailed source-code truncated for AI context efficiency. */
```
Indexes:
- `pages.slug`: UNIQUE constraint (implicit B-tree)
- `pages.type`: B-tree
- `pages.search_vector`: GIN (full-text search)
- `pages.frontmatter`: GIN (JSONB queries)
- `pages.title`: GIN with pg_trgm (fuzzy slug resolution)
- `content_chunks.embedding`: HNSW with cosine ops (vector search)
- `content_chunks.page_id`: B-tree
- `links.from_page_id`, `links.to_page_id`: B-tree
- `tags.tag`, `tags.page_id`: B-tree
- `timeline_entries.page_id`, `timeline_entries.date`: B-tree
## Search architecture
```
Query: "when should you ignore conventional wisdom?"
|
v
+---------------------+
| Multi-query expansion|
| (Claude Haiku) |
| "contrarian thinking"
| "going against the crowd"
+---------------------+
| | |
v v v
[embed all 3 queries]
| | |
+---+---+
|
+----+----+
| |
v v
+--------+ +--------+
| Vector | | Keyword|
| Search | | Search |
| (HNSW | | (tsv + |
| cosine)| | ts_rank)|
+--------+ +--------+
| |
+----+----+
|
v
+------------------+
| RRF Fusion |
| score = sum( |
| 1/(60 + rank)) |
+------------------+
|
v
+------------------+
| 4-Layer Dedup |
| 1. By source |
| 2. Cosine > 0.85 |
| 3. Type cap 60% |
| 4. Per-page max |
+------------------+
|
v
+------------------+
| Stale alerts |
| (compiled_truth |
| older than |
| latest timeline)|
+------------------+
|
v
[Results]
```
## Chunking strategies
| Strategy | Input | Algorithm | When to use |
|----------|-------|-----------|-------------|
| Recursive | Any text | 5-level delimiter hierarchy (paragraphs > lines > sentences > clauses > whitespace). 300-word chunks, 50-word overlap. | Timeline (predictable format), bulk import |
| Semantic | Quality text | Embed each sentence, Savitzky-Golay filter for topic boundaries, cosine similarity minima. Falls back to recursive. | Compiled truth (intelligence assessments) |
| LLM-guided | High-value text | Pre-split to 128-word candidates, Claude Haiku finds topic shifts in sliding windows. 3 retries per window. | Explicitly requested via `--chunker llm` |
Dispatch: compiled_truth gets semantic chunker. Timeline gets recursive chunker. Override with `--chunker` flag or `chunk_strategy` in frontmatter.
## Skills (fat markdown, no code)
Each skill is a markdown file that AI agents (Claude Code, OpenClaw) read and follow. The skill contains the workflow, heuristics, and quality rules. No skill logic is in the binary.
| Skill | What it does |
|-------|-------------|
| `skills/ingest/SKILL.md` | Ingest meetings, docs, articles. Update compiled truth, append timeline, create links. |
| `skills/query/SKILL.md` | 3-layer search (FTS + vector + structured). Synthesize answer with citations. |
| `skills/maintain/SKILL.md` | Find contradictions, stale info, orphans, dead links, tag inconsistency. |
| `skills/enrich/SKILL.md` | Enrich from external APIs (Crustdata, Happenstance, Exa). Store raw data, distill to compiled truth. |
| `skills/briefing/SKILL.md` | Daily briefing: meetings with context, active deals, open threads. |
| `skills/migrate/SKILL.md` | Universal migration from Obsidian, Notion, Logseq, plain markdown, CSV, JSON, Roam. |
## CEO scope expansions (accepted for v0)
1. **CLI/MCP parity with drift tests.** Both interfaces are thin wrappers over the engine. Tests assert identical output.
2. **Smart slug resolution.** Fuzzy matching via pg_trgm for reads. Writes require exact slugs. `gbrain get "dont scale"` resolves to `concepts/do-things-that-dont-scale`.
3. **Brain health dashboard.** `gbrain health` shows page count, embed coverage, stale pages, orphans, dead links.
4. **Normalized timeline.** `timeline_entries` table only (no TEXT column). `detail` field supports markdown.
5. **Page version control.** `page_versions` table stores full snapshots (compiled_truth + frontmatter + links + tags). `gbrain history`, `gbrain diff`, `gbrain revert` commands. Revert re-chunks and re-embeds.
6. **Typed links + graph traversal.** `link_type` column (knows, invested_in, works_at, etc.). `gbrain graph` uses recursive CTE with max depth (default 5, configurable via `--depth`).
7. **Trigger.dev data cleanup jobs.** Daily embed backfill, weekly stale detection + orphan audit + tag consistency.
8. **Stale alert annotations.** Search results flag pages where compiled_truth is older than latest timeline entry.
9. **Timeline merge on ingest.** Same event created across all mentioned entities.
## Security model (v0)
Single-user, local-only:
- Supabase service role key in `~/.gbrain/config.json` (0600 permissions)
- MCP stdio transport is inherently local (client spawns `gbrain serve` as subprocess)
- No multi-user, no RLS, no OAuth in v0
- Multi-user path (future): Supabase RLS + per-user API keys
## Upgrade mechanism
`gbrain upgrade` detects the installation method and updates accordingly:
| Path | How |
|------|-----|
| npm | `bun update gbrain` (or npm equivalent) |
| Compiled binary | Download new binary to temp dir, atomic rename swap, exec new process |
| ClawHub | `clawhub update gbrain` |
Version check: compare local version against latest GitHub release tag.
## Storage and cost estimates
### Storage (~750MB for 7,471 pages)
| Component | Size |
|-----------|------|
| Page text (compiled_truth + timeline) | ~150MB |
| JSONB frontmatter | ~20MB |
| tsvector + GIN indexes | ~50MB |
| Content chunks (~22K, text) | ~80MB |
| Embeddings (22K x 1536 floats x 4 bytes) | ~134MB |
| HNSW index overhead (~2x embeddings) | ~270MB |
| Links, tags, timeline, raw_data, versions | ~50MB |
| **Total** | **~750MB** |
Supabase free tier (500MB) won't fit. Supabase Pro ($25/mo, 8GB) is the starting point.
### Embedding cost (~$4-5 for initial import)
| Step | Cost |
|------|------|
| Semantic chunker sentence embeddings (~374K sentences) | ~$1 |
| Chunk embeddings (~22K chunks) | ~$0.30 |
| Query expansion (per query, ~3 embeds) | negligible |
| **Total initial import** | **~$4-5** |
Budget alternative: `gbrain import --chunker recursive` skips sentence-level embeddings, then `gbrain embed --rechunk --chunker semantic` upgrades later.
## Serverless operations stack
```
+------------------+ +------------------+ +------------------+
| Supabase | | Vercel | | Trigger.dev |
| (Postgres + | | (web/API, | | (background |
| pgvector) | | optional) | | jobs) |
+------------------+ +------------------+ +------------------+
| Database | | Future web UI | | Embed backfill |
| Connection pool | | API endpoints | | Stale detection |
| pgvector HNSW | | Edge functions | | Orphan audit |
| tsvector FTS | | | | Tag consistency |
| pg_trgm fuzzy | | | | Daily briefing |
+------------------+ +------------------+ +------------------+
```
The CLI connects directly to Supabase Postgres. Trigger.dev and Vercel are for async/scheduled work. The CLI works without them.
## Verification checklist
1. `gbrain import /data/brain/` migrates all 7,471 files losslessly
2. `gbrain export` round-trips to semantically identical markdown
3. `gbrain query "what does PG say about doing things that don't scale?"` returns relevant hybrid search results
4. `gbrain serve` starts MCP server connectable by Claude Code
5. All 3 chunkers produce correct output with test fixtures
6. `gbrain init --supabase` works end-to-end
7. `bun test` passes all tests
8. `clawhub install gbrain` installs the skill and runs guided setup
9. `bun add gbrain` + `import { PostgresEngine } from 'gbrain'` works in external project
10. Drift tests pass: CLI and MCP produce identical results
11. `gbrain health` outputs accurate brain health metrics
12. Migration skill successfully imports an Obsidian vault
## Future plans
See `docs/ENGINES.md` for the pluggable engine architecture and future backend plans.
### v1 candidates (deferred from v0)
- **`gbrain ask` natural language CLI alias.** Trivial to add. P1 TODO.
- **Intelligence compiler.** Treat every fact as a first-class claim with source span, entity links, validity window, confidence, and contradiction status. "What changed, why, and what evidence would flip it again?" From Codex review. Builds on compiled truth model.
- **Active skills via Trigger.dev.** Application-specific briefings, meeting prep. Belongs in OpenClaw, not generic brain infra.
- **Multi-user access.** Supabase RLS + per-user API keys. v0 is single-user.
- **SQLite engine.** Superseded by PGLite (embedded Postgres 17 via WASM) before v1. See [`ENGINES.md`](ENGINES.md) for the current engine architecture.
- **Docker Compose for self-hosted Postgres.** Community PRs welcome.
- **Web UI.** Optional Vercel-hosted dashboard for browsing brain pages.
### Interface abstraction principle
All operations go through `BrainEngine`. The engine interface is the contract. Postgres-specific features (tsvector, pgvector HNSW, pg_trgm, recursive CTEs) are implementation details inside `PostgresEngine`. The interface exposes capabilities, not SQL.
This means:
- A SQLite engine can implement `searchKeyword` using FTS5 instead of tsvector
- A SQLite engine can implement `searchVector` using sqlite-vss instead of pgvector
- A future DuckDB engine could implement analytics-heavy workloads
- The CLI, MCP server, and library consumers never know which engine runs underneath
See [`ENGINES.md`](ENGINES.md) for the full interface spec. (The original SQLite engine plan was superseded by PGLite; the contract-first `BrainEngine` interface made that swap clean.)
## Review history
| Review | Runs | Status | Key findings |
|--------|------|--------|-------------|
| /office-hours | 1 | APPROVED | Builder mode. Full port approach chosen. |
| /plan-ceo-review | 1 | CLEAR | 11 proposals, 10 accepted, 1 deferred. SCOPE EXPANSION mode. |
| /codex review | 1 | issues_found | 24 points challenged, 3 accepted (fuzzy slug, revert spec, tsvector). |
| /plan-eng-review | 2 | CLEAR | 3 issues (upgrade paths, import guardrails, init wizard), 0 critical gaps. |
| /plan-devex-review | 1 | CLEAR | DX score 5/10 to 7/10. TTHW 25min to 90s. Champion tier. |
---
### GBRAIN VERIFY (`docs/GBRAIN_VERIFY.md`)
# GBrain Installation Verification Runbook
> **One-command equivalent:** `gbrain bootstrap verify` runs the whole install
> contract (round-trip, graph floor, and more) automatically and exits non-zero
> on failure — it is the first thing to run after any install. See
> [docs/guides/bootstrap.md](guides/bootstrap.md). This runbook is the
> **manual, deep-verification** companion: use it when `bootstrap verify` fails
> and you need to isolate which layer broke, or when you want to understand
> what "healthy" looks like check by check.
> **Something feels off, or a gbrain call failed?** Start with the
> [agent operator protocol](protocol/AGENT_OPERATOR_v1.md): the error's `code`
> and `fix.next` say what happened, who acts and how to verify; `gbrain errors
> ` explains a code offline, and the
> [troubleshooting symptom table](guides/troubleshooting.md#symptom-table)
> covers symptoms that are not a single error. Then use the checks below.
Run these checks after install to confirm every part of GBrain is working.
Each check includes the command, expected output, and what to do if it fails.
When `gbrain doctor` reports `timeline_history`, `derived_visibility` or
unsealed pages, use [`gbrain repair`](guides/repair.md); when a write is
refused with a named reason, see [write refusal reasons](guides/write-refusals.md).
The most important check is #4 (live sync). "Sync ran" is not the same as
"sync worked." A sync that silently skips pages because of a pooler bug is
worse than no sync at all, because you think it's working.
---
## 1. Schema Verification
**Command:**
```bash
gbrain doctor --json
```
**Expected:** All checks return `"ok"`:
- `connection`: connected, N pages
- `pgvector`: extension installed
- `rls`: enabled on all tables (Postgres/Supabase brains only — PGLite brains
skip this check; the embedded engine has no remote surface)
- `schema_version`: current
- `embeddings`: coverage percentage
A check that carries `skipped_segmented: N` (message ending in
`skipped (segmented): N`) did not read N pages stored in segments, so its
`ok` covers only the pages it read; see
[segmented page storage](guides/memory-boundaries.md#segmented-doctor-skips).
**If it fails:** The doctor output includes specific fix instructions for each
check. See `skills/setup/SKILL.md` Error Recovery table.
### 1a. Migration Plan and DB Probe
**Command:**
```bash
gbrain apply-migrations --list # per-version status: applied / partial / wedged / pending / future
gbrain apply-migrations --dry-run # what a real run would apply or resume
```
Both surfaces are read-only — they never run orchestrators or schema
migrations, even when combined with `--yes`. Each prints a `Database:` probe
line above the plan, so an unreachable database is distinguishable from a
clean one:
- `Database: connected, schema vN (latest M)` — the pre-flight probe
connected. N behind M means schema migrations are pending; a plain run with
`--yes` applies them.
- `Database: UNREACHABLE ()` — the pre-flight connect failed. The
reason is scrubbed through both credential redactors (URL userinfo +
connection-info), so it is safe to paste into issues and CI logs.
- `Database: not probed ()` — no probe was attempted. Normal on
PGLite (`pglite manages schema in-process`): the orchestrators handle the
schema lifecycle internally there, and the probe would briefly hold the
single-writer lock.
**Expected:** `Database: connected, schema vN (latest N)` on Postgres, or
`Database: not probed (pglite manages schema in-process)` on PGLite, followed
by `All migrations up to date.`
**If it fails:** an unreachable database does not stop a default run —
orchestrator migrations still run their filesystem-only phases. Scripts and
CI that need a hard signal add `--require-db`: with it, `--list` and
`--dry-run` exit 1 when the probe failed, and a real run prints the probe
line and aborts with exit 1 before any orchestrator runs. The observational
sibling is `gbrain doctor --no-migrate`, which connects probe-only so a
clean-or-behind schema is reported on as-is instead of being auto-migrated
before the health checks run.
---
## 2. Skillpack Loaded
**Check:** Ask the agent: "What is the brain-agent loop?"
**Expected:** The agent describes the read-write cycle documented in
[docs/guides/brain-agent-loop.md](guides/brain-agent-loop.md): detect entities,
read brain, respond with context, write brain, sync.
**If it fails:** The agent hasn't loaded the skillpack. Have it read
`docs/GBRAIN_SKILLPACK.md` (the index) and follow the Core Patterns links.
---
## 3. Auto-Update Configured
**Command:**
```bash
gbrain check-update --json
```
**Expected:** Returns JSON with `current_version`, `latest_version`,
`update_available` (boolean). The cron `gbrain-update-check` is registered.
**If it fails:** See [docs/guides/upgrades-auto-update.md](guides/upgrades-auto-update.md)
for how to register the update-check cron.
---
## 4. Live Sync Actually Works
This is the most important check. Three parts.
### 4a. Coverage Check
Compare page count in the DB against syncable file count in the repo:
```bash
gbrain stats
```
Then count syncable files:
```bash
find /data/brain -name '*.md' \
-not -path '*/.*' \
-not -path '*/.raw/*' \
-not -path '*/ops/*' \
-not -name 'README.md' \
-not -name 'index.md' \
-not -name 'schema.md' \
-not -name 'log.md' \
| wc -l
```
**Expected:** Page count in `gbrain stats` should be close to the file count.
Some difference is normal (files added since last sync), but if page count is
less than half the file count, sync is silently skipping pages.
**If page count is way too low (Supabase/Postgres brains):** The #1 cause is an
unreachable direct connection on an IPv4-only host. (PGLite brains have no
network layer — for them, check that the sync cron/watch is actually running.) GBrain uses the Transaction pooler (port 6543)
for reads, but routes migrations, DDL, and sync transactions to a derived direct
connection (`db..supabase.co:5432`), which is IPv6-only.
- On an IPv4-only host, reads work but sync transactions fail and silently skip
pages.
- Fix: set `GBRAIN_DIRECT_DATABASE_URL` to the **Session pooler** string (port
5432 on the `pooler.supabase.com` host, IPv4), or enable Supabase's IPv4
add-on. Then run `gbrain sync --full` to reimport everything.
### 4b. Embed Check
```bash
gbrain stats
```
**Expected:** Embedded chunk count should be close to total chunk count.
**If embedded is much lower than total:**
```bash
gbrain embed --stale
```
Without a key for the configured embedding provider (`VOYAGE_API_KEY` for the
default `voyage:voyage-4`, `OPENAI_API_KEY` for OpenAI models), embeddings can't
be generated. Keyword search still works without embeddings, but
hybrid/semantic search won't.
### 4c. End-to-End Test
This is the real test. Edit a brain page, push, wait, search.
1. Edit a page in the brain repo (e.g., correct a fact on a person's page):
```bash
# Example: fix a line in alice-example's page
cd /data/brain
# Make a small edit to one .md file, then commit and push only that file
gbrain git commit-push -m "test: verify live sync" -- people/alice-example.md
```
It must exit 0 and print `pushed to origin/`. On any other
result, stop the test and follow [outcomes](guides/shared-checkout-git.md#outcomes)
(retry once on `commit_lock_busy`; ask the user on `integrate_conflict`).
2. Wait for the next sync cycle (cron interval or `--watch` poll).
3. Search for the corrected text:
```bash
gbrain search ""
```
**Expected:** The search returns the **corrected** text, not the old version.
**If it returns old text:** Sync failed silently. Check:
- Is the sync cron registered and running?
- Is `gbrain sync --watch` still alive (if using watch mode)?
- Run `gbrain config get sync.last_run` to see when sync last ran.
- Run `gbrain sync --repo /data/brain` manually and check for errors.
- If sync errors mention an unreachable host or connection timeout, the direct
connection isn't reachable on IPv4 (see 4a above).
---
## 5. Embedding Coverage
**Command:**
```bash
gbrain stats
```
**Expected:** Embedded chunk count matches (or is close to) total chunk count.
**If zero or very low:** the embedding provider key (`VOYAGE_API_KEY` for the
default model, `OPENAI_API_KEY` for OpenAI models) may be missing or invalid.
Check:
```bash
echo $VOYAGE_API_KEY | head -c 10 # or $OPENAI_API_KEY
```
If blank, set the key. Then:
```bash
gbrain embed --stale
```
### 5a. Fact and take vectors
Chunk coverage says nothing about facts and takes, which are searched by vector
too (fact dedup and consolidation, `think`, `takes search --semantic`).
**Command:**
```bash
gbrain doctor --json
```
**Expected:** the `fact_take_vectors` check is `ok`. On a keyless brain
(embeddings disabled) it reports "not applicable" and stays `ok`.
`details.facts.partially_embedded` counts facts longer than the 8000-character
embedding input: their vector covers only the start of the fact. They count as
current, so nothing re-embeds them or spends on them again (#6975).
**If it warns** (code `stale_vectors`): its `details` count, per source, facts
and takes with no vector for their current text under the brain's embedding
model, and `details.fix` lists the exact commands. Takes are repaired by the
ordinary stale pass:
```bash
gbrain embed --stale
```
Facts are repaired per source, after a preview (paid provider calls need
explicit authorization):
```bash
gbrain embed --facts --stale --source --dry-run --json
gbrain embed --facts --stale --source --yes --max-cost-usd 1
```
If the check says the vectors were not verified (code `vectors_not_verified`),
run `gbrain migrate embeddings --status` to see which model and width the brain
records.
---
## 6. Brain-First Lookup Protocol
**Check:** Ask the agent about a person or concept that exists in the brain.
**Expected:** The agent uses `gbrain search` or `gbrain query` FIRST, not grep
or external APIs. The response includes brain-sourced context with source
attribution.
**If it fails:** The brain-first lookup protocol isn't injected into the agent's
system context. See `skills/setup/SKILL.md` Phase D.
---
## 7. Knowledge Graph Wired
The graph layer needs to be populated for brains with pre-existing content. New
writes are auto-linked, but pages imported before the graph existed need a
one-time backfill.
**Command:**
```bash
gbrain stats | grep -E 'links|timeline'
```
**Expected:** Both `links` and `timeline_entries` are non-zero (assuming the brain
has content with entity references and dated markdown).
**If it's zero on a brain with imported content:** Run the backfill.
```bash
gbrain extract links --source db --dry-run | head -5 # preview
gbrain extract links --source db # commit
gbrain extract timeline --source db
gbrain stats # confirm > 0
```
**Bonus check** — graph traversal works:
```bash
# Pick any well-connected slug from your brain
gbrain graph-query people/ --depth 2
```
**Expected:** Indented tree of typed edges (`--attended-->`, `--works_at-->`, etc.).
If the slug has no inbound or outbound links, try a different one or run extract
again.
**If extract finds nothing:** Your pages may not use entity-reference syntax. The
extractor matches `[Name](people/slug)`, `[Name](../people/slug.md)`, and bare
`people/slug` references. If your brain uses a different format, the auto-link
heuristics won't find them — file an issue with a sample page.
---
## 8. JSONB Frontmatter Integrity
A Postgres-backed brain can carry double-encoded JSONB columns
(`frontmatter->>'key'` returns NULL, GIN indexes are inert). `gbrain upgrade`
runs `gbrain repair-jsonb` automatically via the `v0_12_2` orchestrator.
Verify the repair succeeded.
**Command:**
```bash
gbrain repair-jsonb --dry-run --json
```
**Expected:** `totalRepaired: 0` across all 5 columns (`pages.frontmatter`,
`raw_data.data`, `ingest_log.pages_updated`, `files.metadata`,
`page_versions.frontmatter`). A zero count means every row is properly-typed
JSON objects, not string-encoded JSON.
**If the count is > 0:** The repair didn't run or was interrupted. Re-run
without `--dry-run`:
```bash
gbrain repair-jsonb
```
Idempotent. PGLite brains always report 0 (the embedded engine never
double-encodes).
**Bonus check** — the doctor's dedicated JSONB scan agrees:
```bash
gbrain doctor --json | grep -o '"name":"jsonb_integrity"[^}]*'
```
**Expected:** the fragment contains `"status":"ok"` ("All JSONB columns store
objects/arrays"). If it reports double-encoded rows, run `gbrain repair-jsonb`.
---
## Quick Verification (all checks in one pass)
```bash
# 0. The one-command contract check (exits non-zero on failure)
gbrain bootstrap verify
# 1. Schema
gbrain doctor --json
# 2. Sync recency
gbrain config get sync.last_run
# 3. Page count + embed coverage
gbrain stats
# 4. Search works
gbrain search "test query from your brain content"
# 5. Catch any unembedded chunks
gbrain embed --stale
# 6. Auto-update
gbrain check-update --json
# 7. Knowledge graph populated (links + timeline > 0)
gbrain stats | grep -E 'links|timeline'
# 8. JSONB integrity (Postgres only, PGLite always 0)
gbrain repair-jsonb --dry-run --json
```
If all eight return successfully, the installation is healthy. For the full
end-to-end sync test (4c), push a real change and verify it appears in search.
---
### INSTALL (`docs/INSTALL.md`)
# Install
Start by choosing the setup you need:
- **Add memory to the agent you already use (recommended):** [Grok Bot](guides/grok-bot.md), [Muse](guides/muse.md), or [Codex / Claude Code](tutorials/connect-coding-agent.md). Keep the existing identity; start keyless, without a personal-agent repository.
- **Don't want to run anything yourself:** [gbrain.io](https://gbrain.io/?ref=install-md) is hosted GBrain, the easiest start for a first agent or a team.
- **Connect to your existing hosted brain:** [private handoff and harness access](guides/hosted-harness-access.md). Provision on the host, install in the client environment.
**Optional: create a new persistent personal agent.** If you want identity
files and a private repository, use the separate
[bootstrap guide](guides/bootstrap.md) in a supported harness. The recommended
memory-only setup above preserves your existing agent's identity and needs
neither a bootstrap interview nor a private repository.
The paths below are the manual equivalents and deep-dive detail. Pick one.
Mix later if needed.
Before enabling capabilities, read [memory boundaries](guides/memory-boundaries.md):
durable preferences can be shared, but harness configuration stays local;
remote writes need graph maintenance, cloud providers can receive text, and
Markdown export is not a full database backup.
## 1. Run with an agent platform
Already running [OpenClaw](https://github.com/garrytan/openclaw) or [Hermes](https://github.com/garrytan/hermes)?
```bash
bun install -g github:garrytan/gbrain#latest-stable
gbrain init --pglite --no-embedding # keyless; no server
gbrain skillpack scaffold --all # scaffolds every bundled skill (skills/manifest.json) into your agent workspace
gbrain doctor # inspect diagnostics and expected empty-brain warnings
```
Scaffolding creates skill files; it does not prove the harness has loaded them.
Connect and verify the intended harness before calling it activated. Entity
capture, recurring jobs and paid enrichment require separate opt-in; none of
the commands above schedules a daily enrichment job.
Scaffolded skills are first-class files in your agent repo — edit freely. To pull upstream gbrain improvements later, `gbrain skillpack reference ` diffs your local copy vs the bundle. If your `RESOLVER.md` / `AGENTS.md` still carries the managed `skillpack install` fence, `gbrain skillpack migrate-fence` strips it once and keeps the routing rows inside it.
To upgrade later, use the [memory-only upgrade path](#memory-only-upgrades)
unless services and provider work were deliberately configured. Upgrade runs
schema migrations and post-upgrade work; non-TTY execution is supported and
skips interactive prompts, not all side effects.
## Memory-only upgrades
```bash
GBRAIN_NO_AUTOPILOT_INSTALL=1 GBRAIN_NO_REEMBED=1 gbrain upgrade --no-autopilot-install
```
The autopilot opt-out reaches package postinstall hooks and migration
orchestrators, and skips existing service-unit rewrites. Other migrations still
run. `GBRAIN_NO_REEMBED=1` independently skips potentially paid reindexing.
The same command upgrades a clone linked with Bun: it fetches, checks the new
release's Bun floor, fast-forwards to the checked commit and runs
`bun install`. Avoid a bare `git pull`, which skips that check. When the new
release needs a newer Bun, `gbrain upgrade` refuses and changes nothing (exit
78): run `bun upgrade`, then the upgrade again
([Bun floor](guides/upgrades-auto-update.md#bun-floor)).
Verify a known keyword result, saved fact and process reopen after upgrading.
See the [agent upgrade steps](../INSTALL_FOR_AGENTS.md#upgrade).
## 2. CLI standalone
No agent platform, just shell + MCP-aware editor.
```bash
bun install -g github:garrytan/gbrain#latest-stable
gbrain init --pglite --no-embedding
```
> **If `bun install -g` hits a postinstall error** (Bun blocks postinstall hooks in some environments), the CLI prints a recovery hint pointing at [#218](https://github.com/garrytan/gbrain/issues/218). Run `gbrain doctor` to diagnose, then `gbrain apply-migrations --yes --no-autopilot-install` manually. The deterministic fallback is `git clone https://github.com/garrytan/gbrain.git ~/gbrain && cd ~/gbrain && GBRAIN_NO_AUTOPILOT_INSTALL=1 bun install && bun link`.
The init flow detects your repo size and suggests Supabase for brains > 1000 markdown files. Agent-harness installs that want Postgres first can run the ladder instead:
```bash
gbrain init --prefer-postgres # env URL → Supabase token discovery → local Postgres → opt-in docker → PGLite
```
To switch later:
```bash
gbrain migrate --to postgres --url-env GBRAIN_TARGET_URL --json # PGLite → Postgres: prints the plan, exits 3
gbrain migrate --to pglite # Postgres → PGLite (rare; brains without write history)
```
The move to Postgres carries the brain's full history and runs after the user approves the plan (`--yes --expect `). Walkthrough: [Move a PGLite brain to Postgres](guides/move-to-postgres.md).
If Postgres access ever breaks at runtime, `gbrain engine status --probe` diagnoses it and `gbrain db-repair` fixes it — see the "Engine detection and access repair" section of [`docs/ENGINES.md`](ENGINES.md).
For shared / large / multi-machine deployments (a team or company brain with multiple users hitting one server over HTTP MCP with OAuth scoping per user), follow the dedicated walkthrough: **[Tutorial: set up GBrain as your company brain](tutorials/company-brain.md)**.
Optional provider setup: API keys live in `~/.gbrain/config.json` (file plane) or env vars (`VOYAGE_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`). Set them only after choosing the capability and approving its text disclosure and cost. Vendor API keys (and `database_url`/`database_path`) are file-plane routed, so `gbrain config set ` writes where the pipeline reads it:
```bash
export VOYAGE_API_KEY=pa-... # default embedding (voyage-4) + reranker (rerank-3-lite) — one key
export OPENAI_API_KEY=sk-... # alternative embeddings; also powers automatic fact extraction + chat models
export ANTHROPIC_API_KEY=sk-ant-... # automatic fact extraction + chat models; also improves search via query expansion
```
For a brain initialized with `--no-embedding`, adding a key alone does not enable
embeddings. Follow the CLI's explicit activation path, for example
`gbrain init --force --embedding-model voyage:voyage-4`, after reviewing the
provider and dimension choice. Keyword retrieval needs none of these keys.
Reading a value back: `gbrain config get ` prints redacted by default — sensitive keys (any `key`/`secret`/`token`/`password`-segmented name) print `***`, and a `postgres://` / `postgresql://` value like `database_url` has its `user:password` userinfo replaced with `***` (host, port, database, and query string preserved) — because `get` output lands in agent transcripts and shell history. Scripts that need the real value pass `--raw` (accepted before or after the key). `config show` and the `Set = ...` confirmation that `config set` prints redact the same way. `get` keeps stdout a bare value and reports which plane answered (file/env or DB) on stderr.
Chat-shaped features (automatic fact extraction, enrichment, synthesis, query
expansion) route to whichever supported chat key is present (Anthropic or
OpenAI) — Anthropic when both are set, OpenAI when it is the only one; other
chat providers need an explicit `models.*` pin. With neither key, they stay off
calmly and memory comes from agent-authored `## Facts` fences and the
`remember` verb.
For the autopilot daemon specifically, keys and process-level env (`NODE_EXTRA_CA_CERTS`, proxy vars, custom base URLs) belong in `~/.gbrain/env` — a 0600 file created by `gbrain autopilot --install` and sourced by the daemon wrapper (interactive shell rc files never reach daemon shells; the path honors `GBRAIN_HOME`). Re-run `gbrain autopilot --install` after editing it so the daemon reloads. To keep a key off disk, use your secret manager there: the file is sourced by bash at every daemon start, so a line like `VOYAGE_API_KEY="$(doppler secrets get VOYAGE_API_KEY --plain)"` (or `op read`, `security find-generic-password -w`, `pass show`) fetches the value at start-up and never writes it (#5196). The command must work non-interactively in the daemon's environment.
To change an existing brain's embedding provider, follow the explicit-consent playbook at [`skills/migrations/v0.46.3.0.md`](../skills/migrations/v0.46.3.0.md), with the full reference in [`docs/guides/embedding-migration.md`](guides/embedding-migration.md). Preview the work and cost before approving a migration; do not repoint existing vectors at a different model.
Common follow-ups:
```bash
gbrain import ~/my-knowledge # bulk-import a markdown folder
gbrain sync --watch # live-sync a git repo (autopilot mode)
gbrain autopilot --install # background daemon for nightly enrichment
```
**Wire this same local brain into your coding agent** — zero server, zero token:
```bash
claude mcp add gbrain -- "$(command -v gbrain)" serve --surface full # Claude Code
codex mcp add gbrain -- "$(command -v gbrain)" serve --surface full # Codex
```
The agent spawns `gbrain serve` as a stdio subprocess against your local brain. `--surface full` (what every registration gbrain writes pins) serves every operation, the seven-verb memory protocol ([MEMORY_VERBS v1](protocol/MEMORY_VERBS_v1.md)) included; a harness that caps its tool count can register `--surface starter` (the verbs plus the daily-driver set, 40 ops) or `--surface verbs` (only the seven verbs). Full walkthrough (both this local path and connecting to a remote brain), plus the brain-first protocol to paste into `CLAUDE.md` / `AGENTS.md`: **[Give your coding agent a memory](tutorials/connect-coding-agent.md)**.
## 3. MCP server (any MCP client)
```bash
gbrain serve --surface full # stdio MCP (Claude Desktop / Code / Cursor), every operation
gbrain serve --http # HTTP MCP with OAuth 2.1 + admin dashboard
gbrain mcp expose # publish serve --http on your Tailscale tailnet (HTTPS + user service)
```
To reach the brain on this computer from your other devices, desktop apps or
cloud agents, `gbrain mcp expose` publishes the HTTP server on your Tailscale
tailnet and keeps it running as a user service (`--funnel` is the explicit
opt-in for agents that run in a vendor's cloud). Guide:
[use your brain from anywhere over MCP](guides/remote-mcp.md).
**Say to your agent:** *"use my brain over mcp"* — *"put my brain on tailscale"*.
**Wire a coding agent to a remote brain in one command** (when you have an HTTP
server + a bearer token): `gbrain connect` prints a paste-ready setup block, or
`--install` runs it and smoke-tests the token.
```bash
gbrain auth create "claude-code"
gbrain connect https://your-host/mcp --token gbrain_xxx # Claude Code (default)
gbrain connect https://your-host/mcp --token gbrain_xxx --agent codex # Codex (env-var bearer)
gbrain connect https://your-host/mcp --agent perplexity --oauth --register # Perplexity (OAuth)
```
Per-client setup guides live in [`docs/mcp/`](mcp/):
- [`docs/mcp/CLAUDE_CODE.md`](mcp/CLAUDE_CODE.md)
- [`docs/mcp/CODEX.md`](mcp/CODEX.md)
- [`docs/mcp/CLAUDE_DESKTOP.md`](mcp/CLAUDE_DESKTOP.md)
- [`docs/mcp/CHATGPT.md`](mcp/CHATGPT.md)
- [`docs/mcp/PERPLEXITY.md`](mcp/PERPLEXITY.md)
- [`docs/mcp/HERMES.md`](mcp/HERMES.md) — Hermes (Nous Research CLI)
- [`docs/mcp/GROK.md`](mcp/GROK.md) — Grok Build (xAI CLI)
- [`docs/mcp/OPENCODE.md`](mcp/OPENCODE.md) — opencode (opencode.ai / SST terminal agent)
- [`docs/mcp/OPENCLAW.md`](mcp/OPENCLAW.md) — OpenClaw (bundle plugin or stdio)
- [`docs/mcp/CLAUDE_COWORK.md`](mcp/CLAUDE_COWORK.md) — Claude Cowork (team plan)
- [`docs/mcp/DEPLOY.md`](mcp/DEPLOY.md) — production deploy patterns
The HTTP server ships with an admin SPA at `/admin`, an SSE activity feed at `/admin/events`, DCR-style client registration, scope-gated `read`/`write`/`admin` access, and rate limiting.
## Thin-client mode
Connect to someone else's brain without running a local engine:
```bash
gbrain init --mcp-only # configures remote MCP, skips local DB
# requires: --issuer-url --mcp-url --oauth-client-id --oauth-client-secret
# (or GBRAIN_REMOTE_ISSUER_URL / GBRAIN_REMOTE_MCP_URL / ... env vars)
```
Useful for: team mounts, brain-as-a-service deployments, dev machines without disk space. Most local commands refuse with a paste-ready hint. See [`docs/architecture/topologies.md`](architecture/topologies.md).
## Verifying the install
```bash
gbrain bootstrap verify # the whole install contract; exits non-zero on failure
gbrain doctor --json # full health check
gbrain models # which AI models are configured for what
gbrain models doctor # 1-token probe per configured model
```
If anything's yellow, `gbrain doctor` names the fix command in the message. Most issues are missing API keys or stale schema (`gbrain upgrade --force-schema`). For the manual check-by-check runbook, see [docs/GBRAIN_VERIFY.md](GBRAIN_VERIFY.md).
## Troubleshooting
### PGLite crashes at startup (`RuntimeError: Aborted()`)
This crash (typically first seen after a macOS upgrade) is **not** a
macOS/WASM incompatibility — an unclean shutdown tore the data dir's
write-ahead log, and every subsequent open fails WAL replay. The short
version of the recovery ladder:
1. **Auto-repair (default):** run any gbrain command — gbrain detects the
abort, resets the WAL in place (data preserved, backup kept), and
continues. Then run `gbrain doctor`.
2. **Manual repair:** `gbrain pglite-repair --dry-run`, then
`gbrain pglite-repair --yes`.
3. **Rebuild:** `gbrain reinit-pglite`.
4. **Switch engines:** Supabase or native Homebrew Postgres + pgvector.
The full ladder — safety bounds, kill-switches, when WAL repair can't help,
and the Homebrew Postgres recipe — lives in
[docs/ENGINES.md](ENGINES.md#troubleshooting-startup-abort-runtimeerror-aborted).
---
### RELEASING (`docs/RELEASING.md`)
# Releasing & contributing (gbrain)
The full release + contributor process. CLAUDE.md keeps the ship-critical IRON RULES
inline (the Version-locations table, branch=workspace, post-ship `/document-release`,
the Privacy + Responsible-disclosure rules, PR-title-version-first, never-hand-roll-ship)
and points here for everything else. **Before any ship, read this in full. Use `/ship` —
never hand-roll a release.**
## Pre-ship requirements
Before shipping (/ship) or reviewing (/review), always run the full test suite.
Two equivalent paths:
**Path A — local CI gate (recommended, v0.23.1+):**
- `bun run ci:local` runs the entire stack inside Docker: gitleaks (host),
guards + typecheck, then 4-shard parallel unit + E2E against four pgvector
containers plus a transaction-mode PgBouncer service (unit phase keeps
`DATABASE_URL` unset; `--no-shard` for the legacy sequential flow). Stronger
than PR CI's four-file Tier 1 job; closer to what nightly Tier 1 catches. Spins
up + tears down postgres automatically via `docker-compose.ci.yml`. Override
the host port with `GBRAIN_CI_PG_PORT=5435 bun run ci:local` if 5434 collides.
- `bun run ci:local:diff` checks a doc-only diff in seconds (gitleaks plus
`scripts/ci-doc-checks.sh`) and runs the full gate for any other diff: E2E
narrowing is retired (see docs/TESTING.md "E2E selection").
- `bun run ci:ubicloud` (and `ci:ubicloud:diff`) runs the same lanes across ten
ephemeral Ubicloud VMs in about five minutes instead of one Docker host. Needs
`UBICLOUD_API_KEY` or `UBICLOUD_API_TOKEN`; see "Ubicloud fan-out" in
[docs/TESTING.md](TESTING.md).
**Path B — manual lifecycle (still supported):**
- `bun test` — unit tests (no database required)
- Follow the "E2E test DB lifecycle" steps in
[docs/TESTING.md](TESTING.md) 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.
**Always run typecheck before pushing.** Neither `bun test` (the bun runner)
nor `bun run test` gates on types — `bun run test` is just
`bash scripts/run-unit-parallel.sh` (the sharded unit runner; no typecheck,
no shell pre-checks — see the test-tier table in [docs/TESTING.md](TESTING.md)).
Three ways to actually gate on types:
1. `bun run verify` — runs the shell guard checks (privacy, jsonb, source-id,
progress-to-stdout, …) plus `bun run typecheck` in parallel
(`scripts/run-verify-parallel.sh`). Use this mid-branch.
2. `bun run typecheck` — standalone TypeScript checking with native incremental
analysis in ignored `node_modules/.cache/gbrain-typecheck.tsbuildinfo`. Cold
checks still analyze the whole project; repeated checks reuse compiler state
while retaining input invalidation and diagnostics. See [Testing](TESTING.md).
3. `bun run ci:local` — the full local CI gate from Path A.
The trap is: writing a new test, running `bun test test/foo.test.ts`,
seeing it pass, pushing — and CI's separate typecheck stage rejects an
invalid type literal that the runner accepted. Caught one of these
shipping the v0.23.2 round-trip E2E (`type: 'reflection'` is not a
member of `PageType`). Run `bun run typecheck` once before push, even
when only test files changed.
## Generated artifacts
`bun run regen:all` regenerates every generated artifact offline and keyless
(schema bundles, error-code and agent-protocol blocks, harness reference, tool
catalog, skills manifest, metric glossary, CLI flag registry, plugin tree and
persona variants, structural-suites manifest, then `llms.txt`/`llms-full.txt`
last) and lists the files it changed. Run it before pushing whenever a
freshness gate could fail; a second run changes nothing. `bun run verify`
runs the read-only half, `check:regen-all`, whose failure names each stale
artifact and the same fix. Contract goldens (export surface, CLI goldens, SQL
text) are behavior pins, so `regen:all` leaves them alone unless you pass
`--goldens`, and each changed golden needs a reason in the PR body. Goldens
that need Postgres are named in its output with their own command.
## Nightly-red issues
`.github/workflows/nightly-watch.yml` runs `scripts/nightly-issue.ts` after every
scheduled workflow and keeps one issue per workflow titled `Nightly red: `
(label `nightly-red`). The issue body lists the failing job and step pairs, the
first red run and the commits since the last green one, the `gh workflow run`
re-check, and a "Next step for the agent" block plus a JSON block.
- **Owner:** the agent on release duty owns every open `nightly-red` issue; Garry is
the escalation for owner-only actions (secrets, repository settings).
- **Response within 24 hours:** a repair PR, or a row in
`.github/nightly-known-red.tsv` (job, failure signature, the owning TODOS.md entry,
a review-by date). The file holds at most 3 rows; fix one before adding another.
A matching cell keeps the issue open with the `known-red` label; a new failure in
the same job opens a new incident; a passed review-by date asks for a fix again.
- **Closing:** nightly-watch closes the issue only when a later scheduled run is
green with complete evidence and every previously failing job executed. A
skipped job never closes it.
- **Re-check after a fix:** `gh workflow run .yml --ref master`, then
`gh workflow run nightly-watch.yml -f run_id=` to preview
(`-f dry_run=true`) or apply the issue update.
- **Dependency advisories:** pull requests block on `bun audit` only when they change
`bun.lock`, `admin/bun.lock`, `patches/` or a package.json dependency field, or
carry the `dependency-audit` label; pushes and the nightly run always block, so a
new upstream advisory shows up as one red nightly instead of every open PR.
## Master-red issues
nightly-watch keeps one `master-red` issue per workflow (`Master red: Test`,
`Master red: E2E Tests`) for push-to-master runs; scheduled runs stay in
`nightly-red`. The body names each failing job, every failing test file with
its `bun run test:stress` reproduce line, and the suspect range (last green
push SHA, first red SHA, merged PRs). Labels, close rules and recovery steps:
[CI red runbook](ci-red-runbook.md#ci-issue-labels).
- **Owner:** the agent on release duty owns every open `master-red` issue, as
for `nightly-red`; Garry is the escalation for owner-only actions.
- **First response within 1 hour:** a comment or a linked repair PR. CI health
measures it; nothing enforces it.
- **Response:** a repair PR whose body says `Fixes #`. Known-red rows
never apply to push runs. A master-red repair PR is fast-tracked when Garry
asks.
- **Closing:** nightly-watch closes the issue on a green push run where every
previously failing job (E2E Tests: every failing test file) ran and passed
with complete evidence. Without a merged repair PR it opens `flake` issues.
## Merge queue
`test.yml` and `e2e.yml` carry `merge_group` triggers. They are inert until the
merge queue is enabled for `master` in the repository settings; check with
`gh api repos/garrytan/gbrain/rulesets` (or the branch protection page). Queue runs use
the pull-request profile against the queued merge commit: primary native scope,
the newest Bun version only in the security and persistence matrices, the
2,500-write soak and the 10,001-page export scale; the E2E selector diffs the
queued commit against `master`.
- Without the queue, a release rebases onto the latest `origin/master` and re-runs
the full CI (`test.yml`, `e2e.yml`, persistence-validation) immediately before
merging, because a stale base can break master even when the PR was green.
- With the queue on, `gh pr merge` only enqueues the PR. Wait until the PR is
actually merged (`gh pr view --json state,mergedAt`) before tagging,
announcing or starting dependent work.
## CHANGELOG + VERSION are branch-scoped
**VERSION and CHANGELOG describe what THIS branch adds vs master, not how we got
here.** Every feature branch that ships gets its own version bump and CHANGELOG
entry. The entry is product release notes for users; it is not a log of internal
decisions, review rounds, or codex findings.
**Write the CHANGELOG entry at /ship time, not during development.** Mid-branch
iterations, review rounds (CEO/Eng/Codex/DX), and implementation detours belong
in the plan file at `~/.claude/plans/`, not in the CHANGELOG. One unified entry
per branch, covering what the branch added vs the base branch.
**Never edit a CHANGELOG entry that already landed on master.** If master has
v0.18.2.0 and your branch adds features, bump to the next PATCH version
(v0.18.3.0, never MINOR) instead of editing master's v0.18.2.0. When merging master into your branch, master may
bring new CHANGELOG entries above yours — push your entry above master's
latest and verify:
- Does CHANGELOG have your branch's own entry separate from master's entries?
- Is VERSION higher than master's VERSION?
- Is your entry the topmost `## [X.Y.Z]` entry?
- `grep "^## \[" CHANGELOG.md` shows a contiguous version sequence?
If any answer is no, fix it before continuing.
**CHANGELOG is for users, not contributors.** Write like product release notes:
- Lead with what the user can now **do** that they couldn't before. Sell the capability.
- Plain language, not implementation details. "You can now..." not "Refactored the..."
- **Never mention internal artifacts**: plan file IDs, decision tags (D-CX-#, F-ENG-#),
review rounds, codex findings, subcontractor credits. These are invisible to users.
- Put contributor-facing changes in a separate `### For contributors` section at the bottom.
- Every entry should make someone think "oh nice, I want to try that."
**What to omit:**
- "Codex caught X that the CEO review missed" — private process detail.
- "D-CX-3 split errors/warnings" — tag is meaningless to users; name the feature instead.
- "Fix-wave PR #N supersedes #M" — supersede chains belong in PR bodies, not release notes.
- "215 new cases, 3 decisions applied, 7 reviews cleared" — these are planning-mode metrics.
**What to keep:**
- The user-facing change: what commands exist now, what flag was added, what behavior fixed.
- Numbers that mean something to the user: TTHW, commands that timed out before, detection counts.
- Upgrade instructions: `gbrain upgrade` + any manual step if needed.
- Credit to external contributors when a community PR was incorporated.
## Release restamp
`bun run release:restamp` makes a branch next-to-merge in one command. Run it
when your PR is next in the merge line, not earlier: the merge coordinator
merges one PR at a time, so restamping at that moment allocates the version
and migration numbers without races. Preview first with `--dry-run`, which
prints every planned edit, predicted merge conflict, migration renumbering
and the commit it would make, and changes nothing.
**Say to your agent:** *"Restamp this branch onto master, it's next to merge."*
1. Refuses a dirty working tree (commit or `git stash -u` first) and a
failed fetch (offline: `git fetch origin master`, then rerun).
2. Captures the branch's CHANGELOG entry (the sections above the newest entry
it shares with master; one entry per branch) and its migration inventory.
3. Merges `origin/master` with a merge commit. Version-only hunks in the stamp
files, `CHANGELOG.md` and generated files (migration registry,
`migrations/records.json`, `llms*.txt`, plugin trees, the template repo,
`bun.lock`) resolve mechanically; any other conflict stops with the file
list.
4. Sets VERSION to master's `MAJOR.MINOR.(PATCH+1).0` and rewrites every
required row of the CLAUDE.md "Version locations" table: VERSION,
`package.json`, the three plugin manifests, the BOOTSTRAP runbook stamp,
the CHANGELOG entry (re-stamped on top of master's entries with today's
date), branch-added TODOS lines naming the old version, and every
`since: 'TBD'` row in `src/core/behavior-change-notice.ts` (development
branches write their BEHAVIOR_CHANGES rows as TBD; the stamp gives them the
new version, and a restamp moves the branch's own rows from the old version).
5. Renumbers the branch's own schema migrations (files `origin/master` does
not have) consecutively from master's latest + 1, in their original order.
It changes only the filename, the `export const v` name and the
`version:` literal, and proves the rest of the file is token-identical.
Published migrations are never renumbered or edited; a branch file whose
payload matches a migration master already published under another number
(squash-merged or cherry-picked) stops with the `git rm` fix.
6. Regenerates the migration registry, `migrations/records.json` (when the
branch has migrations), `bun.lock`, the bootstrap template repo and
everything `bun run regen:all` covers.
7. Lists every line the branch added that still names an old migration number
(`v209`, `v209-name`, `migration 209`, `schema_version ... 209`,
`version: 209`) and stops: such a line may mean the moved migration or the
published one that now owns the number, so it is never rewritten. Edit each
line (an edited line is not listed again), or pass `--accept-references`
with `--continue` when a line means the published migration.
8. Runs the drift checks (version stamps and CHANGELOG agree, bootstrap
stamp, plugin tree, template repo, migration registry and order, no
`since: 'TBD'` row left: `bun scripts/check-behavior-since.ts --stamped`, and every
master release heading still in CHANGELOG.md: `bun scripts/check-changelog-headings.ts`), commits
once as `v chore(release): restamp onto master v`, and prints
the old-to-new migration mapping with the collision-recovery steps, the
golden-regeneration reason for the PR body, the PR title and
`bun run verify`.
Every stop prints what happened, why, and the fix, saves its state, and ends
with `bun run release:restamp --continue` (after you fix it) or `--abort`
(back to the pre-run commit). `--no-commit` leaves the restamp edits staged.
A second run with nothing to change commits nothing. It renumbers source
only and never touches a database: if you applied an old number locally,
follow "Collision recovery" in [TESTING.md](TESTING.md#schema-migration-registry)
(disposable DB: rebuild and replay; retained data: explicit `schema_version`
reconciliation).
**Why stamps are not derived at build time.** Several readers take the
version from committed files with no build step: `bun install -g
github:garrytan/gbrain` installs from source, `gbrain bootstrap status`
compares the BOOTSTRAP runbook stamp with the installed binary, the plugin
manifests and generated trees are published as committed, and `release.yml`
fires on a VERSION change. A build-time value would leave those copies
wrong, so the files stay stamped and one command rewrites them.
**Why migration IDs stay sequential.** A brain records one integer,
`schema_version`, and the runner applies every migration above it in order.
A migration numbered at or below master's latest is skipped forever on
current brains, which `check:schema-migration-order` rejects. Unordered IDs
(timestamps, hashes) would need a per-migration applied-set table and a
bookkeeping migration for every existing brain. Renumbering at merge time,
serialized by the merge coordinator, keeps the counter correct with no
schema change. Build on `release:restamp` rather than a second restamp tool.
## CHANGELOG voice + release-summary format
**IRON RULE: the CHANGELOG describes what the user gets, not how the work
happened.** Nobody reading release notes cares that codex caught a bug, that
the plan went through CEO + eng review, that the migration was originally
numbered v68 and renumbered to v79 during master merge, or that two
review rounds caught architectural mistakes. The reader cares what
`gbrain brainstorm` does and how to use it. If a fact only exists because
of the development process, it does NOT belong in the CHANGELOG.
**Specifically forbidden in CHANGELOG entries:**
- Any mention of review processes (CEO review, eng review, codex review,
plan-eng-review, outside voice, adversarial review, autoplan, /review).
- "What we caught and fixed before merging" sections. Bugs found pre-merge
are not changes — they're things that didn't ship.
- Plan file references, plan IDs, plan decision tags (D1, D14, D-CDX-3).
- Migration version drama ("originally v68", "renumbered to v77", "claimed
by parallel waves") — just say "Migration v79 adds X." If the user
cares about migration ordering, they read the diff.
- Round counts, finding counts, decision counts ("25 findings across 2
rounds", "8 architectural decisions", "5/6 expansions accepted").
- Names of internal collaborators ("codex caught", "the reviewer flagged",
"Claude noticed").
- "Plan + reviews" summary bullets. The plan lives in `~/.claude/plans/`;
if a future reader wants the backstory they can grep there.
- Any wording that frames a shipped feature as a *recovery* from a planning
mistake ("the first plan was wrong", "we corrected the approach", "the
shipped version supersedes the original design").
**Smell test:** read the entry as a stranger who has never touched gbrain.
If any sentence makes them think "why are you telling me this?", cut it.
Every sentence in the release-summary AND in the itemized changes must
answer one of three questions: *What can I now do? How do I use it? What
should I watch for after I upgrade?*
Every version entry in `CHANGELOG.md` MUST start with a release-summary section in
the GStack/Garry voice — one viewport's worth of prose + tables that lands like a
verdict, not marketing. The itemized changelog (subsections, bullets, files) goes
BELOW that summary, separated by a `### Itemized changes` header.
The release-summary section gets read by humans, by the auto-update agent, and by
anyone deciding whether to upgrade. The itemized list is for agents that need to
know exactly what changed.
### Release-summary template
**Iron rule: lead ELI10, get precise after.** The first ~150 words of every entry
must be readable by someone who does NOT know gbrain's internals. No file paths,
no function names, no internal constants, no acronyms (no "RRF", no "knobsHash",
no "MODE_BUNDLES", no "CDX-4"), no jargon that requires reading the codebase to
parse. Lead with the user-visible behavior change, in everyday English, like
you're explaining it to a smart engineer who has never opened the repo.
THEN, once the reader knows what shipped and why they'd care, drill into the
precise details: real file paths, real function names, real config keys, real
numbers. The precision part is required (the entry is also the technical record
of what changed), but it lives AFTER the plain-English lead, never before it.
The shape:
1. **One-line bold headline.** What changed for the user, in human English. No
jargon. No internal terms. Example good: "Your search stops boosting weak
pages just because they have a lot of links pointing at them." Example bad:
"PostFusionOpts gains floorRatio; KNOBS_HASH_VERSION bumped 2→3."
2. **Plain-English opener** (~3-5 sentences). Describe the problem this fixes in
everyday terms. Pretend the reader has a brain full of meeting notes and
people pages and wants to know if this release helps them. Concrete example
beats abstract description.
3. **A "How to turn it on" or "How to use it" section** with paste-ready
commands. Real flags, real config keys. This is where precision starts.
4. **A "What you'd see in a concrete example" or "The X numbers that matter"
section** with a table. Use everyday-language column headers ("Page",
"Match quality", "Has many backlinks?") even when the underlying mechanism
is technical. The table teaches what the feature does without requiring the
reader to understand how.
5. **A "What's safe to know about" or "Things to watch" section** for caveats,
side effects, cache invalidation, mid-deploy notes. Still in plain language.
6. **A "What we caught and fixed before merging" section** if the work went
through review (CEO/eng/codex/outside-voice). Translate review findings into
plain English. "We caught a stale-cache bug" beats "knobsHash() did not
include floorRatio in the v=2 hash input."
7. **`### Itemized changes`** (precision lives here). File paths, function
names, types, constants, line numbers. This section is for engineers who
need to know exactly what moved.
Voice rules (apply throughout):
- No em dashes (use commas, periods, "...").
- No AI vocabulary (delve, robust, comprehensive, nuanced, fundamental, etc.) or
banned phrases ("here's the kicker", "the bottom line", etc.).
- Real numbers, real file names, real commands AFTER the ELI10 lead. Not "fast"
but "~30s on 30K pages." In the ELI10 lead, "fast enough that you won't
notice" or "~30 seconds even on a big brain."
- Short paragraphs, mix one-sentence punches with 2-3 sentence runs.
- Connect to user outcomes: "the agent does ~3x less reading" beats "improved
precision."
- Be direct about quality. "Well-designed" or "this is a mess." No dancing.
**The smell test:** if someone who has never opened gbrain reads the first 150
words and walks away knowing what shipped and whether they care, the entry
passes. If they need to grep the codebase to follow along, rewrite the lead.
**Canonical examples in this CHANGELOG:** v0.35.6.0 (floor-ratio gate, written
ELI10-lead-first), v0.34.4.0 (embed stale fix wave). Use those shapes when in
doubt. Avoid the shape of entries that lead with internal constants or release
mechanics; those exist in older history but should not be the model for new
work.
Source material to pull from:
- CHANGELOG.md previous entry for prior context
- Latest `gbrain-evals/docs/benchmarks/[latest].md` for headline numbers (sibling repo)
- Recent commits (`git log ..HEAD --oneline`) for what shipped
- Don't make up numbers. If a metric isn't in a benchmark or production data, don't
include it. Say "no measurement yet" if asked.
Target length: ~250-350 words for the summary. Should render as one viewport.
### "To take advantage of v[version]" block (required, v0.13+)
After the release-summary and BEFORE `### Itemized changes`, every `## [X.Y.Z]`
entry MUST include a human-readable self-repair block under the heading
`## To take advantage of v[version]`.
Why: `gbrain upgrade` runs `gbrain post-upgrade` which runs `gbrain apply-migrations`.
This chain has a known weak link — `upgrade.ts` catches post-upgrade failures as
best-effort (so the binary still works). When that chain silently fails, users end
up with half-upgraded brains. The self-repair block gives them a paste-ready
recovery path; the v0.13+ `~/.gbrain/upgrade-errors.jsonl` trail + `gbrain doctor`
integration close the loop.
Template (adapt the verify commands per release):
```markdown
## To take advantage of v[version]
`gbrain upgrade` should do this automatically. If it didn't, or if `gbrain doctor`
warns about a partial migration:
1. **Run the orchestrator manually:**
```bash
gbrain apply-migrations --yes
```
2. **Your agent reads `skills/migrations/v[version].md` the next time you interact with it.**
[One sentence on whether headless agents need manual action, or whether the
orchestrator already handled the mechanical side.]
3. **Verify the outcome:**
```bash
[release-specific verify commands, e.g. `gbrain graph ... --depth 2`]
gbrain stats
```
4. **If any step fails or the numbers look wrong,** please file an issue:
https://github.com/garrytan/gbrain/issues with:
- output of `gbrain doctor`
- contents of `~/.gbrain/upgrade-errors.jsonl` if it exists
- which step broke
This feedback loop is how the gbrain maintainers find fragile upgrade paths. Thank you.
```
**Skip this block** for patches that are pure bug fixes with zero user-facing action
(rare). If the release has a schema migration, data backfill, or new feature the
user needs to verify, the block is required.
The v0.13.0 entry in CHANGELOG.md is the canonical example.
### Itemized changes (the existing rules)
Below the release summary, write `### Itemized changes` and continue with the
detailed subsections (Knowledge Graph Layer, Schema migrations, Security hardening,
Tests, etc.). Same rules as before:
- 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.
### Reference: v0.12.0 entry as canonical example
The v0.12.0 entry in CHANGELOG.md is the canonical example of the format. Match its
structure for every future version: bold headline, lead paragraph, "numbers that
matter" with BrainBench-style before/after table, "what this means" closer, then
`### Itemized changes` with the detailed sections below.
## Version migrations
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 (see `docs/guides/upgrades-auto-update.md`)
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.
## Migration is canonical, not advisory
GBrain's job is to deliver a canonical, working setup to every user on upgrade.
Anything that looks like a "host-repo change" — AGENTS.md, cron manifests,
launchctl units, config files outside `~/.gbrain/` — is a GBrain migration
step, not a nudge we leave for the host-repo maintainer. Migrations edit host
files (with backups) to make the canonical setup real. Exceptions: changes
that require human judgment (content edits, renames that break semantics,
host-specific handler registration where shell-exec would be an RCE surface).
Everything mechanical ships in the migration.
**Test:** if shipping a feature requires a sentence that starts with "in
your AGENTS.md, add…" or "in your cron/jobs.json, rewrite…", the migration
orchestrator should be doing that edit, not the user.
**The exception is host-specific code.** For custom Minion handlers
(host-specific integrations like inbox sweeps or third-party API scanners), shipping them as a
data file the worker would exec is an RCE surface. Those get registered in
the host's own repo via the plugin contract (`docs/guides/plugin-handlers.md`);
the migration orchestrator emits a structured TODO to
`~/.gbrain/migrations/pending-host-work.jsonl` + the host agent walks the
TODOs using `skills/migrations/v0.11.0.md` — stays host-agnostic, still
canonical.
## Schema state tracking
`~/.gbrain/upgrade-state.json` tracks which recommended schema directories the user
adopted, declined, or added custom. The auto-update agent
(`docs/guides/upgrades-auto-update.md`) 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
All GitHub Actions in `.github/workflows/` are pinned to commit SHAs. Before shipping
(`/ship`) or reviewing (`/review`), check for stale pins and update them:
```bash
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.
## GitHub releases (binary assets + self-update) — #3521
`.github/workflows/release.yml` publishes a GitHub release automatically for
**every VERSION bump that lands on master** (trigger: push to master touching
`VERSION`, plus `workflow_dispatch` for a manual first run or repair). No
manual tag push is part of the ship flow — the workflow reads `VERSION` (the
single source of truth), mints tag `v` at the pushed commit, titles
the release the same, uses that version's `CHANGELOG.md` entry as the notes
(`scripts/changelog-entry.sh`; falls back to a CHANGELOG link if the entry is
missing), and attaches the compiled binaries.
The executable build job pins Bun 1.4.4, the first release with the Brotli fix
for CVE-2026-111497 (#7373): a standalone binary embeds the Bun it was built
with, so never pin a build below it. The job verifies the Darwin artifact with
strict native `codesign` before publishing it. A source merge does not repair
already-published bad binaries; an affected release needs its own explicitly
approved recovery and asset verification. The template and plugin publishing
jobs pin the same Bun version.
### Release CI gate
The `ci-gate` job (`scripts/release-gate.ts`) holds build, publication and the
`latest-stable` move until the push-to-master runs of Test and E2E Tests both
succeed on the release commit.
- **Failed run:** nothing is published and the job fails with the run and the
master-red issue. After master is green again, publish the current VERSION
with `gh workflow run release.yml --ref master`.
- **Run cancelled by a newer push:** the gate follows the next master commit.
If it contains the release commit and carries the same VERSION, that commit
is gated and published. If VERSION moved on, this version is skipped and the
newer VERSION's release run publishes.
- **Backfill:** `gh workflow run release.yml --ref master` gates and publishes
master HEAD's VERSION. Other refs are refused.
- The gate waits up to 110 minutes, then fails with the backfill command.
- **Reused push run:** a push run that reused a passed full-suite run of its
exact tree ([master-push reuse](ci-event-parity.md#master-push-reuse))
publishes only with a readable `reuse.json` naming the same workflow, the
push head and a valid source run. The gate prints the reused run per
workflow and writes `test_reused_run_id` / `e2e_reused_run_id` (empty when
that workflow ran in full); the `ci-gate` job exposes both as outputs.
### The `latest-stable` tag
The **final step of the release job** force-advances the `latest-stable` tag to
the gated release commit (`git push origin "+${RELEASE_SHA}:refs/tags/latest-stable"`).
`latest-stable` is the single sanctioned distribution ref: the README paste
block, the `BOOTSTRAP_FOR_AGENTS.md` fetch URL, and
`bun install -g github:garrytan/gbrain#latest-stable` all reference it
permanently, so paste blocks copied into the wild never rot and there is no 404
window between VERSION landing and assets publishing.
`scripts/check-bootstrap-tag.sh` keeps the entry docs pinned to this ref.
Because it moves ONLY after binaries + provenance attestation have fully
published, a half-built release never advances it. If the tag-advance step
alone fails, re-advance by hand (a full workflow re-run would skip — the
release already exists with all assets):
```bash
git push origin "+refs/tags/v^{commit}:refs/tags/latest-stable"
```
### The `publish-template` job
After the release job, a `publish-template` job force-pushes the rendered
agent-workspace template repo (the GitHub "Use this template" door,
`vars.TEMPLATE_REPO`, default `garrytan/gbrain-agent-template`) from CI only —
no human pushes it by hand, so what adopters clone is exactly what this repo
reviewed. It is guarded three ways: the release above fully published; the
vendored tree `templates/bootstrap/template-repo/` exists (skip, never fail,
if not); and the `TEMPLATE_REPO_PAT` secret is configured (skip if not).
Before pushing, it regenerates the template tree
(`bun run scripts/generate-template-repo.ts`) and byte-diffs it against the
vendored copy — a mismatch fails the job; regenerate + commit the vendored
tree (`scripts/check-bootstrap-templates.sh` runs the same diff offline in
`bun run verify`).
**`TEMPLATE_REPO_PAT` scope:** a fine-grained PAT with `contents: write` on
the template repository ONLY — no other repositories, no other permissions.
Configure it as a repo secret; when absent, template publishing is disabled
and the job skips cleanly.
Why every bump, not selective: `gbrain check-update` resolves the latest
version from `VERSION` on master, while binary self-update
(`src/core/binary-self-update.ts`) downloads assets from `releases/latest`.
Any release that lags `VERSION` tells binary installs an upgrade exists that
self-update cannot apply. `releases/latest` must track `VERSION`.
Invariants:
- **Asset names are a contract.** The build matrix's `artifact:` names must
equal what `expectedAssetName()` in `src/core/binary-self-update.ts`
returns (`gbrain-darwin-arm64`, `gbrain-linux-x64` today). Adding a
platform means updating BOTH plus the version job's completeness check;
`test/release-workflow.test.ts` pins all of it.
- **Idempotent + self-repairing.** The version job skips when a release for
`v` already exists with all expected assets; a partial release
(tag but no release, or missing assets) is completed on re-run. Racing
master pushes queue via the `release` concurrency group — a skipped
intermediate version is fine, latest is what matters.
- **Historical tags are never rewritten.** Old 3-segment versions keep their
history; every new 4-segment `VERSION` mints a fresh tag.
- **Permissions stay scoped.** `contents: write` lives on the release job
only; everything else runs read-only.
- **Never advance `latest-stable` on a partial release.** The tag moves only
as the final release-job step, after every asset has published. Manual
re-advances must point at a fully published `v` release.
## PR descriptions cover the whole branch
Pull request titles and bodies must describe **everything in the PR diff against the
base branch**, not just the most recent commit you made. When you open or update a
PR, walk the full commit range with `git log --oneline ..` and write the
body to cover all of it. Group by feature area (schema, code, tests, docs) — not
chronologically by commit.
This matters because reviewers read the PR body to understand what's shipping. If
the body only covers your last commit, they miss everything else and can't review
properly. A 7-commit PR with a body that describes commit 7 is worse than no body
at all — it actively misleads.
When in doubt, run `gh pr view --json commits --jq '[.commits[].messageHeadline]'`
to see what's actually in the PR before writing the body.
## Community PR wave process
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. Run
`bun run audit:contributors .. --prs ` to re-prove,
per merged change and per open PR (trial-merged), that its tests fail with its product
hunks reversed; the tool pins the PR heads into `prs.pinned.json` so a rerun tests the
same code, and its Markdown table keeps mechanical results apart from your verdicts
(see [Contributor audit](TESTING.md#contributor-audit)). Paste the table into the wave
PR body.
5. **Security review** — run `bun run wave-security-scan ..` over the
collector branch (the repeatable mechanical sweep). It ALARMS on newly-introduced
obfuscation/eval in code, secrets found by gitleaks **with the test/skills allowlist
stripped**, and any committed `admin/dist` change (the bundle-backdoor artifact); new
outbound endpoints, spawns, env reads, and dependency changes print as context. Exit 1
means "eyeball before shipping," not "unsafe" — read the ALARM rows and the context lists,
and confirm each is benign. Link the result (or a one-line "clean") in the wave PR body.
This is the standard's teeth: a wave PR body that claims "security reviewed" must have run
this. It is a net, not a proof — a human still reads the diffs.
6. **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. In the wave PR body, put each folded-in contributor PR on a
`Supersedes #N` line and each fixed issue on a `Fixes #N` line: when the wave merges,
the [fix-wave closeout](#fix-wave-closeout) closes those PRs with a thank-you comment and
GitHub closes the issues. Write `Addresses #N` or `Refs #N` for anything only partly
done, so it stays open. Close declined or duplicate PRs by hand, with the reason.
7. **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.
### Fix-wave gate
`.github/workflows/fix-wave-gate.yml` (job `contributor-gate`) fails every PR into
master unless its head repository is `garrytan/gbrain` or the `maintainer-override`
label counts. Only maintainers can push to `garrytan/gbrain`, so GBRA thread PRs
(`capy/*`) and `garrytan/*` branches pass; fork PRs fail whatever their branch is
called. When a contributor PR opens, a second job posts one comment with the same
text as the failure: the work is welcome and the PR stays open, it lands through a
fix wave with credit (`Contributed by @handle` plus a `Co-Authored-By:` trailer), and
CONTRIBUTING.md "Where does my change go?" explains where changes belong.
The workflow uses `pull_request_target`, so the workflow and
`scripts/fix-wave-gate.ts` always come from the default branch: a PR that edits
either cannot change its own result. It reads only the event payload and the PR
timeline, never PR code, with `permissions: {}` at the top, `pull-requests: read`
for the gate and `pull-requests: write` only for the comment job. A null head
repository (deleted fork) fails closed. The check re-runs on `opened`, `edited`,
`reopened`, `synchronize`, `labeled` and `unlabeled`.
**`maintainer-override` label.** Who: a human on `MAINTAINERS` in
`scripts/fix-wave-gate.ts` (starts as `garrytan`; changing it is a reviewed PR to
master). When: only for a PR a maintainer has decided may land from its fork, such as
a fix wave a maintainer opened from a fork; record the reason in a PR comment. How it
is checked: the label counts only when the most recent `labeled` timeline event for it
was made by an allowlisted `User`; bots (`capy-ai[bot]`, `github-actions[bot]`, any
`[bot]` login) never qualify, and removing the label fails the PR again. Audit: the run
log prints a `notice` naming who applied the label, when, and the timeline event id,
and the step summary repeats it.
**Turning it on (repository settings, maintainer only).** The guard is active only
after this step; until then the check is advisory. Settings → Rules → Rulesets (or
Settings → Branches → the `master` protection rule) → Require status checks to pass →
add `contributor-gate` with GitHub Actions as the source → save. The check must have
run once on any PR before GitHub offers it in the picker.
**Residual risk.** A same-repo branch (`capy/*` or `garrytan/*`) that carries
contributor commits passes by design. Keeping contributor work inside a revised fix
wave on those branches stays a policy rule, enforced by review, not by this check.
### Fix-wave closeout
`.github/workflows/fix-wave-closeout.yml` (job `close-superseded`) runs when a PR
into master closes. If it merged and its head repository is `garrytan/gbrain`,
`scripts/fix-wave-closeout.ts` reads the merged PR's body and closes every open pull
request named on a `Supersedes #N` line (`Supersedes #5085`, `- Supersedes #5089,
#5096 and #5107`, `**Supersedes:** #5113`). Only the list right after the keyword
counts, so `Supersedes #5140, which conflicts with #5000` closes #5140 alone. Each
closed PR gets one comment, keyed by ``, that thanks the
contributor, links the wave, and says the work landed with credit when the wave body
contains `Contributed by @`. Numbers that are issues or already-closed
PRs are skipped. A failed close is a warning in the run log, and the step summary
lists every number with what happened to it. One run closes at most 50 PRs.
Issues need nothing extra: `Fixes #N` in the same body closes them through GitHub.
Before this workflow, contributor PRs stayed open after their wave merged, which is
most of why the open-PR count grew. To preview a body locally without writing
anything, save the event payload and run
`bun scripts/fix-wave-closeout.ts --event --dry-run`.
Like the gate, it uses `pull_request_target`: the workflow and script come from the
default branch, it sparse-checks-out only the script, and it never checks out or
runs PR code. Permissions are `{}` at the top and `contents: read` plus
`pull-requests: write` for the one job.
## Checking out PRs from garrytan-agents
`garrytan-agents` is the AI-authored PR account and is NOT a collaborator on
this repo. Its PRs live in a fork, so GitHub Actions triggered by
`pull_request` events on those PRs do not receive base-repo secrets. Any CI
job that needs `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or similar will fail
with empty-env auth errors, regardless of what's set on the base repo. This
is a GitHub security default, not a config bug.
When the user says "check out " and the PR is from `garrytan-agents`
(or any other non-collaborator fork), move the branch into the base repo
before running CI:
1. `gh pr checkout ` — pull down the fork's branch. Note the PR number and
head branch name (`gh pr view --json headRefName --jq .headRefName`).
2. `git push origin HEAD:` — push the same branch to the base
repo (origin points at `garrytan/gbrain`, not the fork). This is the move
that gives CI access to secrets.
3. `gh pr close --comment "moving to base-repo branch for secret access"`
— close the fork PR so the queue stays clean.
4. `gh pr create --base master --head ` — open the replacement
PR from the base-repo branch. **Preserve the original PR's title and body
verbatim** (`gh pr view --json title,body`); contributor attribution
moves to a `Co-Authored-By:` trailer if needed.
Why this over alternatives: adding `garrytan-agents` as a collaborator, or
flipping the repo-wide "send secrets to fork PRs" toggle, both broaden
secret distribution to every fork PR from that account or any fork. Moving
the branch keeps secret scope tight to just the one PR being shipped.
## ClawHub bundle plugin publish (manual)
`openclaw.plugin.json` makes this repository a ClawHub bundle plugin (see
[docs/mcp/OPENCLAW.md](mcp/OPENCLAW.md)). Publishing a new version to ClawHub is
a manual step outside `release.yml`, run from a clean checkout of the release
tag by an owner with an authenticated `clawhub` CLI:
```bash
bun run prepublish:clawhub # bun run build:all: bin/gbrain-darwin-arm64 + bin/gbrain-linux-x64
bun run publish:clawhub # clawhub package publish . --family bundle-plugin
```
`build:all` compiles only those two targets; the full binary matrix ships
through the GitHub release job above. ClawHub users upgrade with
`clawhub update gbrain`, which `gbrain upgrade` runs for ClawHub installs.
## Plugin dist tree (codex/claude lanes)
The committed `plugin/` and `plugin-variants/` trees embed the VERSION stamp
(the variants' generated plugin manifests carry it too), so a release bump
drifts them. After bumping VERSION/package.json, run `bun run
scripts/generate-plugin-tree.ts --out plugin --variants-out plugin-variants`
and stage `plugin/` + `plugin-variants/` + `skills/plugin-lanes.json`.
`scripts/check-plugin-tree.sh` (in `bun run verify`) and the release
`publish-codex-plugin` job both fail on drift.
When personas change in `skills/plugin-lanes.json#personas`, also hand-edit
`.claude-plugin/marketplace.json`: the variant entries must match the
personas block exactly (`test/codex-plugin-manifest.test.ts` pins the
mapping, so a persona added without a marketplace entry fails the suite).
---
### TESTING (`docs/TESTING.md`)
# Testing (gbrain repo)
This is the contributor reference for how gbrain is tested: which lanes exist,
what each one proves, how CI runs them, and the guards that keep those claims
honest. It describes current behavior and invariants only. Release history
lives in `CHANGELOG.md`; per-file detail lives in the test files and in
`docs/architecture/KEY_FILES.md`.
## Quick start
Prerequisites: Bun 1.4.0 or newer (CI pins 1.4.4), Git, and bash. E2E needs
Docker for a `pgvector/pgvector:pg16` container and Python 3 on `PATH` (the E2E
runner validates Bun's JUnit reports with the standard-library XML parser).
```bash
bun install --frozen-lockfile && bun run test && bun run verify
```
`bun run test` is the parallel unit loop plus the serial pass (a few minutes on
a laptop); `bun run verify` is CI's guard battery (about a minute). For E2E,
follow [E2E test DB lifecycle](#e2e-test-db-lifecycle-always-follow-this) and
run `DATABASE_URL=postgresql://postgres:postgres@localhost:5434/gbrain_test bun run test:e2e`.
`bun run ci:local` runs the whole CI gate in Docker; `bun run ci:ubicloud` runs
it on ephemeral VMs in about five minutes.
A failing `bun run test` writes every failure block to
`.context/test-failures.log`, one line per shard to `.context/test-summary.txt`
and executed-test receipts to `.context/test-receipts/`; the banner prints the
log's absolute path. A failing `bun run verify` keeps each failed check's log
and prints it. In CI, each red job's step summary lists the failing tests with a
`bun test … -t` reproduce command.
**Red CI on master:** [CI red runbook](ci-red-runbook.md).
| File suffix or location | Lane | Command | Runs in PR CI |
|---|---|---|---|
| `*.test.ts` | unit (parallel shards) | `bun run test` | yes, 10 weighted shards |
| `*.serial.test.ts` | serial (one process per file; listed in `scripts/serial-files.tsv`) | `bun run test:serial` | yes, 4 pooled workers |
| `*.slow.test.ts` | slow (cold paths, long workloads) | `bun run test:slow` | named jobs and unit shards |
| `test/e2e/*.test.ts` | E2E (real Postgres) | `bun run test:e2e` | yes, Selected E2E plus named jobs |
| `*.live.test.ts`, `test/live/` | paid provider calls | named per file (see [API keys](#api-keys-and-running-all-tests)) | no |
| `tests/heavy/*.sh` | ops-shape shell scripts | `bun run test:heavy` | label `heavy-tests` and nightly |
| `admin/e2e/*.pw.ts` | browser | `bun run test:admin` | yes, `admin-browser` |
## CI runner capacity
Repository-owned Linux validation jobs use ephemeral Ubicloud runners pinned to
Ubuntu 24.04. The Ubicloud Managed Runners GitHub App must have access to this
repository and active billing in its connected project; runner labels alone do
not grant access. No Ubicloud API token is passed to workflow jobs.
| Workload | Runner | Capacity |
| --- | --- | --- |
| Unit shards, slow and eval jobs, BrainBench, admin browser, shared-skills compatibility, persistence soak, reconciliation crashes and read latency, native Linux cells, OpenClaw startup, JSONB parity, PR serial pool, E2E backend matrix, Tier 2, coverage reports and Semgrep | `ubicloud-standard-4-ubuntu-2404` | 4 vCPU, 16 GB RAM |
| Nightly coverage serial pool, `verify`, PgBouncer/RLS deployment matrix | `ubicloud-standard-8-ubuntu-2404` | 8 vCPU, 32 GB RAM |
| E2E Tier 1 (its CLI `init` spawns exceed their timeouts on 4 vCPUs), label-gated and nightly heavy-tests jobs | `ubicloud-standard-16-ubuntu-2404` | 16 vCPU, 64 GB RAM |
| Label-gated heavy test suite | `ubicloud-standard-30-ubuntu-2404` | 30 vCPU, 120 GB RAM |
| Native ARM64 glibc and musl tests | `ubicloud-standard-4-arm-ubuntu-2404` | 4 vCPU |
| Selected E2E (one Bun process each), planning, status aggregation, dependency audit, gitleaks, security regressions and actionlint | `ubicloud-standard-2-ubuntu-2404` | 2 vCPU, 8 GB RAM |
macOS and Windows matrices stay on GitHub-hosted runners. Release building and
publishing also stay unchanged. The pinned upstream OSV reusable workflow does
not expose a runner override, so its runner remains upstream-owned.
Sizes come from measured CPU use, not guesses. Each Ubicloud project shares one
vCPU quota between pull-request CI and agent `ci:ubicloud` VMs, so an oversized
runner makes every other job wait, and an undersized one lengthens the PR
critical path. A unit shard is one Bun process that averages 1.1-1.5 busy
cores, so two shards share each 4-vCPU runner; on 2 vCPUs one shard's mean
rose from 542s to 608s and made Test the critical path. On matched
VMs a unit shard takes the same time on 4, 8 and 16 vCPUs; the serial pool and
`verify` take the same time on 8 and 16 vCPUs (serial shard 2: 222s and 224s;
277s on 4); the 2,500-write PGLite soak averages 1.3-1.8 busy cores and takes
523s on 4 vCPUs and 500s on 16. Selected E2E workers run one file at a time and
fit on 2 vCPUs. Re-measure with `scripts/ubicloud/ubi-runner.sh run -s standard-N`
before resizing a runner: more CPU does not shorten a single-process job, and
the decision rule is critical path first, vCPU-minutes second.
`test/scripts/ci-runner-routing.test.ts` pins capacity and platform routing;
`.github/actionlint.yaml` declares the exact custom runner labels.
### Event parity
Every test file and Bun cell runs on each push to master, nightly, on manual
dispatch and in the merge queue. A pull request runs the cheap tier;
merge needs `full-suite` and `e2e-full-suite` from a full run on its head
([full CI for PRs](ci-event-parity.md#full-ci-on-pull-requests)).
Each narrower PR behavior is a named exception whose comment names the run
covering it (`test/scripts/ci-pr-scope.test.ts` fails on an unclassified one).
Table, audit rule and cost: [docs/ci-event-parity.md](ci-event-parity.md).
The `changes` job classifies a pull request's changed files with
`scripts/ci-native-scope.sh`: native lock sources, the native toolchain, IPC,
persistence, publication, backup, export and sync sources, their native tests,
`package.json`, `bun.lock` and the workflow files select every target; a
`package.json` or `openclaw.plugin.json` diff that changes only the version
does not (`scripts/ci-manifest-diff.sh`). An unreadable file list selects
every target too. Skipped cells never report a
failure: `test-status` needs the `native-locks` and `persistence-validation`
workflow calls, which succeed when their remaining cells do, so the required
check names are unchanged. `test/scripts/ci-pr-scope.test.ts` pins every scope.
Shared persistence suites use `test/helpers/test-backends.ts`: direct invocation
defaults to PGLite, and a safe `DATABASE_URL` opts into both engines. Their E2E
wrappers select PostgreSQL before registering tests, refusing a missing or unsafe
database instead of silently running only the local backend. Backend selection is
captured at registration so hooks retain it after the import environment restores.
Every backend's assertions remain in the shared suites; engine-specific cases run
in their owning lane.
Ordinary PostgreSQL `setupDB()` clears fixture data, operator configuration and
source sync identity while retaining `config.version` and the stored embedding
identity, avoiding historical migration
replay against an already-current schema. Migration-focused fixtures use
`setupDB({ replayMigrations: true })`; an absent ledger also runs the cold chain.
`test/e2e/fixture-reset-postgres.test.ts` checks both paths, cleanup and vector-shape
preservation, including the deliberate legacy-width restoration helper. That
helper aligns both the physical columns and stored embedding identity with the
legacy test configuration; ordinary resets preserve that identity.
Shared-skills suites, the old-binary compatibility job and the lifecycle benchmark are described in
[scripts/shared-skills/README.md](../scripts/shared-skills/README.md#tests-and-ci).
### Executed-test receipts
A green job proves only that nothing failed; receipts prove which tests ran.
With `GBRAIN_TEST_RECEIPT_DIR` set, every Bun invocation a runner makes
(`test-shard.sh`, `run-unit-shard.sh` per file, the parallel wrapper's rescue
pass, `run-serial-tests.sh` pooled runs and rescues, `run-slow-tests.sh`,
`run-e2e.sh`, and bare `bun test` CI steps through
`scripts/run-with-receipt.sh -- bun test …`) writes one receipt:
`.receipt` (lane, kind `primary|rerun|rescue`, shard, backend arm, commit,
run attempt, exit code), `.files` (the assigned files) and Bun's native
JUnit report. `GBRAIN_TEST_RECEIPT_LANE` overrides the runner's lane name.
`scripts/lib/test-env.sh` (`receipts_init`) reads both variables and unsets
them, so tests and nested runners never inherit them. `bun run test` writes
receipts to `.context/test-receipts/` by default, cleared per run.
`bun run verify` records each check as pass, fail, timeout or skip in
`/outcomes.tsv` and in a JUnit receipt. A check that skips itself
prints `GBRAIN_CHECK_SKIPPED: ` and exits 0; the recorder counts it as
a skip, never a pass. Verify keeps its per-check logs when a check fails.
`scripts/ci-executed-counts.ts` is the ledger. It accounts for every executed
test by identity, (lane, file, test name, backend arm); repeated names inside
a file are numbered by order (`name [#2]`). One side prints the per-lane
executed/skipped/failed table and every completeness problem; two sides also
list every base identity that no longer executes in head:
```bash
bun scripts/ci-executed-counts.ts --head-run ,
bun scripts/ci-executed-counts.ts --base-run , --head-run , --summary pr-table.md --json ledger.json
bun scripts/ci-executed-counts.ts --base-dir --head-dir
```
A comparison is `incomplete`, and fails, when an assigned file has no valid
JUnit from any attempt, a report is truncated or comes from an earlier run
attempt, a shard is missing, a lane executed zero tests, or a base artifact is
missing from head. A later rescue or rerun supersedes an earlier attempt for
the files it re-ran. A dropped identity passes only when
`docs/test-audit/2026-10-04/expected-deltas.tsv` declares it as `retire`
(with a Retiring-a-test evidence pointer), `move` (new lane, file or test
name), `skip` or `job`; otherwise the tool prints the exact row to add. New
tests need no row. `--fail-on-additions` compares two baseline runs for
stability. Both workflows upload `receipts-` artifacts, and the
report-only `executed-receipts` job writes the ledger table to the step
summary.
Failure reporting rides the same machinery. `scripts/capture-test-log.ts`
adds the last 50 failures to a red job's step summary (file, test, backend
arm, first error block and a `bun test … -t` reproduce command), falling back
to the log tail when no `(fail)` line exists. `run-e2e.sh` kills and names any
process still running under a file's `HOME`, and fails that file by name when
its `HOME` cannot be removed. Coverage lanes write `executed-files.txt` on red
runs too; `lane-manifest.json` is written only on a green run.
### Canonical reconciliation
Canonical reconciliation, durable `put_page` acceptance and required-write suites are described next to
their harness in [scripts/persistence/README.md](../scripts/persistence/README.md#test-suites).
### Search and transport regressions
Real-planner search regressions run on Postgres:
`test/e2e/vector-candidate-safety-postgres.test.ts` (natural plans against
forced-HNSW controls, server cancellation of exact fallback),
`test/e2e/search-query-contract-postgres.test.ts`,
`test/e2e/projection-statistics-postgres.test.ts` (owner, restricted-reader and
FORCE-RLS roles) and `test/e2e/vector-plan-real-column-postgres.test.ts`, which
needs CREATEDB and `CREATE EXTENSION vector` for its dedicated 64-dim database
so runs under `bun run ci:local`. Their PGLite and SQL-shape counterparts
are `test/search/vector-freshness.test.ts` and
`test/search/vector-statement.test.ts`; `scripts/bench/vector-plan-5824.ts` is
the opt-in reporter-scale bench. `test/e2e/projection-recovery-parity.test.ts`
runs the shared recovery contracts and `symbol-resolver-projection-race.test.ts`
on Postgres; PGLite work caps never count a Promise race as cancellation
evidence. `test/pglite-in-memory-create-retry.serial.test.ts` mocks the PGLite
module (own process) to pin one cold retry before an in-memory database opens.
OAuth transport contracts live in `test/e2e/serve-http-oauth.test.ts` and
`test/oauth-scope-hint.test.ts`; each file's header lists its cases.
### Performance-change parity
`bun run bench:parity `; see `scripts/bench/contract-parity.ts`.
### Coverage responsibilities before consolidation
Assign ownership to an **assertion and its execution boundary**, not to a test
filename or a shared helper. Record the contract, backend, runtime version,
OS/architecture/libc, source-versus-compiled artifact, transport/authentication,
process/storage/crash boundary, workload size and required cadence. Shared
scenario code across two engines is not duplicate engine coverage: PostgreSQL
JSONB, locking and pooler behavior are not established by a PGLite pass.
| Responsibility | Execution owner | What it does not establish |
|---|---|---|
| Keyless behavior, structural guards and shared contracts | Unit shards and `verify` in `test.yml`; process-isolated serial and dedicated slow lanes where required | Real PostgreSQL, native activation or compiled behavior |
| PostgreSQL behavior and engine parity | Selected E2E and named jobs in `e2e.yml`; the complete nightly runner corpus | Execution of key-gated or native-door assertions merely because their files were discovered |
| Durable publication and recovery under sustained load | `persistence-validation.yml` and `scripts/persistence/README.md` | Power-loss safety, production authentication or equivalence to two smaller databases |
| Native lock ABI and compiled-process exclusion | `native-locks.yml`, compiled smoke and release validation | All compiled CLI features or native-harness activation |
| Browser journeys | Required `admin-browser` job and `admin/e2e/*.pw.ts` | Vendor-native agent behavior |
| Native agent doors and heavier operational scenarios | Explicit jobs in `heavy-tests.yml` | A passing skipped door or generic protocol test is not native activation |
| Live-provider and optional recipe/eval behavior | Their explicitly configured opt-in commands/jobs | A missing key, early return or skipped assertion is not live-provider evidence |
| Line-coverage accounting | PR `prCorpus` and nightly `fullCorpus` reports | Subprocess coverage, all platforms or proof that every discovered case executed |
Before removing repeated work, identify the surviving owner for the same
contract **and every relevant boundary**, prove that owner actually executes,
and retain its cadence, failure gate and coverage artifacts. A shared fixture
can reduce maintenance while keeping both engine arms. Making one crash lane
authoritative or collecting LCOV in a named owner requires a separate ownership
change; nightly sharding alone makes neither change.
The 2026-09-29 test audit's lane reports, inventories and mutation-probe logs
are committed under [docs/test-audit/2026-09-29/](test-audit/2026-09-29/README.md);
cite them for the surviving-owner and probe evidence behind a consolidation.
Recorded ownership changes:
- `test/e2e/reconcile-crash.test.ts` and `test/e2e/reconcile-crash-unactivated.test.ts`:
the PR owner is `persistence-validation.yml`, called from `test.yml` on every
PR on both supported Bun versions against pg16. Its "Require all
reconciliation crash boundaries" step runs both files by name and uploads the
crash manifests, unchanged. Both files are in `E2E_EXCLUSIONS`
(`PERSISTENCE_VALIDATION_OWNED` in `scripts/e2e-matrix.ts`), so PR
`selected-e2e` does not run them a second time; `scripts/e2e-matrix.ts`
prints `excluded: (owned by persistence-validation.yml)` on stderr. The nightly full-corpus E2E run and the local gates
(`ci:local`, `ci:ubicloud`, their `:diff` forms) still run them. Run them
locally with the same command the workflow uses, with `DATABASE_URL`
exported for the test database from "E2E test DB lifecycle":
```bash
GBRAIN_TEST_ALLOW_DATABASE_URL=1 \
GBRAIN_TEST_RECONCILE_CRASH_MANIFEST_DIR=.context/reconcile-crashes \
bun --no-env-file test --timeout=180000 \
test/e2e/reconcile-crash.test.ts test/e2e/reconcile-crash-unactivated.test.ts
```
- Attendance parity (`test/attendance-retrieval.test.ts`,
`test/attendance-repair.test.ts`, `test/extract-timeline-attendance.test.ts`):
the unit lane owns the PGLite arm; the `test/e2e/*-postgres.test.ts` wrappers
load the scenarios through `registerPostgresTests`, so E2E runs only the
PostgreSQL arm.
Name the profile when reporting “all tests.” The local fast loop, `test:full`,
`ci:local`, required PR checks and nightly `fullCorpus` are not interchangeable
supersets. Native matrices, sustained persistence validation, browser tests and
optional recipe/eval commands have separate responsibilities. A faster nightly
E2E schedule does not shorten a PR critical path dominated by persistence.
Report matched executed timings separately from dry-run partition estimates,
including setup, queueing and retries; never count skip-only output as coverage.
#### Postgres-arm lanes
The unit, serial and slow lanes unset `DATABASE_URL`, so a test file whose
PostgreSQL arm is gated on it (a zero-argument `testBackends()` call, or a
`DATABASE_URL` read used as a condition or connection argument) runs that arm
only where a Postgres lane names it. Those lanes are: a workflow step that
runs with `DATABASE_URL` and names the file, a `test/e2e/` wrapper that
imports it (`registerPostgresTests`), a `tests/heavy/` script that names it,
or a row in `scripts/e2e-backend-matrix.txt`. Unit-lane files with no other
Postgres owner are listed in `test/postgres-unit-arms.txt`, read by
`persistence-validation.yml`'s `unit-postgres-arms` job (one Bun process per
file), the [race hunt](#race-hunt) and the lane guard.
`bun run check:postgres-lanes` (in `verify`) fails on every arm with no lane
and on a bad list row. An arm deliberately left out is an `ALLOWLIST` row in
`scripts/check-postgres-lane-coverage.ts` naming its reason and TODO; a row
for a file that is laned, has no arm or is gone fails.
### Stress gate
`stress-changed-tests` (in `test-status`) runs each touched test file 10x on fresh databases; local twin `bun run test:stress`. Details: [scripts/stress/README.md](../scripts/stress/README.md).
### Race hunt
Nightly: every listed Postgres arm 10x ([details](../scripts/stress/README.md#race-hunt)).
### Scale tier
The gate shape and cadence are defined once, by O-CEO-16 (with O-ENG-16 and
O-CEO-9) in the Foundations 1 plan; `scripts/scale/gates.ts` and
`.github/workflows/scale-tier.yml` implement it. This section says how to run it.
How to run it, what it measures, exit codes, the watchdog and the large-brain
ceilings: [scripts/scale/README.md](../scripts/scale/README.md). The import-rate
gate times PGLite by the import process's CPU time and Postgres by wall time;
the README says why.
### Authoring gate
Before adding a test, answer four questions in the PR description or the test
header:
1. What observable behavior or contract does it protect?
2. What credible regression makes it fail?
3. Why does existing coverage not already catch it?
4. Does it need a production seam that no production caller needs?
A regression test must fail when its fix is reverted; prove it with
`scripts/check-test-discriminates.sh` (see CONTRIBUTING.md). If question 1 has
no answer, or the answer to question 3 names an existing owner at the same
boundary, do not add the test.
Good: a test that runs `gbrain remote ping` against a fake MCP server returning
`{ status: 'failed' }` and asserts exit code 1 with the failure reason in the
JSON output. It protects a user-visible contract, fails if the poll loop reads
the wrong field, and needs no seam.
Bad: a test that reads `src/commands/remote.ts` and asserts it contains
`job.status`. It passes when the loop is broken in a way that keeps the token,
fails on a harmless rename, and duplicates the behavioral test above.
### Contributor audit
`bun run audit:contributors .. [--prs ] [--json]`
(`scripts/contributor-audit.ts`) re-proves discrimination for every
first-parent commit in the range and for each PR head in `--prs`, trial-merged
onto ``. In an isolated worktree of `` it runs the change's test
files, one Bun process per file as the unit loop does (green baseline required), reverses only that change's product hunks
(`git diff M^1 M -- | git apply -R`; tests and docs stay),
reruns, restores, checks the tree is identical and re-verifies green. Hunks
that no longer apply at `` are audited at the merge commit itself.
Results use the helper's vocabulary (`discriminates`, `does_not_discriminate`,
`vacuous_failure`) plus `setup_failed`, `conflict` and `not_audited`, with a
reason. Human verdicts (`accept`, `rework`, `reject`, `not_yet_proven`) live in
a separate `--verdicts` file and print in their own column. It also runs
`wave-security-scan` (range and each PR) and `check:postgres-lanes` (head and
each trial merge) from the trusted checkout; `--skip-security` and
`--skip-lanes` opt out.
Preflight checks Bun against `engines.bun`, the refs, gitleaks and python3,
and a `--postgres` database (which must be test-shaped). PR heads are pinned
into `/prs.pinned.json`; state and per-step logs live in the run dir
(default `.git/contributor-audit/-/`), so `--resume` skips finished
cases and refuses when refs or pins differ. `--step-timeout` (default 900s)
bounds each step. Exit: 0 clean, 1 needs a human look, 2 usage or preflight
refusal (an agent-contract envelope), 130 interrupted.
Untrusted code (install with `--ignore-scripts`, tests) runs under `env -i`
with an allowlist: temporary `HOME` and `GBRAIN_HOME`, no credential files,
`DATABASE_URL` and `GBRAIN_DATABASE_URL` empty unless `--postgres` is given,
`bun --no-env-file`. For stronger isolation, run the unit audit on an
ephemeral Ubicloud VM with outbound network blocked after `bun install`
(optional). First run: `bun scripts/contributor-audit-fixture.ts ` builds
an offline range covering each result. Tests:
`test/scripts/contributor-audit.test.ts`.
### Retiring a test
Delete or merge a test only with evidence, recorded in the PR body:
1. Name the contract the test claims to protect and classify the evidence case
below.
2. Probe it: make a behavior-breaking edit to the production code (or, for a
vacuous assertion, show that such an edit passes), run the test and the
surviving owner, then revert. Behavior-preserving edits that fail the test
are useful extra evidence of implementation coupling.
3. Confirm the surviving owner executes ([executed-test receipts](#executed-test-receipts), not skip output)
at the same or a more frequent cadence, with an equal or stronger failure
gate, per "Coverage responsibilities before consolidation" above.
4. Remove the deleted file's entries from `scripts/ubicloud/weights.json`,
`scripts/test-weights.json`, `scripts/serial-weights.json` and
`scripts/e2e-weights.json` (`bun run check:weight-coverage` fails on a
leftover), grep `scripts/` and `.github/` for the path, and regenerate `scripts/structural-suites.tsv`
(`bun scripts/classify-tests.ts`).
Evidence cases:
- **Retained contract:** the contract still matters. Evidence is a surviving
owner at the same boundary plus an executed mutation that fails it.
- **Intentionally abandoned contract:** the behavior is being removed or was
never shipped. Evidence is the approved disposition plus reachability proof
(no production caller) and a check that no user-facing promise (docs, skills,
`--help`, CHANGELOG) still describes it.
- **Vacuous assertion:** the test asserts nothing about product behavior (a
constant compared to itself, a copied function, a `typeof` probe that
typecheck already enforces). Evidence is a demonstration that a
behavior-breaking edit leaves it passing, or that it imports no product code.
Evidence template:
| Deleted test | Probe edit | Result | Surviving owner | Owner result |
|---|---|---|---|---|
| `test/x.test.ts` › "name" | `src/y.ts`: what changed | deleted test passes (blind) | `test/z.test.ts` › "name" | fails (N of M) |
### Test command tiers
The sequential E2E runner gives each test file a fresh `HOME` and `GBRAIN_HOME`.
Configuration written by a CLI initialization or schema migration remains
available within that file, but cannot change a later file's selected schema or
harness state. Each file's home is removed after it exits, including failures;
the runner's exit trap also cleans up interrupted runs.
Test command tiers, each with a clear scope:
| Command | What it runs | Wallclock | When to use |
|---|---|---|---|
| `bun run test` | Parallel unit loop (`scripts/run-unit-parallel.sh`): weighted shards (CPU-detected, 4 by default, at most 8; CI uses 10), then the serial pass. Excludes `*.slow.test.ts` and `test/e2e/*`; no typecheck. Builds the PGLite schema snapshot first and exports `GBRAIN_PGLITE_SNAPSHOT` (opt out: `GBRAIN_NO_SNAPSHOT=1`). Caps total concurrency to available memory at `GBRAIN_TEST_MEM_PER_FILE_MB` (default 1536) per slot, shedding intra-shard width before shards. Shards that fail with the WASM out-of-memory signature or are killed externally get one serial rescue pass: phantoms go green with an `oom_rescued` note, real failures stay red. Knobs: `GBRAIN_TEST_NO_MEM_ADAPT=1`, `GBRAIN_TEST_NO_OOM_FALLBACK=1`, `GBRAIN_TEST_MAX_CONCURRENCY` (default 4), `GBRAIN_TEST_SHARD_TIMEOUT` / `GBRAIN_TEST_SHARD_KILL_AFTER`, `--shards N` / `--max-concurrency N` / `--dry-run`. | a few minutes on a laptop | Inner edit loop. Default. |
| `bun run verify` | CI's authoritative pre-test gate set, fanned out by `scripts/run-verify-parallel.sh` through a bounded worker pool (default `detect_cpus`; override `GBRAIN_VERIFY_MAX_PARALLEL`) with the heavy checks ordered first (typecheck, the two compile-embed checks, admin build, fuzz bundles, whole-tree greps), then the self-timed `SOLO_CHECKS` alone ([why](operations/verify-and-nightly-e2e.md#verify-solo-checks)). Two evals ride the unit lane instead ([why](operations/verify-and-nightly-e2e.md#evals-in-the-unit-lane)). The `CHECKS` array in that script is the single source of truth — CI literally calls `bun run verify` in a dedicated job. | ~65-85s | Before pushing; before `/ship`. |
| `bun run test:full` | `verify && bun run test && bun run test:slow && [smart e2e]`. Smart e2e runs only when `DATABASE_URL` is set and propagates its failure; otherwise it prints a skip notice to stderr. Use `ci:local` to provision the databases and require PgBouncer execution. | ~3-5min depending on slow + e2e | Pre-merge sanity, before opening a PR. |
| `bun run ci:local` | Independent host gitleaks scans, then frozen dependencies, guards/typecheck, the complete serial and slow lanes, and four unit/E2E shards inside Docker. Each E2E shard has its own pgvector database; selected PgBouncer tests must execute against the transaction-mode pooler. Unit, serial, and slow lanes have database URL overrides unset. Any failed stage fails the command. Complete shard logs survive container teardown under `.context/ci-local-shards/`. `ci:local:diff` runs only gitleaks and the doc checks on a doc-only diff and the full gate otherwise; `--no-shard` runs unit/E2E sequentially. Doc-only diffs still require successful gitleaks scans. | Depends on the full corpus | Full local gate before shipping. |
| `bun run ci:ubicloud` | The `ci:local` lanes (gitleaks, guards/typecheck, serial, slow, unit, all E2E with required PgBouncer execution) fanned out across ephemeral Ubicloud VMs from one heaviest-first work queue; `ci:ubicloud:diff` takes the same doc-only fast path as `ci:local:diff`. Needs `UBICLOUD_API_KEY` or `UBICLOUD_API_TOKEN`, no local Docker. See "Ubicloud fan-out" below. | ~5 min | Full gate before shipping when a Ubicloud token is available. |
| `bun run test:slow` | Just the `*.slow.test.ts` set (intentional cold-path correctness checks). | seconds-to-minutes | When touching slow-path code. |
| `bun run test:serial` | The `*.serial.test.ts` set listed in `scripts/serial-files.tsv`, one Bun process per file, run through a pool of concurrent per-file processes (`min(detect_cpus, 4)`, memory-adapted) heaviest-first from `scripts/serial-weights.json` (absent weights fall back to the corpus p75; scheduling only). The `EXCLUSIVE_FILES` in `scripts/run-serial-tests.sh` (machine-global state, at most 3) run sequentially after the pool, on shard 1 only. Per-test timeout 120s; each pooled file is killed at 300s. `SHARD=N/M` partitions pooled files by duration. Externally killed files get one sequential rescue run. Knobs: `GBRAIN_SERIAL_POOL=N` (`1` is fully sequential), `GBRAIN_SERIAL_FILE_TIMEOUT`. | a few minutes at pool=4 | Debugging quarantined files; CI's serial-tests job. |
| `bun run test:e2e` | Real Postgres E2E. Requires Docker + `DATABASE_URL`. Sequential within a shard; `SHARD=N/M` fans out against separate databases (ci-local runs 4 containers). Activates the PGLite snapshot like every other runner (per-file cold-path opt-outs where the test asserts the path TO post-initSchema state), exporting it as an ABSOLUTE path so CLI children spawned with varying cwd still find it. | ~5-10min | Pre-ship; nightly. |
| `bun run test:compile-smoke` | Self-update integrity verify under a REAL `bun build --compile` binary, offline; also runs unconditionally in the serial lane. The unit suite mocks the network seams; this proves the dependency-free crypto/base64/JSON verify path survives compilation — the failure mode `sigstore-js` would have hit. | under 1s (one small compile) | When touching `src/core/binary-self-update.ts`; pre-ship on self-update changes. |
| `bun run regen:all` | Regenerates every generated artifact (schema, migrations registry, error-code docs, protocol blocks, tool catalog, skills manifest, structural suites, `llms.txt` last, and the others in `scripts/regen-all.ts`) offline and keyless, and lists what changed; a second run changes nothing. `--check` is read-only and runs in `verify` as `check:regen-all`. `--goldens` also regenerates the offline contract goldens, a deliberate act each PR justifies; Postgres goldens are named with their own commands. | about a minute | After any change a freshness check flags; before `/ship`. |
| `bun run test:agent-voice` | The agent-voice recipe's vitest unit suite (`recipes/agent-voice/tests/unit`), via `scripts/test-agent-voice.sh`: installs pinned vitest + ws into a temporary prefix and links it as the recipe's `node_modules` for the run. Needs node + npm and registry access. CI runs it in test.yml's verify job. | ~10s | When touching `recipes/agent-voice/`. |
| `scripts/ship-remote-tests.sh` | Pushes the branch, dispatches `test.yml` (or `--workflow`) on GitHub's runners for that branch or `--ref`, and waits with `gh run watch --exit-status`, so its exit code is the run's. Needs an authenticated `gh`; unlike `ci:ubicloud` it needs no Ubicloud credential and runs the workflow's own job inventory. | one CI run | Offloading the suite from a saturated local machine. |
| `bun run test:profile` | Reads a captured `bun test` log on stdin and prints the N slowest tests (`-n N`, default 10): `bun test 2>&1 \| bun run test:profile`. | seconds | Finding slow tests to fix or demote to `*.slow.test.ts`. |
| `bun run test:admin` | Pinned Playwright Chromium tests for the production embedded admin UI, served with an isolated temporary home/cwd and in-memory PGLite. Exercises owner login, OAuth consent, registration, setup, and lifecycle actions. | seconds-to-minutes | When touching the admin browser flow; required `admin-browser` CI job. |
For the admin browser lane, install frozen dependencies in the repository and
`admin/`, run `bunx playwright install --with-deps chromium` on Linux, then run
`bun run build:admin` before `bun run test:admin`. Tests live in
`admin/e2e/*.pw.ts` so Bun's unit-test discovery does not execute them. The
browser suite proves the GBrain dashboard journey; it does not establish
activation inside a native vendor harness.
There is no `check:all` script: a second, hand-synced guard registry would
drift from `verify`, leaving checks that never run anywhere. The `CHECKS`
array in `scripts/run-verify-parallel.sh` is the single execution list
(including `check:newlines`,
`check:no-legacy-getconnection`). The guard REGISTRY is `scripts/guards-manifest.tsv` (see "Guard registry and
self-test" below).
`bun run typecheck` ([heap ceiling](operations/verify-and-nightly-e2e.md#typecheck-heap)) uses TypeScript's native incremental analysis in
`node_modules/.cache/gbrain-typecheck.tsbuildinfo`. Every invocation still runs
the compiler; source, root-file, configuration and dependency changes invalidate
the affected analysis, and cached diagnostics remain failures. CI's `typecheck`
job restores and always saves it (#6056), as `ci:ubicloud` does.
The local Docker runner isolates root and admin `node_modules`, plus the generated
admin bundle, in named volumes. Admin build dependencies, Vite's generated cache
and build output stay inside container volumes instead of replacing host files
or leaving root-owned directories behind. `ci:local --clean` removes these volumes
too; build the admin app on the host when updating its committed bundle.
### Ubicloud fan-out (`ci:ubicloud`)
`scripts/ci-ubicloud.ts` runs the `ci:local` gate (uncommitted edits included) on ephemeral Ubicloud VMs
from one heaviest-first work queue; every VM is destroyed on exit. VM setup, scheduling, weights, quota
and flags are in [scripts/ubicloud/README.md](../scripts/ubicloud/README.md).
VMs are named `ubirun---`; set `UBI_OWNER` to your thread
code. Teardown destroys every VM the run asked for, including creates still in
flight, and stale-VM sweeps run only with `UBI_GC_HOURS` set and only on your
own VMs. `scripts/ubicloud/ubi-runner.sh usage` shows vCPUs by owner.
A sleeping machine kills the run with no signal, so teardown never runs: on Capy, run
`ci:ubicloud` as a watched background operation. After any interrupted run, check
`ubi-runner.sh list --mine` and reap leftovers with `down NAME` (or `gc HOURS`, own VMs only).
The project quota is 512 vCPUs, shared with PR CI; a full gate takes 64, or 160 when it is free.
In a multi-lane wave, lanes run `ci:ubicloud:diff` or targeted suites (`bun
test `, `--lanes`); only the integrator runs the full gate.
### E2E backend matrix
`scripts/e2e-backend-matrix.txt` lists the E2E files that must pass on direct
Postgres and through a transaction-mode PgBouncer: the E5 executor binding
matrix (`test/e2e/executor-binding-matrix.test.ts`, whose PGLite arm is
`test/executor-binding-matrix.test.ts`) and every `test/e2e/*parity*` file.
When `GBRAIN_PGBOUNCER_E2E_URL` is set, `scripts/run-e2e.sh` runs each listed
file twice: first against `DATABASE_URL` with
`GBRAIN_TEST_BACKEND=postgres-direct`, then with `DATABASE_URL` set to the
pooled URL and `GBRAIN_TEST_BACKEND=pgbouncer`. The PGLite arm inside each
parity file runs in both passes. Both passes must execute the same, non-zero
number of tests, and the summary prints the per-backend counts. The pooled
URL must carry `?prepare=false`, because `resolvePrepare` only auto-detects
port 6543 and CI poolers listen elsewhere; the runner refuses a pooled URL
without it. With `GBRAIN_CI_REQUIRE_PGBOUNCER=1`, a listed file fails when no
pooled URL is configured.
Instead of a full URL, a lane may set `GBRAIN_PGBOUNCER_E2E_DB=`: the
runner then reaches that database through the pooler in
`GBRAIN_PGBOUNCER_URL`, pins `prepare=false` itself, and creates the database
on first use through `GBRAIN_PGBOUNCER_DIRECT_URL`
(`scripts/lib/ensure-e2e-database.ts`). `ci:ubicloud` routes each slot's own
pooler at the slot database, `ci:local` gives each shard a
`gbrain_pooled__test` database behind its single pooler, and `e2e.yml`'s
`tier1-backend-matrix` job runs the list in two weighted shards (`SHARD=N/2`) against a `pgbouncer` service; it is
the PR owner of the listed `test/e2e/` files, which Selected E2E excludes. An entry may carry
`pooled-timeout=` when its pooled pass needs more than the
per-file cap; `!pathreason` records a parity file deliberately left out.
`test/scripts/e2e-backend-matrix.test.ts` pins the list's completeness, the CI
wiring and the runner's count assertion.
### Engine-sql
The engine-sql executor (`src/core/engine-sql/`, refactor wave 1 W1) is pinned
by these tests; the `*-parity` and RLS files run on every backend in the matrix
above, and each E2E file keeps a PGLite arm in the unit lane.
- `test/executor-binding-matrix.test.ts` / `test/e2e/executor-binding-matrix.test.ts`:
the E5 case table runs twice per backend, through `engine.executeRaw` and
through the dialect adapters (`engineSqlExecutor` factory), so the adapters
bind, count, fail and cancel exactly like master's raw path.
- `test/engine-sql-executor.test.ts`: `sqlFragment` renders the same text and
values as the postgres.js tagged template (vendored serializer); Postgres
driver options (`prepare: true, simple: false` for converted statements,
master's options for `executeRaw` / `unsafe`), gauge bypass, EO1 transaction
lane, brand `@ts-expect-error` fixtures.
- `test/e2e/engine-sql-prepare-parity.test.ts`: `pg_prepared_statements` holds a
converted statement on direct Postgres and nothing through PgBouncer; a
zero-parameter multi-statement string is rejected on every backend.
- `test/engine-sql-transaction.test.ts` / `test/e2e/engine-sql-transaction-parity.test.ts`:
per-domain write-then-throw rollback through `engine.transaction()` and
`transactionDirect()` (dual pool on Postgres), with a concurrent pool read.
Add a case to `test/helpers/engine-sql-rollback-cases.ts` for every migrated
domain write. A mutation that caches the executor on the engine fails it
(`DISCRIMINATE_BASE= bash scripts/check-test-discriminates.sh`).
- `test/engine-sql-capabilities.test.ts` / `test/e2e/engine-sql-capabilities-parity.test.ts`:
each dialect capability with a boundary-size and a concurrent-write case.
- `test/e2e/engine-sql-normalize-parity.test.ts`: every declared column kind
of `normalize.ts` decodes to one shape on each backend.
- `test/e2e/engine-sql-rls-scope.test.ts`: `ScopedRead` reads under a
non-owner `NOBYPASSRLS` role (cross-source denial, concurrent isolation,
nested rollback restoration, connection reuse).
- SQL text: `test/engine-sql-sql-text.test.ts` goldens must stay byte-identical
after a conversion; only `sql-text/_driver.json` moves (tagged ->
`runUnsafe`).
### Native writer locks
Native lock tests, the eight-target `native-locks.yml` matrix, compiled smokes and the OpenClaw native-host
fixture are described in [native/locks/README.md](../native/locks/README.md#tests-and-ci).
### Datastore shutdown and lease ownership
`test/pglite-lock.test.ts` proves process pause/crash handoff, metadata damage,
legacy migration refusal and stable ownership across datastore replacement.
`test/pglite-engine-disconnect.serial.test.ts` uses actual disk-backed PGLite
for concurrent opens, consumer/statement drains, persisted reopen, delayed
close and failed close. A close deadline retains the kernel lock; it is never
successful shutdown evidence. Watchdog and telemetry regression suites cover
loop starvation and background statement teardown.
`test/db-lock-concurrency.test.ts` proves unique identities even when two
acquisitions have identical database timestamps, exact successor-safe cleanup,
renewal cancellation/late-completion drain and mandatory loss propagation.
`test/e2e/db-lock-acquisition-token.test.ts` repeats acquisition/cleanup
invariants against real Postgres in Selected E2E. `test/engine-control-routing.test.ts` pins direct/shared pool routing,
nested transaction confinement and the Postgres resident-stop barrier.
### Durable persistence schedules and process crashes
Persistence suites (native-matrix publication, managed writers, schedules, crash boundaries, runtime
matrix, read latency, convergence) live in [scripts/persistence/README.md](../scripts/persistence/README.md#test-suites).
### Engine graduation
Graduation fixtures and suites: [scripts/persistence/README.md](../scripts/persistence/README.md#engine-graduation-tests).
### PGLite schema snapshot (default-on)
`scripts/build-pglite-snapshot.ts` (`bun run build:pglite-snapshot`) bakes a
post-`initSchema()` PGLite data dir into `test/fixtures/pglite-snapshot.tar`
plus a version file; `PGLiteEngine.initSchema()` restores the tar instead of
replaying the embedded schema + all migrations when the env var
`GBRAIN_PGLITE_SNAPSHOT` points at it. Runners activate it through the shared
`ensure_pglite_snapshot` helper in `scripts/lib/test-env.sh` (also home of
`detect_cpus` and `detect_available_mem_mb`), sourced by
`run-unit-parallel.sh`, `test-shard.sh`, `run-slow-tests.sh`,
`run-serial-tests.sh`, `run-verify-parallel.sh`, and `run-e2e.sh` (which
re-exports the path as ABSOLUTE — its tests spawn CLI children with varying
cwd); `scripts/ci-local.sh` calls the builder directly. The helper builds or
refreshes the snapshot and exports the env var, no-ops on
`GBRAIN_NO_SNAPSHOT=1` or an inherited path, and is non-fatal on build
failure: tests fall back to cold init, with a one-line "active" echo so a
silent fallback stays visible in CI logs. Measured effect: ~3.5x per
PGLite-booting file (a cold boot replays every migration, ~3.1s each in CI).
Properties:
- **Idempotent.** A hash short-circuit exits in ~40ms when the snapshot is
fresh, and REBUILDS a stale one. The hash covers the raw file bytes of the
static import closure of `pglite-schema.ts`, the schema-migration registry,
`migrate.ts` and the forward-reference bootstrap (`engine-sql/bootstrap.ts`),
plus `pglite-engine.ts` (`src/core/snapshot-schema-inputs.ts` computes the
list; no hand list). Imported SQL and handler changes
invalidate the fixture; coverage instrumentation does not change the hash.
`test/snapshot-inputs-closure.test.ts` checks that list against an
independent TS-AST closure, requires every literal dynamic import in the
closure to be classified, and discovers all 13 `pglite-snapshot-*` CI cache
keys: identical `hashFiles` inputs covering every hash input, each profile
restoring its own tar. A failure names the missing file and both workflow
files to edit.
- **Concurrency-safe.** Each profile has its own lock with a PID/token owner
and host/process-namespace identity. Only a confirmed dead local owner using
the current retirement protocol can be reclaimed. Both normal release and
crash recovery retain a nonempty owner tombstone so a delayed observer cannot
remove the next builder's lock. Keep those records while builders may run.
Live, foreign, ownerless, or older-protocol locks time out without building;
callers visibly fall back to cold initialization.
Temporary tar/version files are atomically renamed, with the version last.
- **Never authoritative.** The loader (`tryLoadSnapshot` in
`src/core/pglite-engine.ts`) verifies the schema hash AND the embedding
shape the snapshot was baked with (`dims=` / `model=` lines in the version
file) against what this process would create; any mismatch — including a
version file without shape lines — warns once and falls through to normal
cold init. A wrong fixture can never poison the suite.
- **Opt out.** `GBRAIN_NO_SNAPSHOT=1` skips the build + env export for a run;
the migration-replay canary tests clear the env themselves regardless.
Pinned by `test/snapshot-shape-guard.test.ts` (hash + shape refusal matrix,
imported SQL/handler dependency hash sensitivity).
The builder accepts `--profile legacy|default` (legacy remains the default).
Legacy uses the unit preload's embedding shape. Default uses the CLI's canonical
embedding shape and writes `pglite-snapshot-default.tar` plus its `.version`.
The artifacts, locks, and CI caches are separate. `ensure_default_pglite_snapshot`
exports an absolute `GBRAIN_TEST_DEFAULT_SNAPSHOT`; BrainBench applies it only
to CLI children, including `run-all`. The parent unit process retains its legacy
snapshot. The slow runner and direct BrainBench test invocation prepare the
default profile automatically. `GBRAIN_NO_SNAPSHOT=1` clears both paths and
survives test preloads.
### PGLite checkpoint harness (outside PR CI)
`scripts/pglite-checkpoint-harness/` reproduces the large-store PGLite checkpoint freeze outside PR CI;
usage and flags are in its [README](../scripts/pglite-checkpoint-harness/README.md).
### macOS 26 validation (`macos-validation`)
`.github/workflows/macos-validation.yml` runs on a GitHub-hosted `macos-26`
runner nightly, on manual dispatch, and on pull requests that carry the
`macos-validation` label. It uses no secrets and has a 90-minute cap. It checks
the device-identity re-stamp (#5604) on real APFS (the step first asserts an
APFS volume with a non-zero birth time and inode; the device-number change
itself stays simulated because a runner never reboots), runs the PGLite checkpoint
harness on a store of at least 2 GiB with the WAL-bound assertion
(#5449), and verifies the latest published signed `darwin-arm64` release
binary with `codesign --verify --strict` and `--version` against its release
tag (#5286). It also runs the bash 3.2 parse guard under the
runner's `/bin/bash`, then `bun run verify` (#5810), so a script or guard that
only works under bash 4 or later fails there. Maintainers with triage or write access apply the label; an
outside contributor whose change touches macOS-specific persistence, locking
or release code asks for it in the pull request. Scheduled and dispatched runs
use the default branch's workflow file, so the label is the way to get this
evidence for a change before it merges. `test.yml`'s security matrix,
`release.yml`'s darwin build and `native-locks.yml`'s darwin cells pin
`macos-26` / `macos-26-intel` rather than `macos-latest`.
### Keeping CI partitions balanced
Required CI runs 22 weighted unit workers, four serial workers with bounded
per-file pools, and up to eight selected E2E workers. E2E selection and exclusions
run once before setup; the resulting file lists are frozen and executed against
separate Postgres services. An explicit empty selection launches no tests;
selection errors, failed workers, cancellations, and unexpected skips fail the
existing aggregate checks. Nightly full-corpus E2E uses four independent
Postgres jobs with the same weighted partitioner and one fresh Bun process per
file, sequential within each job. It does not use the selected-E2E exclusion
list: default discovery includes every `test/e2e/*.test.ts` and
`test/phantom-redirect-engine-parity.test.ts`.
Each full-profile worker first initializes its own service schema with the
guarded `setupLegacyEmbeddingDB()` helper, in a temporary home with provider
keys stripped and local environment-file loading disabled. No partition relies
on a preceding file to create shared tables. Bootstrap is a separate timed CI
step and must be included in end-to-end comparisons.
Twice a unit shard's mined weight, plus setup, must end a minute inside its
job (`UNIT_SHARD_BUDGET_MS`); on failure re-mine, then raise `UNIT_SHARDS`.
Refresh after a large test wave or when the longest shard repeatedly exceeds
the mean shard execution time by 25%. `bun run check:weight-coverage` (in
`verify`) fails on an entry naming a missing file and, when a lane's unweighted
share passes 5% (unit) or 10% (serial, E2E), warns on pull requests and pushes
and fails the scheduled run, printing the lane's miner command:
```bash
bun run weights:mine --lane unit --run
bun run weights:mine --lane serial --run
bun run weights:mine --lane e2e --run
bun run weights:mine --lane e2e --e2e-profile full --run
```
The miner accepts `--from-file` or stdin for timestamped GitHub-format logs and
`--out` for inspection before replacing a checked-in map. Unit timing uses only
unit matrix jobs, includes `evals/`, and closes the final file at the Bun summary.
Serial timing uses runner durations, never timestamps of buffered output. E2E
uses each file's Bun summary and merges partial selections into known weights.
File/stdin imports also merge unobserved entries; only a complete GitHub unit,
serial or explicit full-profile E2E run replaces that lane's entire map. Captured artifacts need their final
successful completion marker, and GitHub imports verify every expected job.
Incomplete or failed inputs leave the existing map intact. Sidecar metadata
records the source run/commit, units, and counts. Unit/E2E weights are milliseconds;
serial weights remain seconds. New files receive the corpus p75 estimate.
The default E2E miner reads selected jobs and merges partial observations.
`--e2e-profile full` instead requires a successful GitHub run with a source SHA
matching checkout HEAD. It pins the run attempt and full-job IDs, reconstructs
default discovery using the committed runner and tracked test paths, and
requires every source file exactly once across complete successful job logs.
Missing/extra files, ambiguous basenames, duplicate execution or failed evidence
leave weights and metadata untouched. Basename resolution preserves the
outside-directory parity entry. Full mode replaces the complete map and records
source SHA, attempt, jobs, log hash and corpus hash; file/stdin imports cannot
claim full-profile provenance. These weights schedule work; they are not an
observed parallel runtime.
CI retains timestamped unit/E2E logs, frozen E2E selection, and serial attempt
records for 14 days. Compare push-to-required-green time including queueing,
first failure, rescues/reruns, runner minutes, unique file counts, and coverage
completeness. Compare cold and warm caches separately. Snapshot timings and
partition estimates are projections until matched workflow runs confirm them.
### E2E selection
`prepare-e2e` reads the pull request's changed files from the GitHub API
(`scripts/ci-changed-files.sh`, shallow checkout) and passes them to
`scripts/select-e2e.ts`: a doc-only change selects nothing, every other change
selects every `test/e2e/*.test.ts`. Diff narrowing is retired: a typical E2E
file imports most of `src/`, so a file-to-test map selected every file on 40 of
40 merged pull requests. An incomplete list (more than 3000 files, a compare
capped at 300, an API error, no pull request or merge-group context) fails
closed to the whole corpus. `scripts/e2e-matrix.ts` then drops
`E2E_EXCLUSIONS`, the files a named job owns, printing each owner: Tier 1's
named files, `tier1-backend-matrix` for every `test/e2e/` row of
`scripts/e2e-backend-matrix.txt` (direct Postgres and PgBouncer, so a
Selected E2E direct-only run would duplicate it), persistence-validation.yml and the live-key lanes.
`test/scripts/e2e-wiring.test.ts` requires every excluded file to have a named
owner. Locally, `ci:local:diff` and `ci:ubicloud:diff` run gitleaks and
`scripts/ci-doc-checks.sh` (llms freshness, KEY_FILES byte caps, documented
paths, skill references, privacy guards) on a doc-only diff and the full gate
otherwise, printing "E2E narrowing is retired".
### Refactor wave 1 goldens
Outputs captured on master before refactor wave 1 moves any code live under
`test/fixtures/goldens/`; `test/fixtures/goldens/README.md` maps each file to
its owning test and named normalizer. `test/helpers/golden.ts` writes and
compares them (`expectGolden`) and proves each normalizer by capturing twice
(`expectNormalizerStable`). Regenerate only deliberately, never in a refactor
commit: `GBRAIN_TEST_UPDATE_GOLDENS=1 bun test ` (the switch carries the
`GBRAIN_TEST_` prefix because the unit preload scrubs other `GBRAIN_*`
overrides). Performance baselines are a bench, not a test:
`docs/designs/refactor-wave-1/perf-baseline.md`.
### Doctor check registry
`gbrain doctor` runs `DOCTOR_CHECK_REGISTRY` (`src/commands/doctor/registry.ts`)
in order: one `{ name, emits, run(ctx) }` entry per topic block under
`src/commands/doctor/checks/`, each returning its checks or `STOP_DOCTOR`.
`test/doctor-registry.test.ts` fails with a `FAIL` / `Why` / `Fix` / `See`
block when an entry's `name` or any `emits[]` name is missing from
`src/core/doctor-categories.ts`, when `emits[]` differs from what the entry's
`run` can push (AST walk in `test/helpers/doctor-registry-ast.ts`), or when a
STOP gate moves away from where master's `buildChecks` returned early.
`test/doctor-mode-matrix.serial.test.ts` wraps every entry and the engine
with recorders and asserts, per mode (default, `--fast`, `--fix`,
`--fix --dry-run`, no engine, connection failure), which entries ran, where
the run stopped, which engine calls happened and which mutations landed (the
SKILL.md DRY auto-repair, the dead-holder lock reap). The W0 registry,
early-stop and `--json` goldens pin the output itself.
### Move-only verifier
`scripts/verify-move-only.ts` proves a commit tagged `Move-Only: yes` moves code
without editing it: every top-level statement of every touched TS file on the
base side reappears token for token on the head side (tokens from
`scripts/lib/normalize-tokens.ts`, so whitespace and comments are ignored and
string/SQL text is exact). Imports, `export ... from` lines and toggling the
`export` modifier on a moved statement are allowed and counted. Run
`bun scripts/verify-move-only.ts ` (default `HEAD~1..HEAD`);
`--wrapper migration` inlines `export const vNNN: Migration = {...}` files into
the generated registry array so the W3 split must reproduce the base side's
single `MIGRATIONS` literal entry for entry; `--wrapper doctor-entry` inlines each
`run(ctx: DoctorContext): Promise` body (minus its ctx
destructure / `connectedEngine` / `const checks` prologue and `return checks;`)
at its `checks.push(...(await runX(ctx)));` call in `buildChecks`, drops the
`const ctx: DoctorContext = {...};` glue and resolves relative `import()` /
`require()` specifiers to repo paths, so the W4 doctor peel must reproduce the
original `buildChecks` body; and `--rename-map ` applies identifier rewrites for
`Mechanical-Rename: yes` commits. Failures print `FAIL: ` with the
first differing token. Pinned by `test/scripts/verify-move-only.test.ts`.
### Schema migration registry
Schema migrations live one per file in `src/core/schema-migrations/v-.ts`
(NNN zero-padded to 3, `name` = the slug with `-` → `_`, one
`export const v: Migration = {...}` per file). `bun run new:migration `
scaffolds the next version; `bun run build:schema-migrations` regenerates the committed
`registry.generated.ts` + `latest.generated.ts` (regenerate, never hand-merge). The
array order is master's historical order (`HISTORICAL_ARRAY_ORDER` in
`scripts/build-schema-migrations.ts`), then ascending; the runner sorts by version.
Two guards run in `bun run verify`:
- `check:schema-migrations` (`scripts/check-schema-migrations-fresh.sh`) regenerates
both into temp files and diffs them; the generator also fails on a
filename/version/name mismatch and on a version defined twice, naming both files
with the `git mv` + `version:` + regenerate recipe.
- `check:schema-migration-order` (`scripts/check-schema-migration-order.ts`) fails
when a migration origin/master does not have is numbered at or below origin/master's
latest version (it would be skipped forever on current brains) or reuses a version
with a different name. Base ref: `GBRAIN_MIGRATION_BASE_REF` (default
`origin/master`); skipped with a notice when the ref is missing, failed under `CI=true`.
Collision recovery: an unapplied branch migration is renumbered (`git mv`, edit
`version`, regenerate); one already applied to a disposable dev DB means rebuilding
that DB and replaying; one applied to retained data needs explicit `schema_version`
reconciliation, never just a counter edit. `bun run release:restamp` does the
renumbering at merge time and prints the old-to-new mapping with these steps
([RELEASING.md](RELEASING.md#release-restamp)). Pinned by
`test/scripts/build-schema-migrations.test.ts` and `test/migrations-golden.test.ts`.
### Schema generator freshness
`check:schema-fresh` (`scripts/check-schema-fresh.sh`) runs `scripts/build-schema.ts
--out-dir ` (fragments -> `src/schema.sql` regions -> `schema-embedded.generated.ts`
-> `pglite-schema.generated.ts`) and diffs every output, naming the source to edit.
Canonical sources and PGLite capability rules: `docs/ENGINES.md#canonical-schema-sources`.
Pinned by `test/scripts/build-schema.test.ts`; the end state by the E4 catalog goldens.
### Guard registry and self-test
The privacy and test-isolation guards use `scripts/lib/guard-candidates.sh` to
scan fresh file contents in bounded batches before applying their detailed
per-file rules. They do not cache passing results. Candidate scanner failures
fail the guard, and matching files retain the same allowlists and diagnostics.
`scripts/guards-manifest.tsv` is THE single registry of `scripts/check-*`
guards, each classified `scanner` (greps/parses repo sources —
must eventually carry fixtures), `buildfresh`, or `repostate` (build/freshness
guards are exempt-with-reason, not fixture-tested).
`scripts/guard-self-test.sh` (`bun run check:guard-self-test`, wired into
`bun run verify`) proves every `selftest=yes` scanner CAN fail: it runs each
one against known-bad (must exit non-zero) and known-good (must pass) fixture
trees under `test/fixtures/guards//{bad,good}/` via the
`GBRAIN_GUARD_ROOT` env seam (guards run 4 at a time, `GUARD_SELF_TEST_JOBS`
overrides; results print in manifest order; the whole pass must finish inside
its 30 s budget), and enforces manifest completeness — a new
`scripts/check-*` script that isn't registered in the manifest fails the
build. A guard whose pattern rots into a permanently-green no-op fails CI
instead of masquerading as coverage.
A guard may carry extra known-bad trees named `bad-/`; each one must
fail on its own. Refactor wave 1 adds one inside each split module location for
every scanner that names a split file, listed in
[`docs/designs/refactor-wave-1/path-consumers.md`](designs/refactor-wave-1/path-consumers.md).
#### Layering guard
`scripts/check-layering.ts` (`bun run check:layering`, in `bun run verify`)
parses every file under `src/core/engine-sql/`, `src/core/schema-migrations/`
and `src/core/persistence/` and fails on any import, type-only included, of an
engine façade (`pglite-engine.ts`, `postgres-engine.ts`, `engine-factory.ts`)
from engine-sql, of `src/core/migrate.ts` from schema-migrations, or of
`src/core/ai/gateway.ts` from persistence. The first two directories are loaded
by the engines and by `migrate.ts`, so an import back up is an ESM cycle that
can fail with a temporal-dead-zone error at module load. Take the executor as a
parameter and import types from `src/core/engine.ts`; migration helpers live in
`schema-migrations/helpers.ts` and the `Migration` type in
`schema-migrations/types.ts`; persistence embeds via `src/core/embedding.ts`.
#### Write-path model guards
`scripts/check-ai-sdk-importers.ts` (in `bun run verify`) fails when a file
outside `scripts/ai-sdk-importers.allowlist` imports a provider SDK (`ai`,
`@ai-sdk/*`, `@anthropic-ai/sdk`, `openai`) as a value, so every model call
goes through `invokeAI`. Each mutating op has a write-inference class
(`src/core/ops/write-inference.ts`). `test/write-path-zero-llm.serial.test.ts`
asserts no generative call before commit and only attributed facts extraction
after it; `test/write-path-no-egress.serial.test.ts`: keyless CLI writes open
no connection. Helper: `test/helpers/ai-tripwire.ts`.
#### Durable-flush guard
`scripts/check-durable-flush.ts` (`bun run check:durable-flush`, in
`bun run verify`) fails on an `fsyncSync(fd)` anywhere in `src/` outside
`src/core/fs-durable.ts` whose `fd` is assigned from a read-only `openSync`
(flags omitted, a flag string without `w`/`a`/`+`, or `O_RDONLY` without
`O_WRONLY`/`O_RDWR`), file or directory, and on one whose flags it cannot
read: Windows refuses fsync on a read-only handle and has no directory flush
(EPERM; #5595, #5475). Fix: fsync the descriptor you wrote through before
closing it (`fchmodSync(fd)` first for its final mode), or call `flushFile` /
`flushDirectory(path, { bestEffort? })` from `src/core/fs-durable.ts`. A file
that cannot migrate yet goes in the guard's `ALLOWLIST` with a reason; a stale
entry fails. Fixtures: `test/fixtures/guards/check-durable-flush.ts/`. The
#5595/#5475 regressions run natively on the `windows-latest` row of the
test.yml `security-regressions` job; `test/helpers/win32-flush-semantics.ts`
makes them discriminate on POSIX.
#### Windows hidden-console guard
`scripts/check-windows-hide.ts` (`bun run check:windows-hide`, in `verify`;
#4992): a runtime `child_process` import or `Bun.spawn*` in `src/` outside
`src/core/spawn.ts` fails unless the file is in `NOT_YET_MIGRATED` (a ratchet;
a stale entry fails); `windowsHide: false` needs an `ALLOWLIST` reason.
`test/windows-hidden-console.test.ts` is the native proof on the same row.
#### Engine-sql ratchet
`scripts/check-engine-sql-ratchet.ts` (`bun run check:engine-sql-ratchet`, in
`bun run verify`) keeps each storage domain's SQL in one place,
`src/core/engine-sql/.ts`, by stopping SQL from growing back into the
engines. It parses `src/core/pglite-engine.ts`, `src/core/postgres-engine.ts`
and every file under `src/core/pglite-engine/` and `src/core/postgres-engine/`,
and names each class member (`PostgresEngine.getPage`), top-level function and
top-level variable (`insertFact`). A unit is SQL-bearing when the literal text
of a string, template, tagged template or `+` chain inside it has SQL
structure: `SELECT ... FROM `, `SELECT (`, `INSERT INTO `,
`UPDATE [alias] SET`, `DELETE FROM `, `WITH AS (`,
`CREATE|ALTER|DROP
