2ndbrain

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

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 gets exactly one machine recommendation (suggest-target --verdict, prompt selected by a measured eval — see docs/link-prompt-eval.md): repair case/separator drift, relink to a "did you mean?" pick (source-note context + --llm re-rank), or remove the dead link when nothing matches confidently (the model's explicit decline is the removal signal). Fix all applies only high-confidence rewrites (drift + high); Remove dead links batches the removal-recommended ones behind a pre-checked confirm; everything else surfaces top 2-3 recommendations for a human pick, with create-the-note always available
• 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.

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

Documents

Search & AI

Git (read-only)

Quality

Integration

Import / Export

Configuration

All commands support --json, --yaml, --csv, --tsv for machine-readable output, plus --format raw/md to emit a document body (or any Serialize()-able value) verbatim, --format text for plain text, and (on listings) --format paths/tree and --total. --copy also writes a command's rendered output to the clipboard (macOS pbcopy): read/print, meta --get, and daily copy in their default output; any command run with a machine format copies that output.

Obsidian-CLI syntax compatibility. 2nb accepts obsidian-CLI-style invocations as a drop-in scripting replacement for the headless file/markdown layer. The full mapping table, accepted argument forms, and intentional non-goals live in docs/obsidian-cli-mapping.md. It understands key=value arguments (file=, path=, content=, template=, query=, vault=, old=/new=, etc.), boolean tokens (total, append, overwrite, done/todo), colon-commands (daily:path/daily:append, property:set → meta, tags:rename → tags rename, tag:add/tag:remove → tag add/tag remove, link:unresolved), and command aliases (print → read; fm/frontmatter/properties → meta; files → list; search-content → keyword search; list-vaults/set-default-vault/add-vault → the vault subcommands). file= resolves a target by exact path, then basename/title/alias/shortest-unique suffix (failing loudly on ambiguity); path= is a strict exact path. A free-text search/ask query that contains = is preserved (never parsed as a parameter), and an unrecognized key=value passes through unchanged.

Defaults and search scoring

• Parent-command defaults: running a command group without a subcommand invokes its most-useful read-only action: 2nb ai → ai status, 2nb models → models list, 2nb git → git status, 2nb mcp → mcp status, 2nb plugin → plugin status, 2nb skills → skills list, 2nb config → config show. --help still works on every command.
• Similarity threshold — hybrid search drops vector hits whose cosine similarity is below the active threshold so barely-related neighbors stop padding result lists. Resolution order: explicit vault config (2nb config set ai.similarity_threshold 0.25) > user calibration saved by 2nb models calibrate --save > per-model recommendation from the builtin catalog > global default 0.20. Builtin recommendations: Nova-2 0.25 (measured; queries embed with Nova's asymmetric GENERIC_RETRIEVAL purpose, which collapses the cosine scale — see CLAUDE.md), Nemotron 0.60, nomic-embed-text/Titan-v2/Cohere-embed 0.50, mxbai/snowflake/bge-m3 0.55, all-minilm 0.35 (all estimated from each model's training objective — run 2nb models calibrate to tune for your vault). Override per-query with 2nb search "foo" --threshold 0.35. 2nb ai status shows the active value and which tier supplied it.
• Calibration — 2nb models calibrate samples random chunk pairs from your vault, reports the noise-floor cosine distribution (p50/p90/p95/p99), and recommends a threshold. Add --save to persist it to the per-vault user catalog (or --save --scope global for all vaults).
• Score display — 2nb search now shows (rrf=X.XXX, cos=Y.YYY) on each result. The rrf is the Reciprocal Rank Fusion score used for ranking; cos is the raw cosine similarity from the vector channel, which is what you actually want to look at when judging whether a result is relevant. If legitimate matches are being cut, lower the threshold; if noise is slipping through, raise it.
• Hybrid weighting — 2nb config set ai.vector_weight 1.5 (or ai.bm25_weight) biases the RRF fusion toward semantic or keyword recall. Both default to 1.0 (equal-weight RRF); raise ai.vector_weight to lean on the vector channel, ai.bm25_weight for exact-term-heavy vaults.
• RAG context — ask feeds the full matching note(s) to the model (parent-document retrieval), so an answer in a section deep in a long note isn't truncated away; a note is only windowed around the matched section when it exceeds the budget. Tune with 2nb config set ai.rag_context_budget <runes> (total, default 60000) / ai.rag_note_budget (per note, default 20000).

Portable vaults

A vault is self-describing. Paths in the index are relative, IDs are UUIDs, and embeddings live in the DB as raw float32 BLOBs — you can tar a vault and open it on another machine without any migration step.

If the receiver's current AI provider doesn't match what produced the embeddings, 2nb ai status tells you exactly what's wrong:

Vault Embedding State:
  As-embedded:    amazon.nova-2-multimodal-embeddings-v1:0 (1024d), 42 of 42 docs
  Current cfg:    ollama / nomic-embed-text (768d)
  Status:         DIMENSION BREAK
  Action:         Vault was embedded with 1024d vectors but current provider produces 768d.
                  Run `2nb index --force-reembed` or switch provider back.

2nb search and 2nb ask fail loudly (stderr + BM25 fallback) on dimension mismatch instead of silently returning worse results. The macOS app surfaces the same warnings as a yellow banner over search results and the Ask AI panel, and the status bar AI dot turns yellow.

Shipping a vault:

tar czf vault.tar.gz \
  --exclude='.2ndbrain/logs' \
  --exclude='.2ndbrain/recovery' \
  --exclude='.2ndbrain/mcp' \
  --exclude='.2ndbrain/bench.db' \
  my-vault/

Include .2ndbrain/config.yaml and .2ndbrain/index.db — the receiver gets the vault's as-embedded state and avoids re-embedding from scratch. For git-shared team vaults, 2nb vault create writes a .gitignore that excludes personal/local state (config, DBs, logs, recovery) and commits only schemas.yaml. Missing or corrupt config.yaml / index.db self-heal on next open with a one-line stderr warning — the vault never bricks.

Heads-up for scripters: 2nb search --json and 2nb ask --json now return envelopes ({mode, warnings, results} / {mode, warnings, answer, sources}; multi-turn asks via --history add rewritten_query). If you were parsing a raw array/object, extract .results / .answer.

MCP Server

The MCP server exposes 22 tools for AI coding assistants:

move/rename (the wikilink-rewriting vault mutation) is intentionally CLI-only: the highest-blast-radius write stays behind 2nb move/2nb rename with their mandatory --dry-run preview rather than an MCP tool.

Each running 2nb mcp-server writes a sidecar status file to .2ndbrain/mcp/<pid>.json with PID, start time, parent PID, and the last 50 tool invocations. Run 2nb mcp status to list live servers, or use the Cmd+Shift+M status panel in the dashboard.

The easy way: 2nb setup --client claude-code (or claude-desktop, warp, codex, or --all) installs the skill and writes the MCP config for you, backing up any existing file and preserving your other servers. 2nb mcp install --client <name> writes just the MCP entry. The manual snippets below are a fallback.

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "2ndbrain": {
      "command": "2nb",
      "args": ["mcp-server"],
      "cwd": "/path/to/your/vault"
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "2ndbrain": {
      "command": "2nb",
      "args": ["mcp-server"],
      "cwd": "/path/to/your/vault"
    }
  }
}

Claude Desktop

2nb setup --client claude-desktop (or mcp install --client claude-desktop) writes this for you. Claude Desktop is a GUI app launched with a minimal PATH, so the command must be an absolute 2nb path and must NOT include a cwd or url field (a url field silently corrupts the file). Restart Claude Desktop to apply.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "2ndbrain": {
      "command": "/opt/homebrew/bin/2nb",
      "args": ["mcp-server", "--vault", "/path/to/your/vault"]
    }
  }
}

Codex

2nb mcp install --client codex (or 2nb setup --client codex) runs codex mcp add so Codex manages its own ~/.codex/config.toml — no manual edit. If the codex CLI isn't installed, the command prints the exact codex mcp add line and the [mcp_servers.2ndbrain] TOML to paste.

Run `2nb m