auto-brain-notify

auto-brain-notify is the return loop of the company brain. The Obsidian vault holds EC's load-bearing knowledge — strategy, meeting notes, research, copy, legal. Automations and people keep writing into it, but until now that knowledge only reached someone if they happened to open Obsidian and happened to look in the right folder. This automation closes the circuit: the vault notices its own changes and tells the right person what changed and why it matters to them.

The value it brings

• Knowledge propagates on its own. When anyone on the team writes a note — a meeting analysis, a research finding, a strategy update — the people it affects hear about it, without anyone having to remember to tell them.
• It kills the manual "state-of-the-company" digest. EC used to produce hand-written snapshots ("what changed / what's true now") every so often. This produces that continuously, for free, per person.
• It is the router for everything else. Every other automation writes into the vault; auto-brain-notify is how those outputs reach humans. When market intelligence surfaces a signal, or the transcript bot files an analysis, the notification rides this channel.
• Silence is a feature. A high relevance threshold and a hard per-digest budget mean it only speaks when there is something worth saying. Its single worst failure mode would be to become the noise it exists to defeat — the design guards against exactly that.

How it works

The pipeline is three stages, ordered by how much judgement each needs — almost all of it is deterministic code, with an LLM entering only at the very end.

Stage 1 — Diff engine (deterministic, no LLM, no network)

On a schedule (every few hours), a stdlib-only Python script snapshots the vault: a content hash of every .md file. Comparing against the previous snapshot tells it exactly which files are new, modified, or deleted, and — since it also records the heading structure — which sections changed inside a file.

Two safeguards make it trustworthy:

• Debounce. A change is only reported once it is stable across two consecutive scans. Obsidian Sync writes files in pieces; without this the engine would report half-synced files.
• Source-level exclusions. Machine-generated lineage folders (audit receipts, activity ledgers) are excluded so they never drown the signal.

Output is a local append-only log (changes.jsonl) plus a status.json heartbeat.

Stage 2 — Classification (mostly deterministic)

Each change is mapped to one of the vault's existing topic clusters via a human-owned folder-to-cluster table (e.g. Team Meetings/ → team-operations, A-Strategy/VC_Seed_Narrative/ → buyers-revenue). An LLM is consulted only for files the folder map doesn't cover — and the rate of unmapped files is itself a monitored signal that the vault needs tidying.

Stage 3 — Routing & digest (Phase 1+, in build)

A cluster-to-people table decides who receives what. Each person gets a digest — a Slack DM or thread — where every item is: the vault path, one line of what changed (this is the one place an LLM writes), and one line of why it matters to you (the cluster). Hard rules: at most a handful of items per digest, no digest when nothing clears the relevance threshold, and a default-deny on sensitive areas (legal, recruiting, comp).

The compound loop: 👍/👎 reactions on digest items feed back into the relevance judgement, so the filter improves with use.

Infrastructure & components

auto-brain-notify is its own git repo (auto-brain-notify) deployed as a systemd timer on the hub. It is deliberately dependency-free (stdlib Python), so it runs anywhere Python 3.11+ exists.

Component	What it is
scan.py	The diff engine + classifier + control-plane contract. One invocation = one scan.
Vault replica	/srv/vault on the hub, kept live by the Obsidian container. Mounted read-only for this automation — it can diff the vault but never write to it, enforced both in code and by the systemd sandbox.
state/	Machine-local: brain.db (SQLite snapshot + debounce state), changes.jsonl (the report feed), status.json (heartbeat). Never leaves the box.
inbox/	Control-plane command drop-box: pause / resume (soft kill) / run-now.
systemd unit + timer	auto-brain-notify.service (oneshot scan) driven by auto-brain-notify.timer (every few hours). Sandboxed: own unix user, read-only vault, writable only in its own state dir, memory/CPU capped.

How it reaches the box

Like every automation, it deploys push-based and secretless:

No GitHub credentials live on the hub; the box only ever talks to AWS, authenticated by its own instance identity.

Status & phases

• Phase 0 (live). Diff engine + classifier running on the hub as a scheduled timer, writing the local change feed. No notifications yet — this phase validates that change detection is accurate and quiet.
• Phase 1. Per-person digests to Slack with LLM one-line summaries and threshold tuning.
• Phase 2. The full routing table, reactions feedback loop.
• Phase 3. A launch-time "what can we claim today, with what evidence" query surface over the same vault index.