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.):

> What is the context tree structure?

Your coding agent will then execute the command:

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:

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

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:

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

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:

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

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:

> first query the context tree about Express setup, then query about TypeScript testing patterns

Your coding agent will then execute:

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:

brv query "Express health check endpoint with TypeScript and tests"

vs. vague queries:

brv query "server stuff"

Include technical details:

brv query "JWT authentication middleware implementation with refresh tokens"

Reference specific patterns or technologies:

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:

> query all context about authentication

Your coding agent will execute:

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:

> query context about OAuth PKCE flow implementation

Your coding agent will execute:

brv query "OAuth PKCE authorization code flow implementation"

ByteRover searches specific domains and topics for targeted information.

Getting Started

LLM Providers

Agent Connectors

Context Tree

Knowledge Sharing

Memory Swarm

Git-Semantic Version Control

Review Changes

BRV Hub

Headless Mode

Daemon-First Architecture

Local Web UI

Reference

FAQs

Security

ByteRover Cookbook

Query the Context Tree

Query context from the context tree

How Query Works

Compound Scoring

Path-Scoped Queries

Manual Query via `/query`

When to Use `/query` vs Agent Prompts

What Makes This Intelligent?

Multi-Step Queries

Crafting Effective Queries

You’re in Control of Your Queries

Broad Exploration

Focused Retrieval

​Query context from the context tree

​How Query Works

​Compound Scoring

​Path-Scoped Queries

​Manual Query via /query

​When to Use /query vs Agent Prompts

​What Makes This Intelligent?

​Multi-Step Queries

​Crafting Effective Queries

​You’re in Control of Your Queries

​Broad Exploration

​Focused Retrieval

Query context from the context tree

How Query Works

Compound Scoring

Path-Scoped Queries

Manual Query via `/query`

When to Use `/query` vs Agent Prompts

What Makes This Intelligent?

Multi-Step Queries

Crafting Effective Queries

You’re in Control of Your Queries

Broad Exploration

Focused Retrieval