ByteRover 知识管理

使用 brv CLI 管理项目的长期记忆。

安装命令：npm install -g byterover-cli

知识以人类可读的 Markdown 文件形式存储在 .brv/context-tree/ 目录中。

无需认证。brv query、brv curate 和 brv vc（本地版本控制）可直接使用。登录仅在远程同步时需要（brv vc push / brv vc pull）。

工作流程

1. 思考前：运行 brv query 以了解现有模式。
2. 实现后：运行 brv curate 保存新的模式或决策。

命令

1. 查询知识

概述：从项目知识库中检索相关上下文。使用配置好的 LLM 提供商，从 .brv/context-tree/ 内容中合成答案。

使用此技能的情况：

• 用户希望你回忆某些内容
• 当前上下文中没有你需要的信息
• 你需要回忆自己的能力或过往行为
• 执行任何操作前，检查是否存在相关的规则、标准或偏好

不使用此技能的情况：

• 信息已存在于当前上下文中
• 查询内容为通用知识，而非存储的记忆

brv query "如何实现认证？"

2. 搜索上下文树

概述：通过纯 BM25 检索从 .brv/context-tree/ 中获取匹配文件的排序列表。与 brv query 不同，此操作不调用 LLM —— 无合成过程、无 token 开销、无需提供方设置。返回结构化结果，包含路径、得分和摘要片段。

使用此技能的情况：

• 你需要文件路径以便阅读，而非合成答案
• 需要快速、低成本的检索，避免 LLM 开销
• 处于自动化流水线中，需消费结构化输出

不使用此技能的情况：

• 需要从多个文件中合成自然语言回答 —— 请改用 brv query
• 信息已存在于当前上下文中

brv search "认证模式"
brv search "JWT 令牌" --limit 5 --scope "auth/"
brv search "auth" --format json

选项说明：--limit N（1-50，默认 10），--scope "domain/"（路径前缀过滤），--format json（用于自动化的结构化输出）。

3. 整理上下文

概述：分析并保存知识到本地知识库。使用配置好的 LLM 提供商对您提供的上下文进行分类和结构化。

使用此技能的情况：

• 用户希望你记住某些内容
• 用户有意整理记忆或知识
• 有来自用户交互的重要记忆需要持久化
• 有关于你所做、所知、所作决策或行动的重要事实

不使用此技能的情况：

• 信息已存在且未改变
• 信息为临时性内容，仅与当前任务相关，或仅为通用知识

brv curate "认证使用 JWT，有效期 24 小时。令牌通过 authMiddleware.ts 存储在 httpOnly cookie 中"

可附加源文件（最多 5 个，仅限项目范围）：

brv curate "认证中间件详情" -f src/middleware/auth.ts

4. 审查待处理变更

概述：在执行 curate 操作后，部分变更可能需要人工审查才能应用。使用 brv review 列出、批准或拒绝待处理的操作。

使用场景：

• curate 操作报告存在待审变更（显示在 curate 输出中）
• 用户希望检查、批准或拒绝待处理变更

不使用场景：

• 不存在待审变更（请先通过 brv review pending 确认）

命令：

列出当前项目所有待审变更：

brv review pending

示例输出：

2 项操作待审核

  任务：ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3
  [UPSERT · 高影响] - 路径：architecture/context/context_compression_pipeline.md
  原因：记录切换至基于 token 预算的滑动窗口
  之后：src/agent/infra/llm/context/compression/ 中的上下文压缩管道从 reactive-overflow 切换为 token-budget sliding window

  [UPSERT · 高影响] - 路径：architecture/tools/agent_tool_registry.md
  原因：记录基于能力权限的工具注册表重写
  之后：src/agent/infra/tools/tool-registry.ts 中的代理工具注册表重写，采用基于能力的权限机制

  全部批准：brv review approve ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3
  全部拒绝：brv review reject ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3
  按文件：brv review <approve|reject> ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3 --file <路径> [--file <路径>]

每项待处理任务显示：操作类型（ADD/UPDATE/DELETE/MERGE/UPSERT）、文件路径、原因，以及修改前后的摘要。高影响操作会特别标记。

批准某任务的所有操作（应用更改）：

brv review approve <taskId>

拒绝某任务的所有操作（丢弃待处理变更；恢复 UPDATE/DELETE 操作的备份）：

brv review reject <taskId>

批准或拒绝任务中的特定文件：

