vault-workflow

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.