neuro-vault-mcp 3.4.0 → 4.0.0

package/README.md

@@ -1,12 +1,16 @@
 # Neuro Vault MCP
 
-**Semantic vault search and direct vault operations for your Obsidian vault — right inside your AI assistant.**
+> 🧠💾 **Plug your knowledge in like a USB drive.** Your Obsidian vault, available in every AI conversation — search it, query it, write to it. Same vault in Claude Code, Cursor, Windsurf — no copy-paste, no context-switching, no re-indexing.
+
+https://github.com/user-attachments/assets/0ba43373-3f97-4dc6-ab91-4f30bdafd0bf
 
 [![npm version](https://img.shields.io/npm/v/neuro-vault-mcp)](https://www.npmjs.com/package/neuro-vault-mcp)
 [![Node.js](https://img.shields.io/node/v/neuro-vault-mcp)](https://nodejs.org)
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
 
-> "What did I write about that idea last month?" — and now your assistant can actually answer.
+Your second brain stops being a folder you open between contexts and becomes a first-class participant in every project. Ask, recall, decide, write back — all without leaving the conversation.
+
+> _"What did I write about that idea last month?"_ — and now your assistant can actually answer.
 
 ---
 
@@ -22,30 +26,35 @@
 
 ---
 
-## 🏗 How it works
+## 🧰 Two superpowers, one server
 
-```mermaid
-flowchart LR
-    You([You]) --> AI[AI assistant]
-    AI <-->|MCP| NV[Neuro Vault]
-    NV <--> Vault[(Obsidian vault)]
-```
+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:
 
-You ask, the assistant calls Neuro Vault, Neuro Vault reads your vault — semantic search uses embeddings already in `.smart-env/`, vault operations go through the `obsidian` CLI. No database, no background processes.
+|                  | 🔭 **Semantic recall**                                                    | 🛠 **Vault operations**                                                        |
+| ---------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| **What it does** | Finds notes by meaning, not keywords. Surfaces neighbours and duplicates. | Reads, writes, edits notes; manages frontmatter, tags, daily notes.            |
+| **Best for**     | _"What did I think about X?"_, fuzzy recall, exploratory research.        | Structured queries, capturing decisions, updating tasks, batch reads.          |
+| **Powered by**   | Smart Connections embeddings (already in your vault).                     | The official Obsidian CLI — Smart Connections, sync, plugins all stay in sync. |
 
-For module wiring and internal data flow, see [docs/architecture/module-structure.md](./docs/architecture/module-structure.md).
+The two work together: semantic search finds the right region of the vault, vault operations let the assistant actually _do something_ with what it found.
 
 ---
 
-## 🧭 Your vault, but queryable
+## ✨ What it looks like in practice
 
-A plain-text vault is great for humans and rough on agents. Without the right tools, an assistant ends up listing folders, opening dozens of notes, and grepping inside each one just to answer a simple question.
+**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.
 
-Neuro Vault gives your assistant a way to **ask the vault directly** — by tag, by frontmatter property, by folder, by similarity. Things like:
+**After:** _"Could you check my notes about that LangGraph experiment?"_
+→ One semantic search, top-3 ranked notes back, 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."_
+> _"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 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.
 
@@ -53,6 +62,21 @@ One question, one answer. Your assistant stops being a file browser and starts b
 
 ---
 
+## 🏗 How it works
+
+```mermaid
+flowchart LR
+    You([You]) --> AI[AI assistant]
+    AI <-->|MCP| NV[Neuro Vault]
+    NV <--> Vault[(Obsidian vault)]
+```
+
+You ask, the assistant calls Neuro Vault, Neuro Vault reads your vault — semantic search uses embeddings already in `.smart-env/`, vault operations go through the `obsidian` CLI. No database, no background processes.
+
+For module wiring and internal data flow, see [docs/architecture/module-structure.md](./docs/architecture/module-structure.md).
+
+---
+
 ## ⚡ Quickstart
 
 ```bash

package/dist/cli.d.ts

@@ -13,6 +13,11 @@ interface SmartSource {
     embedding: number[];
     blocks: SmartBlock[];
 }
+
+interface SmartConnectionsCorpus {
+    sources: Map<string, SmartSource>;
+}
+
 interface BlockSearchResult {
     path: string;
     heading: string;
@@ -54,15 +59,12 @@ interface SearchEngine {
 }
 type PathExistsCheck = (vaultRelativePath: string) => Promise<boolean>;
 
-interface SmartConnectionsCorpus {
-    sources: Map<string, SmartSource>;
-}
-
 interface SemanticModuleDeps {
     loadCorpus?: (smartEnvPath: string, modelKey: string) => Promise<SmartConnectionsCorpus>;
     embeddingServiceFactory?: (modelId: string) => EmbeddingProvider;
     searchEngine?: SearchEngine;
     pathExists?: PathExistsCheck;
+    readNoteContent?: (vaultRelativePath: string) => Promise<string>;
 }
 
 type NoteIdentifier = {