FirmVault Search
Retrieve documents from the FirmVault case corpus by semantic similarity + structured filters. Backed by qmd query and a Python wrapper that adds frontmatter-based filters and case-scope auto-detection.
When to use
- "Find Dr. Smith's notes in the Whaley v. Acme case"
- "Show me all medical records from October 2025"
- "What did the insurance adjuster say last month?"
- "Search across cases for surgery records mentioning rotator cuff"
- "Find all correspondence with State Farm in the active case"
- "Pull up legal filings from the Acme matter"
How to call
uv run firmvault_search "<query text>" \
[--scope all|case|<slug>] \
[--category medical|legal|insurance|communication] \
[--case <slug>] \
[--date 2025-10-15] \
[--date-range 2025-10-01..2025-10-31] \
[--provider <name>] \
[--limit 10]
Output is a JSON array — one object per hit:
{
"file_path": "/Users/.../FirmVault/cases/<slug>/medical/2025-10-15-dr-smith-visit.md",
"score": 0.87,
"snippet": "Patient presented with...",
"frontmatter_excerpt": {
"case_slug": "whaley-v-acme",
"document_category": "medical",
"document_date": "2025-10-15",
"provider": "Dr. Smith Clinic",
"document_type": "office_visit_note"
}
}
Scope auto-detection
If --scope is not given OR --scope=case:
- The CLI walks up from cwd looking for
FirmVault/cases/<slug>/. If found, the search scopes to that slug automatically.
- If no such ancestor exists, the search falls back to cross-case (all cases).
Pass --scope=all to force cross-case. Pass --scope=<slug> to target a specific case explicitly.
Filters
--category — exact document_category match (medical | legal | insurance | communication)--case — exact case_slug match (alternative to --scope=<slug>)--date — exact document_date match (YYYY-MM-DD)--date-range START..END — inclusive document_date range--provider — case-insensitive substring match on provider / sender / recipient--limit — max hits returned (default 10)
Filters apply Python-side post-filter on the markdown frontmatter, so unindexed fields still work.
Tips
- Read the top hit's
file_path with the Read tool to surface details to the user.
- For "find all X" queries, set
--limit 25 or higher and summarize.
- Use the
snippet for at-a-glance scanning — only Read full files when needed.
- When inside a case directory, omit
--scope to get case-scoped results automatically.
