vault-search · diff
git:20260710.9cbcee2 to git:20260710.a38941a
26 added, 0 removed. Audit A to A.
---
name: vault-search
description: >
Search persistent memory for relevant context — including architectural
decisions, resolved bugs, and implementation patterns — when the user asks
about past decisions, when debugging a recurring issue, when uncertain whether
something was already decided, or before re-implementing something that may
have been done before. Use when the user says "do you remember…", "what did
we decide about…", or "have we solved this before".
allowed-tools: "Bash"
---
# vault-search
Retrieve relevant memories from the vault using hybrid BM25 + vector search.
## Mindset
Search before you implement, design, or debug — not after. A 2-second search
that surfaces a prior constraint saves hours of work in the wrong direction.
When search returns empty, say so honestly; never fabricate a memory.
## When to use
- Before starting a non-trivial task: search for related prior decisions
- When the user asks "do you remember…" or "what did we decide about…"
- Before proposing an approach: check for existing constraints or patterns
- When a bug appears familiar: search for past workarounds
## How to use
```bash
vault-cli search "<query>" [--top-k <n>] [--project <id>]
```
Exits 1 with "No results." if nothing is found.
## Query construction
- Use **noun phrases**, not questions: `"auth token expiry"` not `"how does auth token expiry work?"`
- Use `--project` to narrow scope when working in a known project context
- If the first query returns nothing, broaden: remove specific version numbers or
error codes and retry with a higher-level term (e.g. `"postgres connection"` instead of `"ECONNREFUSED 5432"`)
## Handling no results
If the search exits with "No results.":
1. Retry with a broader synonym query
2. If still empty, tell the user no prior memory exists on this topic
3. Never invent or guess at a prior decision — proceed fresh and offer to capture the new decision
## Examples
```bash
vault-cli search "authentication approach"
vault-cli search "database migration strategy" --project my-app
vault-cli search "recurring TypeScript error" --top-k 3
vault-cli search "postgres connection refused" --project api
```
## Output format
Each result shows:
```
1. [category] summary (date)
tier: episodic | strength: 0.87 | score: 0.0312
content preview...
```
## Never
- **Never skip search before a non-trivial implementation task** — prior constraints may invalidate your approach before you write a line
- **Never fabricate a memory** when search returns empty — report "No results found" and proceed without invented context
- **Never search with a full sentence or question** — BM25 scores individual terms; verbose queries dilute signal
+ ## Mindset
+
+ Search memory first; do not re-derive what was already decided. Treat retrieval as cheap and re-work as expensive. Know **when not to**: trivial, self-evident steps do not need a memory lookup.
+
+ ## Anti-Patterns
+
+ ### NEVER re-implement something without searching memory first
+
+ - WHY: past decisions, constraints, and fixes are often already recorded; re-deriving them wastes effort and risks contradicting a prior decision.
+ - BAD: writing a new approach from scratch for a recurring problem.
+ - GOOD: `vault-cli search "<topic>"` first, then build on what returns.
+
+ ### NEVER search with the user's literal phrasing when concrete nouns work better
+
+ - WHY: memory is indexed on concepts, not surface wording.
+ - BAD: searching the whole question verbatim.
+ - GOOD: extract the key nouns and search those.
+
+ ### ALWAYS treat an empty result as meaningful
+
+ - WHY: a miss suggests the decision is genuinely new and worth capturing.
+
+ ## References
+
+ - [Vault Search: Query Tips](references/query-tips.md) - practical query construction guidance.
+