一个 Go CLI 工具，可将你的 Obsidian 知识库转变为完全离线的知识后端，供 AI 编程智能体 使用。NoteBrain 将 Markdown 笔记索引到本地 ChromaDB 向量数据库，并通过结构化输出提供语义搜索、维基链接图遍历和隐藏关联发现——专为自主智能体、Shell 管道和 LLM 工具调用工作流直接串联而设计。

附带 AI 智能体技能 和 OpenCode 智能体配置，可与 OpenCode、Google Antigravity、Pi agent 和 Claude Code 等自主编程智能体集成。此配置专门针对降低 token 用量和延迟进行了优化。

注意

你好，我是 Nimendra。 我每天都用 Obsidian 作为主要笔记方案。当 AI 智能体出现时，我想把 Obsidian 知识库用作 RAG 系统，但多数现有方案无法满足我的需求。 在研究过程中，我看到了这篇文章，它给了这个项目启发。于是我为自己构建了这个工具。虽然你可以直接使用，但我强烈建议你复刻并修改这个方案以适应自己的使用场景。

我不使用 Windows 或 macOS，因此不会直接提供这些系统版本，但你可以通过源码编译二进制文件。

• 语义搜索 — 使用离线 all-MiniLM-L6-v2 ONNX 嵌入模型，按含义而非关键词查找笔记。
• 多查询搜索 — 通过多条独立查询提高复杂主题和 AI 智能体工作流的检索效果。
• 知识图谱遍历 — 通过反向链接、多跳连接和共享标签关系探索 Obsidian 维基链接图。
• 隐藏关联 — 发现语义相关但未显式链接的笔记，并支持深层段落级分析。
• 图谱增强排序 — 结合语义相似度与图谱关系，提升搜索相关性。
• 交互式终端 UI — 通过模糊搜索界面浏览结果，并在无结果时提供智能引导。
• 高级过滤 — 按段落、标签、代码块、任务和其他笔记元数据细化结果。
• 完整笔记检索 — 从已索引内容按需重建完整笔记。
• 结构化输出 — 以 JSON 或 TSV 格式导出结果，内置 JSONPath 查询，便于自动化。
• AI 智能体集成 — 包含内置 AI 智能体技能和专用配置，用于自主知识检索。
• 终端超链接 — 在支持的终端中使用 OSC 8 超链接直接打开笔记。
• 编辑器集成 — 在你偏好的编辑器或 Obsidian 中一键打开搜索结果。
• Obsidian 感知索引 — 遵循 Obsidian 配置，包括忽略文件、附件文件夹以及可选排除空笔记引用。

注意：目前该工具仅处理 Markdown 文本，不支持 PDF 或图片 OCR。

工作原理

• Goldmark AST 感知分块 — 按标题层级而不是随意字符偏移量切分 Markdown，严格保留列表、GFM 表格、引用块/标注和代码块。
• 嵌入式 ChromaDB — 通过 chroma-go 将向量直接存储在磁盘上。
• 增量摄入 — SHA-256 内容哈希在重新运行时能在毫秒级跳过未修改的笔记。

更多细节请参阅架构指南。

前提条件

• Go 1.26.4+
• 启用 CGO 的工具链
• Linux（macOS 和 Windows 二进制文件未经测试）

安装

从 GitHub 发布页面下载预构建二进制文件，或从源码构建：

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/

详见完整的安装指南。

快速开始

1. 索引你的知识库：

notebrain ingest --vault-path "/path/to/your/Obsidian Vault"

注意：首次索引可能需要几分钟，具体取决于知识库大小。

2. 按含义搜索笔记：

notebrain search "消息代理是如何工作的？" --limit 5 --top-k 2

3. 发现笔记段落间的深层隐藏关联：

使用 --deep 逐块节匹配（§ <标题>）寻找语义相近但无直接维基链接的笔记：

notebrain hidden "TLS" --deep

4. 为脚本和 AI 智能体获取结构化输出：

notebrain search "消息代理是如何工作的？" --limit 2 --top-k 1 --format=json | jq

示例 JSON 输出

5. 串联命令以获取完整笔记：

从最佳搜索结果中提取 slug

SLUG=$(notebrain search "message broker" --limit 1 --jsonpath="$.results[0].note_slug")

检索完整的笔记文本

notebrain get "$SLUG" --jsonpath="$.text"

6. 自动化索引 使用 cron 作业或 systemd 定时器，保持索引最新（参阅定时摄入）。

7. 与 AI 智能体集成

使用内置的 AI 智能体技能 和 OpenCode 智能体配置 进行知识检索。

提示

我强烈建议搭配提供的技能使用 Pi 智能体。即使使用 DeepSeek Flash 等低成本模型，它也能给出更高质量的结果，而不会消耗不必要的 token。同时它还能提高缓存命中率，有助于降低总体成本。

对于 LLM 模型，使用默认或中等思维模式即可获得快速响应。

视频/嵌入内容：NoteBrain CLI 演示

配置

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

关键设置（完整参考）：

vault-path = "/path/to/Second-Brain" vault-name = "Second-Brain" format = "text" # "text", "json", "tsv", "ndjson"

skip-attachments = true # 在图中忽略图片/文件链接 skip-phantom = true # 排除未创建的“幽灵”笔记 respect-exclude = true # 遵循 Obsidian 的忽略规则

数据位置

所有持久化数据存放在 ~/.notebrain/ 下：

路径	内容
~/.notebrain/chroma/	ChromaDB 向量存储（嵌入、元数据、链接图）
~/.notebrain/config/config.toml	用户配置文件

卸载

要完全卸载，请移除 notebrain 二进制文件并删除 ~/.notebrain/。

