Configuration Reference
Context-tree directory:
$HERMES_HOME/byterover — profile-scoped, created automatically on first use. All brv commands run against the .brv/ context tree inside this directory.
Troubleshooting
brv_query or brv_curate returns [error]
brv_query or brv_curate returns [error]
Cause: The
brv binary cannot be found, or the ByteRover daemon is not running.Steps to diagnose:-
Check that
brvis installed and in your PATH: -
If
brvis missing, install it:Then restart your shell (or run theexport PATHline the installer prints). -
If
brvis installed but the error persists, check that the daemon is running:If it is not running, anybrvcommand will start it automatically on the next call. -
If
brvis installed in a non-standard location (e.g.~/.brv-cli/bin/,~/.npm-global/bin/), the plugin searches these paths automatically. Confirm the binary resolves:
Memory provider not active / brv tools not available to agent
Memory provider not active / brv tools not available to agent
Cause: The ByteRover provider is not selected in Hermes config.Solution: Run the interactive setup or set it manually:Verify the active provider:Expected output:
byteroverbrv_query times out or returns no results
brv_query times out or returns no results
Cause: The query exceeded the 10-second timeout, or the context tree is empty.Solution:
-
Check that an LLM provider is configured for ByteRover (required for query and curation):
If no provider is connected, add one:
-
If the context tree is empty (new project), seed it first:
brv_curate returns [error] or takes too long
brv_curate returns [error] or takes too long
Cause: Curation has a 120-second timeout. Failures are usually due to a missing LLM provider or network issues when using a cloud provider.Solution:
-
Verify your LLM provider is reachable:
-
Run a manual curation to see the full error output:
ByteRover CLI is missing
ByteRover CLI is missing
Cause: The See the full installation guide for platform-specific instructions.
brv command is not in your PATH.Solution: Install the ByteRover CLI:File Reference
Advanced
How it works: provider lifecycle
How it works: provider lifecycle
The ByteRover memory provider hooks into the Hermes agent loop at four points:
- Before each LLM call (
prefetch) — Runsbrv querywith the user’s message (10s timeout) and injects the results as additional context into the system prompt. - After each turn (
sync_turn) — Runsbrv curatein the background (non-blocking, 120s timeout) to extract and store valuable knowledge from the conversation turn. - Before context compression (
on_pre_compress) — Extracts insights from the full message history before it is summarized, ensuring nothing is lost during compaction. - On built-in memory writes (
on_memory_write) — Mirrors writes to Hermes’ built-in memory store into the ByteRover context tree automatically.
brv binary is resolved once per session (thread-safe cache) by searching your PATH first, then checking well-known install locations: ~/.brv-cli/bin/, /usr/local/bin/, ~/.npm-global/bin/.Migrating existing Hermes memory data
Migrating existing Hermes memory data
If you have existing Hermes session notes or memory files, migrate them to the ByteRover context tree:ByteRover reads each file, extracts valuable insights, and organizes them into the context tree:
Uninstalling / switching providers
Uninstalling / switching providers
To stop using ByteRover, switch to a different provider or disable memory:The
.brv/ context tree in $HERMES_HOME/byterover/ is preserved and can be reactivated at any time.Next Steps
Onboard Context
Learn how to onboard context into ByteRover
LLM Providers
Connect an external provider or use the built-in LLM