NoteBrain is a Go CLI tool. It makes your Obsidian vault a fully offline knowledge backend for AI coding agents. NoteBrain indexes markdown notes and PDFs into a local ChromaDB vector database. It provides semantic search, wikilink graph traversal, and hidden connection discovery. It gives structured output. AI agents, shell pipelines, and LLM tool workflows can use this output directly.
NoteBrain includes an AI agent skill and an OpenCode Agent Configuration. You can use them to integrate with autonomous coding agents (for example, OpenCode, Pi agent, and Claude Code). This setup decreases 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.
- Semantic Search: Find notes by meaning with the offline
all-MiniLM-L6-v2ONNX embedding model. - Multi-Query Search: Do a search with multiple independent queries. This gives better results for complex topics.
- Knowledge Graph Traversal: Examine your Obsidian wikilink graph. Find backlinks, multi-hop connections, and shared tags.
- Hidden Connections: Find notes that have a semantic relationship but no explicit links. You can use deep section-level analysis.
- Graph-Boosted Ranking: Combine semantic similarity with graph relationships for better search results.
- Advanced Filtering: Filter results by sections, tags, code blocks, tasks, and other metadata.
- Full Note Retrieval: Get the complete note from the indexed content.
- Structured Output: Export results as JSON or TSV. Use built-in JSONPath queries for automation.
- AI Agent Integration: NoteBrain has a built-in AI agent skill for autonomous knowledge retrieval.
- Terminal Hyperlinks: Use OSC 8 hyperlinks to open notes from supported terminals.
- Obsidian-Aware Indexing: NoteBrain obeys your Obsidian configuration. It ignores excluded files and attachment folders.
- Optional PDF Support: Get text from PDFs. NoteBrain uses an LLM API to read scanned documents.
- Shell Completion: Tab completion for bash, zsh, and fish. It completes commands, flags, and note slugs from your index.
- PDF Support: NoteBrain extracts text from PDFs with PDFium-go. It converts the raw text into structured Markdown with an LLM API. The API supports OpenRouter, DeepSeek, OpenAI, Gemini, and local Ollama. This makes chunks that match native markdown notes.
- Goldmark AST-Aware Chunking: NoteBrain splits markdown by header hierarchy. It preserves lists, GFM tables, blockquotes, callouts, and code blocks.
- Embedded ChromaDB: NoteBrain writes vectors to the disk with
chroma-go. - Incremental Ingestion: NoteBrain calculates SHA-256 content hashes. It ignores unmodified notes in milliseconds during subsequent runs.
Read the Architecture guide for more information.
- Go 1.26.4+
- A CGO-enabled toolchain.
- Linux. NoteBrain does not test macOS and Windows binaries.
- Download a pre-built binary from the GitHub Releases page.
- Or build the binary from the source code:
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/Read the Installation Guide for full instructions.
1. Initialize your configuration:
notebrain initThis command starts an interactive wizard. The wizard configures your vault path and PDF settings.
2. Index your vault:
notebrain ingest
# To index PDFs, you must provide an LLM model and an API key (DEEPSEEK_API_KEY, OPENROUTER_API_KEY, etc.):
# OPENROUTER_API_KEY="sk-or-..." notebrain ingest --enable-pdf --llm-model "tencent/hy3"Note: The first indexing operation takes several minutes. The time depends on your vault size and the quantity of PDFs.
3. Search your notes by meaning:
notebrain search "how do message brokers work?" --limit 5 --top-k 2
# Include PDF results in search:
notebrain search "message broker" --with-pdf
4. Discover deep hidden connections across note sections:
Find notes that share concepts but have no direct wikilinks. Use --deep for chunk-by-chunk section matching (§ <Heading>):
notebrain hidden "TLS" --deep
5. Get structured output for scripts and AI agents:
notebrain search "how do message brokers work?" --limit 2 --top-k 1 --format=json | jqExample JSON output
6. 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"7. Automate indexing: Set a cron job or systemd timer to keep your index current. Read Scheduled Ingestion.
8. Integration with AI Agents: Use the built-in AI agent skill and OpenCode Agent Configuration to retrieve knowledge.
Tip
Use the Pi Agent with the provided skill. The agent gives better results with low-cost models (for example, DeepSeek V4 Flash, tencent hy3, or Gemini Flash 3.6). It does not consume unnecessary tokens. It increases cache hit rates and decreases costs.
For LLM models, use the medium or low thinking mode to get fast responses.
NoteBrain uses a TOML file for configuration at ~/.notebrain/config/config.toml. You can also supply --config=/path/to/config.toml. CLI flags always override TOML values.
To start, copy the template:
mkdir -p ~/.notebrain/config
cp config.example.toml ~/.notebrain/config/config.tomlKey configuration values (read the full reference):
vault-path = "/path/to/Second-Brain"
vault-name = "Second-Brain"
format = "text" # "text", "json", "tsv"
debug = false # enable debug logging to stderr
respect-exclude = false # honor Obsidian's ignore rules
show-tags = false # include tag names in outputNoteBrain stores persistent data in ~/.notebrain/:
| Path | Contents |
|---|---|
~/.notebrain/chroma/ |
ChromaDB vector store (embeddings, metadata, link graph) |
~/.notebrain/config/config.toml |
User configuration file |
To uninstall NoteBrain, remove the notebrain binary and delete the ~/.notebrain/ directory.
| Guide | Description |
|---|---|
| Installation | Prerequisites, pre-built binaries, and compilation commands |
| Commands Reference | Full CLI command and flag information |
| Architecture | Internal functions: chunking pipeline, embeddings, and ChromaDB schema |
| Ranking | How NoteBrain ranks search and hidden connection results |
| PDF Ingestion | LLM-based text extraction from PDF attachments |
| Scheduled Ingestion | Instructions for cron and systemd timers to index data in the background |
| Shell Completion | Tab completion setup for bash, zsh, and fish |
| AI Agent Skill Usage | Instructions for the built-in AI agent skill |
| OpenCode Agent Integration | Configuration for NoteBrain as an OpenCode AI coding assistant |
| Pi Agent Integration | Run the Pi agent in a notebrain-only mode against the vault |
| DeepWiki | AI-generated codebase documentation |
We welcome contributions. Open an issue or a pull request on GitHub.
This project uses Conventional Commits, Go vendoring (vendor/), and pre-commit hooks with Lefthook.
MIT License — Copyright © 2026 nmdra