nora retrieval

Run searches from the CLI, manage retrieval presets, diagnose failures.

The retrieval command group is the CLI surface for the retrieval subsystem — the layer between agent queries and your knowledge.

Commands

Command	Description
retrieval search <query>	Run a search query.
retrieval diagnose <cluster-id>	Pin first broken retrieval stage in a failure cluster.
retrieval presets list	List all retrieval presets.
retrieval presets get <id>	Fetch one preset’s config.
retrieval presets upsert <id>	Create/replace a preset.
retrieval presets delete <id>	Delete a preset.

retrieval search

nora retrieval search "how do refunds work" \
  --preset high-precision \
  --k 10 \
  --method hybrid \
  --filters '{"tag": "billing"}'

Runs the query and prints results.

Flags:

• <query> (positional) — the text to search.
• --preset <preset-id> — use a saved preset (see below).
• --k <n> — top-K to return.
• --method vector|keyword|hybrid|kg_rooted — retrieval mode.
• --filters <json> — metadata filter expression.
• --include-subgraph — expand results to include related graph nodes.
• --graph-expansion — enable knowledge-graph traversal.

Without --preset, uses the workspace default preset.

retrieval diagnose

nora retrieval diagnose cl_billing_misses

For a failure cluster (Signals → cluster), pins the first broken retrieval stage. Answers “where in the retrieval pipeline did this cluster’s failures actually happen?” — filter dropped it? Vector score too low? Reranker demoted it? Grounding rejected it?

Output identifies the specific stage and shows evidence per failing trace.

Best used as a targeted diagnostic before deciding which retrieval lever to tune.

Presets

Presets bundle retrieval settings (top-K, weights, filters, reranker) so multiple Agents can share one config.

List

nora retrieval presets list

Get

nora retrieval presets get high-precision

Prints the preset’s config as JSON.

Upsert

nora retrieval presets upsert high-precision \
  --name "High Precision" \
  --config '{
    "k": 6,
    "method": "hybrid",
    "vector_weight": 0.6,
    "keyword_weight": 0.4,
    "reranker": true,
    "cutoff": 0.2
  }'

Creates the preset if it doesn’t exist; replaces it if it does.

Flags:

• <id> (positional, required) — the preset’s ID.
• --name <n> (required) — display name.
• --config <json> (required) — the full preset config. See Retrieval presets for the field reference.

Delete

nora retrieval presets delete high-precision

Fails if any Agent references the preset. Update those Agents first.

Recipes

Iteratively tune a preset

# Snapshot current
nora retrieval presets get high-precision --json > preset.json

# Edit locally (e.g., bump vector_weight)
jq '.config.vector_weight = 0.7' preset.json > preset-tuned.json

# Re-upsert
nora retrieval presets upsert high-precision \
  --name "$(jq -r '.name' preset-tuned.json)" \
  --config "$(jq -c '.config' preset-tuned.json)"

# Test with a real query
nora retrieval search "sample question" --preset high-precision

Compare two presets side-by-side

diff <(nora retrieval search "refund" --preset old) \
     <(nora retrieval search "refund" --preset new)

Test retrieval isolation between tenants

nora retrieval search "sensitive-question" \
  --filters '{"tenant":"acme"}'
# Should NOT return chunks with tenant="other"

Combine with the app’s isolation-test view for a definitive check.

Attach a preset via agents sources update

Once a preset is dialed in, attach it to an Agent’s data source:

nora agents sources update ag_support \
  --kind documents_folder \
  --source-id billing \
  --set-preset high-precision

See nora agents for full source attachment options.

What the CLI does NOT do

• Save retrieval results to a dataset — use the app’s Trace view for that (search a trace, add the retrieval step to a dataset).
• Configure grounding graphs directly — grounding is enabled via preset config ({"grounding": {"graph_id": "..."}}), but graph editing is via nora causal.

Debugging queries

• Add --json for the raw score breakdown per result.
• Try --method vector, then --method keyword separately to see which pass is stronger.
• If the right chunk exists but doesn’t rank, retrieval diagnose on a cluster containing similar queries usually explains why.