Obsidian Vault Integration

Obsidian Vault Integration

The agent manages an Obsidian vault as a persistent, structured knowledge base. Family members can share notes with the agent, the agent writes daily diary entries, and both the owner and agent store reference material for long-term recall.

Architecture

The vault lives locally on the agent Mac at ~/Obsidian/. Obsidian Sync keeps it in sync with all other devices (phone, tablet, desktop) via the headless sync daemon. The agent accesses notes via native plugin tools (obsidian_read_note, obsidian_write_note, etc.) that run inside the gateway process — no exec calls, no sandbox escape, no approval prompts. The obsidian-note CLI is available as a fallback via exec.

Two Access Paths

Path	How it works	Approval needed
Plugin tools (preferred)	obsidian_* tools → mcporter → mcp-obsidian MCP server	None — runs in gateway process
CLI fallback	obsidian-note via exec	Allowlisted (no approval for main agent)

The plugin path is preferred because it bypasses both the exec allowlist and sandbox entirely. The CLI fallback is useful if mcporter or the MCP server is unavailable.

Use Cases

Daily Diary

The agent maintains a daily note as a running log of what happened each day:

• A 10 PM cron job creates the next day’s note from a template with “What happened today” and “Mood” sections
• Throughout the day, the agent appends entries as events occur — trip updates, interesting conversations, completed tasks, notable moments
• Daily notes are factual logs, not task lists or reminders (those live in Apple Reminders)
• Notes follow the format YYYY-Mon-DD.md in daily-notes/YYYY/Month/

# Read today's diary
obsidian-note daily read

# Add an entry
obsidian-note daily append "Booked restaurant for Saturday — confirmed 7:30 PM at the waterfront place"

Trip Journals

Trip notes live in trips/ and follow templates that mirror the Travel Hub trip structure:

Template	Purpose
trip-overview	Dates, travelers, itinerary summary
trip-journal	Day-by-day journal entries
trip-activities	Planned activities and reservations
trip-restaurants	Restaurant research and reservations
trip-packing	Packing lists

The agent creates trip notes when a new trip is planned and populates them with details from Travel Hub, flight confirmations, and hotel reservations. During the trip, journal entries capture the day-to-day experience.

Reference Documents

Long-lived reference docs store knowledge that accumulates over time:

• Airport and airline notes — lounge reviews, timing tips, seat recommendations, organized alphabetically with strict formatting rules
• Destination guides — research and tips for specific cities or regions
• Recipes — collected recipes
• Packing lists — reusable lists for different trip types

Reference docs use a surgical editing workflow rather than blind appending — the agent reads the full document, identifies the correct insertion point (e.g., alphabetical order), and uses find-and-replace to insert content at the right location.

Shared Notes with the Agent

Family members can share information with the agent by asking it to save a note:

“Save this for reference — the gate code for the beach house is 4521#”

The agent creates or appends to the appropriate note in the vault. Later, anyone can ask the agent to recall it:

“What’s the gate code for the beach house?”

The agent searches the vault and returns the answer. This turns the Obsidian vault into a shared family knowledge base that’s accessible through natural conversation.

Vault Structure

vault-root/
├── daily-notes/YYYY/Month/       Daily notes (YYYY-Mon-DD.md)
├── destinations/                  Destination research and guides
├── flights/                       Individual flight logs
├── trips/                         Trip planning and journals
├── packing-lists/                 Reusable packing lists
├── recipes/                       Food recipes
├── reference/                     Reference documents
├── templates/                     Note templates
└── (standalone notes)             Top-level reference docs

CLI Reference

The obsidian-note CLI wrapper provides all vault operations:

# Reading
obsidian-note read "Note Name"                    # Read by name
obsidian-note read --path "trips/Tokyo 2026.md"   # Read by vault-relative path
obsidian-note daily read                           # Read today's daily note

# Writing
obsidian-note append "Note Name" --content "text"  # Append to end
obsidian-note prepend "Note Name" --content "text" # Prepend after frontmatter
obsidian-note daily append "text to add"            # Append to today's daily note

