Brain Proactivity

Hybrid search and GraphRAG are reactive — the user asks, the brain answers. This skill is the proactive half: commands that surface things the user did not think to ask for. All run from any directory and are read-only unless "Safety rules" below says otherwise.

For a specific question, quotes, or voice writing, use consult-brain; for one composed cited answer, brain-ask; for themes across a relationship, brain-graph; for open action items, brain-todo; for jotting or triaging a thought, brain-capture; for ingesting existing content, ingest-brain; for a deliberate titled note, brain-authoring. Boundary with brain-memory: that skill owns what you the agent record about the user across sessions — this skill only reads and triages what the user already put in their corpus.

Which command answers which question

Daily digest — brain brief

Recent captures, open todos, pins, people/orgs/projects new this week (graph on), and best-effort LLM next steps. Surfaces titles, todo texts and entity names only — never document bodies.

brain brief                              # today's digest to the terminal
brain brief --since 48 --todo-since 14   # widen both windows
brain brief --wiki                       # also write the dated vault page
brain brief --no-enrich                  # skip the LLM next-step suggestions
brain brief --date 2026-06-09 --json

Delivery (opt-in, BRAIN_BRIEF_DELIVERY=email|slack) sends the page's titles to you, never to a shared channel; detail in docs/configuration.md (BRAIN_BRIEF_DELIVERY).

Saved searches — brain watch

A saved query; every brief checks the enabled ones and lists documents that newly match (new, or edited since) under "Watch hits". By words unless --semantic. add records current matches as already seen.

brain watch add roadmap "quarterly roadmap" [--source krisp] [--tag t] [--person P] [--semantic]
brain watch list | check [NAME] [--peek] | hits [NAME] --since 7d | pause | resume | rm NAME

check RECORDS what it finds; to look without consuming the brief's notifications use --peek (MCP brain_watch_check always peeks).

Near-duplicates — brain dedup

Pairs of near-copies (a forwarded email, a re-sent draft, one file ingested twice), recorded at an estimated word-5-gram similarity of 0.85 or more; documents under 50 words and two of one Gmail thread never pair. Flags only: it never merges or deletes. The brief job scans nightly and the brief shows a "Possible duplicates (N)" count.

brain dedup list [--status open|dismissed|confirmed] [--json]   # MCP: brain_dedup_list
brain dedup scan [--all] [--limit N] | dismiss A B | confirm A B   # A B: id prefixes

dismiss and confirm are the user's labels: a dismissed pair is never re-opened, so ask before labelling, and deleting one of a pair stays brain rm.

Spaced repetition — brain resurface

Scores every non-draft, non-action-item document from age, last-access staleness, and importance (tags + summary), then lists the highest scorers. Re-scored fresh on each run, so a doc the user just opened drops out on its own.

brain resurface                      # top 7 due for review
brain resurface -n 15                # surface more
brain resurface --min-age-days 30    # only docs older than 30 days
brain resurface --source krisp       # krisp | gmail | manual | slack
brain resurface --json

Defaults: --limit/-n 7, --min-age-days 14.

Weekly synthesis and the review queue — brain review

Six subcommands. weekly writes a synthesis page; scan fills a findings queue that list reads and snooze / resolve / dismiss work through.

# Weekly synthesis page → <vault>/reviews/<week>.md
brain review weekly                          # current ISO week
brain review weekly --week 2026-W23          # a specific week
brain review weekly --no-graph               # tag-cluster themes (no AGE)
brain review weekly --no-emit --json         # stdout only, writes nothing

# Contradiction + staleness scan, then read the queue
brain review scan                            # both scans
brain review scan --conflicts --dry-run      # conflicts only, no writes
brain review scan --stale
brain review list --kind conflicts -n 10     # kind: conflicts | stale | all

Working the queue

Three verbs move a finding out of the open queue. Pick the one that matches what actually happened — they are not interchangeable, and the queue is only useful while they stay honest.

brain review snooze <id-prefix>              # hide for 7 days (default)
brain review snooze <id-prefix> --days 3     # hide for 3
brain review resolve <id-prefix>             # "I acted on this"
brain review dismiss <id-prefix>             # "this was never real"