贡献

欢迎贡献！请在 GitHub 上提交 issue 或 pull request。

该项目使用约定式提交、Go vendor 目录（vendor/）以及通过 Lefthook 配置的 pre-commit 钩子。

许可证

MIT 许可证 — 版权所有 © 2026 nmdra

A Go CLI tool that turns your Obsidian vault into a fully offline knowledge backend for AI coding agents. NoteBrain indexes markdown notes into a local ChromaDB vector database and exposes semantic search, wikilink graph traversal, and hidden connection discovery through structured output — designed to be chained directly by autonomous agents, shell pipelines, and LLM tool-use workflows.

Ships with an AI agent skill and OpenCode Agent Configuration for integration with autonomous coding agents like OpenCode, Google Antigravity, Pi agent, and Claude Code. This setup is specially optimized to reduce token usage and latency.

Note

Hi, I'mNimendra.
I use Obsidian daily as my primary note-taking solution. When AI agents emerged, I wanted to use my Obsidian vault as an RAG system.But most existing solutions don't fulfill my requirements.
While researching, I came across this article, which inspired this project.So I built this for my personal use. While you can use it directly, I highly encourage you to fork and modify this solution for your own use case.

I don't use Windows or macOS, so those versions aren't shipped directly, but you can compile the binary using the source code.

• Semantic Search — Find notes by meaning, not just keywords, using the offline all-MiniLM-L6-v2 ONNX embedding model.
• Multi-Query Search — Search with multiple independent queries to improve retrieval for complex topics and AI agent workflows.
• Knowledge Graph Traversal — Explore your Obsidian wikilink graph through backlinks, multi-hop connections, and shared tag relationships.
• Hidden Connections — Discover semantically related notes that aren't explicitly linked, with optional deep section-level analysis.
• Graph-Boosted Ranking — Improve search relevance by combining semantic similarity with graph relationships.
• Interactive Terminal UI — Browse results with a fuzzy-search interface, plus intelligent guidance when searches return no matches.
• Advanced Filtering — Refine results by sections, tags, code blocks, tasks, and other note metadata.
• Full Note Retrieval — Reconstruct complete notes on demand from indexed content.
• Structured Output — Export results as JSON or TSV, with built-in JSONPath querying for easy automation.
• AI Agent Integration — Includes a built-in AI agent skill and dedicated for autonomous knowledge retrieval.
• Terminal Hyperlinks — Open notes directly from supported terminals using OSC 8 hyperlinks.
• Editor Integration — Open search results instantly in your preferred editor or directly in Obsidian.
• Obsidian-Aware Indexing — Respects your Obsidian configuration, including ignored files, attachment folders, and optional exclusion of empty-note references.

Note: Currently, this tool focuses on Markdown text only and does not support PDF or image OCR.

• Goldmark AST-Aware Chunking — Splits markdown by header hierarchy rather than arbitrary character offsets, strictly preserving lists, GFM tables, blockquotes/callouts, and code blocks.
• Embedded ChromaDB — Stores vectors directly on disk via chroma-go.
• Incremental Ingestion — SHA-256 content hashing skips unmodified notes in milliseconds on re-runs.

See theArchitecture guide for more details.

• Go 1.26.4+
• CGO-enabled toolchain
• Linux (macOS and Windows binaries are untested)

Download a pre-built binary from the GitHub Releases page, or build from source:

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/

See the full Installation Guide for details.

1. Index your vault:

notebrain ingest --vault-path "/path/to/your/Obsidian Vault"

Note: First-time indexing may take several minutes depending on your vault size.

2. Search your notes by meaning:

notebrain search "how do message brokers work?" --limit 5 --top-k 2

3. Discover deep hidden connections across note sections:

Find notes that share similar concepts without direct wikilinks, using --deep chunk-by-chunk section matching (§ <Heading>):

notebrain hidden "TLS" --deep

4. Get structured output for scripts and AI agents:

notebrain search "how do message brokers work?" --limit 2 --top-k 1 --format=json | jq

Example JSON output

5. Chain commands to retrieve full notes:

# Extract slug from top search result
SLUG=$(notebrain search "message broker" --limit 1 --jsonpath="$.results[0].note_slug")

# Retrieve complete reconstructed note text
notebrain get "$SLUG" --jsonpath="$.text"

6. Automate indexing with a cron job or systemd timer so your index stays fresh (see Scheduled Ingestion).

7. Integration with AI Agents

Use the built-in AI agent skill and OpenCode Agent Configuration for knowledge retrieval.

Tip

I highly recommend using the Pi Agent with the provided skill. It delivers higher-quality results, even with low cost models such as DeepSeek Flash, without consuming unnecessary tokens. It also improves cache hit rates, helping reduce overall costs.

For LLM models, use the default or medium thinking mode for fast responses.

NoteBrain reads configuration from a TOML file at ~/.notebrain/config/config.toml (or pass --config=/path/to/config.toml). CLI flags always override TOML values.

Copy the template to get started:

mkdir -p ~/.notebrain/config
cp config.example.toml ~/.notebrain/config/config.toml

Key settings (full reference):

vault-path = "/path/to/Second-Brain"
vault-name = "Second-Brain"
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

All persistent data is stored under ~/.notebrain/:

Path	Contents
~/.notebrain/chroma/	ChromaDB vector store (embeddings, metadata, link graph)
~/.notebrain/config/config.toml	User configuration file

To fully uninstall, remove the notebrain binary and delete ~/.notebrain/.

Contributions are welcome! Please open an issue or pull request on GitHub.

This project uses Conventional Commits, Go vendoring (vendor/), and pre-commit hooks via Lefthook.

MIT License — Copyright © 2026 nmdra