nmdra/notebrain-cli

# NoteBrain CLI 一款 Go CLI 工具，可将你的 [Obsidian](https://obsidian.md/) 仓库转化为完全离线的知识后端，专为 **AI 编程智能体** 设计。NoteBrain 会将 markdown 笔记索引到本地的 **[ChromaDB](https://www.trychroma.com/)** 向量数据库中，并通过结构化输出提供语义搜索、wikilink 图谱遍历以及隐藏关联发现等功能——旨在直接由自主智能体、shell 管道和 LLM 工具使用工作流进行链式调用。 内置 [AI 智能体技能](wiki/Skill_Usage.md)，可与 [Google Antigravity](https://antigravity.google/)、[Pi agent](https://pi.dev) 和 Claude Code 等智能体集成。该技能经过专门优化，可减少 token 消耗并降低延迟。 [](https://github.com/nmdra/notebrain-cli/actions/workflows/release.yml) [](https://pkg.go.dev/github.com/nmdra/notebrain-cli) [](https://github.com/nmdra/notebrain-cli/blob/master/go.mod) [](https://github.com/nmdra/notebrain-cli/blob/main/LICENSE) [](https://github.com/nmdra/notebrain-cli/releases) [](https://github.com/nmdra/notebrain-cli/stargazers)

## 前置条件 - **Go 1.26.4+** - **启用 CGO 的工具链** - Linux（macOS 和 Windows 的二进制文件尚未测试） ## 功能 - **语义搜索** — 根据含义而不仅仅是关键词来查找笔记。使用 [`all-MiniLM-L6-v2`](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) ONNX 模型进行完全离线的推理。 - **多查询支持** — 支持使用多个查询进行搜索。这使得 AI 智能体能够通过将包含不同主题的搜索分离开来，从而更准确地进行搜索。 - **图谱遍历** — 通过 BFS 遍历你的 Obsidian wikilink 图谱（`[[Note]]`）：`backlinks`、`connections`（多跳）、`tags`（共享标签邻居）。 - **隐藏关联** — 发现在语义上相似但未显式链接的笔记。 - **图谱增强搜索** — 结合语义相似度得分与结构化图谱邻近度，提供更丰富的结果。 - **交互式 TUI** — 通过模糊查找浏览搜索结果。由 [Bubble Tea](https://github.com/charmbracelet/bubbletea) 提供支持。 - **高级过滤** — 通过 `--section`、`--has-code`、`--has-tasks` 或 `--tag` 缩小搜索范围。 - **完整笔记检索** — 从已索引的块中即时重建完整的笔记内容（`notebrain get`）。 - **机器可读输出** — 通过 `--format` 标志提供结构化的 JSON、TSV 输出，并内置 `--jsonpath` 提取功能（无需 `jq`）。 - **AI 智能体技能** — 内置 AI 智能体技能（`.agents/skills/notebrain/`），用于自主知识检索（参见 [AI 智能体技能使用](wiki/Skill_Usage.md)）。 - **OSC 8 超链接** — 可直接在终端中点击的 `obsidian://open` 链接。适用于 [alacritty](https://github.com/alacritty/alacritty)、[WezTerm](https://wezfurlong.org/wezterm/)、[kitty](https://sw.kovidgoyal.net/kitty/) 以及其他支持 [OSC 8 规范](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) 的终端。 - **编辑器集成** — 直接从 TUI 中在 `$EDITOR` 或 Obsidian 打开匹配的笔记。 - **Obsidian 感知摄入** — 遵循 Obsidian 配置中的 `userIgnoreFilters` 和 `attachmentFolderPath`。可选择跳过虚影链接和附件引用。 ### 底层原理 - **Goldmark AST 感知分块** — 根据标题层级而非任意字符偏移量来拆分 markdown，保留代码块和结构化元数据。 - **嵌入式 ChromaDB** — 通过 [`chroma-go`](https://github.com/amikos-tech/chroma-go) v0.4.x 直接将向量存储在磁盘上（无需外部数据库服务器）。 - **增量摄入** — SHA-256 内容哈希在重新运行时可在毫秒级内跳过未修改的笔记。 ## 安装 从 [GitHub Releases](https://github.com/nmdra/notebrain-cli/releases) 页面下载预构建的二进制文件，或从源码构建： ``` git clone https://github.com/nmdra/notebrain-cli.git cd notebrain-cli make build # CGO_ENABLED=1 go build -o notebrain . sudo mv notebrain /usr/local/bin/ ``` 有关详细信息，请参阅完整的[安装指南](wiki/Installation.md)。 ## 快速开始 **1. 索引你的仓库：** ``` notebrain ingest --vault-path "/path/to/your/Obsidian Vault" ``` **2. 根据含义搜索你的笔记：** ``` notebrain search "how do message brokers work?" --limit 5 --top-k 2 ```

