# 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

```bash
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:
   ```bash
   npm run test:gate
   ```
2. Do a dry run and review what would be ingested:
   ```bash
   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:

```bash
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:

```bash
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):

```bash
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](https://github.com/tobi/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.

```bash
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:

```bash
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

```bash
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.