-
MCP (default for vault data operations)
- Read/write/patch/move/search notes
- Frontmatter and tag updates
- Metadata and batch note operations
-
Obsidian CLI/App context (only when app context is needed)
- Open a note in Obsidian from URI
- Trigger app/plugin workflows that MCP cannot perform
-
CLI git (sync/backup workflows)
- Initialize repo, configure remote, commit, pull, push
- Periodic or manual vault backup/sync requests
When a request is ambiguous, pick MCP first unless the user explicitly asks for sync/backup/git/app behavior.
-
patch_note rejects multi-match by default. With replaceAll: false, if oldString appears more than once the call fails and returns matchCount. Set replaceAll: true only when you mean it, or add surrounding context to make the match unique.
-
patch_note matches inside frontmatter. The replacement runs against the full file including the YAML block. A generic string like title: will match frontmatter fields. Include enough context to target the right occurrence.
-
patch_note forbids empty strings. Both oldString and newString must be non-empty and non-whitespace. To delete text, use newString with a single space or restructure the note with write_note.
-
search_notes returns minified JSON. Fields are abbreviated: p (path), t (title), ex (excerpt), mc (matchCount), ln (lineNumber), uri (obsidianUri). Hard cap of 20 results regardless of limit.
-
search_notes multi-word queries score terms individually AND as a phrase. Each term is OR-matched, so a document matching any term appears in results. The full phrase gets an additional scoring boost.
-
write_note auto-creates directories. Parent folders are created recursively. In append/prepend mode, if the note doesn't exist it's created. Frontmatter is merged (new keys override) in append/prepend; replaced entirely in overwrite.
-
delete_note requires exact path confirmation. confirmPath must be character-identical to path. No normalization, no trailing-slash tolerance. Mismatch silently fails with success: false.
-
move_file needs double confirmation. Both confirmOldPath and confirmNewPath must exactly match their counterparts. Use move_note for markdown renames (text-aware, no confirmation needed); use move_file only for binary files or when you need binary-safe moves.
-
manage_tags reads from two sources but writes to one. list merges frontmatter tags + inline #hashtags. add/remove only modify the frontmatter tags array. Inline tags are never touched.
-
read_multiple_notes never rejects. Uses allSettled internally. Failed files appear in the err array; successful ones in ok. Always check both. Hard limit of 10 paths per call.
When the user asks to "sync", "backup", or "store my vault with git", use CLI git with this behavior:
-
Run a preflight before changing anything:
git available- current directory is a git repo (or prompt to initialize)
git config user.name and git config user.email are set- at least one remote exists for push/pull sync
-
If preflight is incomplete, ask exactly one targeted question with a recommended default.
- Use askuserquestion for decisions that materially change behavior.
- Good examples:
- "No git repo found. Initialize one in this vault now? (Recommended: Yes)"
- "No remote configured. Set up GitHub remote now via gh if available, or provide remote URL? (Recommended: Set up via gh)"
- "Local and remote diverged. Try
git pull --rebase now? (Recommended: Yes)"
-
Safe sync sequence (never force push by default):
git add -A- (skip commit if no changes)
Load these only when needed, not on every invocation.
