notebrain-cli

README

NoteBrain CLI

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 JSON output — designed to be chained directly by autonomous agents, shell pipelines, and LLM tool-use workflows.
Ships with a built-in AI agent skill for integration with assistants like Google Antigravity and Pi agent.

[!NOTE] Hi, I'm Nimendra.
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.

Prerequisites

• Go 1.26.4+ (for building from source)
• CGO-enabled toolchain — GCC or Clang on Linux/macOS (the embedded vector store uses C/C++ bindings via SQLite and HNSW)
• ~33 MB disk for the ONNX embedding model (auto-downloaded on first run)
• Linux (macOS and Windows binaries are untested)

Features

• Semantic Search — Find notes by meaning, not just keywords. Uses the all-MiniLM-L6-v2 ONNX model for fully offline, on-device inference.
• Graph Traversal — Walk your Obsidian wikilink graph ([[Note]]) via BFS: backlinks, connections (multi-hop), tags (shared tag neighbors).
• Hidden Connections — Discover notes that are semantically similar but not explicitly linked.
• Graph-Boosted Search — Combine semantic similarity scores with structural graph proximity for richer results.
• Interactive TUI — Navigate search results with fuzzy-finding, arrow keys, and live ingestion progress. Powered by Bubble Tea.
• Advanced Filtering — Narrow searches by --section, --has-code, --has-tasks, or --tag.
• Full Note Retrieval — Reconstruct complete note content on the fly from indexed chunks (notebrain get).
• Machine-Readable Output — Structured JSON, TSV via --format flags, plus built-in --jsonpath extraction (no jq needed).
• OSC 8 Hyperlinks — Clickable obsidian://open links directly in your terminal. Works in alacritty, WezTerm, kitty and others supporting the OSC 8 spec.
• Editor Integration — Open matched notes in $EDITOR or Obsidian directly from the TUI.
• Obsidian-Aware Ingestion — Honors userIgnoreFilters and attachmentFolderPath from your Obsidian config. Optionally skip phantom links and attachment references.

Under the Hood

• Goldmark AST-Aware Chunking — Splits markdown by header hierarchy rather than arbitrary character offsets, preserving code blocks and structural metadata.
• Embedded ChromaDB — Stores vectors directly on disk via chroma-go v0.4.x (no external database server required).
• Incremental Ingestion — SHA-256 content hashing skips unmodified notes in milliseconds on re-runs.
• AI Agent Skill — Ships with a built-in AI agent skill (.agents/skills/notebrain/) for autonomous knowledge retrieval (see AI Agent Skill Usage).

Installation

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.

Quick Start

1. Index your vault:

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

2. Search your notes by meaning:

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

3. 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

4. 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"

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

Configuration

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 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

Data Location

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/.

Documentation

Guide	Description
Installation	Prerequisites, pre-built binaries, building from source
Commands Reference	Full CLI command and flag documentation
Architecture	Internals: chunking pipeline, embedding, ChromaDB schema
Scheduled Ingestion	Cron and systemd timer setup for background indexing
AI Agent Skill Usage	Using the built-in AI agent skill for autonomous retrieval
DeepWiki	AI-generated codebase documentation

Contributing

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.

License

MIT License — Copyright © 2026 nmdra

Documentation

Overview

Copyright © 2026 nmdra

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.