Obsidian Vault File Operations Reference

This document describes how to perform filesystem-first operations on an Obsidian vault. All operations use file tools (read_file, write_file, search_files, patch) in preference to shell commands (cat, find, ls, grep, echo, heredocs) because vault paths may contain spaces and file tools handle them reliably.

Prerequisites

• The Obsidian vault path must be known or resolvable.
• File tools (read_file, write_file, search_files, patch) must be available.
• For wikilinks, note names must be valid Obsidian note names.

Resolving the Vault Path

Before any file operation, resolve the vault path to a concrete absolute path. File tools do not expand shell variables, so you must never pass a path containing $OBSIDIAN_VAULT_PATH to them.

1. Check the OBSIDIAN_VAULT_PATH environment variable. It may be set in ${HERMES_HOME:-~/.hermes}/.env.
2. If the variable is unset, use the fallback path ~/Documents/Obsidian Vault.
3. If the vault path is still unknown, use terminal to resolve OBSIDIAN_VAULT_PATH or check whether the fallback exists.
4. Once known, use the resolved absolute path for all file tools.

Reading a Note

To read a note with line numbers and pagination:

1. Resolve the absolute path to the note.
2. Use read_file with that path.

Listing Notes

To list all markdown notes in the vault:

• Use search_files with target: "files" and the resolved vault path.
• Use pattern: "*.md" to restrict to markdown files.

To list notes in a subfolder, search under that subfolder's absolute path.

Searching Notes

Search by Filename

• Use search_files with target: "files" and a filename glob as pattern.

Search by Content

• Use search_files with target: "content", a content regex as pattern, and optionally file_glob: "*.md" to restrict to markdown notes.

Creating a Note

1. Resolve the absolute path for the new note.
2. Use write_file with that path and the full markdown content.

When creating a note, you can add wikilinks using [[Note Name]] syntax to link related notes.

Appending to a Note

Prefer the file-tool workflow. Read the target note first with read_file.

• Option A (anchored append with patch): Use patch to replace an anchor with the anchor plus new content. This works when stable context exists, such as after a heading or before a known trailing block. Replace the anchor with anchor plus new content.
• Option B (full rewrite): Use write_file to rewrite the entire note if a fragile patch would be unclear.
• Last resort: If no stable context exists and the file-tool workflow is awkward, terminal is acceptable as the clearest safe option.

Making Targeted Edits

Use patch with stable context from the current content. The anchor text must be unique and unchanged for the patch to succeed.

Parameters

OBSIDIAN_VAULT_PATH

• Meaning: Environment variable specifying the vault's absolute path; may contain spaces.
• Required: Yes, or use fallback ~/Documents/Obsidian Vault.

target

• Meaning: For search_files: "files" for filename search, "content" for content search.
• Required: Yes for search_files.

pattern

• Meaning: For search_files: filename glob (e.g., "*.md") or content regex.
• Required: Yes for search_files.

file_glob

• Meaning: Optional filter for content search (e.g., "*.md" to restrict to markdown notes).
• Required: No

Constraints and Caveats

• File tools do not expand shell variables; resolve the vault path to a concrete absolute path before passing to read_file, write_file, patch, or search_files.
• Do not pass paths containing $OBSIDIAN_VAULT_PATH to file tools.
• Vault paths may contain spaces; prefer file tools over shell commands for this reason.
• Prefer file tools (read_file, write_file, search_files, patch) over shell commands (cat, find, ls, grep, echo, heredocs) for all operations.
• terminal is acceptable only for resolving the vault path or as a last resort for simple append when no stable context exists.
• For anchored append with patch, replace the anchor with anchor plus new content.

Failure Modes

• Using unresolved $OBSIDIAN_VAULT_PATH in file tools causes failure because shell variables are not expanded.
• Using shell commands for file operations may fail due to spaces in the vault path or quoting issues.
• Fragile patch may fail if anchor text is not unique or has changed.
• Terminal-based append may produce unexpected results if not carefully constructed.

Examples

• Reading a note: Use read_file with the resolved absolute path to get line numbers and pagination.
• Listing all markdown notes: Use search_files with target: "files" and pattern: "*.md".
• Searching note content: Use search_files with target: "content" and a regex pattern, optionally with file_glob: "*.md".
• Creating a note: Use write_file with the resolved path and full markdown content.
• Appending after a heading: Use patch to replace the heading anchor with the heading plus new content.
• Adding a wikilink: Use [[Note Name]] syntax when creating or editing a note.