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

# How Query Works

<Tip>
  Prefer a visual workflow? See [Tasks in the web UI](/local-web-ui/tasks).
</Tip>

## Query Intelligence

When you query the context tree (via `/query` or `brv query`), ByteRover uses a 5-tier strategy that routes each query to the fastest path capable of producing a high-quality answer.

| Tier | Name          | Speed       | How It Works                                                                                                                           |
| ---- | ------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 0    | Exact cache   | \~0ms       | Matches a previously seen query by MD5 fingerprint. Cached results expire after 60 seconds.                                            |
| 1    | Fuzzy cache   | \~50ms      | Finds a cached query with ≥60% token similarity (Jaccard). Returns the cached result if the context tree hasn't changed.               |
| 2    | BM25 direct   | \~100–200ms | Runs a BM25 full-text search. If the top result scores ≥0.85 with a clear gap over the runner-up, returns it directly — no LLM needed. |
| 3    | LLM pre-fetch | \<5s        | Pre-fetches the top BM25 results and injects them as context for the LLM, which synthesizes a focused answer.                          |
| 4    | Agentic loop  | 8–15s       | Full multi-step reasoning: the agent reads files, follows relations, and iteratively gathers context before answering.                 |

Tiers 0–2 bypass the LLM entirely for speed. Tier 3 uses a single LLM call with pre-fetched context. Tier 4 gives the agent full tool access for complex, multi-hop questions.

### Structural Context Injection

For Tier 3 and 4 queries, ByteRover also injects structural context from the manifest (`_manifest.json`) alongside the BM25 search results. The manifest organizes all context tree entries into three lanes with token budgets:

| Lane          | Contents                         | Ordered By                          |
| ------------- | -------------------------------- | ----------------------------------- |
| **Summaries** | `_index.md` files                | Condensation order (broadest first) |
| **Contexts**  | Knowledge files                  | Importance score (highest first)    |
| **Stubs**     | `_archived/*.stub.md` ghost cues | —                                   |

The manifest is read lazily — fresh if unchanged since the last curate, rebuilt on the fly if stale. This gives the LLM a broad structural overview of the knowledge base without scanning every file on every request.

### Out-of-Domain Detection

When the top search result scores below the relevance threshold, or significant query terms have no matches in the index, ByteRover recognizes the topic is outside the context tree. Instead of returning a low-quality guess, it tells you the topic isn't covered and suggests curating relevant knowledge first.

## Compound Scoring

Search results are ranked using a compound score that balances three signals, boosted by the file's maturity tier:

```
score = (0.6 × BM25 + 0.2 × importance + 0.2 × recency) × tierBoost
```

| Component      | Weight | Range | Description                                                                                          |
| -------------- | ------ | ----- | ---------------------------------------------------------------------------------------------------- |
| BM25 relevance | 60%    | 0–1   | Full-text relevance, normalized via `score / (1 + score)`                                            |
| Importance     | 20%    | 0–100 | Accumulated value from search hits (+3) and curation updates (+5). Decays by `0.995^days` when idle. |
| Recency        | 20%    | 0–1   | Exponential decay since last update (`e^(-days/30)`)                                                 |

**Tier boosts** reward mature knowledge and penalize unproven drafts:

| Maturity  | Boost |
| --------- | ----- |
| core      | ×1.15 |
| validated | ×1.0  |
| draft     | ×0.85 |

This means a `core` knowledge file with moderate BM25 relevance can significantly outrank a `draft` file with higher text relevance — surfacing the most trusted knowledge first.

### Parent Score Propagation

When a search result matches a knowledge file, its score propagates upward through the context tree hierarchy to any parent node that has an `_index.md` summary. The propagation factor decays with each level:

```
parentScore = childScore × 0.55^levels_up
```

For example, a file scoring 0.80 would contribute 0.44 to its parent and 0.24 to its grandparent. Propagated results undergo the same maturity and gap filtering as direct BM25 results, preventing low-relevance structural noise from entering the response.

### Score-Gap Filter

After scoring and propagation, results below 70% of the top score are dropped:

```
minimum = topScore × 0.7
```

This eliminates long-tail noise — if the best result scores 0.90, anything below 0.63 is excluded. The filter applies to both direct BM25 results and propagated parent results.

## Path-Scoped Queries

Beyond plain full-text queries, ByteRover automatically detects path-like patterns in your query and uses them to scope the search.

**Slash-separated paths** — When your query contains `/`, ByteRover splits it into a path prefix (used as scope) and remaining text (used as the search query):

```
auth/jwt refresh token rotation
```

This searches for "refresh token rotation" scoped to the `auth/jwt` domain/topic — ignoring other areas of the tree.

**Domain-name prefix** — If the first word of your query matches a known domain name, it's automatically used as scope even without `/`:

```
authentication refresh token rotation
```

Searches for "refresh token rotation" scoped to the `authentication` domain.

## Archived Knowledge in Search Results

Archive stubs (`_archived/*.stub.md`) are included in the BM25 index alongside regular knowledge files. When a stub appears in search results, it indicates that the full content exists but has been archived due to low importance.

Each stub carries enough context (a \~220-token ghost cue) for the query agent to evaluate relevance. Stubs are excluded from `vc push`/`vc pull` sync — they are local-only derived artifacts.