2ndbrain

2ndbrain

[](LICENSE) [](https://github.com/apresai/2ndbrain/releases) [](https://github.com/apresai/homebrew-tap)

AI companion for your Obsidian vault with semantic search. A Go CLI, MCP server, and native macOS dashboard share a SQLite index, making your knowledge base searchable by both you and your AI coding assistant. Obsidian stays your editor; 2ndbrain is the engine that indexes, searches, and answers underneath it.

Install

brew install --cask apresai/tap/secondbrain

This installs both the 2nb CLI and the SecondBrain macOS dashboard app. If you only need the CLI:

brew install apresai/tap/2nb

Or download from GitHub Releases: the CLI as a tar.gz, and the app as a branded drag-to-Applications .dmg.

The app and its .dmg are both Developer ID-signed, Apple-notarized, and stapled, so it launches with no Gatekeeper prompt — whether installed via the cask or by downloading the disk image directly.

New here? Follow the [Quick Start guide](docs/quick-start.md) for the full walkthrough: app, Obsidian plugin, AI setup, and first search.

Quick Start

The complete walkthrough (macOS app, Obsidian plugin, AI providers, MCP) lives in [docs/quick-start.md](docs/quick-start.md). The CLI fast path:

# Point 2nb at your existing Obsidian vault (or scaffold a fresh one)
2nb vault set ~/path/to/your-obsidian-vault
2nb vault create ~/vault                      # only for a brand-new vault

# Configure AI for semantic search & ask
2nb ai setup

# Index with AI embeddings (safe to run repeatedly)
2nb index

# Search (hybrid BM25 + semantic)
2nb search "authentication"
2nb search "how does auth work" --type adr

# Ask questions (RAG with source citations)
2nb ask "What authentication approach did we choose and why?"

# Check vault health any time
2nb vault

# One-time: enable shell tab-completion (zsh)
2nb completion install

> The legacy 2nb init command still works (it prints a deprecation notice). Prefer 2nb vault create . > > Homebrew installs shell completions automatically. For manual installs, 2nb completion install detects your existing completion directory from .zshrc (falling back to ~/.zsh/completions/_2nb) and updates .zshrc with the required fpath and compinit block. The block is placed before early-return guards and before any existing compinit/fpath setup (e.g. from gcloud or Homebrew), so completions load correctly even when other tools initialize the completion system first. Re-running is safe — the block is replaced in-place, not duplicated. If multiple 2nb binaries are found on PATH, a warning is printed showing each binary's version and which is active.

Features

• Hybrid search — BM25 keyword + vector semantic search with Reciprocal Rank Fusion
• RAG Q&A — Ask questions, get answers with source citations
• MCP server — 22 tools for Claude Code, Cursor, and any MCP client, with live status sidecar files and an observability panel
• Suggest Links — AI finds semantically related documents in your vault and proposes wikilinks to insert
• Polish — AI copy-editor that fixes spelling, grammar, and clarity, repairs broken [[wikilinks]] to existing notes (case/separator/whitespace/alias drift, never guessing an ambiguous target), and adds grounded new links (never inventing a target). Returns the original and polished text together so any client can show a diff; the Obsidian plugin applies it in one click from the note toolbar, ribbon, command, or right-click menu, with an Undo button
• Vault health dashboard — unified panel showing index state, embedding portability, stale docs, and provider reachability with one-click Sync and Re-embed All. Notes edited in Obsidian are re-indexed and re-embedded automatically (a debounced incremental index), so search and AI stay current without a manual rebuild. When an upgrade improves how 2nb chunks or embeds your notes, vault status (and the app/plugin) prompt you to reindex or re-embed so your existing vault picks up the improvement — always a prompt, never an automatic re-embed
• Built-in installer: the dashboard updates the CLI (brew upgrade behind an Update CLI button) and installs or updates the Obsidian plugin into the bound vault (2nb plugin install behind an Install/Update button)
• AI Clients card: per-client rows for Claude Code, Warp, Claude Desktop, and Codex — each showing whether the skill is installed, whether the 2ndbrain MCP server is configured, and (for Claude Code / Claude Desktop) whether the global-instructions block is present, with a one-click Configure button (runs 2nb setup --client …, backup-safe) so you can wire up any assistant at a glance
• AI connection testing — one-click probe of your configured embedding and generation models with live latency
• Incremental re-embed — 2nb index rebuilds embeddings only for documents whose content hash changed
• Git integration (read-only) — Recent Activity panel with per-commit file diffs in the dashboard, plus MCP git tools for AI clients
• Skill files — One command to teach 8 AI coding agents about your vault
• Three AI providers — AWS Bedrock, OpenRouter, Ollama (fully local)
• Schema validation — Typed frontmatter, enum constraints, status state machines
• Wikilinks — [[target#heading|alias]] with link resolution and graph traversal
• Broken-link resolution, no dead ends — 2nb lint and the dashboard's Validation tab don't just flag broken [[wikilinks]]; every finding is resolvable: repair case/separator drift to the right note, pick a "did you mean?" suggestion (suggest-target → relink), create the missing note, or unlink it (keeping the text) — with a one-click bulk Repair drift links for a whole batch
• Document templates — ADR, runbook, prd, prfaq, postmortem, note with enforced schemas
• Native macOS dashboard — SwiftUI + AppKit companion app for vault health, AI configuration, plugin install, MCP monitoring, and git activity; Obsidian remains the editor
• Local-first — All data on disk as plain markdown in your Obsidian vault. 2nb writes only a gitignored .2ndbrain/ sidecar and never rewrites a note's body except via explicit, user-invoked commands (append, prepend, replace); frontmatter edits via meta have always rewritten files in place.

AI Providers

2ndbrain supports three AI providers for embeddings and generation. Most Bedrock models run through the Converse API (Claude, Nova, Llama, Mistral, and more); partner-hosted frontier models on the newer Bedrock "mantle" plane (openai.gpt-5.5, xai.grok-4.3) run over its OpenAI-compatible REST API and need a Bedrock API key (bearer token), set via 2nb config set-key bedrock.

| Provider | Embeddings | Generation | Setup | |----------|-----------|------------|-------| | AWS Bedrock | Nova Embeddings v2 | Nova Micro, Claude, Llama, any model | Uses existing AWS SSO — zero new keys | | OpenRouter | Nemotron Embed (free) | Gemma 4 31B (free), GPT-4o, Claude, etc. | OPENROUTER_API_KEY env var | | Ollama | nomic-embed-text | qwen2.5, gemma3, llama3 | brew install ollama — fully local | | llama-local (experimental, CLI-only) | EmbeddingGemma 300M | Gemma 4 E2B / E4B | fully offline via llama.cpp; needs llama-server on PATH (brew install llama.cpp) since the engine isn't bundled yet. Hidden in the app until it is. |

Quick Setup (Any Provider)

The setup wizard detects credentials and offers recommended defaults:

2nb ai setup
# → Pick provider (Bedrock / OpenRouter / Ollama)
# → Easy mode: recommended models, or Custom: pick from catalog
# → Tests connectivity, saves config, offers to index

Local AI with Ollama

Run everything locally with no cloud calls:

# Check readiness (models, disk, RAM)
2nb ai local

# Guided setup (installs models, configures vault)
2nb ai setup

# Or configure manually
2nb config set ai.provider ollama
ollama pull embeddinggemma
ollama pull qwen2.5:0.5b
2nb index

AWS Bedrock (Default)

Uses your existing AWS SSO credentials — no new API keys needed:

2nb ai status
2nb config set ai.bedrock.profile my-profile
2nb config set ai.bedrock.region us-west-2

OpenRouter

export OPENROUTER_API_KEY=sk-or-...
2nb config set ai.provider openrouter
2nb index

Model Catalog & Benchmarking

Browse verified models across all providers, test any model, and benchmark your favorites:

# See all verified models with pricing
2nb models list

# Discover vendor catalogs (Bedrock, OpenRouter, Ollama)
2nb models list --discover

# Check credentials and reachability
2nb models list --status

# Test if a model works before switching (--save adds it to your catalog)
2nb models test amazon.nova-micro-v1:0 --save
2nb models test google/gemma-4-31b-it:free

# Discover and auto-promote all passing models in one step
2nb models list --discover --promote

# Benchmark your favorites
2nb models bench fav amazon.nova-micro-v1:0
2nb models bench fav us.anthropic.claude-haiku-4-5-20251001-v1:0
2nb models bench                  # runs embed/generate/search/rag probes
2nb models bench compare          # side-by-side latency leaderboard
2nb models bench history          # view past runs

# End-to-end wizard: discover → pick → cost preview → test → save
2nb models wizard                 # TTY interactive flow
2nb models wizard --json          # JSON-event stream (GUI / automation)
2nb models wizard --set-active    # also write the chosen models into the vault config

# Estimate before you run
2nb models cost-preview us.anthropic.claude-opus-4-6-v1 --probe bench_rag

# Hide a model from selection dropdowns without removing it from the catalog
2nb models disable cohere.embed-multilingual-v3 --provider bedrock --scope vault
2nb models enable  cohere.embed-multilingual-v3 --provider bedrock --scope vault

Models are tiered as verified (tested with 2nb) or unverified (available from vendor, use models test to check). The benchmark suite stores results in .2ndbrain/bench.db for tracking performance over time.

Every catalog entry declares an invoke_strategy (e.g. bedrock_converse, bedrock_invoke_cohere_embed, openrouter_chat) so adding a new model variant doesn't require a code change — a catalog entry with the right strategy is enough. The macOS dashboard's AI → AI… opens the AI Hub — a single sheet with provider cards (enable / disable Bedrock, OpenRouter, Ollama), active model status, and the full catalog with inline Test / Set active / Enable / Disable / Discover actions. Catalog changes written by the CLI propagate to the running GUI via FSEvents without reopening the vault.

CLI Commands

Commands are organized into groups (2nb --help shows the full list).

Global flags: --json, --csv, --yaml, --format (json/csv/tsv/yaml/raw/md/text; listings also paths/tree), --porcelain, --vault, --unconfigured (permit a write to a vault Obsidian doesn't know — without it such a write is refused), --copy (also copy output to the clipboard), --verbose (-v for debug logging to stderr and .2ndbrain/logs/cli.log)

Getting Started

| Command | Description | |---------|-------------| | vault | Health report for the active vault (same as vault status) | | vault create | Initialize a new vault (open it in Obsidian to use it; 2nb follows your open Obsidian vault) | | vault set | Register an existing vault in recents (the active vault follows Obsidian) | | vault list | List recently used vaults | | vault show | Terse summary: path, source, name, doc count | | init [path] | Deprecated alias for vault create |

Documents

| Command | Description | |---------|-------------| | create [--type adr\|runbook\|prd\|prfaq\|postmortem\|note] [--path ] [--content ] [--overwrite\|--append] | Create document from template. --path files it under a vault-relative subdirectory (created if missing); default is the vault root. --content sets the initial body instead of the type template. --overwrite replaces an existing same-title note in place (keeps its id); --append appends to it (else creates) | | read [--chunk ] | Read document or specific section. Alias: print | | append [--text \| --file \| stdin] | Append content to a document's body. Explicit, opt-in body write; frontmatter is left untouched | | prepend [--text \| --file \| stdin] | Insert content at the start of a document's body, after the frontmatter | | replace [--section ] [--text \| --file \| stdin] | Replace the whole body, or just one heading's section content with --section (first match wins on duplicate headings) | | daily | Resolve today's daily note from Obsidian's daily-notes config (.obsidian/daily-notes.json), create it if missing, and print the path (daily path is the explicit subcommand form). daily read prints its body; daily append/daily prepend [--text \| --file \| stdin] add to it. Falls back to Obsidian defaults (root folder, YYYY-MM-DD) when the plugin is disabled or unconfigured; the date format honors Moment [literal] escaping | | meta [--set key=value] [--get ] [--remove ] | View frontmatter, or --set to write, --get to read one field (exit 1 if absent), --remove to delete a field in place (preserves comments/order; refuses identity and schema-required keys). Array fields (tags, aliases, schema list/tags fields) are coerced to a YAML list, comma-split, replace semantics (--set tags=a,b); use tag add/tag remove for incremental edits. Aliases: frontmatter, fm, properties | | delete [--force] | Delete document from vault and index | | move [--dry-run] [--force] | Move/rename a note to a new vault-relative path, rewriting every [[wikilink]] AND markdown-style [text](path.md) link across the vault that points at it (preserving heading/block/alias/embed suffixes on wikilinks, the label text + #anchor/?query suffix + .md extension on markdown links, and the bare-vs-path form; external-URL and anchor-only markdown links are skipped; links inside code are untouched). --dry-run previews the rename, per-note rewrites, and ambiguous skips without writing; without --force a bare-name-ambiguous move is refused. The target file moves LAST for crash safety | | rename [--dry-run] [--force] | Rename a note in place (same folder, .md appended if omitted), delegating to move | | list [--type] [--status] [--tag] [--sort] | List documents with filters | | tasks [--done] [--todo] [--path ] | List GFM checkbox tasks (- [ ] / - [x]) across the vault. v1 is GFM open/done only (custom statuses like [>]/[-] are ignored) | | task [--done \| --todo \| --toggle] | Toggle a single GFM checkbox at a 1-based body line (default toggle). Errors if the line is not a checkbox; frontmatter is left untouched |

Search & AI

| Command | Description | |---------|-------------| | search [--type] [--status] [--tag] [--threshold] | Hybrid BM25 + semantic search (shows rrf + raw cos scores) | | ask [--history ] | RAG Q&A with source citations; --history makes it multi-turn | | chat | Interactive multi-turn Q&A session (REPL over the same pipeline) | | suggest-links [--limit 10] | Rank semantically related documents for wikilink insertion | | polish [--system ] [--write] [--links] [--repair-links] [--undo] [--force] | AI copy-edit a document (JSON with original + polished body). --links adds grounded [[wikilinks]] to existing notes (never invents a target). --repair-links repairs broken [[wikilinks]] to existing notes (case, separator (hyphen/underscore vs space), whitespace, and alias drift; ambiguous or unmatched targets reported, never guessed). --write applies the po

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: apresai
• Source: apresai/2ndbrain
• License: MIT
• Homepage: https://github.com/apresai/2ndbrain

Install and usage instructions live in the source repository linked above.