Communitygithub.com

nmdra/notebrain-cli

NoteBrain 是一款高性能的 Go 语言 CLI 工具,可将您的 Obsidian 知识库索引到本地 ChromaDB 向量数据库中,使 AI 代理能够智能地探索您的个人知识库,提供强大的语义搜索、反向链接遍历和基于标签的发现功能。

notebrain-cli 是什么?

NoteBrain 是一个专为 AI 代理设计的命令行工具,它将 Obsidian Vault 中的 Markdown 笔记索引到本地嵌入的 ChromaDB 向量数据库中。它的核心优势在于提供了语义搜索、图遍历(连接)、反向链接发现、未链接但语义相关的“隐藏”关系发现以及完整笔记检索等功能。该工具支持在 Claude Code、Cursor 和 Codex 等 AI 代理环境中使用,并强调通过 JSON 输出(`--format json`)和 `--jsonpath` 参数实现非交互式执行,以避免代理会话挂起。NoteBrain 不仅执行简单的向量搜索,还推荐多信号检索流程(搜索 → 反向链接 → 连接 → 隐藏链接),帮助代理全面理解用户的知识图谱。它作为独立的 Go 二进制文件运行,无需依赖外部数据库(如 Docker 容器),并通过 OS 调度程序自动处理数据摄取。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add nmdra/notebrain-cli

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

AI 代理的 NoteBrain CLI 技能

NoteBrain 是一个高性能的 Go CLI 工具,可将 Obsidian Vault 索引到本地 ChromaDB 向量数据库中。它提供跨 Markdown 笔记的语义搜索、图遍历、反向链接发现、隐藏关系查找、完整笔记检索和标签分析功能。

核心执行原则与原理

为高效运行并防止浪费 Token 或挂起会话,请遵循以下基本原则:

  1. 仅使用 NoteBrain — 不使用通用文件搜索:切勿使用 grep、find、ls 或针对 Vault Markdown 文件的临时 Shell 脚本来回答用户问题。NoteBrain 的命令是基于索引的向量和图数据库专门构建的,始终能产生比文件系统级文本搜索更高质量、更相关的结果。将 notebrain 视为访问 Vault 内容的唯一接口。如果 notebrain 命令似乎没有返回有用结果,请优化 notebrain 查询(使用不同的措辞、更宽的 --limit、替换命令),而不是回退到通用文件搜索。
  2. 非交互式执行(--format json):默认情况下,NoteBrain 会启动一个为人类浏览设计的交互式终端 TUI(Bubble Tea)。此交互界面会导致自动化的代理会话挂起。请始终在查询命令中指定 --format json(或 --format ndjson / --format tsv),以便立即获得结构化的、可解析的数据。注意,所有 JSON 信封字段都使用简洁的 snake_case 键(note_slug、title、file_path、score、tags、text)。
  3. AI 代理命令链(--jsonpath):当你只需要特定字段(例如提取笔记 slug 或文本以传递给后续命令)时,请使用 --jsonpath(例如 --jsonpath="$.results[0].note_slug" 或 --jsonpath="$.results[*].note_slug")。使用 --jsonpath 时,标量值将输出为原始的未引号字符串,数组中的每个项目将打印在新行上,从而无需 jq 即可实现无缝的 Shell 变量提取。
  4. 检索完整笔记(notebrain get):当 search 返回相关笔记块时,请使用 notebrain get <note-slug-or-path> 来检索跨所有索引块拼接起来的完整、重建的 Markdown 笔记文本,而不是猜测块索引。切勿对底层 Vault 文件使用 cat — get 能正确重建分块的笔记,并尊重 Vault 的索引状态。
  5. 为综合内容检索内容(--include-text):默认情况下,search 和遍历命令返回轻量级的元数据信封(标题、文件路径、标签、相似度分数)。只要你的任务需要直接从搜索结果中总结或推理单个块,请附加 --include-text。返回的 text 字段包含保留代码块的丰富 Markdown,因此代码片段是可复制粘贴的。
  6. 二进制文件解析与引号使用:在开发环境中,如果 notebrain 不在系统 PATH 中,请执行 ./notebrain。笔记标题通常包含空格或方括号(如 "Q3 Planning [Draft]"),因此务必用双引号括住笔记标题、标签和搜索查询。
  7. 嵌入式持久化存储:NoteBrain 仅作为嵌入式数据库运行(~/.notebrain/chroma)。不需要也不支持独立的 ChromaDB Docker 容器或 HTTP 服务器。
  8. 自动摄取:摄取由操作系统调度程序处理(每 3 小时 cron/systemd 定时任务)。除非用户明确要求在编辑笔记后立即重新索引,否则在查询前无需手动运行 ingest。

