Vault Operations

Relevant source files

• src/utils/__tests__/file-write-lock.test.ts
• src/utils/__tests__/fs.test.ts
• src/utils/__tests__/is-errno-exception.test.ts
• src/utils/file-write-lock.ts
• src/utils/fit-image-to-byte-budget.ts
• src/utils/fs.ts
• src/utils/is-errno-exception.ts
• src/vault-mcp/mcp-core/tools/asset-tools.ts
• src/vault-mcp/obsidian-markdown/__tests__/links.test.ts
• src/vault-mcp/obsidian-markdown/links.ts
• src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts
• src/vault-mcp/vault-operations/__tests__/note-mover.test.ts
• src/vault-mcp/vault-operations/__tests__/task-updater.test.ts
• src/vault-mcp/vault-operations/__tests__/vault-filesystem.test.ts
• src/vault-mcp/vault-operations/__tests__/vault-patcher.test.ts
• src/vault-mcp/vault-operations/asset-operations.ts
• src/vault-mcp/vault-operations/note-mover.ts
• src/vault-mcp/vault-operations/task-format-config.ts
• src/vault-mcp/vault-operations/vault-filesystem.ts
• src/vault-mcp/vault-operations/vault-patcher.ts

The Vault Operations layer (vault-operations/) provides the filesystem I/O foundation for reading, writing, and surgically transforming Obsidian vault content. It bridges the gap between pure Markdown parsing and the physical storage layer, ensuring that all file manipulations maintain vault integrity and follow Obsidian-compatible conventions. All functions in this layer follow a consistent (params, logger) two-argument pattern src/vault-mcp/vault-operations/vault-filesystem.ts71-73

Core Filesystem Operations

The vaultFs object in vault-filesystem.ts provides the primary interface for interacting with .md files and binary assets. It handles path resolution, atomic writes, and structured data extraction.

Path Safety and Validation

All operations enforce strict path safety to prevent directory traversal attacks and ensure files remain within the vault boundaries.

• resolveSafePath: Resolves a vault-relative path to an absolute path, throwing an error if the result escapes the vault root src/vault-mcp/vault-operations/vault-filesystem.ts55-65
• toVaultRelativePath: Canonicalizes paths by normalizing separators and collapsing traversal segments to prevent evasion of protected-path checks src/vault-mcp/vault-operations/vault-filesystem.ts51-52
• Protected Paths: Operations like deleteNote check against protectedPaths (configured via MEMORY_DIR and DAILY_NOTES_FOLDER) after normalization to prevent accidental deletion of core configuration or memory files src/vault-mcp/vault-operations/vault-filesystem.ts400-410
• Extension Guard: CRUD functions utilize assertPathHasExtension to ensure operations only target .md files src/vault-mcp/vault-operations/vault-filesystem.ts184-188

Atomic Write Strategies

To prevent file corruption and partial writes (especially critical when syncing via Obsidian Sync), Vault Cortex uses atomic write patterns:

• atomicWriteFile: Writes content to a unique .tmp file and then performs a rename over the target. This ensures readers see either the old or new content, never a truncated or 0-byte file src/vault-mcp/vault-operations/vault-filesystem.ts117-135
• atomicWriteFileExclusive: A "no-clobber" write that fails with EEXIST if the target exists. On supported filesystems, it uses hard link for atomicity; on Windows bind-mounts (where WINDOWS_MODE is active), it uses an O_EXCL (wx flag) placeholder reservation followed by a rename to maintain TOCTOU safety src/vault-mcp/vault-operations/vault-filesystem.ts156-182

Specialized Reads and Asset Operations

Beyond raw file reading, vaultFs and asset-operations.ts provide structured access:

• readNoteOutline: Returns frontmatter and a list of all headings in the note src/vault-mcp/vault-operations/vault-filesystem.ts257-273
• readNoteSection: Extracts the content of a specific heading section, including its sub-headings src/vault-mcp/vault-operations/vault-filesystem.ts275-305
• readAssetContent: Dispatches files to their most useful representation: images fitted to a byte budget, canvases linearized, or PDFs rendered as images/structured text src/vault-mcp/vault-operations/asset-operations.ts21-31

Sources: src/vault-mcp/vault-operations/vault-filesystem.ts src/vault-mcp/vault-operations/asset-operations.ts src/vault-mcp/config.ts

Surgical Editing with Vault Patcher

The vaultPatcher implements high-precision edits that target specific parts of a note, preserving frontmatter and formatting without full-file rewrites where possible.

Heading-Targeted Patching

The patchNote function supports operations relative to a specific heading src/vault-mcp/vault-operations/vault-patcher.ts186-196

Operation	Behavior
append	Adds content at the end of the section's body src/vault-mcp/vault-operations/vault-patcher.ts107-112
prepend	Adds content at the start of the section's body src/vault-mcp/vault-operations/vault-patcher.ts113-118
replace	Overwrites the entire body of the section src/vault-mcp/vault-operations/vault-patcher.ts119-124
insert_before	Places content immediately before the targeted heading src/vault-mcp/vault-operations/vault-patcher.ts125-130

