brain_search
Search a markdown vault by keyword, returning hits ranked by relevance with authority indicators, and listing excluded notes with reasons.
Instructions
Keyword search across the vault. Returns { hits, excluded }. Each hit has path, title, folder, status, snippet, and authority.
IMPORTANT — ranking is by keyword relevance, NOT by truth. A superseded document repeats the query words just as often as the live one, so it can outrank it. Every hit carries an authority: authoritative (source of truth — prefer it), current, provisional (draft/proposed — never quote as settled), superseded, archived. Rank order is a suggestion; authority is the signal.
excluded is the explainable-rejection list: notes that matched the query but were withheld because they are archived, superseded, or expired (past their valid_until), each with a reason (e.g. "superseded by price-live", "expired 2026-06-01"). When you deliberately ignore a stale note, cite its excluded entry — say what you skipped and why, instead of quoting it. If you need a withheld note, re-search with includeInvalid: true (superseded/expired) or includeArchive: true.
Before quoting a price, guarantee, contract term, or any other single-valued fact, open the authoritative note. If two live notes disagree on such a fact, that is a defect in the vault — report it rather than averaging them.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | max hits (default 20) | |
| query | Yes | search query — a few keywords beat a full sentence | |
| folder | No | restrict to one top-level folder, e.g. 'decisions' | |
| includeArchive | No | return archived notes as hits (default false → they go to `excluded`) | |
| includeInvalid | No | return superseded/expired notes as hits, still demoted (default false → `excluded`) |