Neuro Vault MCP

🧠💾 Make your personal vault usable by agents. Low-token retrieval, explicit provenance, and safe writes for your Obsidian notes — in Claude Code, Cursor, Windsurf, and any MCP client.

Neuro_Vault.1.mp4

Your second brain stops being a folder you open between contexts and becomes a first-class participant in every project. Agents can recall the right notes, inspect the evidence, and write back through vault-aware operations — without grepping the whole folder or flooding the context window.

"What did I write about that idea last month?" — and now your assistant can actually answer.

---

✨ Why Neuro Vault?

• 🧠 Hybrid search that already knows your vault — a semantic leg reuses Smart Connections embeddings (no re-indexing, no API keys), and a lexical leg catches exact names, codes, and terms embeddings miss. One call, both answers; a note hit by both is the strongest relevance signal.
• 🎯 Quick or deep, your call — effort: "quick" for fast direct lookups, effort: "deep" for exploration with related-note expansion; mode: "lexical" when you want exact text matching only (works even without embeddings).
• 🧾 Context with provenance, not mystery memory — results come back with paths, matched queries, block-level snippets, and backlink counts so the assistant can show where an answer came from.
• 🧭 A real navigation toolkit for your agent — instead of grepping files and opening notes one by one, your assistant walks the vault like a database: filter by tags and properties, batch-read metadata, traverse the wikilink graph, discover the structure, jump to semantic neighbours.
• 🔎 Ask structured questions in plain language — "active projects tagged #ai", "todo tasks with a deadline this week", "meeting notes from Work/ newest first" — one call, ranked answer, no chains of reads.
• ✍️ Full write surface for your notes — create, in-place replace, or rewrite the whole body; manage frontmatter, tags, and daily notes. Every write goes directly to disk — no Obsidian installation or running instance required; if you have Obsidian open, its own file watcher picks up the change on its usual cadence.
• ⚡ Zero infrastructure — local stdio MCP server, in-memory index, no database, no background processes, no watchers.
• 🔌 Drop-in for any MCP client — Claude Code, Cursor, Windsurf — configuration is a single JSON block.

---

🧰 Two superpowers, one server

Most "vault MCP" servers give you one or the other. Neuro Vault gives you both, and lets your assistant pick the right one per question:

	🔭 Hybrid recall	🛠 Vault operations
What it does	Finds notes by meaning and by exact wording — semantic + lexical legs in one response. Surfaces neighbours and duplicates.	Reads, writes, edits notes (in-place replace and full-body rewrite); manages frontmatter, tags, daily notes.
Best for	"What did I think about X?", fuzzy recall, exploratory research — and exact names, codes, terms the embeddings don't know.	Structured queries, capturing decisions, updating tasks, batch reads.
Powered by	Smart Connections embeddings (already in your vault) + direct text matching over titles, headings, and bodies (no index needed).	Direct reads and writes against the vault directory on disk — no Obsidian install or running instance needed.

The two work together: hybrid search finds the right region of the vault, vault operations let the assistant actually do something with what it found.

---

✨ What it looks like in practice

Before: "Could you check my notes about that LangGraph experiment?" → Assistant lists Notes/, opens 12 files, greps for "LangGraph", gives up halfway, you paste the relevant note manually.

After: "Could you check my notes about that LangGraph experiment?" → One hybrid search — semantic matches plus exact "LangGraph" hits in the same response — follow-up question already grounded in your own writing.

A few more questions Neuro Vault makes one-shot:

"What are my active projects tagged #ai with a deadline this quarter?" "Show meeting notes from Work/ from the last two weeks, newest first." "Find notes similar to this one I'm reading." "Append today's decision to the daily note." "What's on my agenda today — and what did I capture in other notes since this morning?" "What did past-me write about retrieval policy before I started building it?"

One question, one answer. Your assistant stops being a file browser and starts being an actual second brain.

→ See docs/guide/finding-notes.md for the full query language and examples.

---

🔍 Pre-filter: scope search with structural filters

search_notes accepts an optional filter to narrow the candidate set before ranking — combining the precision of query_notes with the recall of hybrid search. The filter applies identically to every leg: only notes that pass it can appear in the fused matches[] list. Useful when domain-relevant notes are crowded out by larger narrative clusters.

{ "query": "trading lessons", "filter": { "tags": ["trading"] } }

filter accepts path_prefix (string or array), exclude_path_prefix (string or array — drops matched subtrees), tags (ANY-of), and a frontmatter sift filter. Composition is include → exclude → tags → frontmatter, then each leg ranks within the allowed set (threshold further cuts the semantic leg only). See the Finding Notes guide for full details.

---

🏗 How it works

flowchart LR
    You([You]) --> AI[AI assistant]
    AI <-->|MCP| NV[Neuro Vault]
    NV <--> Vault[(Obsidian vault)]

Loading

You ask, the assistant calls Neuro Vault, Neuro Vault reads your vault — the semantic leg uses embeddings already in .smart-env/, the lexical leg reads notes straight from disk, and vault operations read and write the vault directory directly on disk too. No database, no background processes, no Obsidian install required.

