brv-bridge

Standard interface for connecting agent frameworks to ByteRover's Context Tree.

Any agent harness that implements the bridge gets context sharing for free - recall curated knowledge before a turn, persist new knowledge after a turn, and search the context tree for structured file results.

Install

npm install @byterover/brv-bridge

Prerequisites: ByteRover CLI installed and a space initialized.

Usage

import { BrvBridge } from "@byterover/brv-bridge";

const bridge = new BrvBridge({ cwd: "/path/to/project" });

// Check if brv is set up
if (await bridge.ready()) {
  // Retrieve relevant context (synthesized answer)
  const { content } = await bridge.recall("what did we decide about auth?");

  // Search for structured file results (paths, scores, excerpts)
  const { results } = await bridge.search("authentication");
  for (const r of results) {
    console.log(`${r.title} [${r.score}] — ${r.path}`);
  }

  // Store knowledge
  await bridge.persist("User prefers JWT over session cookies");
}

// Clean up
await bridge.shutdown();

API

new BrvBridge(config)

Option	Type	Default	Description
cwd	string	process.cwd()	Working directory with .brv/ initialized
brvPath	string	"brv"	Path to the brv binary
recallTimeoutMs	number	10000	Timeout for recall operations
persistTimeoutMs	number	60000	Timeout for persist operations
searchTimeoutMs	number	5000	Timeout for search operations
logger	BrvLogger	no-op	Logger instance

bridge.ready(): Promise<boolean>

Check if the bridge is configured — verifies cwd exists and has a .brv directory. Does not make network calls.

bridge.recall(query, options?): Promise<RecallResult>

Retrieve relevant context from the Context Tree. Returns { content: "" } on failure — never throws.

Options: signal (AbortSignal), cwd (override per-call).

bridge.persist(context, options?): Promise<PersistResult>

Store context into the Context Tree. Defaults to detach mode (fire-and-forget). Returns { status, message? }.

Options: detach (default true), cwd (override per-call).

bridge.search(query, options?): Promise<SearchResult>

Search the Context Tree for structured file results. Returns ranked results with paths, scores, and excerpts. Pure BM25 retrieval - no LLM, no token cost.

Unlike recall() which returns a synthesized answer, search() returns individual file-level results.

Options: limit (default 10, max 50), scope (path prefix, no trailing slash), cwd (override per-call).

const { results, totalFound } = await bridge.search("authentication", {
  limit: 5,
  scope: "auth",
});
// results: [{ path, title, excerpt, score, symbolKind?, backlinkCount? }]

bridge.shutdown(): Promise<void>

Clean up resources. Adapters should call this for forward compatibility.

For adapter authors

The bridge is designed to be wrapped by framework-specific adapters. Each adapter maps its framework's lifecycle hooks to recall(), persist(), and search():

// OpenClaw adapter example
class ByteRoverContextEngine {
  private bridge = new BrvBridge({ cwd, logger });

  async assemble(params) {
    const { content } = await this.bridge.recall(query);
    // inject content into system prompt
  }

  async afterTurn(params) {
    await this.bridge.persist(serializedConversation);
  }
}

License

Elastic License 2.0 (ELv2)