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);
}
}