brv review approve <taskId> --file <路径> --file <路径>
brv review reject <taskId> --file <路径>

文件路径为相对于上下文树的相对路径（如 brv review pending 输出所示）。

注意：在批准或拒绝关键变更前，请务必征询用户意见。

JSON 输出（适用于代理驱动的工作流）：

brv review pending --format json
brv review approve <taskId> --format json
brv review reject <taskId> --format json

5. LLM 提供商配置

brv query 和 brv curate 需要配置 LLM 提供商。连接默认的 ByteRover 提供商（无需 API 密钥）：

brv providers connect byterover

若使用其他提供商（如 OpenAI、Anthropic、Google），请列出可用选项并使用您的 API 密钥连接：

brv providers list
brv providers connect openai --api-key sk-xxx --model gpt-4.1

6. 项目位置

概述： 列出已注册的项目及其上下文树路径。返回项目元数据，包括初始化状态和活跃状态。使用 -f json 可获取机器可读的输出格式。

适用场景：

• 需要查找项目的上下文树路径
• 需要确认哪些项目已被注册
• 需要验证某个项目是否已完成初始化

不适用场景：

• 当前上下文已明确知道项目路径
• 需要获取项目内容而非元数据 —— 请改用 brv query

brv locations -f json

JSON 字段：projectPath、contextTreePath、isCurrent、isActive、isInitialized

7. 版本控制

概述： brv vc 提供基于 Git 的上下文树版本控制功能。采用标准 Git 语义——分支、提交、合并、历史记录与冲突解决，全部本地运行，无需认证。团队远程同步为可选功能。旧版命令 brv push、brv pull 和 brv space 已弃用，请改用 brv vc push、brv vc pull、brv vc clone 或 brv vc remote add。

适用场景：

• 用户希望追踪、提交或检查知识库的变更
• 用户希望创建分支、合并或撤销知识更改
• 用户希望与团队同步知识（推送/拉取）
• 用户希望连接或克隆团队空间
• 用户询问知识的历史记录或差异

不适用场景：

• 用户希望查询或整理知识 —— 请改用 brv query / brv curate
• 用户希望查看待处理的整理操作 —— 请改用 brv review
• 版本控制未初始化且用户未主动要求设置

可用命令：

init、status、add、commit、reset、log、branch、checkout、merge、config、clone、remote、fetch、push、pull

首次设置

本地设置（无需认证）：

brv vc init
brv vc config user.name "Your Name"
brv vc config user.email "you@example.com"

**克隆团队空间（需 brv login）：**

brv login --api-key sample-key-string
brv vc clone https://byterover.dev/<team>/<space>.git

**将现有项目连接到远程（需 brv login）：**

brv login --api-key sample-key-string
brv vc remote add origin https://byterover.dev/<team>/<space>.git

本地工作流

检查状态：

brv vc status

暂存并提交：

brv vc add .                     # 暂存所有文件
brv vc add notes.md docs/        # 暂存特定文件
brv vc commit -m "add authentication patterns"

查看历史记录：

brv vc log
brv vc log --limit 20
brv vc log --all

取消暂存或撤销操作：

brv vc reset                     # 取消暂存所有文件
brv vc reset <file>              # 取消暂存特定文件
brv vc reset --soft HEAD~1       # 撤销上一次提交，保留暂存状态
brv vc reset --hard HEAD~1       # 丢弃上一次提交及所有更改

分支管理

brv vc branch                    # 列出所有分支
brv vc branch feature/auth       # 创建分支
brv vc branch -a                 # 列出所有分支（含远程跟踪分支）
brv vc branch -d feature/auth    # 删除分支
brv vc checkout feature/auth     # 切换分支
brv vc checkout -b feature/new   # 创建并切换分支

合并操作：

brv vc merge feature/auth        # 将分支合并到当前分支
brv vc merge --continue          # 冲突解决后继续合并
brv vc merge --abort             # 中止存在冲突的合并

设置上游跟踪：

brv vc branch --set-upstream-to origin/main

云同步（远程操作）

需完成 ByteRover 认证（brv login）并配置远程仓库。

管理远程仓库：

brv vc remote                    # 显示当前远程
brv vc remote add origin <url>   # 添加远程仓库
brv vc remote set-url origin <url>  # 更新远程地址

获取、拉取与推送：

