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
What we're building
- 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.
5 Chunks
✓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
Before — Grep-based search in CLAUDE-VAULT.md
## 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
Frontmatter
---
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
Fast-paths: semantic/metadata search short-circuit grep when DB available
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.
Step 1 command
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)
Eval results (bge-base, whole-note, 200-note index)
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.
CLI usage
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)
Filter inference from query
"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.
Before ❌
Use absolute paths
(starting with /Users/...
or ~/ClaudeVault/...
expanded to the real path)
After ✓
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
Three sections updated
✓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
After — Debugging section
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.
First commit ❌
3. Apply the documented fix.
`Read` specific source files
from Sources only if you
need more depth.
After fix ✓
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
Four sections updated
✓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
Vault-First Loop — before → after
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.
Fix applied
### 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
Constant renamed
# 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",
]
7 sites updated
✓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
Dry-run output
$ 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/
Test suite
$ 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.
Changes to 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
New files
- agents/vault-explorer.md — Haiku agent
- ~/.claude/agents/vault-explorer.md
- vault-search (filter mode) — metadata CLI (merged into vault_search.py)
Modified files
- CLAUDE-VAULT.md
- skills/parsidion/SKILL.md
- install.py
- docs/ARCHITECTURE.md
- vault_common.py — DB-first find_*
- update_index.py — writes note_index
Key improvements
- 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