add claude-obsidian

2026-05-28 10:57:16 +09:00
parent 1b07531a45
commit 72dad72703
205 changed files with 41703 additions and 80 deletions
@@ -0,0 +1,62 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 480" role="img" aria-labelledby="retrieval-title retrieval-desc">
+  <title id="retrieval-title">Hybrid retrieval pipeline: BM25 + contextual prefix + cosine rerank</title>
+  <desc id="retrieval-desc">Pipeline diagram showing user query feeding BM25 sparse search and an optional contextual-prefix Anthropic API call. Both feed a cosine rerank via local ollama embeddings. The output is a ranked list of candidate pages with traceability via --explain.</desc>
+
+  <defs>
+    <marker id="arrow3" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#475569" />
+    </marker>
+  </defs>
+
+  <rect width="1200" height="480" fill="#ffffff" />
+
+  <text x="600" y="32" text-anchor="middle" font-family="system-ui, sans-serif" font-size="18" font-weight="600" fill="#0f172a">Hybrid retrieval pipeline (v1.7+, opt-in via setup-retrieve.sh)</text>
+  <text x="600" y="54" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" fill="#64748b">Anthropic Sept 2024 contextual retrieval pattern. Local-by-default. Measured +32pp top-1 over v1.6 baseline.</text>
+
+  <!-- Query -->
+  <rect x="40" y="200" width="170" height="80" rx="10" fill="#fef3c7" stroke="#d97706" stroke-width="2" />
+  <text x="125" y="230" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" font-weight="600" fill="#92400e">User query</text>
+  <text x="125" y="252" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">"what do you know</text>
+  <text x="125" y="268" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">about hot cache?"</text>
+
+  <line x1="210" y1="220" x2="330" y2="140" stroke="#475569" stroke-width="2" marker-end="url(#arrow3)" />
+  <line x1="210" y1="260" x2="330" y2="340" stroke="#475569" stroke-width="2" marker-end="url(#arrow3)" />
+
+  <!-- BM25 -->
+  <rect x="330" y="100" width="220" height="100" rx="10" fill="#dbeafe" stroke="#2563eb" stroke-width="2" />
+  <text x="440" y="128" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" font-weight="600" fill="#1e3a8a">BM25 sparse search</text>
+  <text x="440" y="150" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">scripts/bm25-index.py</text>
+  <text x="440" y="168" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">Unicode tokenizer · idf scoring</text>
+  <text x="440" y="186" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-style="italic" fill="#2563eb">~50 candidates</text>
+
+  <!-- Contextual prefix -->
+  <rect x="330" y="300" width="220" height="120" rx="10" fill="#fef2f2" stroke="#ef4444" stroke-width="2" />
+  <text x="440" y="328" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" font-weight="600" fill="#991b1b">Contextual prefix</text>
+  <text x="440" y="350" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">scripts/contextual-prefix.py</text>
+  <text x="440" y="368" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">Anthropic API (opt-in)</text>
+  <text x="440" y="386" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-style="italic" fill="#dc2626">requires --allow-egress</text>
+  <text x="440" y="405" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-style="italic" fill="#dc2626">falls back to synthetic if denied</text>
+
+  <line x1="550" y1="150" x2="700" y2="220" stroke="#475569" stroke-width="2" marker-end="url(#arrow3)" />
+  <line x1="550" y1="360" x2="700" y2="280" stroke="#475569" stroke-width="2" marker-end="url(#arrow3)" />
+
+  <!-- Rerank -->
+  <rect x="700" y="200" width="220" height="100" rx="10" fill="#ede9fe" stroke="#7c3aed" stroke-width="2" />
+  <text x="810" y="228" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" font-weight="600" fill="#5b21b6">Cosine rerank</text>
+  <text x="810" y="250" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">scripts/rerank.py</text>
+  <text x="810" y="268" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">ollama nomic-embed (local)</text>
+  <text x="810" y="286" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-style="italic" fill="#7c3aed">cached in .vault-meta/</text>
+
+  <line x1="920" y1="250" x2="1010" y2="250" stroke="#475569" stroke-width="2" marker-end="url(#arrow3)" />
+
+  <!-- Output -->
+  <rect x="1010" y="200" width="160" height="100" rx="10" fill="#dcfce7" stroke="#16a34a" stroke-width="2" />
+  <text x="1090" y="228" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" font-weight="600" fill="#15803d">Top-K candidates</text>
+  <text x="1090" y="250" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">page paths</text>
+  <text x="1090" y="268" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">snippets · scores</text>
+  <text x="1090" y="286" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-style="italic" fill="#16a34a">--explain traces each</text>
+
+  <!-- Bottom note -->
+  <text x="600" y="445" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">BM25 always runs. Prefix tier is opt-in (consent-gated). Rerank is local-only by default; --allow-remote-ollama to point elsewhere.</text>
+  <text x="600" y="463" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#94a3b8">Pipeline degrades gracefully: if rerank is unavailable, BM25-only results return with rerank_source="skipped".</text>
+</svg>
@@ -0,0 +1,71 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 480" role="img" aria-labelledby="locking-title locking-desc">
+  <title id="locking-title">Multi-writer safety: per-file advisory locking via wiki-lock.sh</title>
+  <desc id="locking-desc">Diagram showing two parallel ingest writers attempting to acquire a lock on the same wiki page. The lock manager grants one writer access while the other waits and retries on the next pass, preventing corruption.</desc>
+
+  <defs>
+    <marker id="arrow2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#475569" />
+    </marker>
+    <marker id="arrow-green" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#16a34a" />
+    </marker>
+    <marker id="arrow-amber" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#d97706" />
+    </marker>
+  </defs>
+
+  <rect width="1200" height="480" fill="#ffffff" />
+
+  <text x="600" y="32" text-anchor="middle" font-family="system-ui, sans-serif" font-size="18" font-weight="600" fill="#0f172a">Multi-writer safety: per-file advisory locks (v1.7+)</text>
+  <text x="600" y="54" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" fill="#64748b">Closes the latent corruption hole when parallel agents target the same page.</text>
+
+  <!-- Writer A -->
+  <rect x="40" y="100" width="200" height="90" rx="10" fill="#dbeafe" stroke="#2563eb" stroke-width="2" />
+  <text x="140" y="130" text-anchor="middle" font-family="system-ui, sans-serif" font-size="15" font-weight="600" fill="#1e3a8a">Writer A</text>
+  <text x="140" y="152" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">/wiki-ingest sub-agent</text>
+  <text x="140" y="170" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-style="italic" fill="#3b82f6">processing source-1.md</text>
+
+  <!-- Writer B -->
+  <rect x="40" y="320" width="200" height="90" rx="10" fill="#fef3c7" stroke="#d97706" stroke-width="2" />
+  <text x="140" y="350" text-anchor="middle" font-family="system-ui, sans-serif" font-size="15" font-weight="600" fill="#92400e">Writer B</text>
+  <text x="140" y="372" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">/wiki-ingest sub-agent</text>
+  <text x="140" y="390" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-style="italic" fill="#d97706">processing source-2.md</text>
+
+  <!-- Arrows to lock manager -->
+  <line x1="240" y1="145" x2="400" y2="220" stroke="#475569" stroke-width="2" marker-end="url(#arrow2)" />
+  <text x="290" y="170" font-family="system-ui, sans-serif" font-size="11" fill="#475569">acquire wiki/concepts/Foo.md</text>
+
+  <line x1="240" y1="365" x2="400" y2="260" stroke="#475569" stroke-width="2" marker-end="url(#arrow2)" />
+  <text x="290" y="335" font-family="system-ui, sans-serif" font-size="11" fill="#475569">acquire wiki/concepts/Foo.md</text>
+
+  <!-- Lock manager -->
+  <rect x="400" y="180" width="280" height="120" rx="10" fill="#ede9fe" stroke="#7c3aed" stroke-width="2" />
+  <text x="540" y="212" text-anchor="middle" font-family="system-ui, sans-serif" font-size="15" font-weight="600" fill="#5b21b6">scripts/wiki-lock.sh</text>
+  <text x="540" y="236" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">atomic acquire / release</text>
+  <text x="540" y="254" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">.vault-meta/locks/&lt;hash&gt;.lock</text>
+  <text x="540" y="276" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-style="italic" fill="#7c3aed">stale reap: 60s default</text>
+
+  <!-- Outcomes -->
+  <line x1="680" y1="210" x2="800" y2="160" stroke="#16a34a" stroke-width="2.5" marker-end="url(#arrow-green)" />
+  <text x="720" y="178" font-family="system-ui, sans-serif" font-size="12" font-weight="600" fill="#15803d">✓ granted</text>
+
+  <line x1="680" y1="270" x2="800" y2="340" stroke="#d97706" stroke-width="2.5" stroke-dasharray="5 4" marker-end="url(#arrow-amber)" />
+  <text x="700" y="320" font-family="system-ui, sans-serif" font-size="12" font-weight="600" fill="#b45309">✗ waits + retries</text>
+
+  <!-- Outcome boxes -->
+  <rect x="800" y="100" width="350" height="120" rx="10" fill="#dcfce7" stroke="#16a34a" stroke-width="2" />
+  <text x="975" y="130" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" font-weight="600" fill="#15803d">Writer A writes the page</text>
+  <text x="975" y="155" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">Write/Edit via selected transport</text>
+  <text x="975" y="173" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">(Obsidian CLI / MCP / filesystem)</text>
+  <text x="975" y="195" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-style="italic" fill="#16a34a">then releases the lock</text>
+
+  <rect x="800" y="290" width="350" height="130" rx="10" fill="#fef3c7" stroke="#d97706" stroke-width="2" />
+  <text x="975" y="320" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" font-weight="600" fill="#92400e">Writer B logs the skip</text>
+  <text x="975" y="346" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">wiki/log.md gets a skip-line</text>
+  <text x="975" y="364" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">Page picked up on next pass</text>
+  <text x="975" y="390" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-style="italic" fill="#d97706">No corruption. No half-written page.</text>
+
+  <!-- Bottom note -->
+  <text x="600" y="450" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">PostToolUse hook checks the lock list before auto-committing. Active locks defer the commit.</text>
+  <text x="600" y="466" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#94a3b8">Path validation rejects absolute paths, `..` segments, newlines, NUL bytes. Tests: 22 assertions across test_wiki_lock.sh + test_concurrent_write.sh</text>
+</svg>
@@ -0,0 +1,76 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 420" role="img" aria-labelledby="vault-flow-title vault-flow-desc">
+  <title id="vault-flow-title">claude-obsidian vault flow: sources to ingest to wiki pages to index to query</title>
+  <desc id="vault-flow-desc">Horizontal architecture diagram showing source documents flowing into the wiki-ingest agent, which extracts entities, concepts, and sources into the wiki. The index is updated, and the wiki-query interface answers questions by reading the hot cache, index, and pages in order.</desc>
+
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#475569" />
+    </marker>
+    <linearGradient id="bg-card" x1="0" x2="0" y1="0" y2="1">
+      <stop offset="0%" stop-color="#fafafa" />
+      <stop offset="100%" stop-color="#f1f5f9" />
+    </linearGradient>
+  </defs>
+
+  <rect width="1200" height="420" fill="#ffffff" />
+
+  <text x="600" y="30" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="600" fill="#0f172a">Vault flow: from raw source to cited answer</text>
+
+  <!-- Sources -->
+  <rect x="40" y="160" width="170" height="90" rx="10" fill="url(#bg-card)" stroke="#3b82f6" stroke-width="2" />
+  <text x="125" y="195" text-anchor="middle" font-family="system-ui, sans-serif" font-size="15" font-weight="600" fill="#1e3a8a">.raw/ sources</text>
+  <text x="125" y="218" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">PDFs · markdown</text>
+  <text x="125" y="234" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">URLs · transcripts</text>
+
+  <line x1="210" y1="205" x2="270" y2="205" stroke="#475569" stroke-width="2" marker-end="url(#arrow)" />
+
+  <!-- Ingest -->
+  <rect x="270" y="150" width="200" height="110" rx="10" fill="#ede9fe" stroke="#8b5cf6" stroke-width="2" />
+  <text x="370" y="180" text-anchor="middle" font-family="system-ui, sans-serif" font-size="15" font-weight="600" fill="#5b21b6">/wiki-ingest</text>
+  <text x="370" y="202" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">read · extract entities</text>
+  <text x="370" y="218" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">extract concepts</text>
+  <text x="370" y="234" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">cross-reference</text>
+  <text x="370" y="250" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-style="italic" fill="#7c3aed">acquires wiki-lock per page</text>
+
+  <line x1="470" y1="180" x2="540" y2="120" stroke="#475569" stroke-width="2" marker-end="url(#arrow)" />
+  <line x1="470" y1="205" x2="540" y2="205" stroke="#475569" stroke-width="2" marker-end="url(#arrow)" />
+  <line x1="470" y1="230" x2="540" y2="290" stroke="#475569" stroke-width="2" marker-end="url(#arrow)" />
+
+  <!-- Output pages -->
+  <rect x="540" y="95" width="170" height="60" rx="8" fill="#ecfeff" stroke="#06b6d4" stroke-width="2" />
+  <text x="625" y="120" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" font-weight="600" fill="#155e75">wiki/entities/</text>
+  <text x="625" y="140" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#475569">people · orgs · products</text>
+
+  <rect x="540" y="175" width="170" height="60" rx="8" fill="#f0fdf4" stroke="#22c55e" stroke-width="2" />
+  <text x="625" y="200" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" font-weight="600" fill="#166534">wiki/concepts/</text>
+  <text x="625" y="220" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#475569">ideas · patterns · frameworks</text>
+
+  <rect x="540" y="255" width="170" height="60" rx="8" fill="#fef3c7" stroke="#f59e0b" stroke-width="2" />
+  <text x="625" y="280" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" font-weight="600" fill="#92400e">wiki/sources/</text>
+  <text x="625" y="300" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#475569">source summaries</text>
+
+  <line x1="710" y1="125" x2="770" y2="200" stroke="#475569" stroke-width="2" marker-end="url(#arrow)" />
+  <line x1="710" y1="205" x2="770" y2="205" stroke="#475569" stroke-width="2" marker-end="url(#arrow)" />
+  <line x1="710" y1="285" x2="770" y2="215" stroke="#475569" stroke-width="2" marker-end="url(#arrow)" />
+
+  <!-- Index -->
+  <rect x="770" y="160" width="180" height="90" rx="10" fill="#fef2f2" stroke="#ef4444" stroke-width="2" />
+  <text x="860" y="190" text-anchor="middle" font-family="system-ui, sans-serif" font-size="15" font-weight="600" fill="#991b1b">wiki/index.md</text>
+  <text x="860" y="212" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">master catalog</text>
+  <text x="860" y="228" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">+ wiki/hot.md cache</text>
+  <text x="860" y="244" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-style="italic" fill="#dc2626">+ wiki/log.md append</text>
+
+  <line x1="950" y1="205" x2="1010" y2="205" stroke="#475569" stroke-width="2" marker-end="url(#arrow)" />
+
+  <!-- Query -->
+  <rect x="1010" y="150" width="150" height="110" rx="10" fill="#fef3c7" stroke="#d97706" stroke-width="2" />
+  <text x="1085" y="180" text-anchor="middle" font-family="system-ui, sans-serif" font-size="15" font-weight="600" fill="#92400e">/wiki-query</text>
+  <text x="1085" y="202" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">read hot</text>
+  <text x="1085" y="218" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">read index</text>
+  <text x="1085" y="234" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">read pages</text>
+  <text x="1085" y="250" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-style="italic" fill="#b45309">synthesize + cite</text>
+
+  <!-- Bottom annotation -->
+  <text x="600" y="365" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#475569">Every page is gated by per-file advisory locks (v1.7+). Mode router (v1.8+) picks the destination folder per active methodology.</text>
+  <text x="600" y="385" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#94a3b8">Hot cache is refreshed on Stop hook. Index + log update atomically. Compounds with every ingest.</text>
+</svg>