Patch Note
vault_patch_notePerform precise edits to markdown notes — append, prepend, replace, or insert content by heading while preserving frontmatter.
Instructions
Surgical edits to a markdown note — append, prepend, replace, or insert content by heading. Frontmatter values are preserved; YAML formatting may be normalized to block style on first edit.
Example: vault_patch_note({ path: "TASKS.md", operation: "append", heading: "Active", content: "- [ ] New task" })
Cross-section move (e.g. completing a task on a board):
vault_read_note to get current content and verify exact text
vault_patch_note({ path, operation: "append", heading: "Done", content: "- [x] Task text" }) to add at target
vault_replace_in_note({ path, old_text: "- [ ] Task text", new_text: "" }) to remove from source (for a large multi-line block, prefer vault_delete_span); on error, re-read and retry until the source copy is gone Add at the target before deleting from the source — the two writes are not atomic, so this order can briefly duplicate the moved block on a failure but never lose it.
When to use: Modifying part of an existing note without overwriting the entire body. Prefer vault_write_note for creating new notes, or full rewrites (with overwrite: true). Prefer vault_replace_in_note for in-place text changes (typos, renaming) that stay in the same location.
Operations:
append: add content at end of section (or end of file if no heading)
prepend: add content after heading line (or at the top of the body, below frontmatter, if no heading — how you add a leading callout)
replace: replace section body (heading preserved; requires heading)
insert_before: insert content above the heading line (requires heading)
Heading-targeted ops keep the matched heading and write content verbatim — don't begin content with the target heading (it's rejected to avoid a duplicate).
Section boundaries: a section spans from its heading to the next heading of the same or higher level (or EOF). Child headings are included in the parent section.
Editing a leading callout: read it via vault_read_note(outline: true), then vault_replace_in_note the old block for the new one (a no-heading prepend would stack a second callout above it).
Errors:
"note not found" — path does not exist; check vault_list_notes for valid paths
"heading not found" — no heading matches the text; error lists available headings
"ambiguous heading" — multiple headings match; use heading_level to disambiguate, or rename a heading if they share the same level
"operation … requires a heading target" — replace and insert_before need a heading
"content begins with the heading … which would duplicate it" — content's first line repeats the target heading; omit it (the matched heading is kept automatically)
"concurrent write in progress" — another write to this note is in flight; re-read the note and retry
Obsidian syntax: Content is Obsidian Flavored Markdown (no escaping applied). Watch for: #word = tag, [[ = wikilink, %% = comment block. Inserting heading-level content (## New Section) changes the note's structure — future heading-targeted ops may resolve differently. Table rows: send only the data row ("| cell1 | cell2 |"), not the header or separator — duplicating them splits the table.
Returns: Confirmation message.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative path to the note, including the ".md" extension (e.g. "TASKS.md", "Projects/plan.md") | |
| content | Yes | Markdown content to insert. Must not begin with the target heading text (it would duplicate the heading, which is kept automatically). | |
| heading | No | Target heading text (case-sensitive exact match). Required for replace and insert_before. Optional for append/prepend (omit for file-level operation). | |
| operation | Yes | append | prepend | replace | insert_before. replace and insert_before require a heading; append and prepend work with or without one. | |
| heading_level | No | Heading level (1-6) for disambiguation when multiple headings share the same text |