secondbrain-py 0.2.1__py3-none-any.whl

brain/templates/docker/age/Dockerfile

@@ -0,0 +1,79 @@
+# Custom Postgres image for second-brain GraphRAG (task G0-1).
+# PostgreSQL 16 + pgvector (vector) + pgcrypto (contrib) + Apache AGE (openCypher graph).
+#
+# Canonical, packaged source of truth for the AGE image. The repo-root
+# docker-compose.yml does NOT build this — prod stays on stock
+# `pgvector/pgvector:pg16` until the gated AGE cut-over. This image is built only
+# by docker-compose.age-test.yml (the port-5434 test instance, build context
+# ./src/brain/templates/docker/age) and by the rendered $BRAIN_HOME compose:
+# `brain setup` materializes a copy into $BRAIN_HOME/docker/age/Dockerfile so the
+# generated compose can build it there.
+#
+# Why a custom image:
+#   - stock `pgvector/pgvector:pg16` has pgvector + pgcrypto but NOT Apache AGE
+#   - stock `apache/age:PG16` has AGE but NOT our exact pgvector setup
+#   so we start from the pgvector image (keeps the running DB's pgvector ABI/data
+#   layout identical) and compile AGE from a pinned release tag against the SAME
+#   PG16 server headers, so the resulting .so/.control/.sql match the server exactly.
+#
+# Pins (immutable):
+#   - Base: pgvector/pgvector:0.8.2-pg16   (PG16 + pgvector 0.8.2; matches running DB)
+#   - AGE : release tag PG16/v1.5.0-rc0    (commit 0048900f372d4dfd5c236f78b8a8453bcdbb458e)
+#           NOTE: upstream Apache AGE has NO GA PG16 tag. `PG16/v1.5.0-rc0` is the
+#           latest released PG16 tag (the only newer one is `PG16/v1.6.0-rc0`). It is
+#           a release candidate, labelled honestly as "1.5.0-rc0" everywhere — not GA.
+#
+# Apache AGE does NOT require `shared_preload_libraries=age` for the per-session
+# `LOAD 'age';` bootstrap used by `brain init` / `connect`. It can be enabled
+# optionally for performance (see docs/specs/2026-05-20-graphrag-age-image.md).
+
+FROM pgvector/pgvector:0.8.2-pg16
+
+# Pinned Apache AGE source. AGE_COMMIT is the immutable checkout; AGE_REF is the
+# release tag it must resolve to — verified at build time so the build FAILS if the
+# tag ever moves off the pinned commit (drift guard). Override via --build-arg to
+# upgrade (bump BOTH the ref and the commit together).
+ARG AGE_REPO=https://github.com/apache/age.git
+ARG AGE_REF=PG16/v1.5.0-rc0
+ARG AGE_COMMIT=0048900f372d4dfd5c236f78b8a8453bcdbb458e
+
+# Build AGE from source against the image's PG16, then drop all build deps so the
+# final image only carries the compiled extension artifacts (lean image).
+RUN set -eux; \
+    apt-mark hold locales; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends \
+        build-essential \
+        git \
+        ca-certificates \
+        postgresql-server-dev-16 \
+        bison \
+        flex \
+        libreadline-dev \
+        zlib1g-dev; \
+    git clone "$AGE_REPO" /tmp/age; \
+    # drift guard: the pinned tag MUST resolve to the pinned commit
+    test "$(git -C /tmp/age rev-list -n 1 "$AGE_REF")" = "$AGE_COMMIT"; \
+    git -C /tmp/age checkout "$AGE_COMMIT"; \
+    make -C /tmp/age PG_CONFIG="$(command -v pg_config)"; \
+    make -C /tmp/age PG_CONFIG="$(command -v pg_config)" install; \
+    # sanity: AGE control file must land where PG16 expects extensions
+    test -f "$(pg_config --sharedir)/extension/age.control"; \
+    rm -rf /tmp/age; \
+    apt-get purge -y --auto-remove \
+        build-essential \
+        git \
+        postgresql-server-dev-16 \
+        bison \
+        flex \
+        libreadline-dev \
+        zlib1g-dev; \
+    apt-mark unhold locales; \
+    rm -rf /var/lib/apt/lists/*
+
+LABEL org.opencontainers.image.title="second-brain-pg16-age-pgvector" \
+      org.opencontainers.image.description="PostgreSQL 16 + pgvector 0.8.2 + pgcrypto + Apache AGE 1.5.0-rc0 for second-brain GraphRAG" \
+      org.opencontainers.image.base.name="pgvector/pgvector:0.8.2-pg16" \
+      brain.age.ref="PG16/v1.5.0-rc0" \
+      brain.age.commit="0048900f372d4dfd5c236f78b8a8453bcdbb458e" \
+      brain.pgvector.version="0.8.2"

brain/templates/docker-compose.stock.yml.j2

@@ -0,0 +1,26 @@
+# Jinja variables: brain_home, pg_port, compose_project, container_name
+# Stock pgvector compose — the FTS/hybrid twin of the committed root
+# docker-compose.yml, with NO AGE build stanza. Used by `brain setup --profile
+# minimal|standard`; the AGE image (docker-compose.yml.j2) is full-profile only.
+name: {{ compose_project }}
+services:
+  postgres:
+    image: pgvector/pgvector:pg16
+    container_name: {{ container_name }}
+    # shared_buffers 512MB: the working set exceeds the stock 128MB default,
+    # forcing cold FTS re-reads from disk. Applied as a `postgres -c` flag
+    # (no custom postgresql.conf). Matches the committed root compose.
+    command: postgres -c shared_buffers=512MB
+    environment:
+      POSTGRES_USER: brain
+      POSTGRES_PASSWORD: brain
+      POSTGRES_DB: second_brain
+    ports:
+      - "{{ pg_port }}:5432"
+    volumes:
+      - {{ brain_home }}/data/postgres:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U brain -d second_brain"]
+      interval: 5s
+      timeout: 3s
+      retries: 10

brain/templates/docker-compose.yml.j2

@@ -0,0 +1,34 @@
+# Jinja variables: brain_home, pg_port, compose_project, container_name
+name: {{ compose_project }}
+services:
+  postgres:
+    # Custom PG16 image: pgvector 0.8.2 + pgcrypto + Apache AGE 1.5.0-rc0 (GraphRAG).
+    # `image:` points at the prebuilt multi-arch image on GHCR, so a fresh install
+    # can `docker compose pull` it instead of compiling AGE from C source (slow +
+    # fragile on Apple Silicon). The `build:` stanza is a LOCAL FALLBACK: `brain
+    # setup` materializes the packaged Dockerfile into
+    # {{ brain_home }}/docker/age/Dockerfile, so `docker compose up --build`
+    # resolves and compiles locally when the registry image is unavailable.
+    build:
+      context: {{ brain_home }}/docker/age
+      dockerfile: Dockerfile
+    image: ghcr.io/mshtawythug/second-brain-age:pg16-v1.5.0-rc0-pgv0.8.2
+    container_name: {{ container_name }}
+    # shared_buffers 512MB: the working set exceeds the stock 128MB default,
+    # forcing cold FTS re-reads from disk. Applied as a `postgres -c` flag (no
+    # custom postgresql.conf). Matches the stock template + committed root
+    # compose; the heavier full profile (graph + FTS + vector) benefits most.
+    command: postgres -c shared_buffers=512MB
+    environment:
+      POSTGRES_USER: brain
+      POSTGRES_PASSWORD: brain
+      POSTGRES_DB: second_brain
+    ports:
+      - "{{ pg_port }}:5432"
+    volumes:
+      - {{ brain_home }}/data/postgres:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U brain -d second_brain"]
+      interval: 5s
+      timeout: 3s
+      retries: 10

brain/templates/env.example

@@ -0,0 +1,190 @@
+# Embedder backend: arctic (default, free, local) | voyage (paid SaaS)
+#                   | qwen3 (free, local, China-origin)
+BRAIN_EMBEDDER=arctic
+
+# Ollama (required for arctic + qwen3; install: brew install ollama && brew services start ollama)
+#   For arctic: ollama pull snowflake-arctic-embed2
+#   For qwen3:  ollama pull qwen3-embedding:8b
+OLLAMA_HOST=http://localhost:11434
+QWEN3_MODEL=qwen3-embedding:8b
+
+# Voyage AI (required only when BRAIN_EMBEDDER=voyage)
+# VOYAGE_API_KEY=
+
+# Local Postgres (Docker)
+# DATABASE_URL → prod on the stock pgvector image, port 55432
+# (docker-compose.yml, ./data/postgres bind-mount). `brain setup` substitutes
+# the chosen --port into the {{ pg_port }} placeholder below (default 55432);
+# the same value is rendered into docker-compose.yml so the two never drift.
+# The Apache AGE cutover of the prod container is gated — see
+# docs/specs/2026-05-20-graphrag-age-image.md.
+# TEST_DATABASE_URL → the SEPARATE Apache-AGE test instance on port 5434
+# (docker-compose.age-test.yml, named volume), so the suite runs against the
+# PG16 + pgvector 0.8.2 + pgcrypto + Apache AGE 1.5.0-rc0 superset image.
+# Start it: docker compose -f docker-compose.age-test.yml up -d --build
+DATABASE_URL=postgresql://brain:brain@localhost:{{ pg_port }}/second_brain
+TEST_DATABASE_URL=postgresql://brain:brain@localhost:5434/second_brain_test
+
+# Vault folder (default: ~/brain-vault). Override to point elsewhere — e.g.
+# ~/Documents/brain-vault for iCloud-friendly sync on macOS.
+# BRAIN_VAULT_PATH=
+
+# Owner email — used by the email-thread reading mode (P4.4) to power the
+# "Show only my replies" filter on `_ingested/gmail/<thread>/` pages. The
+# Quartz build reads this at build time and bakes it into rendered pages
+# as `window.BRAIN_USER_EMAIL`. Leave unset to render the toggle without
+# a user identity (the filter matches nothing).
+# BRAIN_USER_EMAIL=you@example.com
+
+# Comma-separated list of identifiers (emails AND/OR display names) that
+# count as the corpus owner. Stripped from participant_keys before
+# derived-edge rules R2 (shared_participant) and R3 (same_day_participant)
+# evaluate, so a meeting/email isn't linked to every other doc the owner
+# is on. Both forms accepted; matching is case-insensitive (entries are
+# trimmed + lowercased at load time). Leave unset for the default
+# behaviour (no stripping).
+# Example: BRAIN_OWNER_PARTICIPANTS="Ali Sarkis,redacted@example.com,redacted@example.com"
+# BRAIN_OWNER_PARTICIPANTS=
+
+# Recency boost half-life in days. After RRF, each document's score is
+# multiplied by 0.5 ** (age_days / halflife_days) where age_days comes from
+# coalesce(sent_at, ingested_at). Default 180 days. Set to a very large value
+# (e.g. 999999) to effectively disable the boost. Must be a positive float.
+# BRAIN_RECENCY_HALFLIFE_DAYS=180
+
+# Snippet-context expansion budget (tokens). After the best-matching chunk is
+# identified, this many tokens of neighboring-chunk context are stitched
+# around it to give richer reading context. Default 200. Set to 0 to use the
+# legacy single-chunk snippet. Must be a non-negative integer.
+# BRAIN_SNIPPET_CONTEXT_TOKENS=200
+
+# Enrichment model (Ollama) for auto-summary + auto-tags. Default
+# llama3.1:8b. Override for higher quality (gemma3:27b — ~60s/doc on M1 Pro,
+# best summarization in the non-Chinese open-weight space) or higher speed
+# (llama3.2:3b — ~4s/doc, looser tags). Switching models causes
+# `brain enrich --backfill` to re-enrich all docs whose summary_model no
+# longer matches the current setting.
+# BRAIN_ENRICH_MODEL=llama3.1:8b
+
+# Enrichment HTTP timeout in seconds. Default 60. Raise when running a
+# larger model (gemma3:27b / phi4:14b / mistral-small) — cold-load + long
+# inputs can exceed 60s on Apple Silicon.
+# BRAIN_ENRICH_TIMEOUT_SECONDS=60
+
+# Minimum input tokens before a doc is enriched. Docs shorter than this
+# skip enrichment (a 1-paragraph note doesn't benefit from a summary).
+# Default 50. Set to 0 to enrich every doc.
+# BRAIN_ENRICH_MIN_TOKENS=50
+
+# Maximum input tokens fed to the enricher. Long docs are head-truncated.
+# Default 4000. Lower to speed up the backfill at the cost of summary
+# fidelity on long docs.
+# BRAIN_ENRICH_MAX_INPUT_TOKENS=4000
+
+# --- GraphRAG (Apache AGE entity graph) --------------------------------------
+# Default-ON entity-graph sync alongside the vector/hybrid search. `brain setup`
+# provisions a Postgres image that ships Apache AGE; the committed
+# docker-compose.yml in the repo root stays on stock pgvector and operators flip
+# to AGE via a local docker-compose.override.yml — see
+# docs/specs/2026-05-20-graphrag-age-image.md. On a stock pgvector DB the graph
+# stack auto-degrades to a no-op (init prints "graph skipped — AGE not
+# available"; ingest's graph sync is best-effort and never raises). Names match
+# the design spec §10.
+
+# Enable the people-aspect graph sync hook. When true AND the DB ships Apache
+# AGE, every ingest/edit/delete keeps the people graph in lock-step with the
+# documents table; on a stock pgvector DB the sync is a best-effort no-op
+# (silent no-op when AGE is absent; logged + dropped if AGE is present but reconcile raises). Accepts 1/true/yes/on or 0/false/no/off.
+# Default true (the brain setup template provisions an AGE-capable image).
+# Set to false to disable graph sync at ingest time.
+# BRAIN_GRAPH_ENABLED=true
+
+# Tenant id stamped on every graph row/vertex/edge and every query. Single-user
+# local deployments leave this at the default. Default "default".
+# BRAIN_GRAPH_TENANT=default
+
+# Co-occurrence sliding-window radius (inclusive, unit-agnostic). For the people
+# aspect every participant shares one notional position, so any window >= 1
+# yields the complete graph over a document's persons. Positive integer.
+# Default 3.
+# BRAIN_GRAPH_COOCCUR_WINDOW=3
+
+# Per-document entity cap — bounds the O(pairs) co-occurrence work on an
+# entity-dense document. A positive integer, or "none"/"unlimited" to disable
+# the cap. Default 40.
+# BRAIN_GRAPH_MAX_ENTITIES_PER_DOC=40
+
+# Generic-entity document-frequency ratio. An entity appearing in more than
+# round(ratio * tenant_corpus_N) documents is treated as generic and its edges
+# are suppressed at derive time. A float in (0.0, 1.0]. Changing it forces a
+# corpus-wide re-derive — run `brain graphrag refresh`. Default 0.30.
+# BRAIN_GRAPH_GENERIC_DF=0.30
+
+# --- GraphRAG concept extraction + retrieval ---------------------------------
+# Names match the design spec §10. The concept extractor v2 passed its eval
+# gate (f1 ~0.88 on the local eval set) so the aspect is default-ON.
+
+# Enable the concept aspect (LLM entity extraction over topics/projects/orgs/
+# tools) alongside the always-on people aspect. Requires
+# BRAIN_GRAPH_EXTRACT_MODEL to be pullable via `ollama pull <name>` (default
+# llama3.1:8b — ~4.7 GB). Set to false to disable concept extraction (people
+# aspect still works without an LLM). Default true.
+# BRAIN_GRAPH_CONCEPTS=true
+
+# Ollama model for the concept entity extractor. Any model pullable via
+# `ollama pull <name>` that supports JSON-mode output. Default llama3.1:8b.
+# BRAIN_GRAPH_EXTRACT_MODEL=llama3.1:8b
+
+# Bounded traversal radius for local/themes retrieval (variable-length hops).
+# Positive integer. Default 2.
+# BRAIN_GRAPH_DEPTH=2
+
+# Frontier cap — max entities reached per seed during traversal. Positive
+# integer. Default 200.
+# BRAIN_GRAPH_FRONTIER_CAP=200
+
+# Per-node expansion fan-out cap during traversal. Positive integer. Default 50.
+# BRAIN_GRAPH_MAX_DEGREE=50
+
+# Minimum normalized-lift edge weight admitted into a traversal. A float in
+# [0.0, 1.0]; 0.0 admits every edge. Default 0.20.
+# BRAIN_GRAPH_MIN_EDGE_WEIGHT=0.20
+
+# Number of ranked theme groups returned by "themes with X". Positive integer.
+# Default 5.
+# BRAIN_GRAPH_THEME_LIMIT=5
+
+# --- GraphRAG global communities (wave G3) -----------------------------------
+# Parsed in wave G3; consumed by `brain graphrag communities build|refresh`
+# (networkx Louvain over the tenant entity graph) and the global retrieval path.
+# §17c pins the migration-013 schema + perf budgets but NOT these tuning
+# defaults — the values below are chosen to be consistent with the other graph
+# knobs.
+
+# Louvain resolution. Higher values yield more, smaller communities; lower
+# values yield fewer, larger ones. Positive float. Default 1.0 (networkx
+# default).
+# BRAIN_GRAPH_COMMUNITY_RESOLUTION=1.0
+
+# RNG seed for deterministic Louvain detection (so repeated builds over an
+# unchanged graph produce stable communities). Non-negative integer.
+# Default 1234.
+# BRAIN_GRAPH_COMMUNITY_SEED=1234
+
+# Minimum members for a community to be materialized — smaller communities are
+# dropped. Positive integer. Default 3.
+# BRAIN_GRAPH_COMMUNITY_MIN_SIZE=3
+
+# Jaccard overlap threshold for stable-identity matching across rebuilds: a new
+# community whose member set overlaps an old one by >= this fraction reuses the
+# old community_key. A float in [0.0, 1.0]. Default 0.5.
+# BRAIN_GRAPH_COMMUNITY_JACCARD=0.5
+
+# Number of ranked communities returned by the global retrieval mode. Positive
+# integer. Default 5.
+# BRAIN_GRAPH_COMMUNITY_LIMIT=5
+
+# Ops safety cap on the number of communities materialized per tenant per build
+# (bounds the summary + embedding cost). A positive integer, or "none"/
+# "unlimited" to disable. Default none (unlimited).
+# BRAIN_GRAPH_COMMUNITY_MAX=none

brain/templates/launchd/__init__.py

@@ -0,0 +1 @@
+"""Marker so importlib.resources can resolve this subdirectory in pipx-installed wheels."""

brain/templates/launchd/com.brain.brief.plist.j2

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Jinja variables: brain_home, user_home, pipx_bin_dir, vault_path, brain_py
+     The launchd renderer (brain.bin.launchd.render_plist) MUST XML-escape every
+     value before substitution (Path strings with '&' / '<' / '>' would otherwise
+     produce invalid plist XML and launchctl bootstrap would fail).
+
+     Unlike the watcher/build agents this is a ONE-SHOT job: StartCalendarInterval
+     fires the brief once at 07:00 local each day (no KeepAlive, no RunAtLoad).
+     The brief writes the daily digest page; LLM suggestions are best-effort and
+     skipped silently if Ollama is down. -->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.brain.brief</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>{{ brain_home }}/.shims/_brain-brief-fg</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>HOME</key>
+        <string>{{ user_home }}</string>
+        <key>PATH</key>
+        <string>{{ pipx_bin_dir }}:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+        <key>BRAIN_VAULT_PATH</key>
+        <string>{{ vault_path }}</string>
+        <key>BRAIN_PY</key>
+        <string>{{ brain_py }}</string>
+    </dict>
+    <key>StartCalendarInterval</key>
+    <dict>
+        <key>Hour</key>
+        <integer>7</integer>
+        <key>Minute</key>
+        <integer>0</integer>
+    </dict>
+    <key>WorkingDirectory</key>
+    <string>{{ brain_home }}</string>
+    <key>StandardOutPath</key>
+    <string>{{ brain_home }}/logs/com.brain.brief.out.log</string>
+    <key>StandardErrorPath</key>
+    <string>{{ brain_home }}/logs/com.brain.brief.err.log</string>
+</dict>
+</plist>

brain/templates/launchd/com.brain.build.plist.j2

@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Jinja variables: brain_home, user_home, pipx_bin_dir, vault_path, brain_py
+     T1.7 renderer MUST XML-escape every value before substitution
+     (Path strings with '&' / '<' / '>' would otherwise produce invalid
+     plist XML and launchctl bootstrap would fail with a parse error). -->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.brain.build</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>{{ brain_home }}/.shims/_brain-build-fg</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>HOME</key>
+        <string>{{ user_home }}</string>
+        <key>PATH</key>
+        <string>{{ pipx_bin_dir }}:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+        <key>BRAIN_VAULT_PATH</key>
+        <string>{{ vault_path }}</string>
+        <!-- BRAIN_PY pins the exact Python interpreter that has `brain` importable.
+             For a pipx install this is the pipx venv Python
+             (e.g. ~/.local/pipx/venvs/secondbrain-py/bin/python).
+             T1.7's plist generator resolves and substitutes this variable.
+             Without it the shell scripts fall back to system python3 which
+             does NOT have brain on sys.path and every `python -m brain.*`
+             call would fail with ModuleNotFoundError. -->
+        <key>BRAIN_PY</key>
+        <string>{{ brain_py }}</string>
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+    <key>WorkingDirectory</key>
+    <string>{{ brain_home }}</string>
+    <key>StandardOutPath</key>
+    <string>{{ brain_home }}/logs/com.brain.build.out.log</string>
+    <key>StandardErrorPath</key>
+    <string>{{ brain_home }}/logs/com.brain.build.err.log</string>
+</dict>
+</plist>

brain/templates/launchd/com.brain.watcher.plist.j2

@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Jinja variables: brain_home, user_home, pipx_bin_dir, vault_path, brain_py
+     T1.7 renderer MUST XML-escape every value before substitution
+     (Path strings with '&' / '<' / '>' would otherwise produce invalid
+     plist XML and launchctl bootstrap would fail with a parse error). -->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.brain.watcher</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>{{ brain_home }}/.shims/_brain-watcher-fg</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>HOME</key>
+        <string>{{ user_home }}</string>
+        <key>PATH</key>
+        <string>{{ pipx_bin_dir }}:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+        <key>BRAIN_VAULT_PATH</key>
+        <string>{{ vault_path }}</string>
+        <!-- BRAIN_PY pins the exact Python interpreter that has `brain` importable.
+             For a pipx install this is the pipx venv Python
+             (e.g. ~/.local/pipx/venvs/secondbrain-py/bin/python).
+             T1.7's plist generator resolves and substitutes this variable.
+             Without it the shell scripts fall back to system python3 which
+             does NOT have brain on sys.path and every `python -m brain.*`
+             call would fail with ModuleNotFoundError. -->
+        <key>BRAIN_PY</key>
+        <string>{{ brain_py }}</string>
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+    <key>WorkingDirectory</key>
+    <string>{{ brain_home }}</string>
+    <key>StandardOutPath</key>
+    <string>{{ brain_home }}/logs/com.brain.watcher.out.log</string>
+    <key>StandardErrorPath</key>
+    <string>{{ brain_home }}/logs/com.brain.watcher.err.log</string>
+</dict>
+</plist>

brain/templates/skill/SKILL.md

@@ -0,0 +1,63 @@
+---
+description: Query the user's local second-brain knowledge base (career, past meetings, Slack/Gmail/Krisp transcripts) via the `brain` CLI. Use when the user asks about their background, past meetings, past Slack threads, past emails, interview prep, or specific people / projects they've mentioned.
+when_to_use: Trigger on phrases like "what did I say about X", "my thoughts on Y", "meetings about Z", "interview prep", "tell me about my work on W", or any question requiring personal context the user has stored in their second brain.
+---
+
+# Second Brain — `brain` CLI
+
+The user has a personal knowledge base at their vault (default
+`~/brain-vault`). Use it whenever a conversation touches their career,
+past meetings, past Slack threads, past emails, interview prep, or
+specific people / projects they've mentioned.
+
+**Search** — `brain search "..."` returns the top 5 matching documents
+with snippets and IDs. Use `--json` if you need to parse output.
+Basic filters: `--source krisp|slack|gmail|manual`, `--tag X`,
+`--has-tag X`, `--without-tag X`, `--since N` (days), `--limit N`,
+`--fts-only`.
+Metadata filters: `--person "Name"` (resolved via the directory, same
+as `brain people`), `--after YYYY-MM-DD`, `--before YYYY-MM-DD`,
+`--kind transcript|email|email_thread|note|markdown|pdf|...`,
+`--thread <gmail-thread-id>`, `--draft` (only drafts) or `--no-draft`
+(only published).
+Prefer narrower queries — e.g. `brain search "interview prep"
+--person "person-x" --after 2026-03-01 --kind transcript` is much better
+signal than the same query unfiltered.
+
+**Explain a search** — `brain explain "..."` shows per-result FTS rank,
+vector cosine, RRF contributions, and recency boost so you can debug
+why a result ranked where it did. `--verbose` also shows active filters.
+
+**Read full** — `brain show <id-prefix>` (6+ chars). Returns the
+document body. `brain show <id> --json` may also include a `summary`
+field if the document has been auto-summarized; the key is omitted on
+docs that haven't been summarized yet.
+
+**Browse people** — `brain people` lists people with at least
+`BRAIN_PEOPLE_HUB_MIN_DOCS` appearances in the corpus (default 3, owner
+filtered out via `BRAIN_OWNER_PARTICIPANTS`). `brain people "Name"`
+takes a case-insensitive substring of a display name and lists that
+person's docs.
+
+**Action items** — `brain todo` lists open Krisp-meeting action items.
+Flags: `--source krisp` (only source supported today), `--since N`
+(only items from docs ingested in the last N days), `--closed` (include
+closed items, default open only), `--limit/-n N`, `--json`.
+
+**Record a rating** — when the user explicitly says a search result was
+useful or irrelevant, call `brain rate <id-prefix> useful` (or
+`irrelevant`) so the interaction is logged. Don't volunteer this — only
+when the user asks.
+
+**Ingest Gmail** — `brain ingest-gmail` (requires one or more scope
+flags — never bulk-ingest the inbox). Scope flags: `--query/-q` (raw
+Gmail search), `--label/-l`, `--from`, `--since YYYY/MM/DD`,
+`--until YYYY/MM/DD`. Optional: `--tag/-t`, `--max N` (default 50),
+`--dry-run`, `--no-enrich`.
+
+**Ingest from Krisp / Slack** — these don't have CLIs; pipe content via
+`brain ingest-stdin --source krisp|slack --external-id … --title … --date
+…` after fetching from the relevant MCP.
+
+**When in doubt:** `brain doctor` confirms it's installed and healthy.
+`brain --help` lists every subcommand.

brain/templates/skill/__init__.py

@@ -0,0 +1 @@
+"""Marker so importlib.resources can resolve this subdirectory in pipx-installed wheels."""