命令选择指南

根据用户的分析目标选择专门的命令:

用户意图命令原因与使用方法
“我的笔记对 X 有什么说法?”search对所有笔记块执行向量相似度搜索。使用 --tag="TagName" 按标签过滤。
“阅读笔记 Y 的完整内容”get通过 slug 或文件路径检索并重建完整的笔记文本和元数据。
“什么直接链接到这篇笔记?”backlinks查找指向目标笔记的显式 [[wikilink]] 引用。
“图中哪部分在结构上相邻?”connections在 wiki 链接上执行广度优先搜索(BFS),最多 --hops N 跳。保持 --hops 1 或 --hops 2 以避免指数级膨胀。
“什么在语义上相关但未被链接?”hidden展示未链接但语义相似的笔记。对于发现概念性桥梁非常有价值。
“查找与 X 相关的概念,围绕笔记 Y 展开”boosted结合向量相似度和与 --seed 笔记的图邻近度。
“哪些笔记与 X 共享标签?”tags分析标签重叠。在 tags 数组中返回干净的标签字符串。
“数据库是最新的吗?”stats输出集合计数(chunks、links)。支持 --format=json 和 --jsonpath。
“索引或重新索引 Vault”ingest将 Markdown 笔记同步到 ChromaDB。重新索引是幂等的。

命令语法

语义搜索与标签过滤(search)

notebrain search "kubernetes reconciliation" --tag="Kubernetes" --limit 5 --format json --include-text

关键搜索标志

标志用途默认值
--top-k N每篇笔记保留的最大块数。防止一篇长笔记主导结果,同时保留深度。3
--context-window N获取每个匹配周围的 ±N 个相邻块,并填充到 context 数组中。大多数任务使用 1 或 2。0
--has-tasks仅返回包含任务列表(复选框)的块。off
--has-code仅返回包含围栏代码块的块。off
--section将结果过滤到特定标题路径下的块(例如 "Architecture > Components")。—
--limit N返回的最大结果总数。10
--tag "TagName"按标签名称过滤或搜索。—
--min-score F抑制低于此相似度分数(0–1)的结果。0

何时使用 --context-window vs notebrain get

  • 使用 --context-window 1:当你需要同时为多个搜索结果提供轻量级的周围上下文时。这很高效——一次搜索调用即可获得匹配的块及其邻居,足以理解本地上下文,而无需获取完整的笔记。
  • 使用 notebrain get:当你需要 完整 的重建笔记文本时——例如,当用户要求阅读或总结特定笔记,或者当你需要查看完整文档结构时。

块窗口方法在处理大量搜索结果时尤其有价值,因为为每个结果获取完整笔记会很浪费。首先获取窗口,然后仅选择性 get 那些真正需要完整上下文的笔记。

完整笔记检索(get)

notebrain get "02areaskubernetesckadkubernetes-native-applications" --format json

图连接与隐藏链接(connections、hidden)

notebrain connections "Distributed Systems" --hops 2 --format json
notebrain hidden "Microservices" --limit 5 --format json --include-text

JSON 输出模式

理解结果结构对于可靠的字段提取至关重要。每个查询命令都将结果包装在此信封中:

