briefd

briefd

为你的 Agent 提供简明简报，而非信息轰炸。
面向 AI 编码团队的可自托管上下文编译器：基于 git 的知识，通过 MCP 提供给编码 Agent，
并以受令牌预算限制的上下文包形式交付。

---

▶ 观看 90 秒介绍视频 · 工作原理 · 快速开始

在同一领域构建多个项目的团队，会把相同的知识记在脑海里，也散落在各种 CLAUDE.md / AGENTS.md 文件中：术语、业务规则、架构决策、约定。每轮都把所有内容加载到每个会话中，会消耗数千个令牌，而放不下的内容则会被舍弃。

briefd 颠覆了这种模式：按需提供上下文，而不是预先加载。 你的知识以 Markdown 格式存储在 git 仓库中。briefd 会为其建立索引，并回答编码 Agent 提出的一个问题——“完成这项任务，我需要了解什么？”——然后生成一个经过整理、去重且绝不会超过你所设令牌预算的内容包。

原因

在此仓库的示例知识库（44 篇文档、47 项贴近实际的开发任务）中，compile_bundle 每项任务消耗的令牌比将所有内容粘贴到 CLAUDE.md 中少 86%，同时 96% 的情况下仍包含解答任务所需的章节（使用仅支持英文的 all-MiniLM-L6-v2 模型时为 98%，这是解说视频中引用的数据）。一个贴近实际的折中方案——手动精选 CLAUDE.md，只保留约定和术语表——成本是 bundle 的 2.8 倍，答案命中率却不到一半。

运行 make bench 可复现结果；方法见 internal/eval/bench.go。

这只是分词器给出的数据。在真实的 Claude Code 会话中（eval/session/、Sonnet、10 项任务、相同提示词），briefd 在答案不变的情况下，将每轮携带的上下文减少了 35%，每项任务的成本降低了 40%，代价是每项任务多进行 3–4 次工具调用往返。知识库越大，节省越明显；静态的 CLAUDE.md 做不到这一点。

不是又一个 Agent 记忆工具

记忆工具（agentmemory、Mem0、claude-mem）会自动记录 Agent 在会话中观察到的内容，并按用户区分。briefd 提供的是 团队 的决策，由成员撰写并像代码一样审查。它们回答的是不同的问题，可以并行使用。

	Agent 记忆	briefd
真相来源	Agent 写入的数据库	git 仓库中的 Markdown
谁来写	Agent 自动写入	成员编写；Agent 发起拉取请求
范围	一个 Agent／一个用户	整个团队，涵盖该领域的每个项目
审查	无	每项更改都有差异、审阅者和署名
过时情况	未知	每个章节都有日期；可检查内容与所管代码之间的偏差
无法回答的问题	不作提示，直接缺失	在仪表板上列为待办事项
运行占用	运行时 + 引擎 + 多个端口	一个静态二进制文件、一个 SQLite 文件、一个端口（或 stdio）
工具表面	数十种工具，每次会话数千个令牌	7 种工具，每次会话约 2.8k 个令牌

使用记忆工具，让 Agent 记住它上周尝试过什么。使用 briefd，让团队中的每个 Agent 都遵循同一套规则——并让成员及时发现规则何时落后于代码。

工作原理

• Git 是真相来源。 索引是可随时丢弃的缓存，可从克隆仓库重建。
• Agent 永远不会写入索引。 propose_update 会创建可审查的分支／PR；只有人工合并后，briefd 提供的内容才会改变。
• 混合检索，无需外部服务。 SQLite FTS5（BM25）+ 多语言嵌入（支持 100 多种语言的 multilingual-e5-small），由纯 Go 编码器计算，并通过倒数排名融合进行融合。无需 Postgres、向量数据库、ONNX 运行时或 CGO。
• 严格的令牌预算。 每个返回上下文的 API 都接受 max_tokens，且绝不会超出限制。

快速开始

30 秒内即可试用——无需仓库：

briefd demo      # serves the built-in sample knowledge base on http://127.0.0.1:7788

然后打开仪表板，或让 Agent 连接到它：claude mcp add --transport http briefd http://127.0.0.1:7788/mcp。 首次运行会下载嵌入模型（约 470 MB）；briefd demo --embeddings none 可跳过。

使用你自己的知识：

# 1. build (Go >= 1.26) or grab a binary from the releases page
git clone https://github.com/ismailperim/briefd && cd briefd && make build

# 2. serve the sample knowledge repo (downloads the 470 MB multilingual embedding model once)
./bin/briefd serve --source testdata/knowledge --db /tmp/briefd.db --token dev-token

