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 output — designed to be chained directly by autonomous agents, shell pipelines, and LLM tool-use workflows.

Ships with an AI agent skill for integration with Agents like Google Antigravity, Pi agent and Claude Code.This skill is specially optimized to reduce token usage and latency.

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+
• CGO-enabled toolchain
• 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 inference.
• Multi-Query Support — Search using multiple queries. This enables AI agents to search more accurately by separating searches that contain distinct topics.
• 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. 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).
• AI Agent Skill — Ships with a built-in AI agent skill (.agents/skills/notebrain/) for autonomous knowledge retrieval (see AI Agent Skill Usage).
• 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.

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

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.

See the Architecture guide for more details.

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"

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