@byterover/byterover

ByteRover context engine plugin for OpenClaw. Integrates the brv CLI as a context engine that curates conversation knowledge and retrieves relevant context for each prompt — giving your AI agent persistent, queryable memory.

Table of contents

• What it does
• Prerequisites
• Quick start
• Configuration
• How it works
• Development
• Project structure
• License

What it does

When you chat with an OpenClaw agent, the conversation is ephemeral — older messages get compacted or lost as the context window fills up. ByteRover changes that by:

1. Curating every turn — after each conversation turn, the plugin feeds the new messages to brv curate, which extracts and stores facts, decisions, technical details, and preferences worth remembering
2. Querying on demand — before each new prompt is sent to the LLM, the plugin runs brv query with the user's message to retrieve curated knowledge relevant to the current request
3. Injecting context — retrieved knowledge is appended to the system prompt so the LLM has the right context without the user needing to repeat themselves

The result: your agent remembers what matters, forgets what doesn't, and retrieves context that's actually relevant to what you're asking about right now.

Prerequisites

• OpenClaw with plugin context engine support
• Node.js 22+
• brv CLI installed and available on your PATH (or provide a custom path via config). The brv path depends on how you installed it:
  • curl: the default path is ~/.brv-cli/bin/brv
  • npm: run which brv to find the path, then set it via brvPath in the plugin config

Quick start

1. Install the plugin

openclaw plugins install @byterover/byterover

For local development, build the plugin once and link your working copy:

cd /path/to/brv-openclaw-plugin
npm install
npm run build
openclaw plugins install --link /path/to/brv-openclaw-plugin

OpenClaw's install validator requires compiled runtime output (dist/index.js) before it will accept a path-linked plugin, so the npm run build step is mandatory. Re-run npm run build after editing the source.

2. Configure the context engine slot

openclaw config set plugins.slots.contextEngine byterover

3. Set plugin options

Point the plugin to your brv binary and project directory:

openclaw config set plugins.entries.byterover.config.brvPath /path/to/brv
openclaw config set plugins.entries.byterover.config.cwd /path/to/your/project

4. Verify

openclaw plugins list

You should see byterover listed and enabled. Restart OpenClaw, then start a conversation — you'll see [byterover] Plugin loaded in the gateway logs.

5. Uninstall (if needed)

openclaw plugins uninstall byterover
openclaw config set plugins.slots.contextEngine ""

Configuration

ByteRover is configured through plugins.entries.byterover.config in your OpenClaw config file (~/.openclaw/openclaw.json):

{
  "plugins": {
    "slots": {
      "contextEngine": "byterover"
    },
    "entries": {
      "byterover": {
        "enabled": true,
        "config": {
          "brvPath": "/usr/local/bin/brv",
          "cwd": "/path/to/your/project",
          "queryTimeoutMs": 12000,
          "curateTimeoutMs": 60000
        }
      }
    }
  }
}

Options

| Option | Type | Default | Description | | ----------------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | brvPath | string | "brv" | Path to the brv CLI binary. Defaults to resolving brv from PATH. | | cwd | string | process.cwd() | Working directory for brv commands. Must be a project with .brv/ initialized. | | queryTimeoutMs | number | 12000 | Timeout in milliseconds for brv query calls. The effective assemble deadline is capped at 10,000 ms to stay within the agent ready timeout. | | curateTimeoutMs | number | 60000 | Timeout in milliseconds for brv curate calls. |

How it works

ByteRover hooks into three points in the OpenClaw context engine lifecycle:

afterTurn — curate conversation knowledge

After each conversation turn completes, the plugin:

1. Extracts new messages from the turn (skipping pre-prompt messages)
2. Strips OpenClaw metadata (sender info, timestamps, tool results) to get clean text
3. Serializes messages with sender attribution
4. Sends the text to brv curate --detach for asynchronous knowledge extraction

Curation runs in detached mode — the brv daemon queues the work and the CLI returns immediately, so it never blocks the conversation.

assemble — retrieve relevant context

Before each prompt is sent to the LLM, the plugin:

1. Takes the current user message (or falls back to scanning message history)
2. Strips metadata and skips trivially short queries (< 5 chars)
3. Runs brv query with a 10-second deadline
4. Wraps the result in a <byterover-context> block and injects it as a system prompt addition

If the query times out or fails, the conversation proceeds without context — it's always best-effort.

compact — delegated to runtime

ByteRover does not own compaction. The plugin sets ownsCompaction: false, so OpenClaw's built-in sliding-window compaction handles context window management as usual.

ingest — no-op

Ingestion is handled by afterTurn in batch (all new messages from the turn at once), so the per-message ingest hook is a no-op.

Development

# Install dependencies
npm install

# Type check runtime code (tests are checked by vitest)
npm run typecheck

# Run tests
npm test

# Build runtime output (required before linking)
npm run build

# Link for local testing with OpenClaw
openclaw plugins install --link .
openclaw config set plugins.slots.contextEngine byterover

Testing locally

1. Initialize a brv project: cd /your/project && brv init
2. Link the plugin and configure as shown in Quick start
3. Restart OpenClaw
4. Send a few messages — check gateway logs for:

• [byterover] Plugin loaded — plugin registered
• afterTurn curating N new messages — curation running
• assemble injecting systemPromptAddition — context being retrieved and injected

Project structure

index.ts                    # Plugin entry point and registration
openclaw.plugin.json        # Plugin manifest (id, kind, config schema)
src/
  context-engine.ts         # ByteRoverContextEngine — implements ContextEngine
  brv-process.ts            # brv CLI spawning (query, curate) with timeout/abort
  message-utils.ts          # Metadata stripping and message text extraction
  types.ts                  # Standalone type definitions (structurally compatible with openclaw/plugin-sdk)

License

Elastic License 2.0 (ELv2)