Patch Note
vault_patch_noteAppend, prepend, replace, or insert content in markdown notes by targeting headings. Frontmatter and formatting are preserved.
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_replace_in_note({ path, old_text: "- [ ] Task text", new_text: "" }) to remove from source
vault_patch_note({ path, operation: "append", heading: "Done", content: "- [x] Task text" }) to add at target
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. 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 after frontmatter if no heading)
replace: replace section body (heading preserved; requires heading)
insert_before: insert content above the heading line (requires heading)
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.
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
Obsidian syntax: Content is rendered as Obsidian Flavored Markdown with no escaping applied. Beyond standard Markdown, watch for: #word (no space) = tag, [[ = wikilink, %% = comment block. Escape with # or [[ when unintentional. Structural note: inserting heading-level content (e.g. ## New Section) changes the note's section structure — future patch calls targeting headings may resolve differently.
Returns: Confirmation message.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative path to the note | |
| operation | Yes | Patch operation to apply | |
| content | Yes | Content to insert or replace with | |
| heading | No | Target heading text (case-sensitive exact match). Required for replace and insert_before. Optional for append/prepend (omit for file-level operation). | |
| heading_level | No | Heading level (1-6) for disambiguation when multiple headings share the same text |