claude-code — parsidion
Building the Vault Explorer Agent
parsidion · Claude Code Build Session · 2026-03-13
user ~/Repos/parsidion $ claude
✦ Welcome to Claude Code!
claude-sonnet-4-6 · parsidion
  • A new vault-explorer Haiku subagent for read-only vault search
  • Replace direct Grep loops in CLAUDE-VAULT.md and SKILL.md
  • Refactor install.py to support multiple agents
  • Sync everything to ~/.claude/ and verify
5 chunks Claude Haiku 61/61 tests stdlib-only
The Implementation Plan
user ~/Repos/parsidion $ execute plan docs/superpowers/plans/2026-03-13-vault-explorer-agent.md
Using executing-plans → subagent-driven-development skill.
Plan loaded — 5 independent chunks, dispatching fresh subagents per task.
✓Task 1 — Create agents/vault-explorer.md
✓Task 2 — Update CLAUDE-VAULT.md guidance
✓Task 3 — Update skills/parsidion/SKILL.md
✓Task 4 — Refactor install.py for multi-agent
✓Task 5 — Sync to ~/.claude/
Architecture: Four independent file changes applied in order. No new library dependencies — install.py is stdlib-only. Model: Claude Haiku for the new agent.
The Problem: Direct Grep Loops
## Debugging: Search Before You Diagnose 2. Search ~/ClaudeVault/Debugging/ first: Grep: path=~/ClaudeVault/Debugging, glob=**/*.md, pattern=<signal> 3. Widen to Frameworks/, Languages/, Projects/ if nothing found. 4. Found a match? Apply the fix. 5. No match? Diagnose and solve it...
Every vault lookup consumed the main session's context window with repeated Grep tool calls across multiple folders. The vault-explorer agent isolates this work in a fresh Haiku context — fast, cheap, and non-polluting.
Context pollution Multi-folder Grep loops → Delegate to Haiku agent
Task 1: vault-explorer.md
claude → Write agents/vault-explorer.md
--- name: vault-explorer description: > Use when you need to search ~/ClaudeVault/ for relevant notes, debugging solutions, reusable patterns, or prior art... Trigger on: "search the vault for X", "check the vault", "have we seen this before", "find vault notes about X"... Do NOT trigger for vault writes, index rebuilds, summarization. model: haiku color: purple ---
✓ agents/vault-explorer.md created (82 lines) ✓ Frontmatter: name ✓ model: haiku ✓ color: purple ✓ ✓ Committed: feat(agent): add vault-explorer Haiku agent for read-only vault search
Agent: 7-Step Search Procedure
1Semantic search — vault_search.py --json; if ≥3 results with score ≥0.35 → skip to step 6
2Metadata search — vault-search (filter mode) with inferred filters (--tag, --folder, --type, --project, --recent-days); if ≥3 results → skip to step 6
3Orient — Read ~/ClaudeVault/CLAUDE.md index
4Extract signals — exception class, package name, keyword
5Search by priority folder (Grep by query type)
6Rank & read — top 5 by semantic score first, then folder priority
7Synthesize — return fixed ## Answer + ## Sources
Error / exception → Debugging/ → Frameworks/ → Languages/ Feature / pattern → Patterns/ → Frameworks/ → Projects/ Cross-project → Projects/ → Patterns/ Library / tool → Tools/ → Frameworks/ Research → Research/ → all folders
Semantic Search Enhancement
Added bge-base-en-v1.5 (768-dim ONNX, MRR 0.889) as step 1. When the embeddings DB exists, vault_search.py bypasses all grep loops — faster lookup and query-intent matching instead of exact-keyword matching.
uv run --no-project ~/.claude/skills/parsidion/scripts/vault_search.py "QUERY" --json 2>/dev/null # → [{"score": 0.87, "path": "/Users/probello/ClaudeVault/Patterns/...", ...}, ...] # If ≥ 3 results with score ≥ 0.35 → use paths, skip to step 6 # If DB absent or < 3 results → fall through to metadata search (step 2)
MRR: 0.889  |  Recall@1: 0.833  |  Recall@5: 0.917  |  12s build
bge-base-en-v1.5 sqlite-vec cosine graceful fallback config-driven
Step 2: Metadata Search (vault-search filter mode)
New Tier 2 between semantic and grep. Queries the note_index SQLite table — instant indexed lookups vs O(n) file walks. Returns [] gracefully when DB absent.
vault-search \ --folder Debugging --type debugging --recent-days 7 # → [{"stem": "fix-uv-hook", "path": "/Users/probello/ClaudeVault/...", ... # "tags": ["python", "tool"], "is_stale": false, ...}, ...] # If ≥ 3 results → use those paths, skip to step 6 (rank+read) # If < 3 results or DB absent → continue to step 3 (CLAUDE.md orient)
"debugging notes" → --type debugging "patterns for X" → --folder Patterns "recent work" → --recent-days 7 "python tag" → --tag python "parsidion project" → --project parsidion
note_index table 5 secondary indexes graceful fallback stdlib-only
Code Review → Path Format Fix
The spec-reviewer approved the file. The code-quality reviewer found one Important issue: the Sources format instruction was self-contradicting.
Use absolute paths (starting with /Users/... or ~/ClaudeVault/... expanded to the real path)
Use absolute paths only — expand ~ to full home dir (e.g. /Users/probello/ ClaudeVault/...) Never output ~/... paths
Also clarified: "0 or 1 candidate files" threshold for folder widening (was ambiguous "fewer than 3" without accumulation rule)
Task 2: Update CLAUDE-VAULT.md
claude → Edit CLAUDE-VAULT.md — 3 section replacements
✓Debugging: replaced Grep: syntax + widen steps with vault-explorer dispatch
✓Implementation: replaced 3-folder Grep search with single agent dispatch
✓Efficient Vault Search: replaced Grep table with ## Answer / ## Sources prose
2. Dispatch the `vault-explorer` agent with the signal as the query. 3. **Answer returned?** Apply the documented fix. Update the note if you learn something new. `Read` source files only if needed. 4. **"No relevant vault notes found"?** Diagnose and solve it, then dispatch research-agent to save...
✓ No Grep: instructions remain in modified sections ✓ Saving Solutions and Vault Organization sections unchanged
Review Catch: "Update the Note" Reminder
The code-quality reviewer caught a behavioral regression: the "update the note" reminder was silently dropped from Debugging step 3. This instruction is how the vault improves over time.
3. Apply the documented fix. `Read` specific source files from Sources only if you need more depth.
3. Apply the documented fix. Update the note if you learn something new. `Read` files only if needed.
Two-stage review (spec compliance → code quality) caught what a single-pass review would have missed.
Task 3: Update SKILL.md
claude → Edit skills/parsidion/SKILL.md — 4 section replacements
✓Debugging: removed bash grep -r shell examples
✓Implementation: removed multi-folder grep examples
✓Efficient Vault Search: replaced table + "Prefer Grep tool" line
✓Vault-First Loop: updated flowchart to reference vault-explorer
Error or question → Search vault → Found? Apply → Not found? Save → Rebuild index
Error or question → Dispatch vault-explorer → Found? Apply → Not found? Dispatch research-doc-agent
Review Catch: Manual Usage Section
The code-quality reviewer found a Critical issue: the Manual Usage → Searching the Vault section still told Claude to use Grep/Glob directly — directly contradicting the new vault-explorer guidance.
### Searching the Vault - Dispatch the **`vault-explorer` agent** for natural language queries — it searches priority folders, ranks matches, and returns a synthesized answer with source paths. - Use `vault_common.py` for programmatic search from scripts. - Use Obsidian's built-in search for interactive exploration (if installed). - Use `Grep` or `Glob` only for targeted investigation when you know the specific file or exact pattern needed.
Also aligned: "discover new nuance" → "learn something new" (consistent wording with CLAUDE-VAULT.md)
Task 4: Refactor install.py
claude → Edit install.py — 7 reference sites
# Before AGENT_SRC: Path = REPO_ROOT / "agents" / "research-agent.md"
# After AGENT_SRCS: list[Path] = [ REPO_ROOT / "agents" / "research-agent.md", REPO_ROOT / "agents" / "vault-explorer.md", ]
✓Module constant → AGENT_SRCS list[Path]
✓install_agent() → install_agents() with loop + skip-on-missing
✓Call site — existence check moved inside function
✓Printout block — for loop over AGENT_SRCS
✓uninstall() — for loop over AGENT_SRCS
✓--skip-agent help → "Do not install any agents"
✓Module docstring updated
Verification: Dry-run + Tests
$ uv run install.py --dry-run --yes Installation Plan Install agent: /Users/probello/.claude/agents/research-agent.md Install agent: /Users/probello/.claude/agents/vault-explorer.md [dry-run] Install agent: research-agent.md → ~/.claude/agents/ [dry-run] Install agent: vault-explorer.md → ~/.claude/agents/
$ uv run pytest tests/ -v ... 61 passed in 0.03s ✓
Both agents appear in plan output. All 61 vault_common.py tests pass — install.py changes have no regressions.
Task 5: Sync to ~/.claude/
claude → uv run install.py --force --yes
Parsidion Installer + Install skill: parsidion → ~/.claude/skills/parsidion + Patch vault_common.py: VAULT_ROOT=/Users/probello/ClaudeVault + Install agent: research-agent.md → ~/.claude/agents/ + Install agent: vault-explorer.md → ~/.claude/agents/ ✓ All hooks already registered + Install CLAUDE-VAULT.md → ~/.claude/CLAUDE-VAULT.md + Rebuild vault index (update_index.py) ✓ Vault index rebuilt ✓ Installation complete!
$ ls ~/.claude/agents/ | grep vault vault-explorer.md ✓ $ grep -c "vault-explorer" ~/.claude/CLAUDE-VAULT.md 3 ✓ (three dispatch instructions, no Grep: remaining)
Commit History
claude → git push origin main
90dccb0 feat(install): support multiple agents with AGENT_SRCS list 9fc9f02 docs(skill): replace direct Grep guidance with vault-explorer agent dispatch f71d980 docs(vault): replace direct Grep guidance with vault-explorer agent dispatch fb44be2 feat(agent): add vault-explorer Haiku agent for read-only vault search 4fbb31b docs(plan): vault-explorer agent implementation plan 48496c7 docs(spec): fix all review issues in vault-explorer agent spec d5d6c91 docs(spec): vault-explorer agent design spec
To github.com:paulrobello/parsidion.git afb47e9..90dccb0 main -> main ✓
4 commits pushed atomic commits conventional commit format
Docs Sync: ARCHITECTURE.md
user ~/Repos/parsidion $ update docs and slideshow
Running sync-all-docs-to-impl skill → dispatched subagent for docs/ARCHITECTURE.md.
✓TOC — added Vault Explorer Agent and Context Preview Script entries
✓Mermaid diagram — added VE node, CC→VE edge, VE→folder edges
✓New section ### Vault Explorer Agent with model, scope, triggers, priority table
✓File layout — vault-explorer.md in agents/ (source + installed)
✓ docs/ARCHITECTURE.md committed: "docs(architecture): sync to current implementation"
What We Built
  • agents/vault-explorer.md — Haiku agent
  • ~/.claude/agents/vault-explorer.md
  • vault-search (filter mode) — metadata CLI (merged into vault_search.py)
  • CLAUDE-VAULT.md
  • skills/parsidion/SKILL.md
  • install.py
  • docs/ARCHITECTURE.md
  • vault_common.py — DB-first find_*
  • update_index.py — writes note_index
  • Vault search isolated in Haiku subagent — no main-session Grep loops
  • Two-stage review (spec + quality) caught 3 issues missed in self-review
  • install.py now scales to N agents via AGENT_SRCS list
  • Manual Usage section aligned — vault-explorer is primary search path
  • Semantic search (step 1) — bge-base MRR 0.889, fast-paths past grep when DB exists
  • Metadata search (step 2) — vault-search --flag hits note_index table; sub-ms indexed queries vs O(n) file walk
⚠ SubagentStop hook exclusion: this agent is listed in excluded_agents — its transcripts are not harvested by the SubagentStop hook, preventing recursive vault-search loops.
61/61 tests 5 commits Haiku model Live in ~/.claude/ sqlite-vec semantic note_index metadata