Read a markdown note by its vault-relative path. Returns the full raw content including properties, or just the parsed properties when properties_only is set.

Example: vault_read_note({ path: "Projects/vault-cortex.md" }) Example: vault_read_note({ path: "Projects/vault-cortex.md", properties_only: true })

When to use: You know the exact path and need the full content of a specific note. Use properties_only: true when you only need properties (saves tokens on large notes). Prefer vault_search when you don't know the path. Prefer vault_get_memory for About Me/ files (returns content without properties).

Returns: Raw markdown string (default), or JSON object of properties (when properties_only: true).

Create or update a markdown note. Body replaces the entire note content — this is a full overwrite, not a partial edit. Properties are passed separately and merged with any existing properties (new keys added, matching keys overwritten, unmentioned keys preserved).

Example: vault_write_note({ path: "Projects/notes.md", body: "# Notes\n\nProject notes here.", properties: { tags: ["project"], type: "project" } })

When to use: Creating a new note or fully replacing an existing note's body. Prefer vault_update_properties for property-only edits (no body round-trip). Prefer vault_update_memory for appending dated entries to About Me/ memory files.

Limitation: Overwrites the entire body. Do not use for surgical edits to large files — existing content will be lost unless you include it in the body parameter.

Obsidian syntax: Body content is rendered as Obsidian Flavored Markdown with no escaping applied. Beyond standard Markdown, watch for Obsidian-specific patterns:

• #word (no space after #) = tag — escape with # or backticks

