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

# 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

<AccordionGroup>
  <Accordion title="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 theme={null}
       which brv
       brv --version
       ```

    2. If `brv` is missing, install it:
       ```bash theme={null}
       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 theme={null}
       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 theme={null}
       ls ~/.brv-cli/bin/brv
       ```
  </Accordion>

  <Accordion title="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 theme={null}
    hermes memory setup
    # — or —
    hermes config set memory.provider byterover
    ```

    Verify the active provider:

    ```bash theme={null}
    hermes config get memory.provider
    ```

    Expected output: `byterover`
  </Accordion>

  <Accordion title="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 theme={null}
       brv providers list
       ```
       If no provider is connected, add one:
       ```bash theme={null}
       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 theme={null}
       cd $HERMES_HOME/byterover
       brv curate "Initial project context: <description>"
       ```
  </Accordion>

  <Accordion title="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 theme={null}
       brv providers list
       ```

    2. Run a manual curation to see the full error output:
       ```bash theme={null}
       cd $HERMES_HOME/byterover
       brv curate "test"
       ```
  </Accordion>

  <Accordion title="ByteRover CLI is missing">
    **Cause:** The `brv` command is not in your PATH.

    **Solution:** Install the ByteRover CLI:

    ```bash theme={null}
    curl -fsSL https://byterover.dev/install.sh | sh
    # or
    npm install -g byterover-cli
    ```

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

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

<AccordionGroup>
  <Accordion title="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/`.
  </Accordion>

  <Accordion title="Migrating existing Hermes memory data">
    If you have existing Hermes session notes or memory files, migrate them to the ByteRover context tree:

    ```bash theme={null}
    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.
    </Tip>
  </Accordion>

  <Accordion title="Uninstalling / switching providers">
    To stop using ByteRover, switch to a different provider or disable memory:

    ```bash theme={null}
    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.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Onboard Context" icon="lightbulb" href="/common-workflows/onboard-context">
    Learn how to onboard context into ByteRover
  </Card>

  <Card title="LLM Providers" icon="cpu" href="/external-llm-providers/overview">
    Connect an external provider or use the built-in LLM
  </Card>
</CardGroup>