Skip to main content

​
Overview

brv swarm query searches all active memory providers simultaneously and returns results ranked by Reciprocal Rank Fusion (RRF). No LLM is involved — this is pure algorithmic search that typically completes in under 500ms. 
brv swarm query "How does JWT refresh work?"
Output: 
Swarm Query: "How does JWT refresh work?"
Type: factual | Providers: 4 queried | Latency: 398ms
──────────────────────────────────────────────────
1. [memory-wiki] sources/jwt-token-lifecycle.md    score: 0.0150  [keyword]
   # JWT Token Lifecycle ...
2. [obsidian] SwarmTestData/Authentication System.md    score: 0.0142  [keyword]
   # Authentication System ...
3. [gbrain] alex-chen    score: 0.0117  [semantic]
   # Alex Chen — Senior Backend Engineer ...
Each result shows:
  • Provider label — which source the result came from
  • Path/ID — the document or page identifier
  • Score — RRF-fused relevance score
  • Match type — keyword (BM25) or semantic (vector)
  • Content preview — first portion of the matching content

​
Flags

FlagShortDefaultDescription
--explain—offShow query classification, provider selection, and enrichment details
--format—textOutput format: text or json
--max-results-n10Maximum number of results to return

​
Query Classification

Before searching, the query is automatically classified to determine which providers are relevant: 
# Factual (default) — searches all providers
brv swarm query "rate limiting strategies"

# Temporal — detected by time signals
brv swarm query "what changed since yesterday"

# Relational — detected by connection signals
brv swarm query "what depends on the auth module"

# Personal — routes to local providers only
brv swarm query "how do I usually structure tests"
Use --explain to see the classification: 
brv swarm query "authentication patterns" --explain
Output: 
Classification: factual
Provider selection: 4 of 4 available
  ✓ byterover    (healthy, selected, 0 results, 14ms)
  ✓ obsidian    (healthy, selected, 5 results, 91ms)
  ✓ memory-wiki    (healthy, selected, 2 results, 15ms)
  ✓ gbrain    (healthy, selected, 1 results, 260ms)
Enrichment:
  byterover → obsidian
  byterover → memory-wiki
Results: 8 raw → 7 after RRF fusion + precision filtering
The explain output shows:
  • Which query type was detected
  • Which providers were selected (and why any were excluded)
  • Enrichment chains that were executed
  • How many results survived RRF fusion and precision filtering

​
JSON Output

For programmatic use or piping to other tools: 
brv swarm query "rate limiting" --format json

{
  "meta": {
    "queryType": "factual",
    "totalLatencyMs": 340,
    "providers": {
      "byterover": { "selected": true, "resultCount": 0 },
      "obsidian": { "selected": true, "resultCount": 5 },
      "gbrain": { "selected": true, "resultCount": 1 },
      "memory-wiki": { "selected": true, "resultCount": 1 }
    }
  },
  "results": [
    {
      "provider": "memory-wiki",
      "providerType": "memory-wiki",
      "score": 0.015,
      "content": "# Rate Limiting ..."
    }
  ]
}

​
How Ranking Works

​
RRF Fusion

Results from each provider are ranked by position, not raw score. This solves the problem of incomparable score scales across providers (BM25 vs cosine similarity vs ts_rank): 
score = Σ (provider_weight / (K + rank))
ParameterDefaultDescription
K60Higher values flatten rank differences
Provider weight0.7 – 1.0Per-provider confidence weight

​
Precision Filtering

After RRF fusion, two filters remove noise:
  1. Score floor (min_rrf_score: 0.005) — drops results below the minimum threshold
  2. Gap ratio (rrf_gap_ratio: 0.5) — drops results scoring below 50% of the top result
These defaults are tuned for balanced precision/recall. Adjust in .brv/swarm/config.yaml under routing.

​
Result Caching

Identical queries within a 10-second window return cached results (LRU cache, max 20 entries). This is transparent — cached responses have the same format as fresh ones. Cache is invalidated on any write operation.

​
Swarm Query vs Context Tree Query

brv swarm querybrv query
SourcesAll configured providersByteRover context tree only
LLMNo LLM callLLM synthesizes an answer
OutputRanked search resultsNatural language answer
Speed~200–500ms~2–15s (depends on tier)
CostFree (keyword) or ~$0.001 (vector)LLM token cost
Use brv swarm query when you want raw search results across multiple sources. Use brv query when you want a synthesized answer from the context tree.

​
Examples

Search with limited results: 
brv swarm query "testing strategy" -n 5
Search with full explain output: 
brv swarm query "database migration patterns" --explain
Pipe JSON results to jq: 
brv swarm query "API design" --format json | jq '.results[] | {provider, score}'