Session Layer

Vault Watcher, Auto-Sync Scheduling & Plugin Health State Machine

Health State Machine

Plugin transitions through three states
HEALTHY
All deps up
→ full service
⇄
DEGRADED
Ollama down
→ stale results ok
⇄
UNAVAILABLE
No index / DB
→ cannot serve
HEALTHY → DEGRADED: Ollama health check fails (every 30s)
DEGRADED → HEALTHY: Ollama responds again
HEALTHY → UNAVAILABLE: Index deleted or DB corrupted
UNAVAILABLE → HEALTHY: Successful reindex after recovery
DEGRADED → UNAVAILABLE: Index corrupted while Ollama was down
UNAVAILABLE → DEGRADED: Index restored but Ollama still down

Vault Watcher: Auto-Sync Protocol

File change detection → incremental sync
DETECTION
chokidar watches vault_path (respects deny_dirs / allow_dirs)
Debounces: 2s after last change event
→ Avoids triggering sync for every keystroke in an editor
BATCHING
Collector window: 5s (configurable)
Groups add/update/delete events into a changeset
→ Single sync call for 10 files changed at once
SYNC TRIGGER
After debounce + collect: spawn indexer with obsidian-rag sync
Indexer processes only modified files (uses mtime comparison)
On completion: indexer writes status JSON to ~/.obsidian-rag/sync-result.json
SYNC RESULT
Plugin reads sync-result.json on next tool call
Updates health state: HEALTHY if indexed > 0 docs, UNAVAILABLE if 0
Stale flag: if last sync > 1h ago and vault changed, next search returns status: "degraded"

Session Lifecycle

What happens from plugin load to shutdown
ON LOAD
Read config → Probe Ollama → Probe LanceDB → Probe Vault → Set health state
REGISTER
Register 4 tools with OpenClaw → Start vault watcher
SERVE
Handle tool calls → Auto-sync on file changes → Health re-probe every 30s
ON SHUTDOWN
Stop vault watcher → Wait for in-flight sync → Clean exit

Key Design Points

Why this works

  • Health state machine is simple — only 3 states, clear transitions
  • Debounce + batch prevents Ollama hammering during rapid edits
  • Stale flag on old sync lets agent warn user about freshness
  • Sync results written to filesystem — no IPC needed between indexer and plugin

Trade-offs

  • Vault watcher uses chokidar — filesystem event reliability varies by OS
  • 30s health re-probe adds periodic Ollama load
  • Filesystem-based sync result is a polling model — up to 30s stale