---
name: obsidian
description: Integrate with the user's Obsidian vault — read, search, create notes, and set up bidirectional sync between Hermes skills/memories and the Obsidian vault for seamless access and editing.
version: 2.0.0
tags: [obsidian, notes, vault, sync, knowledge-management, bidirectional]
---

# Obsidian Vault Integration

Hermes can interact with the user's Obsidian vault in multiple ways, from simple read/write to full bidirectional sync with the Hermes skills directory.

---

## 1. Basic Operations

**Location:** Set via `OBSIDIAN_VAULT_PATH` environment variable (e.g. in `~/.hermes/.env`). Falls back to `~/Documents/Obsidian Vault`.

Vault paths often contain spaces — always quote them.

### Read a note

```bash
VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}"
cat "$VAULT/Note Name.md"
```

### List notes

```bash
VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}"
find "$VAULT" -name "*.md" -type f     # All notes
ls "$VAULT/Subfolder/"                  # In a specific folder
```

### Search notes

```bash
VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}"
find "$VAULT" -name "*.md" -iname "*keyword*"         # By filename
grep -rli "keyword" "$VAULT" --include="*.md"         # By content
```

### Create / Append to a note

```bash
VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/Documents/Obsidian Vault}"

# Create new note
cat > "$VAULT/New Note.md" << 'ENDNOTE'
# Title

Content here.
ENDNOTE

# Append to existing
echo "\nNew content." >> "$VAULT/Existing Note.md"
```

### Wikilinks

Obsidian links notes with `[[Note Name]]` syntax. When creating notes, use these to link related content. This works even when notes are served via web (the links become internal page references).

---

## 2. Vault Location & Cross-Platform Paths

### Windows (native Obsidian) → WSL access

When Obsidian runs on Windows but Hermes needs to access the vault:

| Windows path | WSL path |
|-------------|----------|
| `C:\Users\ookii\Documents\Obsidian Vault` | `/mnt/c/Users/ookii/Documents/Obsidian Vault` |

Use the WSL path for file operations from Hermes (when SSHed into WSL or running in WSL).

### WSL Obsidian vault (less common)

If the vault lives in WSL's Linux filesystem (e.g. `~/obsidian/`), it's directly accessible from Hermes running in WSL.

### Hermes server (remote)

If Hermes is on a remote server and the vault is on Windows/WSL, use:
- **Tailscale** (preferred) for network connectivity
- **rsync** for file syncing (see Section 4)
- **SSH via Windows → `wsl.exe`** for remote command execution (see `remote-machine-access` skill)

---

## 3. Advanced Integration: Symlink Hermes into Obsidian Vault

The most powerful integration pattern: create symlinks inside the Obsidian vault that point to Hermes' skills, memories, and plans directories. This lets the user browse, read, and even EDIT these files directly in Obsidian.

### Setup (run inside WSL, where Hermes files live)

```bash
# Identify the Windows vault path as seen from WSL
# Windows: C:\Users\ookii\Documents\Obsidian Vault
# WSL:     /mnt/c/Users/ookii/Documents/Obsidian Vault
VAULT="/mnt/c/Users/ookii/Documents/Obsidian Vault"

# Create a Hermes folder in the vault
mkdir -p "$VAULT/Hermes"

# Symlink Hermes directories into it
ln -s ~/.hermes/skills   "$VAULT/Hermes/🧠 skills"
ln -s ~/.hermes/memories "$VAULT/Hermes/💾 memories"
ln -s ~/.hermes/plans    "$VAULT/Hermes/📋 plans"

# (Optional) Symlink generated HTML report outputs
ln -s ~/.hermes/output/public "$VAULT/Hermes/📊 reports"
```

### Result in Obsidian sidebar

```
📁 Hermes/
├── 🧠 skills/
│   ├── devops/remote-machine-access.md
│   ├── note-taking/obsidian.md
│   └── ... (all 80+ skills)
├── 💾 memories/
│   └── user preferences, environment facts
├── 📋 plans/
│   └── implementation plans and architecture docs
└── 📊 reports/
    └── generated HTML reports
```

### ⚠️ Critical: Syncing Direction Rules

Obsidian can edit the symlinked files directly. To avoid conflicts:

