Zom Brain

A nightly local pipeline that ingests your zom codebases and their GitHub activity through a defense-in-depth privacy gate, compiles them into a queryable markdown brain, and serves it to any Claude Code session over MCP. Each developer runs it locally against the shared zom repos.

Scope: shared code only

The brain compiles only the zom codebases (and optional GitHub PR/issue activity on them). It does not read chat transcripts, sessions, notes, or any personal source. The only content that enters is the shared code every developer already has, so there is nothing personal to leak by construction.

Privacy guarantees

Safety is the top priority and holds by construction:

• Only paths inside your configured allowRoots (your zom repo clones) are ingested. Anything outside is dropped.
• No Obsidian vault or other private directory enters the system: a hard denylist drops any path under it, independent of the allowlist.
• Each gate layer fails closed: canonicalized-path allowlist, hard denylist, secret/email redaction plus sensitivity scan, audit log, required dry-run, reversible store plus a KILL switch.
• Nothing reaches claude -p (the only path off your machine) until after the gate.

Install

npm install
cp config/sources.example.yml config/sources.yml
cp config/denylist.example.yml config/denylist.yml

Edit config/sources.yml and put your real absolute work-repo paths in allowRoots. These files are gitignored.

Required before the first real run

1. Run the safety gate test suite. It must pass:

   npm run test:gate
   

2. Do a dry run and review what would be ingested:

   npm run -s run -- --dry-run
   

   Then open the newest store/audit/audit-*.ndjson and confirm every included item is work content and nothing personal or secret appears. Do not arm the nightly job until this looks clean.

Full Disk Access

Grant Full Disk Access to the node binary that launchd uses (System Settings > Privacy and Security > Full Disk Access). Without it, the launchd context cannot read Desktop-resident repos.

Schedule it

Edit the absolute paths in schedule/com.zom.brain.plist, then:

cp schedule/com.zom.brain.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.zom.brain.plist

schedule/run.sh re-runs the gate test suite as a precondition every night and refuses to ingest if it fails.

Use it from Claude Code (register the MCP server)

Registering the brain is a single additive server entry. It does not touch or interfere with any of your other MCP connectors, and it is removable.

Print the exact, path-filled commands for this install:

npm run mcp:install

That gives you two options: a one-line claude mcp add (user scope, available in every project), or a .mcp.json snippet for project scope. Each developer runs it once, pointing Claude Code at their own local brain. The server resolves its config and store relative to its own location, so it works no matter which repo you launch Claude Code from.

To sanity-check the server speaks MCP before registering it (touches no config):

npm run smoke:mcp

Once registered, call brain_query for a synthesized, cited answer, or brain_recall for raw search hits.

Better search with qmd (recommended)

Out of the box the brain uses a built-in keyword search, so it works with zero extra dependencies. Installing qmd (Tobias Lutke's local markdown search engine) upgrades that to hybrid search: BM25 + vector similarity + re-ranking, which returns far better hits on natural-language questions.

npm install -g @tobilu/qmd   # or: bun install -g @tobilu/qmd
brew install sqlite          # macOS: qmd needs Homebrew SQLite for extensions

That is all you have to do. The pipeline auto-detects qmd: if it is on your PATH, every nightly run registers the brain pages as a qmd collection named zom-brain (created once), re-scans them with qmd update, and rebuilds embeddings with qmd embed. The MCP server then routes brain_query and brain_recall through qmd query scoped to that collection. If qmd is absent, everything falls back to the built-in search automatically, so this is a pure upgrade with no config change.

Verify it took effect after a run:

qmd status                       # shows the zom-brain collection and index health
qmd query "..." -c zom-brain     # search the brain directly from the CLI

Optional: qmd also ships its own MCP server and a Claude Code plugin (claude plugin marketplace add tobi/qmd then claude plugin install qmd@qmd) if you want to point Claude at other markdown collections (your own notes, vault) independently of the brain.

Kill switch

touch KILL   # halts the pipeline immediately
rm KILL      # resume

What stays local

store/, the real config/*.yml, and audit logs are gitignored and never leave your machine. Only code and the *.example.yml files are committable.