# GBrain capture implementation history — August 2026 > Preserved during the 2026-09-12 semantic cleanup before the living capture policy was rewritten. Paths, hooks, Mac configuration, and “every session” claims below are historical and were not live-verified on the VPS. How any Claude session reads from and writes to this brain, set up 2026-08-03. ## The mechanism A zero-dependency stdio MCP server is registered at **user scope**, so every Claude Code session on Mohammad's Mac has brain tools with no per-project setup. - Server: `~/.claude/mcp-servers/brain-mcp.mjs` (source of truth: `~/Desktop/Skills/VITRUVIUS-BOARD/tools/brain-mcp.mjs`) - Registered with `claude mcp add brain --scope user -- node ~/.claude/mcp-servers/brain-mcp.mjs` - Transport to the VPS is plain SSH via the `vps` host alias, reusing a ControlMaster connection (~0.3s per call instead of a 2.4s handshake). **Why SSH rather than the gbrain HTTP MCP:** the gbrain MCP server binds to 127.0.0.1:3200 and uses OAuth 2.1 with dynamic registration. Reaching it from the Mac would mean exposing a new public port and minting a second credential to rotate. The SSH key is already the trust root, so it carries the traffic instead. ## Tools | Tool | Purpose | |---|---| | `brain_search` | hybrid keyword + semantic search — call before answering from memory | | `brain_read` | read one full page by slug | | `brain_list` | list pages by prefix or type | | `brain_write` | create a NEW page; refuses to clobber an existing one | | `brain_append` | add a dated section; the safe default, never destroys history | ## Guards The server refuses, rather than warns: - **Credential-shaped content** — same pattern family as the git export guard. The brain is exported to git nightly, so a leaked key would otherwise abort the whole sync. - **Malformed slugs** — must be lowercase path form. - **Silent overwrites** — `brain_write` on an existing slug returns an instruction to use `brain_append` instead. All user-supplied values cross the wire base64-encoded and are decoded into shell variables on the far side, so quotes, newlines and `$VARS` in a page body cannot break out into remote shell syntax. ## Routing Sessions file knowledge by the lens taxonomy in the lens taxonomy (Revenue / Build / Know): - `vitruvius/decisions/YYYY-MM-DD-` — a decision and its reasoning - `vitruvius/learnings/` — something learned the hard way - `vitruvius/finance/` — quotes, invoices, payments - `companies/` · `people/` · `projects/` - `operations/working-agreements/` — feedback on how Claude should work - `system/` — infra, config, credential *locations* (never values) ## Instruction layer The tools only matter if sessions actually reach for them. Two pieces drive that: - `~/.claude/CLAUDE.md` — loaded into every session: search before answering, write as you go, and a routing table. - `/brain` slash command (`~/.claude/commands/brain.md`) — explicit capture. With an argument it files that fact; with no argument it reviews the session and captures what is worth keeping. ## Verification Write path, guards and shell-injection resistance were all exercised on 2026-08-03 before this page was written — this page itself was created through the MCP server. ## 2026-08-05 — enforcement layer added The tools and the instruction layer existed, but writing to the brain was voluntary — it happened only when a session remembered mid-task. With 558 transcripts on the Mac and 169 touched in a week, most session knowledge was being lost. Four hooks now make it structural, without ever storing a transcript. | Hook | Event | What it does | |---|---|---| | `brain-write-guard.js` | PreToolUse | **Blocks** low-value writes to `brain_write`/`brain_append` | | `brain-session-start.js` | SessionStart | Injects the recent leak rate, escalating when knowledge is going missing | | `brain-precompact.js` | PreCompact | Last call before context is summarised away — fires only if the session is substantive and has written nothing | | `brain-session-end.js` | SessionEnd | Records *whether* a session wrote, never *what* was said | ## What the guard refuses Blocking rather than warning, because advisory warnings get ignored. Every refusal names the fix and the model can retry. - **Transcript shape** — speaker-prefixed lines, or more than five code blocks. Conclusions, not the conversation that produced them. - **Activity logs** — pages where most lines are "ran X, created Y". The steps are already in git; record what is now known or decided. - **Session-summary titles** — name the thing learned, not the session. - **Pages under 12 words** — too thin to act on later. - **Pages with no `[[wikilinks]]`** — an unconnected page is unreachable in the map and invisible to future sessions. This is the rule that makes the brain a graph rather than a pile. Escape hatch: `` in the body bypasses the link rule. Hub pages (`ledger`, `index`, `readme`, `memory`) are exempt automatically. ## Privacy Transcripts contain client data verbatim and, at least once, a pasted OAuth token. They are read locally, counted, and discarded — `~/.claude/brain-queue.jsonl` holds only session id, cwd, turn count, whether files were edited, how many brain writes happened and which slugs. **No transcript ever leaves the Mac**, which is also what [[people/mohammad-almousa/operating-manual]] requires of conclusions over transcripts. A session counts as *substantive* if it edited files or ran 40+ turns; only those can be marked as leaking, so throwaway sessions never generate noise. Source of truth for the hooks is `~/Desktop/Skills/VITRUVIUS-BOARD/tools/hooks/`, installed into `~/.claude/hooks/` and registered in `~/.claude/settings.json` alongside the existing GSD hooks — see [[system/claude-code-setup]]. All nine GSD hooks were preserved when registering. Verified 2026-08-05 against crafted payloads: transcripts, activity logs, six-code-block dumps, thin pages and unconnected pages were all refused; connected multi-line conclusions and hub pages passed; malformed hook input fails open so a hook can never break a session. ## 2026-08-06 — Project owner taxonomy Every `projects/` page now carries frontmatter `owner: vitruvius` (own products, infra, R&D) or `owner: client` plus `client: ` when known — 71 pages migrated 2026-08-06 per [[vitruvius/decisions/2026-08-06-aios-stack]]. New project pages MUST set `owner:` at creation. Four remain for Mohammad: wrent×2 (fractional-CTO equity, neither bucket — see [[companies/wrent]]), jibli (role unclear), [[projects/marketing-site-edits]] (conflates [[projects/starkcretex]] client work with vitruviusit.com — should be split). The AIOS dashboard's Marketing and GBrain tabs group by this field. Gotcha: `gbrain put` WITHOUT `--content` treats stdin as body and REGENERATES frontmatter (it silently changed a page's type during testing) — always pass `--content` with full frontmatter.