• [[ = wikilink, ![[ = embed — escape with [[

• %% = comment block (hidden in reading view) Properties: quote wikilink values ("[[Note]]"), use YAML lists for tags ([tag1, tag2]), keep property types consistent across the vault (string/number/list mismatches cause silent query failures).

Returns: Confirmation message.

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):

1. vault_read_note to get current content and verify exact text

2. vault_replace_in_note({ path, old_text: "- [ ] Task text", new_text: "" }) to remove from source

3. 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.

Find and replace text in a markdown note's body. Matches exact text (case-sensitive). Properties are preserved; YAML formatting may be normalized to block style on first edit. Operates on the body only — properties must be edited via vault_update_properties or vault_write_note's properties parameter.

Example: vault_replace_in_note({ path: "Projects/plan.md", old_text: "TODO: write summary", new_text: "Summary complete." })

When to use: Targeted text changes within a single location — fixing typos, updating values, renaming terms, or removing a specific line (new_text=""). Replaces text in place; does not move content across sections. To relocate content between headings, use vault_replace_in_note to remove from the source (new_text=""), then vault_patch_note to append at the target. Read the note first with vault_read_note to confirm exact text.

Limitation: Exact text match only (no regex). old_text must appear in the note body or an error is returned.

Errors:

• "note not found" — path does not exist; check vault_list_notes for valid paths

• "text not found" — old_text does not appear in the note body; verify exact text with vault_read_note

• "old_text cannot be empty" — old_text must be at least one character

Obsidian syntax: new_text is rendered as Obsidian Flavored Markdown with no escaping applied. Beyond standard Markdown, Obsidian-specific patterns (#word = tag, [[ = wikilink, %% = comment block) apply to replacement text. Verify replacements won't introduce unintended Obsidian rendering.

Returns: Confirmation message with replacement count.

List .md file paths in the vault, optionally filtered by folder and/or glob pattern. Returns paths only — not content or metadata.

Example: vault_list_notes({ folder: "Projects" }) or vault_list_notes({ glob: "**/session-log.md" })

When to use: Browsing what exists in a folder by filename, or finding notes matching a path pattern. Prefer vault_search_by_folder when you need metadata (tags, type, related) along with paths. Prefer vault_search for content-based discovery.

Returns: JSON array of vault-relative paths.

Permanently delete a markdown note. The note is removed from disk directly (not moved to a trash folder), and this server has no undo — recovery depends on your own backups or sync history. After deletion it no longer appears in search results or backlinks, and links to it from other notes become broken (detectable via vault_get_outgoing_links). Protected paths (About Me/, Daily Notes/) are refused to prevent accidental loss of memory or daily notes.

Example: vault_delete_note({ path: "Scratch/temp.md" })

When to use: Removing a note you no longer need. Prefer vault_delete_memory for removing individual dated entries from About Me/ memory files.

Errors:

• "cannot delete protected path …" — the path sits under a protected folder; use vault_delete_memory for memory entries

• "path traversal blocked" — path escapes the vault root; use a vault-relative path

• note does not exist — verify the path with vault_list_notes before deleting

Returns: Confirmation message.

Update properties on a single note. Merges with existing properties — new keys are added, matching keys are overwritten, unmentioned keys are preserved. Body content is never modified.

Example: vault_update_properties({ path: "Projects/todo.md", properties: { status: "active", priority: 1 } })

Read current properties first with vault_read_note({ properties_only: true }) — merge overwrites each key entirely (arrays are replaced, not appended to).

When to use: Changing tags, status, type, or any property without reading/rewriting the full note body. Saves tokens on large notes. Prefer vault_write_note when creating a new note or replacing the body.

Errors:

• "note not found" — path does not exist; create the note first with vault_write_note

• "path traversal blocked" — path escapes vault root

Obsidian syntax: Property values follow YAML conventions. Use arrays for multi-value fields (tags: [a, b]), quote wikilink values ("[[Note]]"), keep property types consistent across the vault (string/number/list mismatches cause silent query failures).

Returns: Confirmation message.

Full-text search across all vault notes, ranked by relevance. Supports filtering by folder, tags, type, and properties. Wrap terms in double quotes for exact phrase matching (e.g. '"machine learning"'); unquoted terms use implicit AND with porter stemming.

Example: vault_search({ query: "kubernetes networking", filters: { tags: ["reference"] } })

When to use: Finding notes by content when you don't know the exact path. The primary discovery tool for content-based queries. Prefer vault_search_by_tag for tag-only queries without text. Prefer vault_search_by_folder for browsing a folder without a search term. Prefer vault_recent_notes for time-based browsing.

Returns: JSON with results array (path, title, snippet, score, tags, folder, type, created, modified) and total count. created is omitted when null.

Find notes with a specific tag. By default uses hierarchical prefix matching — a parent tag matches all children (e.g. "project" matches "project/vault-cortex", "project/blog"). Set exact=true for exact match only.

Example: vault_search_by_tag({ tag: "project" }) returns all notes tagged project or project/*.

When to use: Exploring tag hierarchies or finding all notes with a specific tag, without needing a text query. Prefer vault_search when you also need text-based relevance ranking. Use vault_list_tags first to discover available tags.

Returns: JSON array of note metadata (path, title, tags, related, folder, type, created, modified, additional_properties), sorted by most recently modified. Promoted keys are in top-level fields; additional_properties contains only unpromoted keys.

List all tags in the vault with their note counts, ordered by count descending.

Example: vault_list_tags() returns [{ tag: "session-log", count: 42 }, { tag: "project", count: 15 }, ...]

When to use: Discovering what tags exist in the vault before searching by tag. Good first step for vault orientation. Prefer vault_search_by_tag once you know which tag to query.

Returns: JSON array of { tag, count } objects.

List recently modified or created notes, sorted by timestamp. Returns the most recent notes first — does not filter by date range.

Example: vault_recent_notes({ sort_by: "modified", limit: 10 })

When to use: Catching up on vault changes or finding recent work. Prefer vault_search for content-based discovery. Prefer vault_search_by_folder for browsing a specific folder.

Returns: JSON array of note metadata (path, title, tags, related, folder, type, created, modified, additional_properties), sorted by chosen timestamp.

Browse notes in a folder with full metadata (tags, type, related, created, modified) — unlike vault_list_notes, which returns paths only.

Example: vault_search_by_folder({ folder: "Projects" }) or vault_search_by_folder({ folder: "About Me", recursive: false })

When to use: Exploring a folder's contents with full context for vault orientation. Prefer vault_list_notes when you only need paths. Prefer vault_search when you have a text query.

Parameters:

• folder is matched as a path prefix; pass it without a trailing slash ("Projects").

• recursive (default true) includes all nested subfolders; set false to list only the folder's top level.

• limit (default 20) caps results.

Errors:

• An empty or nonexistent folder returns an empty array, not an error.

Returns: JSON array of note metadata (path, title, tags, related, folder, type, created, modified, additional_properties), sorted by most recently modified.

Read semantic memory from About Me/ files. These are structured memory files containing dated bullet entries organized under H2 headings. With file: single file content. With file+section: just that H2 section's entries. No args: all files concatenated (frontmatter stripped) — can be large. Returns empty string when no memory files exist yet.

Example: vault_get_memory({ file: "Principles", section: "Decision heuristics (newest first)" })

When to use: Reading user preferences, principles, opinions, or other persistent context stored in About Me/ files. Call vault_list_memory_files first to discover valid file and section names. Prefer vault_read_note for reading non-memory notes.

Returns: Raw markdown text.

Append a dated entry to a section of a About Me/ memory file. The server prefixes the date automatically (format: "- YYYY-MM-DD: entry text") and inserts newest-first by default. Pass raw entry text without a date prefix.

Example: vault_update_memory({ file: "Opinions", section: "Code patterns (newest first)", entry: "Prefer immutable data structures" })

When to use: Recording a new preference, principle, opinion, or fact about the user. Call vault_list_memory_files first and reuse existing file and section names so entries stay grouped. Prefer vault_write_note for creating non-memory notes.

Behavior: Additive — existing entries are never overwritten, and repeat calls add duplicate entries. A missing file or section is created automatically; if the section name omits "(newest first)" the server appends it ("Design preferences" becomes "Design preferences (newest first)") — use that full name in later calls.

Parameters:

• options.date — ISO YYYY-MM-DD, defaults to today (server timezone).

• options.position — "top" (default, newest-first) inserts above existing entries; "bottom" appends below them.

Obsidian syntax: Entry text renders as Obsidian Flavored Markdown. Watch for: #word = tag, [[ = wikilink. Escape with backslash or backticks when unintentional.

Returns: Confirmation message.

Discovery tool — lists About Me/ memory files with their H1/H2 heading structure and per-section entry counts. Does NOT return actual entries.

Example: vault_list_memory_files() returns file outlines with headings like "Decision heuristics (newest first)" and entry counts.

When to use: Discovering what memory files and sections exist BEFORE calling vault_get_memory, vault_update_memory, or vault_delete_memory. Always call this first to get valid file and section names.

Returns: JSON array of file outlines.

Delete a single dated entry from a About Me/ memory file. Both date and entry text are required for exact matching — ensures only the intended entry is removed.

Example: vault_delete_memory({ file: "Opinions", section: "AI tooling & memory (newest first)", date: "2026-05-01", entry: "Prefer X over Y" })

When to use: Removing an outdated or incorrect entry from a memory file. Call vault_get_memory(file, section) first to see exact entry text for matching. Prefer vault_delete_note for deleting entire non-protected notes.

Returns: Confirmation message.

Read a daily note by date, using the vault's configured Daily Notes folder and date format (from .obsidian/daily-notes.json). Defaults to today if no date is provided.

Example: vault_get_daily_note({ date: "2026-05-13" })

When to use: When you need today's or a specific date's daily note. Handles path resolution automatically using the vault's Obsidian config — you don't need to know the folder name or filename format. To append content to a daily note section, use the returned path with vault_patch_note.

Errors:

• "invalid date" — use YYYY-MM-DD format (e.g. "2026-05-13")

Returns: JSON with path (resolved vault-relative path), content (note body or null), and exists (boolean). When exists is false, use vault_write_note with the returned path to create the note.

Discover all property keys in the vault with note counts and sample values. Lets you understand the vault's metadata schema without reading individual notes.

Example: vault_list_property_keys() returns [{ key: "tags", count: 342, sample_values: ["session-log", "project"] }, ...]

When to use: Discovering what properties exist before searching by property. Good first step for vault orientation alongside vault_list_tags. Prefer vault_list_property_values when you need the full list of values for a specific key. Prefer vault_search_by_property to find notes matching a specific key-value pair.

Returns: JSON array of { key, count, sample_values } sorted by count descending. sample_values shows the top 3 most common values for quick orientation.

List distinct values for a specific property key with note counts. Useful for discovering the range of values a property takes before searching.

Example: vault_list_property_values({ key: "status" }) returns [{ value: "active", count: 47 }, { value: "done", count: 211 }, ...]

When to use: Enumerating possible values for a property key before calling vault_search_by_property. Handles both scalar properties (status: "active") and array properties (tags: ["a", "b"]) — array elements are enumerated individually. Call vault_list_property_keys first to discover valid key names.

Returns: JSON array of { value, count } sorted by count descending.

Find notes where a property matches a value (exact match). Unlike vault_search, this does not require a text query — it searches by metadata only. Handles both scalar properties (status: "active") and array properties (tags contains "project").

Example: vault_search_by_property({ key: "status", value: "in-progress" })

When to use: Finding notes by metadata when you don't have a text query. Fills the gap where vault_search requires search text. Prefer vault_search when you also have a text query (it supports property filters too). Prefer vault_search_by_tag for tag-specific queries (supports hierarchical prefix matching).

Returns: JSON array of note metadata (path, title, tags, related, folder, type, created, modified, additional_properties), sorted by most recently modified.

Find all notes that link to a given note via incoming [[wikilinks]] or markdown. Reveals what references the target — its context and importance in the knowledge graph, invisible without a graph query. Both link styles are captured; links inside code blocks are ignored, and a note that links to itself appears in its own backlinks.

Example: vault_get_backlinks({ path: "Projects/vault-cortex.md" })

When to use: Understanding what references a note or assessing its connectivity. For outgoing links (what a note links TO), use vault_get_outgoing_links. To find notes with no backlinks at all, use vault_find_orphans.

Parameters:

• path must be the exact vault-relative path — case-sensitive, including the .md extension.

Errors:

• A note with no inbound links, or a path not in the index, returns an empty array (count 0), not an error — don't use this as an existence check.

Returns: JSON with path (the queried note), backlinks (array of { path, title }, sorted by title), and count.

Find all notes a given note links to via outgoing [[wikilinks]] or markdown. Each entry has an exists flag — false marks a broken link (target not in the vault). Both link styles are captured; links inside code blocks are ignored, and a note that links to itself appears in its own outgoing links.

Example: vault_get_outgoing_links({ path: "Projects/vault-cortex.md" })

When to use: Seeing what a note references, navigating the graph forward, or finding broken links in one note. For incoming links (what links TO a note), use vault_get_backlinks.

Parameters:

• path must be the exact vault-relative path — case-sensitive, including the .md extension.

Errors:

• A note with no outbound links, or a path not in the index, returns an empty array (count 0), not an error.

Returns: JSON with path (the queried note), outgoing_links (array of { path, title, exists }, sorted by target path), and count.

Find notes with no incoming links from other notes — orphans are disconnected from the knowledge graph and may be forgotten or need linking. A note that only links to itself still counts as an orphan (self-links are ignored).

Example: vault_find_orphans({ exclude_folders: ["Daily Notes","Templates","About Me"] })

When to use: Vault maintenance — surfacing notes to integrate into the graph. Link an orphan by mentioning it from a relevant note with vault_patch_note. Prefer vault_get_backlinks to check the connectivity of one specific note rather than scanning the whole vault.

Parameters:

• exclude_folders replaces the defaults (["Daily Notes","Templates","About Me"]), it does not add to them — include the defaults yourself to keep them. Matched by folder prefix, recursing into subfolders ("Projects" also excludes "Projects/Archive").

• limit (default 50) caps results after sorting by most-recently-modified.

Errors:

• An empty array means no orphans were found (after exclusions), not an error.

Returns: JSON array of note metadata (path, title, tags, related, folder, type, created, modified, additional_properties), sorted by most recently modified.