Obsidian Vault CRUD

Status: Active Author: Richard Fremmerlid Domain: Obsidian Integration Depends On: obsidian-markdown-mastery (WP05)

Core Mandate

This skill provides the disk I/O layer for all agent interactions with the Obsidian Vault. It does NOT handle syntax parsing (that belongs to obsidian-markdown-mastery ). Instead, it ensures that every file write is:

• Atomic — via POSIX os.rename() from a .tmp staging file

• Locked — via an advisory .agent-lock file at the vault root

• Conflict-aware — via mtime comparison before/after read

• Lossless — via ruamel.yaml for frontmatter (never PyYAML)

Available Commands

Read a Note

python ./scripts/vault_ops.py read --file <path>

Create a Note

python ./scripts/vault_ops.py create --file <path> --content <text> [--frontmatter key=value ...]

Update a Note

python ./scripts/vault_ops.py update --file <path> --content <text>

Append to a Note

python ./scripts/vault_ops.py append --file <path> --content <text>

Safety Guarantees

Atomic Write Protocol

• Write content to <target>.agent-tmp

• Verify the .agent-tmp file was written completely

• os.rename('<target>.agent-tmp', '<target>') — atomic on POSIX

• If any step fails, the .agent-tmp is cleaned up

Advisory Lock Protocol

• Before any write batch: create <vault_root>/.agent-lock

• After write batch completes: remove .agent-lock

• Other agents check for .agent-lock before writing

• This is advisory (does not block Obsidian UI)

Concurrent Edit Detection

• Capture os.stat(file).st_mtime before reading

• Before writing, check st_mtime again

• If mtime changed → another process edited the file → ABORT

Frontmatter Handling

• Uses ruamel.yaml (NOT PyYAML ) to preserve comments, indentation, and array styles

• Ensures Dataview and Obsidian Properties remain intact