---
name: vault-query
description: Deterministic vault retrieval via the brain's retrieval verbs (alexandria tool call search / vaultq_* — the brain layer's bash surface; the same tools over MCP on served brains) — the default way to search and navigate the vault before reaching for raw grep, Glob, or reading files speculatively. Six verbs — resolve (a name/email/phone → the canonical People/Knowledge/area note; ALWAYS run before creating a person/org note, it's the dedup guard), search (ranked keyword search with type/area/status/tag/since filters — the discovery verb, formerly vaultq_find), neighbors (the wikilink neighborhood of a note, N hops, in/out/both — replaces walking the graph by reading), route (content about to be filed → ranked candidate homes + a computed confidence + new-entity flags — run at the START of any ingestion/debrief/filing triage), dupes (near-duplicate detection by content+title similarity — run before creating a note that might already exist), load (a token-budgeted context pack for a note or topic — seed + area folder note + TODO lines + relevance-ranked neighbors in ONE call). Use whenever a task needs "which note is X", "where is Y mentioned", "what surrounds Z", "where does this content belong", "does this note already exist", "brief me on X", entity lookup during ingestion, or any vault search. JSON out for tool use, --pretty for humans; read-only, no API calls, sub-second. NOT for reading a note you already know (just Read it).
served: true
---

# Vault Query (`vaultq`)

Deterministic retrieval verbs over the vault — **scripts gather, models judge**. Call these instead of writing grep/Glob pipelines or re-deriving the graph by reading through it. The routing doctrine lives in `AGENTS.md` § *How knowledge is found*.

All verbs: read-only, stdlib-only, deterministic, sub-second. JSON by default (token-lean: paths + snippets + scores — Read only what a result earns); add `--pretty` when showing a human.

## The verbs

Shell surface (any local brain checkout): `alexandria tool call <tool> --args '<json>'`.
Served brains expose the same six as MCP tools. All read-only, deterministic, sub-second,
seat-scoped on served brains.

> **Renamed 2026-08-03:** ranked search is now **`search`** (was `vaultq_find`), and the
> navigation primitives carry their POSIX names — **`ls`** (was `list_dir`), **`tree`** (was
> `vault_tree`), **`grep`** (was `vault_grep`). Former names still dispatch, so nothing you
> have written breaks; they are no longer listed, so prefer the new ones.

```bash
# vaultq_resolve — entity → canonical note. THE DEDUP GUARD: run before creating
# any person/org note, and to identify a sender/handle during ingestion.
alexandria tool call vaultq_resolve --args '{"query": "Alex Chen"}'
alexandria tool call vaultq_resolve --args '{"query": "+1 415 555 0100"}'   # any phone format
alexandria tool call vaultq_resolve --args '{"query": "alex@example.com"}'
```
Confident `match` (unique exact, or dominant partial — entity notes outrank mere mentions), else `candidates` (you judge), else nothing (→ genuinely new; safe to create).

```bash
# search (was vaultq_find) — ranked keyword search; the discovery verb.
alexandria tool call search --args '{"query": "pilot pricing", "limit": 10}'
alexandria tool call search --args '{"query": "Alex", "type": "meeting-note"}'

# …with passages: the relevant PARTS of each hit, not one grepped line.
alexandria tool call search --args '{"query": "pilot pricing", "limit": 5, "passages": 2}'
```
Title/alias hits outrank body; rare terms outrank common; phrase + recency boosts. Filters: `type/area/status/tag/since`.

`passages: N` attaches up to N scored spans per hit, each with `line_start`/`line_end` and the heading path it sits under. Those line numbers address the file — hand them to `read_file(start:, end:)` to widen one. **This is how you read a long note**: rank it, take its passages, expand the one you want, instead of pulling the whole file into context. It costs one re-read per *hit*, so lower `limit` when you raise `passages`.

```bash
# vaultq_neighbors — the graph around a note; replaces link-walking by reading.
alexandria tool call vaultq_neighbors --args '{"seed": "Acme"}'
alexandria tool call vaultq_neighbors --args '{"seed": "Acme Pilot", "hops": 2, "type": "person"}'
```

```bash
# vaultq_route — content → ranked candidate homes + confidence. START of every
# ingestion/filing triage, one call per piece.
alexandria tool call vaultq_route --args '{"content": "Met Alex Chen re the pilot pricing"}'
```
Resolves entities (⚠ flags new ones with no note), scores topical overlap, computes a `high|med|low` band. You still judge what each piece IS per the AGENTS routing table.

```bash
# vaultq_dupes — does this already exist? Run before creating a note that might.
alexandria tool call vaultq_dupes --args '{"query": "<title or raw text>"}'

# vaultq_load — brief yourself in one call instead of N speculative reads.
alexandria tool call vaultq_load --args '{"query": "Acme Pilot", "budget": 6000}'
```
`vaultq_load` returns the markdown pack + its manifest (seed + area folder note + TODO lines naming it + relevance-ranked neighbors, deduped, budget-capped).

## When to use what

| Need | Verb |
|---|---|
| "Which note is this person/org/handle?" (before creating one, during filing) | `vaultq_resolve` |
| "Where does the vault talk about X?" (strings, not meanings) | `search` |
| "What's connected to this note / who's involved with X?" | `vaultq_neighbors` |
| "Where does this new content belong?" (start of every ingestion triage) | `vaultq_route` |
| "Does a note for this already exist?" (before creating; hygiene sweeps) | `vaultq_dupes` |
| "Brief me on X" / need the neighborhood as context, not one note | `vaultq_load` |
| "Where *inside* these notes is X?" (long notes, transcripts, folder notes) | `search` + `passages` |
| You already know the one note | just `read_file` it |
| Orienting in a vault you don't know | `tree`, then `ls` one folder |
| An exact regex, an ID pattern, or a non-markdown file | `grep` |
| A partial word (`pric` → `Pricing.md`) | `vault_search` — `search` tokenises, so it scores that zero |

`grep` is the fallback for what ranking cannot do, not the starting point: it returns hundreds of
equally-weighted lines for a common word. Start at `search`.
