Hermes Integration Reference

Configuration details, troubleshooting, and advanced topics for the Hermes integration

Configuration Reference

Setting	Where	Required	Description
memory.provider	Hermes config	Yes	Set to byterover to activate the provider

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]

Cause: The brv binary cannot be found, or the ByteRover daemon is not running.

**Steps to diagnose:**

1. Check that `brv` is installed and in your PATH:
   ```bash
   which brv
   brv --version
   ```

2. If `brv` is missing, install it:
   ```bash
   curl -fsSL https://byterover.dev/install.sh | sh
   # or
   npm install -g byterover-cli
   ```
   Then restart your shell (or run the `export PATH` line the installer prints).

3. If `brv` is installed but the error persists, check that the daemon is running:
   ```bash
   brv status
   ```
   If it is not running, any `brv` command will start it automatically on the next call.

4. If `brv` is installed in a non-standard location (e.g. `~/.brv-cli/bin/`, `~/.npm-global/bin/`), the plugin searches these paths automatically. Confirm the binary resolves:
   ```bash
   ls ~/.brv-cli/bin/brv
   ```

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:

```bash
hermes memory setup
# — or —
hermes config set memory.provider byterover
```

Verify the active provider:

```bash
hermes config get memory.provider
```

Expected output: `byterover`

brv_query times out or returns no results

Cause: The query exceeded the 10-second timeout, or the context tree is empty.

**Solution:**

1. Check that an LLM provider is configured for ByteRover (required for query and curation):
   ```bash
   brv providers list
   ```
   If no provider is connected, add one:
   ```bash
   brv providers connect byterover        # Free tier, requires ByteRover login
   brv providers connect anthropic --api-key sk-ant-...
   ```

2. If the context tree is empty (new project), seed it first:
   ```bash
   cd $HERMES_HOME/byterover
   brv curate "Initial project context: <description>"
   ```

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:**

1. Verify your LLM provider is reachable:
   ```bash
   brv providers list
   ```

2. Run a manual curation to see the full error output:
   ```bash
   cd $HERMES_HOME/byterover
   brv curate "test"
   ```

ByteRover CLI is missing

Cause: The brv command is not in your PATH.

**Solution:** Install the ByteRover CLI:

```bash
curl -fsSL https://byterover.dev/install.sh | sh
# or
npm install -g byterover-cli
```

See the full [installation guide](/index) for platform-specific instructions.

File Reference

Path	Description
~/.hermes/config	Hermes configuration (memory.provider: byterover)
~/.hermes/.env	Environment variables (BRV_API_KEY)
$HERMES_HOME/byterover/	ByteRover working directory (profile-scoped)
$HERMES_HOME/byterover/.brv/	ByteRover context tree storage
$HERMES_HOME/byterover/.brv/context-tree/	Hierarchical knowledge files

Advanced

How it works: provider lifecycle

The ByteRover memory provider hooks into the Hermes agent loop at four points:

* **Before each LLM call** (`prefetch`) — Runs `brv query` with the user's message (10s timeout) and injects the results as additional context into the system prompt.
* **After each turn** (`sync_turn`) — Runs `brv curate` in 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.

The `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

If you have existing Hermes session notes or memory files, migrate them to the ByteRover context tree:

```bash
cd $HERMES_HOME/byterover
brv curate "curate the data in the folder ~/.hermes/memory by reviewing each file one by one."
```

ByteRover reads each file, extracts valuable insights, and organizes them into the context tree:

```
update .brv/context-tree/architecture/api_design/auth_flow.md
update .brv/context-tree/decisions/database_schema.md
✓ Context curated successfully.
```

TIP

You can point to any directory that contains .md memory files.

Uninstalling / switching providers

To stop using ByteRover, switch to a different provider or disable memory:

```bash
hermes memory setup
# — or —
hermes config unset memory.provider
```

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