pantheon-org/vault-search

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

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

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 - practical query construction guidance.