brv vc fetch                     # 获取远程引用
brv vc pull                      # 获取并合并远程提交
brv vc push                      # 推送提交至云端
brv vc push -u origin main       # 推送并设置上游跟踪

克隆空间：

brv vc clone https://byterover.dev/<team>/<space>.git

8. 群体查询

概述： 同时在所有激活的记忆提供者中进行搜索——ByteRover 上下文树、Obsidian 仓库、本地 Markdown 文件夹、GBrain、Memory Wiki。结果通过倒数排名融合（RRF）算法融合，并根据提供者权重与相关性排序。不调用大模型，纯算法搜索。

适用场景：

• 需要同时跨多个知识源进行搜索
• 用户已配置多个记忆提供者（可通过 brv swarm status 检查）
• 希望从 Obsidian 笔记、GBrain 实体或维基页面中获取结果，与 ByteRover 上下文结合

不适用场景：

• 用户仅配置了 ByteRover —— 请改用 brv query（该命令通过大模型合成答案）
• 需要大模型生成的合成回答 —— brv swarm query 返回原始搜索结果，不进行文本合成

brv swarm query "How does JWT refresh work?"

输出示例：

Swarm Query: "How does JWT refresh work?"
Type: factual | Providers: 4 queried | Latency: 398ms
──────────────────────────────────────────────────
1. [memory-wiki] sources/jwt-token-lifecycle.md    score: 0.0150  [keyword]
   # JWT Token Lifecycle ...
2. [obsidian] SwarmTestData/Authentication System.md    score: 0.0142  [keyword]
   # Authentication System ...
3. [gbrain] alex-chen    score: 0.0117  [semantic]
   # Alex Chen — Senior Backend Engineer ...

启用解释模式（显示分类、提供者选择、增强信息）：

brv swarm query "authentication patterns" --explain

Classification: factual

Provider selection: 4 of 4 available

✓ byterover (healthy, selected, 0 results, 14ms)

✓ obsidian (healthy, selected, 5 results, 91ms)

✓ memory-wiki (healthy, selected, 2 results, 15ms)

✓ gbrain (healthy, selected, 1 results, 260ms)

Enrichment:

byterover → obsidian

byterover → memory-wiki

Results: 8 raw → 7 after RRF fusion + precision filtering

JSON output:

brv swarm query "rate limiting" --format json

Output:

{
  "meta": {
    "queryType": "factual",
    "totalLatencyMs": 340,
    "providers": {
      "byterover": { "selected": true, "resultCount": 0 },
      "obsidian": { "selected": true, "resultCount": 5 },
      "gbrain": { "selected": true, "resultCount": 1 },
      "memory-wiki": { "selected": true, "resultCount": 1 }
    }
  },
  "results": [
    { "provider": "memory-wiki", "providerType": "memory-wiki", "score": 0.015, "content": "# Rate Limiting ..." }
  ]
}

Limit results:

brv swarm query "testing strategy" -n 5

Flags: --explain（显示路由详情），--format json（结构化输出），-n <value>（最大结果数）

9. Swarm Curate

概述： 将知识存储到最佳可用的外部记忆提供者中。ByteRover 会自动分类内容类型并进行路由：实体类（人物、组织）存入 GBrain，笔记类（会议记录、待办事项）存入本地 Markdown，通用内容则存入首个可写提供者。若无外部提供者可用，则回退至 ByteRover 的上下文树。

使用此技能当：

• 您希望将知识存入外部提供者（GBrain、本地 Markdown、Memory Wiki）
• 用户已配置可写的 swarm 提供者

不要使用此技能当：

• 您希望专门将内容存入 ByteRover 的上下文树 —— 应使用 brv curate
• 未配置任何 swarm 提供者 —— 应使用 brv curate

brv swarm curate "Jane Smith is the CTO of TechCorp"

输出：

Stored to gbrain as concept/jane-smith-cto

指定特定提供者：

brv swarm curate "meeting notes: decided on JWT" --provider local-markdown:notes

输出：

Stored to local-markdown:notes as note-1776052527043.md

brv swarm curate "Architecture uses event sourcing" --provider gbrain

输出：

Stored to gbrain as concept/event-sourcing-architecture

JSON 输出：

brv swarm curate "Test content" --format json

输出：

{
  "id": "note-1776052594462.md",
  "provider": "local-markdown:project-docs",
  "success": true,
  "latencyMs": 1
}

