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

# Query the Context Tree

## Query context from the context tree

This guide walks you through querying context from your context tree using **agentic search**.

There are two ways to query your context tree:

* **`/query`** — Run directly in the ByteRover REPL for quick, manual lookups
* **`brv query`** — Executed by your coding agent for integration into coding workflows. Can be run manually.

**To query your context tree, copy this prompt and paste it into your coding agent's chat (e.g., Cursor, Claude Code, etc.):**

```markdown theme={null}
> What is the context tree structure?
```

Your coding agent will then execute the command:

```bash theme={null}
brv query "What is the context tree structure?"
```

When the command runs, ByteRover intelligently searches your context tree using a multi-tier strategy that combines BM25 full-text search, compound scoring, and multi-step reasoning.

**Example:**

```bash theme={null}
$ brv query "What is the context tree structure?"
Querying context tree...
🔧 search_knowledge → Querying knowledge base...
✅ search_knowledge → Complete (2 topics retrieved)

Query Results:
The context tree is a hierarchical file-based structure used to store and organize knowledge. Here's an overview of its structure:

**Location:** The context tree is stored in the `.brv/context-tree/` directory.

**Domains:**
The top level of the tree consists of a predefined set of domain folders. These domains include categories like `architecture`, `components`, and `apis`.

**Topics:**
Within each domain folder, there are topic subfolders. Each topic folder represents a specific area of knowledge within that domain.

**Content:**
The actual knowledge is stored in markdown files within each topic folder. These files have descriptive names based on their content and are timestamped.
```

## How Query Works

ByteRover routes every query through a 5-tier strategy, starting with the fastest path and escalating only when needed:

| Tier | Name          | Speed        | When It Fires                                                       |
| ---- | ------------- | ------------ | ------------------------------------------------------------------- |
| 0    | Exact cache   | `~0ms`       | You repeat a recent query (MD5 match, 60s TTL)                      |
| 1    | Fuzzy cache   | `~50ms`      | A cached query shares ≥60% token similarity                         |
| 2    | BM25 direct   | `~100-200ms` | Top search result scores high with a clear gap -- no LLM needed     |
| 3    | LLM pre-fetch | `<5s`        | Top results are injected as context for a single LLM call           |
| 4    | Agentic loop  | `8-15s`      | Full multi-step reasoning: reads files, follows relations, iterates |

Tiers 0-2 bypass the LLM entirely for speed. Most repeated or well-covered queries resolve in under 200ms.

For full details on each tier and out-of-domain detection, see [How Query Works](/context-tree/query-engine).

### Compound Scoring

Search results are ranked using a formula that balances text relevance, accumulated importance, and freshness:

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

Mature knowledge files (`core` tier) receive a 1.15× boost, while `draft` files receive a 0.85× penalty — well-established context surfaces above newer drafts even with slightly lower text relevance. Results below 70% of the top score are automatically dropped.

### Path-Scoped Queries

You can scope queries to a specific domain or topic by including a path:

```bash theme={null}
# Slash-separated path scoping
brv query "auth/jwt refresh token rotation"

# Domain-name prefix scoping
brv query "authentication refresh token rotation"
```

The first word (or slash-separated prefix) is detected as a scope, and the remaining text is used as the search query within that scope.

For the full scoring formula and path-scoping rules, see [How Query Works](/context-tree/query-engine).

## Manual Query via `/query`

You can also query the context tree directly in the ByteRover REPL using the `/query` command:

```
/query How is user authentication implemented?
```

This runs the query immediately without going through your coding agent.

**Example output:**

```bash theme={null}
/query What is the context tree structure?
Querying context tree...
🔧 search_knowledge → Querying knowledge base...
✅ search_knowledge → Complete (2 topics retrieved)

Query Results:
The context tree is a hierarchical file-based structure...
```

### When to Use `/query` vs Agent Prompts

| Approach                    | Best For                                                                     |
| --------------------------- | ---------------------------------------------------------------------------- |
| `/query` in REPL            | Quick lookups, ad-hoc questions, exploring what's stored                     |
| Agent prompts (`brv query`) | Complex workflows, multi-step tasks, when context feeds into code generation |

Use `/query` when you want to quickly check what knowledge is available before starting a task. Use agent prompts when the retrieved context should flow directly into your coding workflow.

## What Makes This Intelligent?

**Multi-tier strategy:**
ByteRover doesn't use a single retrieval method. It combines exact caching, BM25 full-text search with compound scoring, LLM-assisted pre-fetch, and full agentic reasoning -- routing each query to the fastest tier that can produce a quality answer.

**Follows explicit relations:**
ByteRover follows the `@domain/topic` relations between topics to gather comprehensive, connected context.

**Synthesizes information:**
Instead of returning ranked documents, ByteRover reads relevant context files and synthesizes a coherent answer with citations.

**Context-aware answers:**
You get understanding, not just matches. ByteRover comprehends your query semantically and provides relevant, actionable information.

**Out-of-domain detection:**
When your query falls outside the knowledge stored in the context tree, ByteRover tells you rather than returning a low-quality guess, and suggests curating relevant knowledge first.

For details on query tiers, compound scoring, and path-scoped queries, see [How Query Works](/context-tree/query-engine).

## Multi-Step Queries

For complex tasks requiring different types of context, you can run multiple queries:

**Copy this prompt and paste it into your coding agent's chat:**

```markdown theme={null}
> first query the context tree about Express setup, then query about TypeScript testing patterns
```

Your coding agent will then execute:

```bash theme={null}
brv query "Express server setup with TypeScript"
brv query "TypeScript testing patterns and best practices"
```

## Crafting Effective Queries

The quality of your results depends on your query. Here are some tips:

**Specific queries work better:**

```bash theme={null}
brv query "Express health check endpoint with TypeScript and tests"
```

**vs. vague queries:**

```bash theme={null}
brv query "server stuff"
```

**Include technical details:**

```bash theme={null}
brv query "JWT authentication middleware implementation with refresh tokens"
```

**Reference specific patterns or technologies:**

```bash theme={null}
brv query "React hooks for form validation with Zod schema"
```

*Note:* While ByteRover understands semantic meaning, specific and detailed queries still produce better results because they help focus the search.

## You're in Control of Your Queries

The `brv query` command is flexible and adapts to how you want to work:

### Broad Exploration

Want to see everything related to a topic? Use a general query:

**Copy this prompt and paste it into your coding agent's chat:**

```markdown theme={null}
> query all context about authentication
```

Your coding agent will execute:

```bash theme={null}
brv query "authentication"
```

ByteRover explores relations across topics to give you a comprehensive view of all authentication-related knowledge.

### Focused Retrieval

Need specific implementation details? Be more precise:

**Copy this prompt and paste it into your coding agent's chat:**

```markdown theme={null}
> query context about OAuth PKCE flow implementation
```

Your coding agent will execute:

```bash theme={null}
brv query "OAuth PKCE authorization code flow implementation"
```

ByteRover searches specific domains and topics for targeted information.