# Editing (surgical insert)
obsidian-note replace "Note Name" --old "find" --new "replace"

# Creating
obsidian-note create "New Note" --folder trips --content "# Title"
obsidian-note daily                                 # Create today's daily note

# Searching
obsidian-note search "query"                        # Search note content
obsidian-note list                                  # List vault root
obsidian-note list trips                            # List folder

Editing Best Practices

For structured documents with specific ordering (alphabetical sections, formatted tables), always use the read-identify-replace-verify workflow:

1. Read the full note to understand its structure
2. Identify the exact text around where the edit should go
3. Replace to insert at the right location (using --old to match the boundary text and --new to include the new content plus the original boundary)
4. Verify by re-reading the area to confirm correct placement

This prevents content from ending up in the wrong section or breaking document structure.

Security

• Main agent only — Both the obsidian_* plugin tools and the obsidian-note CLI are available only to the main agent. Plugin tools are gated by tools.alsoAllow in the agent config.
• Destructive tools excluded — delete_note, move_note, and move_file are intentionally not exposed in the plugin. The agent can read, write, search, and manage metadata but cannot delete or relocate notes.
• Restricted agents cannot read or write vault content directly
• If a family member asks the restricted agent to save a note, it relays the request to the main agent via sessions_send

Setup

Prerequisites

• Obsidian installed on the agent Mac (brew install --cask obsidian)
• Obsidian Headless for sync (npm install -g obsidian-headless)
• Active Obsidian Sync subscription

Install

1. Install the CLI tools:

   brew install obsidian-cli                    # Vault operations
   npm install -g obsidian-headless             # Headless sync daemon

2. Deploy the wrapper script:

   ln -sf ~/GitHub/Lobster/scripts/local-bin/obsidian-note ~/.local/bin/obsidian-note
   chmod +x ~/.local/bin/obsidian-note

3. Link the skill:

   ln -sf ~/GitHub/Lobster/openclaw-skills/obsidian ~/.openclaw/skills/obsidian

4. Add obsidian-note to the main agent’s exec allowlist in exec-approvals.json
5. Restart the gateway: openclaw gateway restart

Headless Sync Setup

Obsidian Headless keeps the vault synced without running the full Obsidian GUI. This replaces the previous iCloud Drive sync approach.

1. Log in to your Obsidian account:

   ob login

2. List remote vaults to find the vault name:

   ob sync-list-remote

3. Configure sync for the local vault:

   cd ~/Obsidian/YourVault
   ob sync-setup --vault "Your Vault Name"

4. Test a one-time sync:

   ob sync

5. Install the LaunchAgent for continuous sync:

   cp ~/GitHub/Lobster/config/com.lobster.obsidian-sync.plist ~/Library/LaunchAgents/
   launchctl load ~/Library/LaunchAgents/com.lobster.obsidian-sync.plist

6. Verify it’s running:

   launchctl list | grep obsidian
   tail /tmp/obsidian-sync.log

The LaunchAgent runs ob sync --continuous with KeepAlive: true, so it restarts automatically after crashes or reboots. Logs go to /tmp/obsidian-sync.log.

Important: Do not run the Obsidian desktop app and headless sync simultaneously on the same machine — this causes conflicts. The headless daemon replaces the desktop app for sync purposes on the agent Mac.

Daily Note Cron

Set up a cron job to create the next day’s note at 10 PM:

{
  "name": "daily-note",
  "schedule": "0 22 * * *",
  "agent": "main-agent",
  "message": "Create tomorrow's daily note using the daily note template"
}

Troubleshooting

Note not found

The obsidian-note read command searches by note title (the filename without .md). If the note has special characters, try using --path with the vault-relative path instead.

Replace fails (old text not found)

The --old text must match exactly, including whitespace, newlines, and markdown formatting. Read the note first and copy the exact text to match.

Daily note already exists

The cron job is designed to be idempotent — if today’s note already exists, it won’t overwrite it. Manual creation with obsidian-note daily also checks for existence first.