READ THIS FIRST, before searching or writing. Returns the vault's SCHEMA.md (folder taxonomy, frontmatter conventions, wikilink model, write protocol) AND a live description of this specific vault: its folders, the status: values actually in use, how search ranks notes by authority, and any integrity warnings. Vaults differ — never assume conventions, read them here.

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.

Read a note: full markdown (frontmatter + body), its authority, and its backlinks. Path is vault-relative, e.g. 'clients/mks/mks.md'.

Pass section to read just one heading's content instead of the whole file — cheaper on long documents. If the heading isn't found you get the list of available headings back.

Always check the returned authority before acting on the content: archived and superseded notes are history, not instructions.

List every note with metadata (path, title, folder, type, tags, status, authority). Use to discover what exists. authority tells you which notes are source-of-truth and which are history.

Notes changed most recently, newest first. Use to catch up on what humans or other agents have done since you last looked.

Return the folder/file tree of the vault.

Notes that link to the given note.

The knowledge graph (nodes + edges from wikilinks and related:). Optional folder filter.

Create or overwrite a note. PREFER body (markdown, no frontmatter) + frontmatter (an object): the YAML is serialised for you and always parses. Hand-writing frontmatter into content risks invalid YAML — a note whose frontmatter fails to parse loses its status, tags and title on every read, so a note claiming status: locked would rank as an ordinary one. Such a write is REJECTED. Follow SCHEMA.md: kebab-case path, dated names for daily/decisions, frontmatter with title/type/tags/status. Path vault-relative (e.g. decisions/foo-2026-07-09.md).

WHEN A FACT CHANGED, DON'T CREATE A DATED SIBLING. Writing acme-pricing-2026.md next to a live acme-pricing.md leaves two live notes disagreeing about one number, and the older one usually matches the query better — this is exactly how a retired price gets quoted. Such a write is REJECTED; use brain_supersede instead, which retires the old note and adds the new one in a single commit. allow_conflict: true overrides it when both notes genuinely belong.

Overwrite a note. Pass content (full raw markdown incl. frontmatter) — read first with brain_read, then write the whole file back. Also accepts body (+ optional frontmatter) like brain_write.

Append text to a note (creates it if missing).

Move or rename a note. This is how you retire something: when a note stops being true, move it to an archive folder (see brain_schema → conventions.ranking.archiveFolders) rather than deleting it. Archived notes are demoted in search and excluded by default, so they stop misleading agents while the reasoning trail survives. Leave a pointer in the replacement note saying what superseded what.

Create a new folder in the vault (with a .gitkeep).

Retire a fact and replace it, atomically. When a fact changes (a price, a term, a decision), DON'T just add a new note — the old value keeps matching searches and gets quoted. brain_supersede(from, to) marks the old note superseded in place (body preserved) and links it to the new one, in a single commit, so add-and-retire can't drift apart. After this, search withholds the old note with the reason "superseded by ".

from = the note being retired; to = the note that replaces it. If to doesn't exist yet, pass body (its markdown) and it's created; otherwise write to first, then supersede. reason is recorded on the old note. Prefer this over brain_move for a value that changed (move is for relocation).

Hand over a ROUGH note / brain-dump and let the vault file it. An agent loop reads SCHEMA.md, searches for what already exists, then deliberately creates a new note, appends to a matching one, or archives what this supersedes — and returns a manifest of every path it touched. It reads a note before overwriting it, and never deletes. Use when you have unstructured input and don't want to choose the path yourself; use brain_write when you do.

Delete a note (recoverable via git history). Prefer brain_move into an archive folder — deleting destroys the reasoning trail, archiving only removes it from search. Delete when the note is wrong or duplicated, archive when it is merely no longer true.