santhoshj/obsidian-rag
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

all in

Browse Source
This commit is contained in:
Santhosh Janardhanan
2026-04-10 19:00:38 -04:00
parent b8996d2ecb
commit 2c976bb75b
10 changed files with 957 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
.superpowers/brainstorm/27-1775849590/content/session-layer.html Normal file
View File

@@ -0,0 +1,115 @@
<h2>Session Layer</h2>
<p class="subtitle">Vault Watcher, Auto-Sync Scheduling & Plugin Health State Machine</p>
<div class="section">
<h3>Health State Machine</h3>
<div class="mockup">
<div class="mockup-header">Plugin transitions through three states</div>
<div class="mockup-body" style="font-family: monospace; font-size: 13px; line-height: 1.6; padding: 16px;">
<div style="display: flex; justify-content: center; gap: 20px; flex-wrap: wrap; margin-bottom: 16px;">
<div style="background: #1a472a; border: 2px solid #2ecc71; border-radius: 8px; padding: 12px; min-width: 140px; text-align: center;">
<div style="color: #2ecc71; font-weight: bold; font-size: 14px;">HEALTHY</div>
<div style="color: #aaa; font-size: 11px;">All deps up</div>
<div style="color: #2ecc71; font-size: 11px;">→ full service</div>
</div>
<div style="color: #666; font-size: 24px; display: flex; align-items: center;">⇄</div>
<div style="background: #3d3200; border: 2px solid #f0a500; border-radius: 8px; padding: 12px; min-width: 140px; text-align: center;">
<div style="color: #f0a500; font-weight: bold; font-size: 14px;">DEGRADED</div>
<div style="color: #aaa; font-size: 11px;">Ollama down</div>
<div style="color: #f0a500; font-size: 11px;">→ stale results ok</div>
</div>
<div style="color: #666; font-size: 24px; display: flex; align-items: center;">⇄</div>
<div style="background: #3d0000; border: 2px solid #e94560; border-radius: 8px; padding: 12px; min-width: 140px; text-align: center;">
<div style="color: #e94560; font-weight: bold; font-size: 14px;">UNAVAILABLE</div>
<div style="color: #aaa; font-size: 11px;">No index / DB</div>
<div style="color: #e94560; font-size: 11px;">→ cannot serve</div>
</div>
</div>
<div style="border-top: 1px solid #333; padding-top: 12px; color: #aaa; font-size: 12px;">
<div><span style="color: #2ecc71;">HEALTHY → DEGRADED</span>: Ollama health check fails (every 30s)</div>
<div><span style="color: #f0a500;">DEGRADED → HEALTHY</span>: Ollama responds again</div>
<div><span style="color: #2ecc71;">HEALTHY → UNAVAILABLE</span>: Index deleted or DB corrupted</div>
<div><span style="color: #e94560;">UNAVAILABLE → HEALTHY</span>: Successful reindex after recovery</div>
<div><span style="color: #f0a500;">DEGRADED → UNAVAILABLE</span>: Index corrupted while Ollama was down</div>
<div><span style="color: #e94560;">UNAVAILABLE → DEGRADED</span>: Index restored but Ollama still down</div>
</div>
</div>
</div>
</div>
<div class="section" style="margin-top: 20px;">
<h3>Vault Watcher: Auto-Sync Protocol</h3>
<div class="mockup">
<div class="mockup-header">File change detection → incremental sync</div>
<div class="mockup-body" style="font-family: monospace; font-size: 13px; line-height: 1.7; padding: 16px;">
<div style="color: #53a8b6;">DETECTION</div>
<div style="color: #eee; margin-left: 16px;">chokidar watches vault_path (respects deny_dirs / allow_dirs)</div>
<div style="color: #eee; margin-left: 16px;">Debounces: 2s after last change event</div>
<div style="color: #888; margin-left: 16px;">→ Avoids triggering sync for every keystroke in an editor</div>
<div style="color: #53a8b6; margin-top: 12px;">BATCHING</div>
<div style="color: #eee; margin-left: 16px;">Collector window: 5s (configurable)</div>
<div style="color: #eee; margin-left: 16px;">Groups add/update/delete events into a changeset</div>
<div style="color: #888; margin-left: 16px;">→ Single sync call for 10 files changed at once</div>
<div style="color: #53a8b6; margin-top: 12px;">SYNC TRIGGER</div>
<div style="color: #eee; margin-left: 16px;">After debounce + collect: spawn indexer with <code style="color: #f0a500;">obsidian-rag sync</code></div>
<div style="color: #eee; margin-left: 16px;">Indexer processes only modified files (uses mtime comparison)</div>
<div style="color: #eee; margin-left: 16px;">On completion: indexer writes status JSON to <code style="color: #f0a500;">~/.obsidian-rag/sync-result.json</code></div>
<div style="color: #53a8b6; margin-top: 12px;">SYNC RESULT</div>
<div style="color: #eee; margin-left: 16px;">Plugin reads sync-result.json on next tool call</div>
<div style="color: #eee; margin-left: 16px;">Updates health state: HEALTHY if indexed > 0 docs, UNAVAILABLE if 0</div>
<div style="color: #eee; margin-left: 16px;">Stale flag: if last sync > 1h ago and vault changed, next search returns <code style="color: #f0a500;">status: "degraded"</code></div>
</div>
</div>
</div>
<div class="section" style="margin-top: 20px;">
<h3>Session Lifecycle</h3>
<div class="mockup">
<div class="mockup-header">What happens from plugin load to shutdown</div>
<div class="mockup-body" style="font-family: monospace; font-size: 13px; padding: 16px;">
<div style="display: flex; flex-direction: column; gap: 8px;">
<div style="display: flex; align-items: center; gap: 10px;">
<div style="background: #53a8b6; color: #000; padding: 2px 8px; border-radius: 4px; font-weight: bold; font-size: 11px;">ON LOAD</div>
<div style="color: #eee;">Read config → Probe Ollama → Probe LanceDB → Probe Vault → Set health state</div>
</div>
<div style="display: flex; align-items: center; gap: 10px;">
<div style="background: #53a8b6; color: #000; padding: 2px 8px; border-radius: 4px; font-weight: bold; font-size: 11px;">REGISTER</div>
<div style="color: #eee;">Register 4 tools with OpenClaw → Start vault watcher</div>
</div>
<div style="display: flex; align-items: center; gap: 10px;">
<div style="background: #53a8b6; color: #000; padding: 2px 8px; border-radius: 4px; font-weight: bold; font-size: 11px;">SERVE</div>
<div style="color: #eee;">Handle tool calls → Auto-sync on file changes → Health re-probe every 30s</div>
</div>
<div style="display: flex; align-items: center; gap: 10px;">
<div style="background: #e94560; color: #000; padding: 2px 8px; border-radius: 4px; font-weight: bold; font-size: 11px;">ON SHUTDOWN</div>
<div style="color: #eee;">Stop vault watcher → Wait for in-flight sync → Clean exit</div>
</div>
</div>
</div>
</div>
</div>
<div class="section" style="margin-top: 20px;">
<h3>Key Design Points</h3>
<div class="pros-cons">
<div class="pros"><h4>Why this works</h4>
<ul>
<li>Health state machine is simple — only 3 states, clear transitions</li>
<li>Debounce + batch prevents Ollama hammering during rapid edits</li>
<li>Stale flag on old sync lets agent warn user about freshness</li>
<li>Sync results written to filesystem — no IPC needed between indexer and plugin</li>
</ul>
</div>
<div class="cons"><h4>Trade-offs</h4>
<ul>
<li>Vault watcher uses chokidar — filesystem event reliability varies by OS</li>
<li>30s health re-probe adds periodic Ollama load</li>
<li>Filesystem-based sync result is a polling model — up to 30s stale</li>
</ul>
</div>
</div>
</div>