**3. 为脚本和 AI 智能体获取结构化输出：** ``` notebrain search "how do message brokers work?" --limit 2 --top-k 1 --format=json | jq ```

JSON 输出示例

**4. 链式命令以检索完整笔记：** ``` # 从顶部搜索结果中提取 slug SLUG=$(notebrain search "message broker" --limit 1 --jsonpath="$.results[0].note_slug") # 获取完整的重构笔记文本 notebrain get "$SLUG" --jsonpath="$.text" ``` **5. 自动化索引** 使用 cron 作业或 systemd 定时器，让你的索引保持最新（参见[定时摄入](wiki/Scheduled_Ingestion.md))。 ## 配置 NoteBrain 从位于 `~/.notebrain/config/config.toml` 的 TOML 文件中读取配置（或通过传递 `--config=/path/to/config.toml` 指定）。CLI 标志始终会覆盖 TOML 的值。 复制模板以快速开始： ``` mkdir -p ~/.notebrain/config cp config.example.toml ~/.notebrain/config/config.toml ``` 关键设置（[完整参考](./config.example.toml))： ``` vault-path = "/path/to/Second Brain 2.0" vault-name = "Second Brain 2.0" format = "text" # "text", "json", "tsv", "ndjson" skip-attachments = true # ignore image/file links in graph skip-phantom = true # exclude uncreated "phantom" notes respect-exclude = true # honor Obsidian's ignore rules ``` ### 数据位置 所有持久化数据均存储在 `~/.notebrain/` 下： | 路径 | 内容 | | --------------------------------- | -------------------------------------------------------- | | `~/.notebrain/chroma/` | ChromaDB 向量存储（嵌入、元数据、链接图谱） | | `~/.notebrain/config/config.toml` | 用户配置文件 | 如需完全卸载，请移除 `notebrain` 二进制文件并删除 `~/.notebrain/`。 ## 文档 | 指南 | 描述 | | ---------------------------------------------------- | ---------------------------------------------------------- | | [安装](wiki/Installation.md) | 前置条件、预构建二进制文件、从源码构建 | | [命令参考](wiki/Commands.md) | 完整的 CLI 命令和标志文档 | | [架构](wiki/Architecture.md) | 内部细节：分块 pipeline、嵌入、ChromaDB schema | | [定时摄入](wiki/Scheduled_Ingestion.md) | 用于后台索引的 Cron 和 systemd 定时器设置 | | [AI 智能体技能使用](wiki/Skill_Usage.md) | 使用内置 AI 智能体技能进行自主检索 | | [DeepWiki](https://deepwiki.com/nmdra/notebrain-cli) | AI 生成的代码库文档 | ## 贡献 欢迎提交贡献！请在 [GitHub](https://github.com/nmdra/notebrain-cli) 上提交 issue 或 pull request。 本项目使用 [Conventional Commits](https://www.conventionalcommits.org/)、Go vendoring (`vendor/`)，并通过 [Lefthook](https://github.com/evilmartians/lefthook) 使用 pre-commit 钩子。 ## 许可证 [MIT 许可证](LICENSE) — 版权所有 © 2026 nmdra

标签：AI智能体, CNCF毕业项目, EVTX分析, Go, RAG, Ruby工具, 向量数据库, 日志审计, 知识管理, 语义检索