# 3. connect Claude Code
claude mcp add --transport http briefd http://localhost:7788/mcp \
  --header "Authorization: Bearer dev-token"

打开 http://localhost:7788/ 查看仪表板，然后向 Claude Code 提问样例语料库涵盖的问题——“收单方调用的重试策略是什么？” 或 “ters ibraz nedir?”——并观察 search_context / compile_bundle 出现在请求日志中。

任何支持流式 HTTP 的 MCP 客户端均可使用。项目级 .mcp.json 配置如下：

{
  "mcpServers": {
    "briefd": {
      "type": "http",
      "url": "http://localhost:7788/mcp",
      "headers": { "Authorization": "Bearer dev-token" }
    }
  }
}

让 Agent 安装。 给你的编码 Agent 一条指令：

获取并遵循以下说明：https://raw.githubusercontent.com/ismailperim/briefd/main/INSTALL_FOR_AGENTS.md

教 Agent 何时提问。 Agent 不调用的工具毫无用处。skills/briefd 技能会告诉 Claude Code（以及任何会读取 SKILL.md 的 Agent）何时编译信息包、如何处理过时的章节，以及何时建议更新；deploy/local/CLAUDE.md 中的 CLAUDE.md 段落提供了相同的指导。

npx skills add ismailperim/briefd

单用户使用，不需要服务？ briefd mcp 通过 stdio 提供 MCP——工具和索引不变，无需端口和令牌。Claude Desktop、Cursor 的 stdio 配置以及 MCP 目录检查器都可以直接启动它：

{
  "mcpServers": {
    "briefd": {
      "command": "briefd",
      "args": ["mcp", "--source", "/path/to/knowledge", "--db", "~/.briefd/knowledge.db"]
    }
  }
}

团队共用一个实例（仪表板、指标、webhook、REST）时使用 serve；Agent 在存放检出内容的机器上运行时使用 mcp。

工具

工具	功能
compile_bundle(task_description, max_tokens?, scopes?, paths?)	在预算范围内生成一个去重的信息块，按领域 → 约定 → 项目排序，每个章节附带来源行和 bundle_id。结果确定且带缓存。
search_context(query, max_tokens?, scopes?, top_k?, paths?)	返回符合预算的排序章节，供检查。paths（正在编辑的代码路径）会将其 refs 涵盖这些路径的文档置顶。
get_document(doc_path, scopes?)	获取一篇完整文档。
list_scopes()	列出范围及其文档数/章节数。
propose_update(doc_path, change_description, new_content)	创建分支 briefd/proposal-<id>（配置后同时创建拉取请求）。绝不触及索引。
report_usage(bundle_id, useful_chunk_ids)	可选反馈：哪些章节有所帮助。空列表表示存在知识缺口。
suggest_links(doc_path?, limit?)	找出知识库缺少的链接（文档提及另一篇文档却未链接）以及失效链接，供 Agent 通过 propose_update 整理知识库。

相同操作也可通过 REST 使用（/api/search、POST /api/bundle、/api/docs/{path}、 /api/scopes、POST /api/proposals、POST /api/usage、/api/gaps、/api/health、/api/stats），并由相同的 bearer token 保护。

你的知识仓库

briefd 需要一个包含 Markdown 文件的 git 仓库（或目录），其中有三类文件夹 （briefd init <dir> 会生成包含示例文档的脚手架）：

knowledge-repo/
├── domain/          # shared: terminology, business rules, ADRs
├── conventions/     # shared: coding standards, infra patterns
└── projects/
    ├── ledger-service/   # visible only when scope "projects/ledger-service" is requested
    └── merchant-portal/

文档会按 ##/### 标题拆分为约 200–800 个 token 的章节，并分配稳定 ID，因此每个章节都可以单独引用。可选的 front matter 可添加元数据：

---
title: Retry policy            # defaults to the first H1
tags: [payments, resilience]
refs: ["services/payment/**"]  # code paths this doc governs
---

testdata/knowledge/ 是一个完整示例（虚构的支付平台），也可用作评估语料库。

Obsidian 知识库和链接