Flags： --provider <id>（指定目标提供者），--format json（结构化输出）

10. Swarm Status

概述： 在运行 swarm 查询或存储前检查提供者健康状态和写入目标。用于确认哪些提供者可用且正常运行。

使用此技能当：

• 在执行 brv swarm query 或 brv swarm curate 前检查可用提供者
• 排查为何某特定提供者的结果缺失

brv swarm status

输出：

Memory Swarm Health Check
════════════════════════════════════════
  ✓ ByteRover       context-tree (always on)
  ✓ Obsidian        /Users/you/Documents/MyObsidian
  ✓ Local .md       1 folder(s)
  ✓ GBrain          /Users/you/workspaces/gbrain
  ✓ Memory Wiki     /Users/you/.openclaw/wiki/main

Write Targets:
  gbrain (entity, general)
  local-markdown:project-docs (note, general)

Swarm is operational (5/5 providers configured).

11. Query and Curate History

概述： 查看过去的查询与存储操作记录。使用 brv query-log view 查看查询历史，brv curate view 查看存储历史，brv query-log summary 获取聚合召回指标。支持按时间、状态、层级等条件过滤，以及查看每项操作的详细输出。

使用此技能当：

• 您希望回顾之前执行的查询或存储操作
• 需要通过 logId 检查特定操作
• 需要按时间窗口或完成状态筛选历史记录
• 需要收集数据用于分析或调试
• 想了解一段时间内新增、更新或删除的知识
• 需要获取查询召回率、缓存命中率或知识缺口的汇总统计

不要使用此技能当：

• 您想执行新的查询 —— 应使用 brv query
• 您想存储新知识 —— 应使用 brv curate

查看存储历史： 用于检查过往的存储操作

• 显示最近条目（前 10 条）

brv curate view

• 查看特定条目的完整详情：包含所有文件及操作（logId 由 brv curate 完成后输出，例如 cur-1739700001000）

brv curate view cur-1739700001000

• 列出包含文件操作信息的条目（无需 logId）

brv curate view --detail

• 按时间与状态过滤

brv curate view --since 1h --status completed --limit 1000

• 查看所有过滤选项

brv curate view --help

查看查询历史： 用于检查过往的查询操作

• 显示最近条目（前 10 条）

brv query-log view

• 查看特定条目的完整详情：匹配的文档与搜索元数据（logId 由 brv query 完成后输出，例如 qry-1739700001000）

brv query-log view qry-1739700001000

• 列出包含匹配文档信息的条目（无需 logId）

brv query-log view --detail

• 按时间、状态或解决层级过滤（0=精确缓存，1=模糊缓存，2=直接搜索，3=优化 LLM，4=完整代理）

brv query-log view --since 1h --status completed --limit 1000
brv query-log view --tier 0 --tier 1

• 查看所有过滤选项

brv query-log view --help

查看查询召回指标： 查看近期查询的聚合统计数据

• 显示最近 24 小时的摘要（默认）

brv query-log summary

• 指定时间窗口的摘要

brv query-log summary --last 7d
brv query-log summary --since 2026-04-01 --before 2026-04-03

• 叙述格式（可读性强的自然语言报告）

brv query-log summary --format narrative

• 查看所有选项

brv query-log summary --help

数据处理

存储方式：所有知识以 Markdown 文件形式存储在项目目录下的 .brv/context-tree/ 目录中。文件为人类可读格式，支持版本控制。

文件访问：brv curate 命令中的 -f 标志仅读取当前项目目录内的文件。项目根目录外的路径将被拒绝。每条命令最多允许 5 个文件，且仅支持文本和文档格式。

LLM 使用：brv query 和 brv curate 命令会将上下文发送至已配置的 LLM 服务提供商进行处理。LLM 将接收查询内容或整理文本以及任何包含的文件内容。除非用户显式执行 brv vc push，否则数据不会发送至 ByteRover 服务器。

云同步：brv vc push 和 brv vc pull 需要认证（通过 brv login）并通过 git 与 ByteRover 的云服务同步知识。其他所有命令均无需 ByteRover 认证即可运行。

错误处理

需用户操作的错误：

当出现错误时，必须向用户提供此故障排查指南。

可由代理自动修复的错误：

必须妥善处理这些错误，并在修复后重试命令。

快速诊断

运行 brv status 以检查认证状态、项目状态及提供方状态。