vault-search git:20260710.a38941aA

Immutable. This exact content never changes and is served at /api/v1/blob/2330b0a3dcda68c4.

---
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.