Find-and-Replace and Span Deletion

• replaceInNote: Performs targeted text replacement with an optional replace_all flag src/vault-mcp/vault-operations/vault-patcher.ts306-344
• deleteSpan: Removes a range of text defined by a startAnchor and an endAnchor src/vault-mcp/vault-operations/vault-patcher.ts346-386

Data Flow: Surgical Patching

Diagram: Patcher Execution Flow

Sources: src/vault-mcp/vault-operations/vault-patcher.ts src/vault-mcp/vault-operations/vault-filesystem.ts

Note Relocation and Link Rewriting

The note-mover.ts module handles moving notes while maintaining vault-wide referential integrity by updating all links pointing to the moved file src/vault-mcp/vault-operations/note-mover.ts1-19

Two-Phase Orchestration

The moveNote function follows a "preflight then commit" pattern src/vault-mcp/vault-operations/note-mover.ts271-354:

1. Preflight: Reads every note identified as a backlink source and computes the rewritten content. If any parse fails, the operation aborts.
2. Commit:
   • Writes the note to the new destination via atomicWriteFileExclusive src/vault-mcp/vault-operations/note-mover.ts322
   • Writes updated backlink sources using mapWithConcurrency src/vault-mcp/vault-operations/note-mover.ts330-338
   • Deletes the original note and optionally pruneEmptyParents src/vault-mcp/vault-operations/note-mover.ts347-350

Intelligent Link Reconstruction

The mover re-resolves links to determine the best format for the new location.

• classifyLinkForm: Detects if the original link was a basename, absolute, or relative path src/vault-mcp/vault-operations/note-mover.ts94-116
• buildReplacementTarget: Constructs the new link. If a short "basename" link would become ambiguous at the new location, it upgrades it to a vault-absolute path src/vault-mcp/vault-operations/note-mover.ts123-155

Diagram: Link Rewriting Logic

Sources: src/vault-mcp/vault-operations/note-mover.ts src/vault-mcp/obsidian-markdown/links.ts

Asset Operations

The asset-operations.ts module provides a grouped read/browse surface for non-markdown files, handling media processing and format conversion src/vault-mcp/vault-operations/asset-operations.ts17-31

Asset Dispatching

• Images: Supported formats (.png, .jpg, .jpeg, .gif, .webp) are processed through fitImageToByteBudget to ensure they fit within MCP response limits src/vault-mcp/vault-operations/asset-operations.ts35-36
• PDFs: Can be rendered as structured Markdown text (preserving headings and links) or as sequential page images using renderPdfPages src/vault-mcp/vault-operations/asset-operations.ts115-122
• Canvas: Obsidian .canvas files are linearized into a readable Markdown outline using linearizeCanvas src/vault-mcp/vault-operations/asset-operations.ts221-224
• Text Passthrough: Formats like .svg, .json, .csv, and .txt are returned verbatim, capped at MAX_TEXT_OUTPUT_BYTES (100 KiB) src/vault-mcp/vault-operations/asset-operations.ts40-54

Sources: src/vault-mcp/vault-operations/asset-operations.ts src/vault-mcp/mcp-core/tools/asset-tools.ts

Structured Memory and Daily Notes

Memory Store

The memory-store.ts module manages the About Me/ directory using heading-aware logic for dated bullet entries src/vault-mcp/vault-operations/memory-store.ts1-15

• Shrink Guard: Refuses writes reducing file size by >50% (above SHRINK_FLOOR_BYTES of 1250) to prevent accidental clobbering src/vault-mcp/vault-operations/memory-store.ts28-43
• Idempotency Guard: Detects if an identical dated entry already exists to avoid duplicate writes src/vault-mcp/vault-operations/memory-store.ts400-405

Daily Notes

The daily-notes.ts module reads .obsidian/daily-notes.json to resolve paths for specific dates using Luxon, respecting user-defined formats and folders src/vault-mcp/vault-operations/daily-notes.ts41-65

Sources: src/vault-mcp/vault-operations/memory-store.ts src/vault-mcp/vault-operations/daily-notes.ts

Write Locking and Concurrency

The system uses file-write-lock.ts to prevent race conditions during concurrent tool calls.

• withFileLock: Serializing. Queues operations. Used by memory-store.ts src/utils/file-write-lock.ts68-78
• withExclusiveFileLock: Fail-fast. Rejects if a write is in progress. Used by vault-patcher.ts src/vault-mcp/vault-operations/vault-patcher.ts9
• withExclusiveMultiFileLock: Multi-file Fail-fast. Atomic acquisition for multiple files. Used by note-mover.ts src/vault-mcp/vault-operations/note-mover.ts33

Sources: src/utils/file-write-lock.ts src/vault-mcp/vault-operations/vault-patcher.ts src/vault-mcp/vault-operations/note-mover.ts