For module wiring and internal data flow, see docs/architecture/module-structure.md.

---

⚡ Quickstart

npm install -g neuro-vault-mcp

Single vault

Add to your MCP client config (here: Claude Code's ~/.claude/settings.json):

{
  "mcpServers": {
    "neuro-vault": {
      "command": "neuro-vault-mcp",
      "args": ["--vault", "/absolute/path/to/your/vault"]
    }
  }
}

Vault directory names must match ^[a-zA-Z0-9_-]{1,64}$ — ASCII letters, digits, _, or -; 1–64 chars. Spaces and Unicode are rejected. The MCP-side alias is the directory basename, so if Obsidian shows the vault as "My Vault", the directory itself must be My_Vault or similar.

🗂 Multi-vault — two vaults, one server

Pass --vault once per vault:

neuro-vault-mcp \
  --vault /Users/me/Vaults/Sandbox \
  --vault /Users/me/Vaults/TeamWiki

Two vaults registered, with names Sandbox and TeamWiki. In your MCP config:

{
  "mcpServers": {
    "neuro-vault": {
      "command": "neuro-vault-mcp",
      "args": ["--vault", "/Users/me/Vaults/Sandbox", "--vault", "/Users/me/Vaults/TeamWiki"]
    }
  }
}

Two vaults cannot share the same directory basename — the basename doubles as the alias and must be unique. If you have a basename collision, rename one of the directories.

With multiple vaults registered:

• Every tool accepts an optional vault: "<name>" parameter to target a specific vault.
• search_notes, query_notes, get_vault_overview, list_tags, and list_properties fan out across all registered vaults when vault is omitted. The response shape switches to results_by_vault: [...] (one entry per vault) plus failed_vaults: [...] for per-vault runtime errors ({ vault, error: { code, message, details? } }) — a single failed vault does not abort the whole call. The envelope also always includes skipped_vaults: [...], reserved for a future fan-out tool that pre-filters vaults; today it's always empty, since nothing skips a vault.
• All other tools (writes, reads of specific paths, single-vault diagnostics) require an explicit vault in multi-vault mode. Omitting it returns VAULT_REQUIRED.
• A vault without a Smart Connections .smart-env/multi/ index still participates in search_notes fan-out — it contributes matches[] fused from its lexical leg alone; no vault is skipped. Targeting such a vault explicitly with the embeddings-only tools (get_similar_notes, find_duplicates) returns SEMANTIC_INDEX_NOT_FOUND.

Then ask your assistant:

"What did I write about building AI agents?"

On first run the embedding model downloads automatically (~40 MB). Subsequent starts are fast.

For other clients (Cursor / Windsurf / npx), see docs/guide/installation.md.

---

📚 Documentation

Every tool accepts an optional vault parameter. In multi-vault mode, search_notes, query_notes, get_vault_overview, list_tags, and list_properties fan out across all registered vaults when vault is omitted.

User guide lives in docs/guide/:

• Installation
• Finding Notes — search_notes (hybrid semantic + lexical), structured queries (query_notes), get_similar_notes, find_duplicates, get_note_links
• Reading & Modifying — note CRUD, daily notes, properties, tags, vault snapshot (get_vault_overview)
• Routing Between Tools
• Configuration — CLI args, vault conventions for external agents, troubleshooting, limitations, development

Architecture / internals: docs/architecture/.

📝 What changed between versions — including every ⚠ BREAKING CHANGES block — lives in CHANGELOG.md (shipped inside the npm package too). The same notes are published per version on GitHub Releases.

---

Vault-specific conventions for external agents

Drop a <vault>/.neuro-vault/for-external-agents.md into your vault to teach external agents the rules that cannot be derived from a structural snapshot — closed sets of frontmatter type values, folders that are off-limits for writes, how you scope notes to a project. The file is optional; without it the server still ships sane defaults plus a pointer to get_vault_overview.

It is delivered two ways:

• 📦 In every get_vault_overview response, as a conventions field — and in the vault://overview resource (vault://<vault-name>/overview when several vaults are registered). This is the channel to rely on: it is read at call time (so edits take effect on the next call, no server restart), it reaches sub-agents, and no client we have measured truncates it. The field is simply absent when you have no such file.
• 📨 At the front of the MCP instructions, under a ## Vault-specific conventions heading, for clients that render them. Treat this one as best-effort — Claude Code cuts instructions at exactly 2048 characters and gives sub-agents none of it, and other clients may differ. The conventions are placed first precisely so they survive that cut.

Keep the file under 8,000 characters. Past that the conventions field carries a trimmed slice and sets conventions_truncated: true — you never lose the call, but you do lose the tail, so compact rules beat exhaustive ones.

With several vaults registered, each one carries its own file: every entry in a fanned-out results_by_vault gets its own vault's conventions, and the instructions get one clearly-labelled block per vault.

---

📄 License

ISC — see LICENSE.

Changelog: CHANGELOG.md · GitHub Releases