---
type: note
tags: [meta, agent, retrieval, doctrine]
author: {{ agent.name | default("the agent") }}
status: active
---

# Retrieval Card

The vault's retrieval doctrine distilled to what a retrieval task needs — a few hundred words instead of the whole constitution. It is [[AGENTS#How knowledge is found|AGENTS.md § How knowledge is found]] reduced, not a replacement: read the constitution when a task files, drafts, edits, or needs conventions beyond finding things. This card is the whole doctrine of the `retrieve` subagent (`.claude/agents/retrieve.md`) — delegate retrieval-shaped questions to it rather than spidering the vault in the main context.

## Pick the tool by the need, not by habit

| You need… | Use | Why |
|---|---|---|
| an exact string, identifier, number, or regex; **to certify something is absent**; line context; non-markdown; anything you'll pipe into `sed`/`awk`/`sort` | **`rg`** (or the Grep tool) — scope notes with `-t md` | first-class, fastest, exhaustive; `rg` reads the vault-root `.ignore`, which hides session worktrees and machine-generated copies |
| a person/org from a name, alias, email, or phone in any format | `vaultq_resolve` | grep has to guess the stored format; resolve normalizes — **mandatory before creating any person/org note** |
| who links to / from a note, N hops | `vaultq_neighbors` | backlinks need a sweep and escaped-pipe links defeat a naive grep |
| where content should be filed; whether a near-twin exists | `vaultq_route` · `vaultq_dupes` | ranked homes + confidence; twins by content, not title |
| a note's outline with line ranges; the relevant lines inside one long note | `vaultq_sections` · `vaultq_find` with `passages` | one call instead of `grep -n "^## "` + `sed`; then read exactly those lines |
| ranked topical sourcing ("where is X covered") | `vaultq_find` — `all: true` for AND | default is OR-scored: it ranks partial matches and **cannot certify absence** |
| a budgeted briefing on an area, project, or person | `vaultq_load` | seed + folder note + TODO lines + ranked neighbors in one call |

Shell: `alexandria tool call vaultq_<verb> --args '<json>'`; served brains expose the same tools over MCP. JSON out, read-only, sub-second.

## How to navigate

- Start from structure: [[Home]] links every area; each folder's same-named note is its overview. Paths are meaningful.
- Notes link with `[[wikilinks]]` — follow them like a spider, but do not rebuild the graph by reading: `vaultq_neighbors` already has it.
- **Prefer the canonical live note over a dated snapshot** for anything that drifts. **Target ≠ actual.**
- **Corroborate a volatile fact before answering** — confirm it against the note that owns it rather than stopping at the first plausible hit.
- Absence is a claim too: certify it with `rg -F` or `vaultq_find` with `all: true`, and say what you searched.

## Answer contract

Answer in one to three sentences, then a final line `PATHS: <comma-separated vault-relative note paths>` naming the note(s) the answer rests on — or `PATHS: none`. Cite real paths only; never invent one. Retrieval is read-only.
