View as Markdown

Writing a query that finds the right resultLink to Writing a query that finds the right result

Describe the behavior you want to find, then narrow the search with filters.

Examples use the uv run prefix, which runs the command inside a project environment. If you installed vaultspec-rag as a standalone tool, drop the prefix and call vaultspec-rag directly; see the installation guide.

Check file coverageLink to Check file coverage

If expected code is missing from results, check which files would be indexed and check index status. A dry run previews file selection; it does not show what is already stored.

Narrow results with filtersLink to Narrow results with filters

Keep your query and add a filter to select part of the index.

Document resultsLink to Narrow results with filters, Document results

Limit document results to ADRs. Replace the query with your own; it is a stand-in:

Command

uv run vaultspec-rag search "cache control on deployed assets" --type vault --doc-type adr

To search one feature across document types, replace docs-site with your feature tag:

Command

uv run vaultspec-rag search "cache control on deployed assets" --type vault --feature docs-site

Code resultsLink to Narrow results with filters, Code results

Exclude a directory you don’t want in results. Replace the query and the .claude/* glob with your own:

Command

uv run vaultspec-rag search "gpu lock around the forward pass" --type code --exclude-path ".claude/*"

Append --language python to limit code results to Python.

See the filter reference for more options.

Name the nouns, and ask one thingLink to Name the nouns, and ask one thing

Describe the behavior you want to find. Include relevant identifiers or technical terms when you know them:

Command

uv run vaultspec-rag search "immutable cache-control on non-hashed assets" --type vault

Ask one question at a time. Split unrelated questions into separate searches.

The filter surfaceLink to The filter surface

When no search type is specified (no --type), search defaults to source code and architecture decision records (ADRs), ranked together. --doc-type plan (or inline type:plan) overrides the default ADR filter while retaining code results.

An explicit --type picks the content domain: vault, code, document, or combined. --type vault searches all vault record types; --type combined searches all three indexes, including extracted documents. The filters below then split by what they narrow. A filter that does not apply to the chosen --type is rejected as a usage error, so a code filter with --type vault fails instead of being ignored. --type combined accepts them all.

Code results:

Filter

Narrows to

--language

one programming language

--path

one exact project-relative path

--include-path / --exclude-path

paths matching or missing a pattern

--function-name / --class-name

one function or class

--structure

one source-code structure kind

To favor production code, tests, or documentation without excluding other code results, use --prefer.

Vault results:

Filter

Narrows to

--doc-type

adr (decision), plan, exec (execution), audit, research, reference

--feature

one feature tag

--date

one date

--tag

one frontmatter tag

--doc-type also takes a comma-separated union, such as --doc-type adr,plan.

Extracted-document results:

Filter

Narrows to

--source-path

one originating file

--extractor-id

documents emitted by one extractor

--extractor-version

documents from one extractor version

--locator-kind

one kind of locator, such as page or sheet

Query markersLink to The filter surface, Query markers

Write markers anywhere in the query text. Most mirror a flag, so type:adr does what --doc-type adr does. Five have no flag equivalent and can only be written this way.

Group

Markers

Documents

type: feature: date: tag:

Code

lang: path: func: class: nodetype:

Noise, no flag

only: exclude: include:

Ranking, no flag

status: intent:

The noise markers take one or more domains from prod, tests, docs, locale, generated, vendored, and worktree. The default profile hides some domains and demotes others, so only:prod keeps production code and exclude:tests drops a test tree that would otherwise still be returned, lower down. The defaults are listed under filter noise by domain. Comma-separated sets accumulate when repeated.

status: and intent: apply to vault results only. status: takes all, active, or a comma-separated set such as accepted,proposed. intent: takes orientation, the default, or debugging, which reorders results for tracking down a fault rather than getting your bearings. debug is accepted as an alias for debugging.

Command

uv run vaultspec-rag search "auth token validation only:prod" --type code
uv run vaultspec-rag search "gpu lock decision type:adr status:active"

path: is the in-query spelling of --include-path: it takes a pattern, and a plain one matches that path and everything under it. --path is a different, exact-path filter.

Inspect result scoresLink to The filter surface, Inspect result scores

Show numeric scores alongside results:

Command

uv run vaultspec-rag search "graph rebuild race" --type vault --scores

Scores help compare ranked results; they aren’t probabilities that your question has been answered. Their meaning depends on the ranking configuration. No universal score cutoff establishes whether your index contains an answer.

When VAULTSPEC_RAG_TYPESAFE_API_KEY is set in the service’s environment, a hosted classifier also reweights candidates and can drop confidently irrelevant ones, so results and scores differ from local ranking. See Typesafe enrollment. The scores described in this documentation come from local ranking.

--max-results caps the results at 10 by default, but doesn’t guarantee that many matches. Results can be irrelevant, and empty output doesn’t explain why.

Use --json for structured output. See the search options for details.

When a result looks wrongLink to When a result looks wrong

  1. Read the returned passages to check whether they answer your question.

  2. Check file coverage and index status if expected code is missing.

  3. Add the filter that states which kind of thing you want.

  4. If results arrive doubled, exclude the duplicate tree with an --exclude-path pattern. The worktree domain already hides .claude/worktrees/ and .git/worktrees/ by default, so a sibling clone of the repository needs the path pattern.

  5. If the query carries two ideas, split it into two searches.

  6. Reword, naming the concrete nouns the target would contain.

If none of that helps, the issue tracker takes questions as well as bug reports. Include the query, the flags, and the --scores output.