知识库可以是 Obsidian 知识库。briefd 会读取正文和 front matter 属性（例如 related:）中的 [[wikilinks]]（包括 [[note|alias]] 和 [[note#heading]]），以及相对 Markdown 链接，按照 Obsidian 的方式解析这些链接（按路径，或在知识库任意位置按文件名查找），并构建链接图谱：仪表板会绘制图谱，get_document 会返回每篇文档的链接和反向链接，供 Agent 跟进；孤立文档（没有链接指向此处）和失效链接（目标不存在）会与知识缺口和覆盖率一起列为维护信号。文件夹范围仍然适用——domain/、conventions/、projects/<name>/——因此请保持知识库顶层结构如此。

实际运行

export BRIEFD_GIT_TOKEN=ghp_...     # only for private HTTPS remotes
./bin/briefd serve --source https://github.com/your-org/knowledge.git --token "$(openssl rand -hex 16)"

briefd 会克隆仓库，并通过 fetch + hard reset 跟踪分支，间隔为 sync.interval（默认 60 s）；或者在代码托管平台使用 GitHub 风格的 HMAC 签名调用 POST /webhook/git 时立即同步。只有变更过的文件才会重新解析和重新生成嵌入。

语言。 默认嵌入模型 multilingual-e5-small 支持 100 多种语言，因此土耳其语、德语或日语知识库，以及用其他语言查询的英文文档，都可以开箱即用。仅使用英语的团队可以设置 embeddings.model: all-MiniLM-L6-v2（87 MB，索引速度约快 2.5 倍）。briefd model pull 可预先下载模型，用于离线或构建镜像；--embeddings none 会启用仅 BM25 模式；Ollama 和兼容 OpenAI 的服务也可作为替代提供方。

Docker

cd deploy
BRIEFD_SOURCE=https://github.com/your-org/knowledge.git BRIEFD_API_TOKEN=... docker compose up

该镜像采用 distroless 设计，纯 Go 编写（约 34 MB，支持 linux/amd64 + arm64）。数据库、检出内容和模型存储在 briefd-data 卷中。也可以挂载目录并设置 BRIEFD_SOURCE=/knowledge，以提供本地文件。

部署指南： deploy/README.md 涵盖 Compose 和 systemd 配置、Git 代码托管平台（GitHub、GitLab、Azure DevOps、Bitbucket、SSH）、离线安装嵌入模型、代理和私有 CA、对外开放与安全、升级和监控。仅在笔记本电脑上使用，请参阅 deploy/local/。

配置 — 使用 briefd.yaml（参阅 deploy/briefd.example.yaml）或 BRIEFD_* 环境变量；命令行标志的优先级高于两者。你实际会用到的配置项：

设置	环境变量	默认值	说明
source	BRIEFD_SOURCE	—	Git URL 或目录
api_token	BRIEFD_API_TOKEN	(无)	留空 = 无需身份验证（仅限受信任的网络）
listen	BRIEFD_LISTEN	:7788
sync.interval	BRIEFD_SYNC_INTERVAL	60s	0 表示禁用轮询
sync.webhook_secret	BRIEFD_SYNC_WEBHOOK_SECRET	—	启用 POST /webhook/git
git.token	BRIEFD_GIT_TOKEN	—	用于 HTTPS 远程仓库；SSH 使用 git.ssh_key
forge.type、forge.token	BRIEFD_FORGE_*	—	github 或 gitlab：为每条提案创建拉取请求 / 合并请求
embeddings.provider	BRIEFD_EMBEDDINGS_PROVIDER	local	ollama、openai，或用于仅 BM25 模式的 none
embeddings.model	BRIEFD_EMBEDDINGS_MODEL	multilingual-e5-small	也可使用 all-MiniLM-L6-v2（仅支持英语，速度更快）
search.default_max_tokens	BRIEFD_DEFAULT_MAX_TOKENS	2000
query_log.retention_days	BRIEFD_QUERY_LOG_RETENTION_DAYS	30	用于生成知识缺口报告；设置 query_log.enabled: false 可关闭
code.repos	—	(无)	与文档的 refs 对比以检查漂移的代码仓库（URL 或路径）

briefd model pull 可预先下载嵌入模型，用于离线或构建镜像。

仪表板和指标

GET / 是嵌入二进制文件中的仪表板（无需构建步骤或外部资源）：

• 概览 — 请求数、已提供和已节省的令牌数、索引和同步状态；知识图谱中标注了过去 24 小时内提供给 Agent 的文档；流转列表；以及 需要关注，按严重程度从高到低排列维护信号，每个信号一行。
• 图谱 — 所有文档和链接，支持缩放和平移（使用鼠标或键盘）、范围筛选和搜索；选择文档即可查看其链接、反向链接以及提供次数 （#graph=<doc path> 可直接跳转到该文档）。
• 维护 — 等待审核的提案、知识缺口、内容落后于代码的文档、最久未更新的文档、待修复的链接和代码覆盖率。
• 活动 — 按工具统计的延迟和调用量、按范围统计的索引以及请求日志；计数器会在重启后保留，也可以重置。
• 实例 — 运行配置（仅显示密钥是否已设置），以及「立即同步」和「重建索引」功能。

GET /metrics 以 Prometheus 文本格式公开计数器；GET /api/stats 以 JSON 格式公开。

知识缺口。 每次 search_context / compile_bundle 调用都会记录其检索置信度（query_log，保留 30 天）。仪表板会列出过去七天内知识库未能解答的问题——没有匹配结果，或 Agent 的 report_usage 指出没有任何章节有帮助——按问题分组，并按提问频率排序；还会列出已解答的问题中首位结果优势不明显的问题。此列表是负责维护代码库的人需要处理的待办事项；GET /api/gaps?days=7&limit=20 会以 JSON 格式返回此列表。

文档时效。 Bundle 中的每个章节都带有文档最后修改日期 （## path — heading (updated 2026-03-04)，取自 Git 历史；对于普通目录，则取文件修改时间），让 Agent 能够根据规则的时效性判断其权重。仪表板会列出最久未更新的文档——应当优先重新阅读的文档。

内容落后于代码。 在文档的 front matter 中为其添加 refs: ["services/payment/**"]，并在 code.repos 中列出代码仓库；briefd 会追踪这些仓库的历史记录（使用裸克隆，不读取文件），并统计文档最后修改之后涉及受管路径的提交数。随后，归属信息行会显示为 (updated 2026-03-01; code changed since: 3 commits, last 2026-06-01)，仪表板会列出落后最严重的文档，并导出 briefd_documents_behind_code。阅读过时规则的 Agent 通常正适合通过 propose_update 修复规则。设计见 ADR-0007。

同一套 refs 机制也适用于反向关联：将任务涉及的文件作为 paths 传给 compile_bundle，管辖这些文件的规则就会优先显示在 Bundle 中；仪表板的 覆盖率 面板则会列出代码仓库中没有任何文档涉及的目录——也就是知识库的盲点（ADR-0008）。 briefd 本身不会为代码编制索引；Agent 的 grep 和 LSP 在这方面做得更好。

检索质量

检索效果以实测为准。make eval 会在示例语料库上对 47 个英文黄金查询（关键词、释义、拼写错误、混合语言）评分，并在土耳其语语料库上对 30 个土耳其语查询评分；如果混合检索效果低于 eval/thresholds.yaml 或 eval/thresholds-tr.yaml 中的阈值，CI 就会失败：

模式	英文 R@5	英文 R@10	英文 MRR	土耳其语 R@5	土耳其语 R@10	土耳其语 MRR
仅 BM25	0.681	0.755	0.591	0.733	0.767	0.602
仅向量	0.830	0.936	0.771	0.950	1.000	0.832
混合（默认）	0.830	0.926	0.746	0.933	1.000	0.847

在公开的 BEIR 数据集上，briefd 的仅向量模式复现了两种嵌入模型已发布的效果，混合模式在每个数据集上的表现都优于 BM25 和仅向量模式——SciFact 的 nDCG@10 为 0.714，而 BEIR BM25 基线为 0.665；请参阅 eval/beir/ 进行复现。

每次更改分块、嵌入或融合方式时，都会附上更改前后的数据 （ADR-0004 就是一个示例）。

命令行界面

briefd demo       # serve the built-in sample knowledge base — try it in 30 seconds
briefd init       # scaffold a knowledge repo (domain/, conventions/, projects/)
briefd serve      # MCP over HTTP + REST + dashboard, for a shared instance
briefd mcp        # MCP over stdio, for one agent on this machine (Claude Desktop, Cursor)
briefd index      # index a directory into the database (--rebuild to start over)
briefd search     # query like search_context does (--mode bm25|vector|hybrid, --json)
briefd model list # local embedding models and whether they are downloaded
briefd model pull # download a model (--model all-MiniLM-L6-v2 for the English one)
briefd eval       # retrieval quality against the golden set
briefd bench      # tokens per task: static CLAUDE.md vs compile_bundle

状态与路线图

v0.1 的功能已完成；在 1.0 之前仍可能存在一些不完善之处。接下来的计划：

• 根据 report_usage 的使用情况调整相关性
• 检测提案中的矛盾
• 为 BM25 部分添加轻量级土耳其语词干提取器，并进行术语表别名查询扩展
• 每个实例支持多个知识库

请阅读 docs/ARCHITECTURE.md，通过图示了解项目架构。完整规范见 SPEC.md；设计决策记录在 docs/adr/ 中。

贡献

欢迎提交问题和拉取请求——请参阅 CONTRIBUTING.md，了解开发环境设置、测试规则和惯例。安全问题请参阅 SECURITY.md。

许可证

Apache-2.0