vault-workflow

---
name: vault-workflow
description: Use when the user asks you to search, read, or reason about notes in their markdown vault — guides when to use which vault tool and how to chain them for good results.
---

# Working effectively with the markdown vault

When the user mentions "my vault", "my notes", or asks a question that could
be answered from their knowledge base, use the markdown-vault-mcp tools as
follows.

## Search strategy

- **Default to `search` with `mode="hybrid"`** — combines BM25 keyword and
  embedding similarity, gives the best recall for conceptual questions.
- Fall back to `mode="keyword"` only when the user gives an exact phrase or
  tag they want matched literally.
- If hybrid returns nothing and the query is a proper noun, retry with
  `mode="keyword"` — embeddings miss exact names.

## Reading and context

- After finding a relevant note with `search`, call `get_context` on the top
  hit before reading the full body. Context returns backlinks, outlinks,
  similar notes, folder peers, and tags in one call — usually enough to
  answer without reading the file.
- Only call `read` when the user asks for the text itself or when
  `get_context` does not give enough signal.

## Link-graph questions

- "What notes reference X?" → `get_backlinks`.
- "What does this note link to?" → `get_outlinks`.
- "How are these two notes connected?" → `get_connection_path`.
- "What is orphaned?" → `get_orphan_notes`.
- "What is most cited?" → `get_most_linked`.

## Writes (only if read-only mode is disabled)

- Prefer `edit` over `write` for targeted changes — `edit` fails safely if
  the old text is not unique, preventing accidental overwrites.
- Use `rename(update_links=True)` for moves, never `write` to a new path plus
  `delete` of the old path — the `update_links` flag repairs internal
  references.
- Never call `reindex` after writes; the server updates its index inline.

## Do not

- Do not use `list_documents` as a search substitute — it is a flat
  enumeration, not ranked.
- Do not read a note and then re-search for it; remember the path from the
  first result.