> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev.byterover.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Swarm Query

> Search across all memory providers with federated ranking

## 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.

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
brv swarm query "rate limiting" --format json
```

```json theme={null}
{
  "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:

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 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:**

```bash theme={null}
brv swarm query "testing strategy" -n 5
```

**Search with full explain output:**

```bash theme={null}
brv swarm query "database migration patterns" --explain
```

**Pipe JSON results to jq:**

```bash theme={null}
brv swarm query "API design" --format json | jq '.results[] | {provider, score}'
```