Skip to main content

​
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:
TierNameSpeedWhen It Fires
0Exact cache~0msYou repeat a recent query (MD5 match, 60s TTL)
1Fuzzy cache~50msA cached query shares ≥60% token similarity
2BM25 direct~100-200msTop search result scores high with a clear gap — no LLM needed
3LLM pre-fetch<5sTop results are injected as context for a single LLM call
4Agentic loop8-15sFull 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.25 × importance + 0.15 × recency) × tierBoost
Mature knowledge files (core tier) receive a 1.15× boost, meaning well-established context surfaces above newer drafts even with slightly lower text relevance.

​
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

ApproachBest For
/query in REPLQuick 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.