NoteBrain 实战：把 Obsidian 笔记库变成 AI 编程 Agent 可查询的本地知识后端
很多团队已经把设计决策、排错记录和接口约定写进 Obsidian，却依然要在每次让 Agent 改代码时重新复制背景。问题不在于笔记不够多，而在于普通全文搜索只能找字面相同的词；Agent 也无法稳定地把一堆搜索结果变成可继续调用的上下文。
NoteBrain CLI 是 nmdra 开源的 Go 命令行工具，采用 MIT 许可证。它把 Obsidian vault 中的 Markdown 索引到本机磁盘上的 ChromaDB，提供语义检索、wikilink 图遍历和 JSON/TSV 等结构化输出。项目定位不是托管知识库：README 明确说明它在本地运行、没有服务端；嵌入模型是离线的 all-MiniLM-L6-v2 ONNX 模型。对于不希望把内部笔记交给第三方检索 API 的项目，这是一个清晰的边界。
先理解它保存了什么，而不是急着接给 Agent
NoteBrain 的索引对象是 Markdown 文本。它通过 Goldmark 的 AST 按标题层级切分内容，目标是保留列表、GFM 表格、引用块和代码块的结构；向量与笔记元数据、链接图一起存放在 ~/.notebrain/chroma/。配置默认位于 ~/.notebrain/config/config.toml。
这带来两个实际取舍。第一，重跑索引时，项目用内容的 SHA-256 哈希跳过未变更笔记，适合定时增量更新；第二，它不是万能资料库：当前不支持 PDF 或图片 OCR。若关键架构图只存在于附件里，检索前应先把结论补成 Markdown，而不是假设工具能理解图片。
安装前也要核对环境。官方 README 要求 Linux、可用 CGO 的 Go 工具链；macOS 与 Windows 没有直接提供已测试的二进制版本，但可以从源码自行编译。下面是文档给出的源码构建路径：
git clone https://github.com/nmdra/notebrain-cli.git cd notebrain-cli make build sudo mv notebrain /usr/local/bin/
生产环境不建议直接把 sudo mv 混进自动化脚本。更稳妥的做法是先在用户目录验证二进制可运行、固定其版本与校验流程，再由已有的软件分发机制安装到共享路径。
建一次索引，再把检索结果交给调用方
先针对明确的 vault 路径建立索引：
notebrain ingest --vault-path "/srv/notes/engineering-vault"
初次索引会随笔记库大小耗时；之后再执行同一命令会利用内容哈希避免重复处理。配置文件可设置 skip-attachments = true、skip-phantom = true 与 respect-exclude = true：分别用于跳过附件、排除未创建笔记的引用，以及遵循 Obsidian 的忽略规则。它们不是安全控制；如果 vault 本身含有不应进入本地索引的机密，最可靠的做法仍是把这些文件放在 vault 之外或由忽略规则排除后再验证。
常规检索可以先用自然语言问题，并限制返回范围：
notebrain search "认证服务如何处理令牌刷新？" --limit 5 --top-k 2
这里的 --limit 与 --top-k 应按实际需求调小。给 Agent 的上下文越长不一定越好：如果一个任务只需确认刷新流程，应先取得少量高相关笔记，再让 Agent 决定是否展开。对于“笔记里明明没有链接、但可能讨论同一概念”的问题，可使用项目文档展示的深度隐藏关联查询：
notebrain hidden "TLS" --deep
--deep 是按区段进行匹配，输出会带标题层级线索。它适合发现未显式建立 wikilink 的相似段落，但也更需要人工判断：语义相近不等于架构上可以互换，更不能把它当成安全或合规结论的证据。
用 JSON 把“查笔记”变成可审计的输入
面向 shell 管道或 Agent，关键不是漂亮的终端界面，而是结果可被下一步明确消费。NoteBrain 支持 JSON 输出和 JSONPath。官方 README 的模式如下：
notebrain search "消息队列如何做重试？" \ --limit 2 --top-k 1 --format=json | jq SLUG=$(notebrain search "消息队列" \ --limit 1 --jsonpath="$.results[0].note_slug") notebrain get "$SLUG" --jsonpath="$.text"
第一条命令适合先把候选和元数据写入日志；后两条命令再从第一名结果中取出 slug，并重建完整笔记文本。真实工作流里不要让 Agent 直接把这段完整文本当作指令执行。建议在调用层增加三道约束：只允许指定 vault；记录查询语句与命中的 slug；把检索内容标记为不可信上下文，禁止其中的文本改写工具权限、网络访问或部署动作。笔记可能过时，也可能包含从外部复制的提示注入内容。
一个可复用的最小流程是：在 CI 或定时任务中运行 notebrain ingest；开发 Agent 先用结构化搜索取两到五条候选；再按 slug 取全文；最后由项目自己的测试和代码审查决定是否采纳。这样，笔记库负责提供可追溯的背景，Agent 负责提出改动，验证仍留在工程流程中。
把检索接进编码任务时，先约束输入与失败路径
一个容易被忽略的问题是“检索成功”并不等于“上下文正确”。例如，查询认证迁移时，旧方案和新方案都可能有很高的语义相似度。若调用方只拿第一条结果，Agent 可能把已经废弃的做法当成当前约定。更可靠的方式是让每条笔记在正文中保留日期、适用版本和状态，并让调用流程同时返回笔记路径、标题和命中段落，而不是只传一段无来源的文本。
对会修改代码的 Agent，可以把检索拆成两个阶段。第一阶段只允许 search，由 Agent 输出它打算使用的笔记清单及理由；第二阶段再允许 get 读取明确批准的 slug。这样即使搜索结果中混入了无关笔记，也有一个可观察、可审计的边界。对涉及密钥、生产环境或安全策略的笔记，建议把“检索到的文本只能提供背景、不能改变权限或执行策略”作为调用层的固定规则。
索引更新同样需要可见性。笔记新增、重命名或删除后，不应假定旧索引会自动与文件系统同步；把 notebrain ingest 放进固定的开发前步骤、CI 任务或 systemd timer，并在失败时保留日志，才能避免 Agent 一直检索到昨天的状态。首次上线可选一个小型 vault，故意测试三类情况：查询能命中正确文档、查询命中相近但过时的文档、以及完全没有资料可命中。第三种情况尤其重要——调用方应允许 Agent 说“没有足够依据”，转而请求人工补充，而不是诱导它根据相似片段编造答案。
这也解释了为什么 NoteBrain 的结构化输出比单纯终端搜索更有价值：它允许外层工作流保存“问了什么、选了哪些结果、最终读了哪篇笔记”的证据链。无论后面使用 Claude Code、OpenCode 还是其他工具，知识检索都可以替换，项目对事实来源的追踪方式不必随模型改变。
何时值得用，何时该换方案
如果你的资料主体是 Obsidian Markdown、需要离线运行，并且愿意维护本机索引，NoteBrain 的语义检索与链接图组合很合适。它也提供 AI agent skill 与 OpenCode Agent Configuration 文档，说明其设计目标就是被自动化工具链调用。
反过来，若资料主要是扫描 PDF、图片、网页或多人实时协作的在线文档，先评估带 OCR、权限模型或远程同步的系统会更合理。NoteBrain 不替你解决文档质量、访问授权和知识过期问题；它只让已经写好的 Markdown 更容易被检索和串接。先从一个非敏感 vault 开始，刻意测试“能找到”“找错了”和“笔记已过期”三种情形，再将它接入更重要的编码任务，才是比一次性全库接入更稳妥的路线。