1. **Hermes learns a new skill →** It writes to `~/.hermes/skills/`. Obsidian picks up changes from the symlink automatically.
2. **User edits in Obsidian →** The symlink writes back to `~/.hermes/skills/`. Next Hermes session reads the updated file.
3. **Conflict resolution:** Compare file modification timestamps. The most recent write wins.
4. **Git protection:** All skills/memories should be under Git version control (see Phase 5 of the full architecture). If Obsidian edits break something, `git checkout` recovers it.

### Pitfall: Obsidian doesn't auto-refresh

If files change on disk (e.g., Hermes writes a new skill), Obsidian may not show the update immediately. Options:

- **Obsidian setting:** Turn on "Refresh" or "Detect file changes" in Obsidian settings
- **Plugin:** "Obsidian Git" plugin with auto-commit detects external changes
- **Manual:** Cmd/Ctrl+Shift+R to reload the vault after major updates

---

## 4. Real-Time Sync: WSL → Cloud Server

When the Obsidian vault is on the local PC/WSL and Hermes runs on a remote server, keep the vault files synchronized:

### Prerequisites
- Tailscale connectivity between server and WSL (see `remote-machine-access`)
- SSH key-based login established
- `inotify-tools` installed on WSL (`sudo apt install inotify-tools`)

### Setup: Real-Time Sync with rsync + inotify

```bash
# On WSL: install tools
sudo apt install inotify-tools

# Create sync script (~/sync-obsidian.sh)
cat > ~/sync-obsidian.sh << 'SCRIPT'
#!/bin/bash
VAULT="/mnt/c/Users/ookii/Documents/Obsidian Vault"
REMOTE="ubuntu@<server-tailscale-ip>:~/files/obsidian"

# Initial full sync
rsync -avz --delete "$VAULT/" "$REMOTE"

# Watch for changes and sync continuously
inotifywait -m -r "$VAULT" -e close_write,moved_to,create,delete |
while read path action file; do
    rsync -avz --delete "$VAULT/" "$REMOTE"
done
SCRIPT
chmod +x ~/sync-obsidian.sh
```

### ⚠️ --delete flag behavior

Using `rsync --delete` makes the remote a perfect mirror:
- **New file →** synced ✅
- **Renamed file →** synced (old name removed, new added) ✅
- **Renamed folder →** synced (entire old path cleaned up) ✅
- **Deleted file →** removed from remote too ⚠️

**Safety net:** Obsidian has its own file recovery and version history. If a sync deletion was a mistake, recover from Obsidian first, then resync.

### Daily ChromaDB self-heal

When remote files change (rename/delete), the vector database may have orphan entries. Run a daily cleanup:

```bash
# Cron job on the cloud server (daily at 5 AM)
0 5 * * * python3 /home/ubuntu/scripts/cleanup_vectors.py
```

This scans all indexed paths, removes entries for files that no longer exist, and re-indexes files that changed.

---

## 5. Web Publishing via Tailscale Funnel

Obsidian notes (.md) can be served publicly via Tailscale Funnel, rendered as HTML:

### Architecture
```
User writes in Obsidian (Windows)
    → WSL inotify detects change
    → rsync to cloud server
    → Caddy web server (with MD→HTML rendering)
    → Tailscale Funnel (public HTTPS)
    → Mobile browser or shareable link
```

### Caddy MD rendering config (in Caddyfile)

```caddyfile
https://<funnel-hostname>.ts.net {
    root * /home/ubuntu/files
    file_server browse

    # Render .md files as HTML
    handle *.md {
        markdown
    }

    # Direct .html files
    handle *.html {
        file_server
    }
}
```

### Result: each note gets a URL like

```
https://funnel-host.ts.net/obsidian/My%20Note.md
```

Shareable with anyone who has the link.

---

## 6. Hermes Writing Back to Obsidian

Hermes can generate notes and write them back to the vault:

```bash
# Remote write (via SSH to WSL)
ssh user@wsl-host "wsl.exe bash -c '
VAULT=\"/mnt/c/Users/ookii/Documents/Obsidian Vault\"
cat > \"\$VAULT/Hermes Notes/$(date +%Y-%m-%d) - Daily Summary.md\" << '\''END'\''
# Daily Summary - $(date +%Y-%m-%d)

Generated by Hermes.
END
'"
```

For automatic sync back, ensure the write target is inside the synced Obsidian directory (so rsync picks up the change in the opposite direction).

## Reference Files

- `references/session-20260515-architecture-design.md` — Full session transcript covering the Obsidian + Hermes integration architecture, storage tiering, Funnel setup, and Git backup plan for user 小天 (Xiao Tian).