Swarm Query - Byterover

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

Flag	Short	Default	Description
`--explain`	—	off	Show query classification, provider selection, and enrichment details
`--format`	—	`text`	Output format: `text` or `json`
`--max-results`	`-n`	`10`	Maximum 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))

Parameter	Default	Description
`K`	60	Higher values flatten rank differences
Provider weight	0.7 – 1.0	Per-provider confidence weight

Precision Filtering

After RRF fusion, two filters remove noise:

Score floor (min_rrf_score: 0.005) — drops results below the minimum threshold
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 query`	`brv query`
Sources	All configured providers	ByteRover context tree only
LLM	No LLM call	LLM synthesizes an answer
Output	Ranked search results	Natural language answer
Speed	~200–500ms	~2–15s (depends on tier)
Cost	Free (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}'

Documentation Index

​Overview

​Flags

​Query Classification

​JSON Output

​How Ranking Works

​RRF Fusion

​Precision Filtering

​Result Caching

​Swarm Query vs Context Tree Query

​Examples