{
  "command": "search",
  "query": "Semantic Search: \"kubernetes\"",
  "total": 3,
  "results": [
    {
      "note_slug": "02areaskubernetes-architecture",
      "title": "Kubernetes Architecture",
      "file_path": "02.Areas/Kubernetes/Architecture.md",
      "score": 0.82,
      "chunk_index": 2,
      "tags": ["Kubernetes", "DevOps"],
      "heading_path": "Components > Control Plane",
      "text": "The API server validates and configures...",
      "context": [
        "Previous chunk text about etcd storage...",
        "The API server validates and configures...",
        "The scheduler watches for newly created Pods..."
      ]
    }
  ]
}
字段何时出现描述
note_slug始终从文件路径派生的 URL 安全标识符。
title始终来自前置元数据或文件名的笔记标题。
file_path始终Vault 内的相对路径。
score始终搜索的相似度分数(0–1);连接的跳数。
chunk_index搜索、隐藏、增强匹配的笔记块索引(从 0 开始)。
tags笔记有标签时标签字符串数组。
heading_path块在标题下时类似 "Section > Subsection" 的面包屑路径。
text传递 --include-text 时匹配块的完整 Markdown 文本,保留代码块。
context--context-window N > 0 时按块索引排序的 ±N 个相邻块文本数组。
extra连接、标签、增强命令特定信息(例如 "2 hop(s)"、"graph-boosted")。

深化答案质量:多信号检索

在回答任何“我对 X 了解什么”或“总结我关于 X 的笔记”类型的问题之前,不要只满足于一次 search 调用。仅搜索结果是无法捕捉到用户在图中构建的周围上下文的。请始终拓宽视野:

  1. 带上下文的搜索——运行带有 --context-window 1 --include-text --top-k 2 的 search,以获取最相关的块及其周围的段落。这在一次调用中同时提供了精度(匹配的块)和上下文(前后的内容)。
  2. 提取每个种子的反向链接——运行 notebrain backlinks <seed-slug> --format json --include-text 来提取每个显式链接到种子的笔记。这些是用户手动策划为相关的笔记,因此它们的内容几乎总是高信号的,应在综合中给予较高权重。
  3. 向外遍历连接——运行 notebrain connections <seed-slug> --hops 2 --format json 来绘制种子周围的局部图邻域。这揭示了结构上相邻的笔记(例如,两跳之外的笔记),这些笔记可能不会出现在纯向量搜索中,但属于同一知识集群。
  4. 检查隐藏链接——运行 notebrain hidden <seed-slug> --include-text --context-window 1 来捕捉用户尚未链接但概念上相关的笔记。向用户明确指出这些笔记是潜在缺失链接,因为这是 NoteBrain 相对于纯搜索最有价值的差异化优势之一。
  5. 综合,而不仅仅是列出——将种子笔记、它们的反向链接、它们的 connections 邻域以及任何 hidden 结果组合成一个连贯的答案,区分哪些是显式链接的(高可信度),哪些仅是语义相似的(值得再次核实)。

对于任何非平凡的探索性问题,默认工作流应是 search → backlinks → connections → hidden 链,而不是仅仅一次 search 调用,因为它能够同时反映用户构建的显式结构和 NoteBrain 可检测到的隐式结构。

AI 代理链管道

# 1. 带周围上下文的搜索 — top-k 使结果在笔记间保持多样性
SLUG=$(notebrain search "message broker backpressure" --limit 3 --top-k 2 \
  --context-window 1 --include-text --format json \
  --jsonpath="$.results[0].note_slug")

# 2. 获取最匹配笔记的完整重建笔记文本
notebrain get "$SLUG" --jsonpath="$.text"

# 3. 查找指向此笔记的所有反向链接笔记 slug 及其内容,
#    以将答案建立用户显式链接的内容之上
notebrain backlinks "$SLUG" --format json --include-text

# 4. 遍历图邻域以展示结构上相邻但向量搜索会遗漏的笔记
notebrain connections "$SLUG" --hops

…

相关技能