All three take the short id prefix that review list prints. An unknown or ambiguous prefix exits 1 with a clear message — read it rather than retrying with a longer guess.

Notes that matter:

• --json on weekly implies --no-emit — asking for JSON never writes the vault page.
• scan with neither --conflicts nor --stale runs both.
• scan --json is newline-delimited JSON, one finding per line — not a JSON array. review list --json is an array.
• Findings land in elicitation_gaps, shared with brain elicit. For eliciting unwritten knowledge rather than reviewing existing notes, hand off to elicit-brain.

Evolution over time — brain timeline

Buckets the documents mentioning an entity by document date (COALESCE(sent_at, ingested_at)) and reports per-period doc counts, co-topics, and representative titles.

brain timeline "platform migration"
brain timeline "hiring" --granularity year
brain timeline "Project Phoenix" --person "Jane Doe"
brain timeline "pricing" --since 2026-01 --until 2026-06
brain timeline "pricing" --synthesize            # best-effort Ollama narrative
brain timeline "pricing" --json

Requires the graph layer (BRAIN_GRAPH_ENABLED + brain graphrag build). An unknown entity prints a friendly note and exits 0 — that is not a failure, so do not retry it with variations. Report "nothing in the graph under that name" and offer brain search --brief instead.

Auto-link suggestions — brain connect

Surfaces note pairs that share entities or semantics but are not linked yet. refresh blends an entity-graph affinity leg with an embedding leg via RRF, drops already-linked and below-threshold pairs, and upserts the top suggestions per source doc. Accepted and rejected rows are frozen and never re-proposed.

brain connect                          # bare = the pending queue
brain connect list --all --json        # every status
brain connect refresh                  # recompute + upsert pending
brain connect refresh --doc <id-prefix> --dry-run
brain connect accept <suggestion-id> --write   # accept + append the wikilink
brain connect accept <suggestion-id>           # accept, write nothing
brain connect reject <suggestion-id>
brain connect stats                    # pending / accepted / rejected counts

Suggestion ids are prefixes of ≥6 chars, same convention as document ids. accept --write appends a path-form wikilink under a ## See Also section at the end of the source doc's vault file; the write is idempotent, so a repeated accept never duplicates the link.

Search-failure gaps — brain gaps

Mines the search_queries log for queries the brain failed to answer — zero_results (nothing matched) and no_click (results returned, never opened) — then clusters them.

brain gaps                            # failed-query clusters over the window
brain gaps --since 60 -n 30           # bare number is DAYS (0 = config default)
brain gaps --json
brain gaps push                       # upsert search_failure gaps into the queue
brain gaps push --dry-run

This answers "what does my brain keep failing to answer" — a retrieval observation. For "what do I know but have never written down", that is tacit-knowledge elicitation: use elicit-brain instead. gaps push feeds the same elicitation_gaps queue, which is where the two meet.

Prerequisites and graceful degradation

If a command errors outright rather than degrading, route to brain-maintenance (brain doctor first) instead of retrying.

Safety rules

• brain connect accept --write mutates a vault file. Confirm with the user before passing --write; accept without it only flips the status.
• brain review dismiss is not undoable from the CLI. Confirm the finding is really noise first. When the user means "not right now", snooze is the correct verb — it is self-reversing. When they mean "I dealt with it", use resolve. Reaching for dismiss because it is the one you remember silently destroys the queue's signal.
• Never clear the review queue on the user's behalf. Snoozing or resolving findings in bulk to make a list look tidy is a data-quality loss, not housekeeping. Adjudicate one at a time, with the user.
• brain review weekly writes <vault>/reviews/<week>.md by default. Use --no-emit (or --json, which implies it) when the user only wants to read the synthesis.
• brain brief prints titles and todo texts, never bodies. Never paste a document body the command did not print. If the user asks for one, fetch it explicitly — brain recall "<topic>" --budget 2000 --json when they want the substance, brain show <id> --json for a single named document. Never brain show every item the brief listed; that is unbounded — one whole body per item. See the cost-ordered table in consult-brain.
• Exit 0 with an empty result is a valid answer. An empty brief, zero resurfaced docs, or an unresolved timeline entity means "nothing to surface" — say so rather than broadening until something appears.