# 2ndbrain > AI-native markdown knowledge base with semantic search, RAG, and MCP server - **Type:** MCP server - **Install:** `agentstack add mcp-apresai-2ndbrain` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [apresai](https://agentstack.voostack.com/s/apresai) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [apresai](https://github.com/apresai) - **Source:** https://github.com/apresai/2ndbrain - **Website:** https://github.com/apresai/2ndbrain ## Install ```sh agentstack add mcp-apresai-2ndbrain ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 ```bash brew install --cask apresai/tap/secondbrain ``` This installs both the `2nb` CLI and the SecondBrain macOS dashboard app. If you only need the CLI: ```bash brew install apresai/tap/2nb ``` Or download from [GitHub Releases](https://github.com/apresai/2ndbrain/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: ```bash # 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](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-call.html) (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: ```bash 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: ```bash # 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: ```bash 2nb ai status 2nb config set ai.bedrock.profile my-profile 2nb config set ai.bedrock.region us-west-2 ``` ### OpenRouter ```bash 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: ```bash # 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](https://github.com/apresai) - **Source:** [apresai/2ndbrain](https://github.com/apresai/2ndbrain) - **License:** MIT - **Homepage:** https://github.com/apresai/2ndbrain Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** yes - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-apresai-2ndbrain - Seller: https://agentstack.voostack.com/s/apresai - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.