Communitygithub.com

nmdra/notebrain-cli

NoteBrain 是一款高效能 Go CLI 工具,可將您的 Obsidian 筆記庫索引至本機 ChromaDB 向量資料庫,讓 AI 代理能夠智慧探索您的個人知識庫,提供強大的語意搜尋、反向連結遍歷與標籤探索功能。

notebrain-cli 是什麼?

NoteBrain 是一個以 Go 語言開發的命令列工具,專為 AI 代理設計,用於將 Obsidian 筆記庫索引至本機 ChromaDB 向量資料庫。它提供語意搜尋、圖形遍歷、反向連結發現、隱藏關係尋找、完整筆記擷取與標籤分析等功能。支援以 `--format json` 參數輸出結構化 JSON,避免互動式 TUI 造成連線阻塞。AI 代理可透過 `--jsonpath` 參數提取特定欄位,串接多個命令形成自動化管線。`notebrain get` 命令能重建完整筆記文字,`notebrain backlinks`、`notebrain connections` 與 `notebrain hidden` 則分別探索顯式連結與隱含語意關係。此工具無需外部 Docker 容器,資料儲存於 `~/.notebrain/chroma` 嵌入式資料庫,並由作業系統排程器(cron/systemd)每三小時自動重新索引。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

NoteBrain CLI 技能(AI 代理專用)

NoteBrain 是一款高效能 Go CLI 工具,可將 Obsidian 筆記庫索引至本機 ChromaDB 向量資料庫。它提供跨 Markdown 筆記的語意搜尋、圖形遍歷、反向連結發現、隱藏關係尋找、完整筆記擷取與標籤分析。

核心執行原則與理由

為提高效率並避免浪費 token 或導致連線停滯,請遵循以下基本原則:

  1. 僅使用 NoteBrain — 不使用通用檔案搜尋:切勿使用 grep、find、ls 或臨時 shell 腳本直接搜尋筆記庫的 Markdown 檔案來回答使用者問題。NoteBrain 的命令是基於索引後的向量與圖形資料庫專門設計,能產出比檔案系統層級文字搜尋更高品質、更相關的結果。將 notebrain 視為存取筆記庫內容的唯一介面。如果某個 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 筆記文字(將其所有索引區塊拼接在一起),而非猜測區塊索引。切勿直接對底層筆記檔案執行 cat — get 能正確重建片段化的筆記,並反映筆記庫的索引狀態。
  5. 為綜合分析擷取內容(--include-text):預設情況下,search 與遍歷命令只回傳輕量中繼資料信封(標題、檔案路徑、標籤、相似度分數)。每當您的任務需要直接從搜尋結果摘要或推理個別區塊時,請加上 --include-text。回傳的 text 欄位包含保留程式碼區塊的豐富 Markdown,方便直接複製貼上。
  6. 二進位檔路徑與引號處理:在開發環境中,若 notebrain 不在系統 PATH 中,請執行 ./notebrain。筆記標題常包含空格或括號(例如 "Q3 Planning [Draft]"),因此務必將筆記標題、標籤與搜尋查詢都用雙引號括起來。
  7. 內嵌持久儲存:NoteBrain 以內嵌資料庫(~/.notebrain/chroma)執行。無需也不支援獨立的 ChromaDB Docker 容器或 HTTP 伺服器。
  8. 自動化索引:索引由作業系統排程器(cron/systemd 計時器,每三小時執行一次)處理。除非使用者明確要求編輯後立即重新索引,否則您無需在查詢前手動執行 ingest。

命令選擇指南

根據使用者分析目標選擇專門的命令:

使用者意圖命令原因與使用方式
「我的筆記對 X 有什麼看法?」search對所有筆記區塊執行向量相似度搜尋。使用 --tag="TagName" 依標籤過濾。
「讀取筆記 Y 的完整內容」get依 slug 或檔案路徑擷取並重建完整筆記文字與中繼資料。
「哪些筆記直接連結到這篇?」backlinks找出明確指向目標筆記的 [[wikilink]] 參照。
「圖形中結構上鄰近的內容有哪些?」connections在 wikilink 上執行廣度優先搜尋(BFS),最多 --hops N 層。為避免指數爆炸,請保留 --hops 1 或 --hops 2。
「哪些筆記在語意上相關但沒有連結?」hidden找出未連結但語意相似的筆記。對於發現概念橋樑極有價值。
「以筆記 Y 為中心,尋找與 X 相關的概念」boosted結合向量相似度與到 --seed 筆記的圖形鄰近度。
「哪些筆記與 X 共享標籤?」tags分析標籤重疊。在 tags 陣列中回傳潔淨的標籤字串。
「資料庫是否為最新狀態?」stats輸出集合計數(chunks、links)。支援 --format=json 和 --jsonpath。
「索引或重新索引筆記庫」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 與 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一律來自 frontmatter 或檔案名稱的筆記標題。
file_path一律筆記庫內的相對路徑。
score一律搜尋時的相似度分數(0–1);連線時的跳數。
chunk_index搜尋、hidden、boosted匹配的是筆記的第幾個區塊(從 0 開始)。
tags當筆記有標籤時標籤字串陣列。
heading_path當區塊位於某標題之下階層路徑,例如 "Section > Subsection"。
text當傳入 --include-text 時匹配區塊的完整 Markdown 文字,保留程式碼區塊。
context當 --context-window N > 0 時前後 ±N 個相鄰區塊文字(依區塊索引排序)的陣列。
extraconnections、tags、boosted命令特定資訊(例如 "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 1 --format json

相關技能