# NeuroVault > Local-first AI memory for Claude, Cursor and any MCP agent. Say it once; it recalls it when relevant. 97% recall@5 on LongMemEval, 100% on-device. Markdown-canonical, open source. - **Type:** MCP server - **Install:** `agentstack add mcp-sirdath-neurovault` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [sirdath](https://agentstack.voostack.com/s/sirdath) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [sirdath](https://github.com/sirdath) - **Source:** https://github.com/sirdath/NeuroVault - **Website:** https://neurovault.dathproject.com ## Install ```sh agentstack add mcp-sirdath-neurovault ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About ### Local-first AI memory for Claude and any MCP agent Claude forgets you after every conversation. **NeuroVault doesn't.** [](LICENSE) [](https://github.com/sirdath/NeuroVault/releases/latest) [](https://github.com/sirdath/NeuroVault/releases) [](https://github.com/sirdath/NeuroVault/stargazers) **[Download](#download--install) · [Documentation](https://neurovault.dathproject.com/docs) · [Website](https://neurovault.dathproject.com) · [Connect your agent](#connect-your-agent-mcp)** NeuroVault is a **local-first memory layer for AI agents**. It sits between your markdown notes and any MCP-compatible agent (Claude Code, Claude Desktop, Cursor, Codex) and gives it a callable `recall()` + `remember()` surface that survives across sessions. Everything runs on your machine — your notes are plain `.md` files, the database is a rebuildable cache over them, and nothing is sent to a server you don't control. > Not RAG-in-a-trenchcoat. A structured, updatable, inspectable knowledge base an AI can read, write, and challenge. [Why this is not RAG ↓](#why-this-is-not-rag) --- ## Download & install Latest release: **[github.com/sirdath/NeuroVault/releases/latest](https://github.com/sirdath/NeuroVault/releases/latest)** | Platform | Asset | |---|---| | **Windows x64** | `NeuroVault_*_x64-setup.exe` (NSIS installer) | | **macOS Apple Silicon (M1–M4)** | `NeuroVault_*_aarch64.dmg` | | **macOS Intel** | No prebuilt binary — [build from source](#quick-start-developers) (GitHub's Intel-mac runners are unavailable) | | **Linux x64** | `neurovault_*_amd64.AppImage` / `*.deb` / `*.rpm` | 1. Download the installer for your platform and run it. 2. Notes are saved as plain markdown in `~/.neurovault/`. ### First launch — clearing the OS warning NeuroVault is open-source and **not code-signed** (Apple/Microsoft signing certificates cost hundreds of dollars a year). The installers are built in public from this repo — the warning is about the **missing certificate, not malware**. Here's how to get past it on each OS. #### 🍎 macOS — "NeuroVault is damaged and can't be opened" That message just means macOS quarantined an app downloaded outside the App Store. Drag **NeuroVault.app** into your **Applications** folder, then run this **one command** in Terminal: ```bash xattr -dr com.apple.quarantine /Applications/NeuroVault.app ``` Now open NeuroVault normally — the warning is gone for good. One line, one time. (On Claude Code or any terminal? Just paste it.) Prefer not to use the Terminal? Right-click **NeuroVault.app → Open → Open**. If macOS still refuses (common on Sonoma/Sequoia/Tahoe), open **System Settings → Privacy & Security**, scroll to the bottom, and click **Open Anyway** next to the NeuroVault message — then launch the app again. #### 🪟 Windows — "Windows protected your PC" Click **More info → Run anyway**. SmartScreen flags any installer without a paid EV certificate. #### 🐧 Linux The AppImage runs without warnings — run `chmod +x neurovault_*.AppImage` first if your file manager doesn't mark it executable. > **Updates** — from **v0.5.1** on, NeuroVault **auto-updates in place**: it checks for a newer *signed* release on launch, and the top-bar **Update** button downloads, installs, and relaunches it — no manual re-download. Your data lives in `~/.neurovault/` and is never touched by an update. ## What you get - **Graphify your codebase** — point NeuroVault at a repo and it becomes part of your brain: files, symbols, and call edges parsed **on-device** (tree-sitter — Rust, Python, TS/TSX, Go, Java, C#, Ruby) and rendered as a gold layer in the graph. Your agent can ask `where_defined`, `who_calls`, `blast_radius` (what breaks if I change this?) — and `fuse` links code to the notes and decisions about it. Your source never leaves the machine. - **Knowledge graph view** — your notes as a living, force-directed map. Node **fill = category** (folder), a **ring = health** (teal active · amber fresh · grey dormant), and **size = importance** (PageRank) in Analytics mode. Spread/zoom controls, animations toggle, Venn-style category grouping, time-lapse playback, and a click-to-frame cluster legend. - **Hybrid retrieval, always on** — semantic + BM25 keywords + knowledge graph, fused via RRF, then a cross-encoder reranker (on by default). In-process Rust. - **Markdown editor** with live preview, auto-save, drag-to-reorder tabs, and `[[wikilinks]]`. - **Drop-folder ingest** — drag any file onto the window; your connected agent reads it and turns it into a clean, indexed note. [How it works →](https://neurovault.dathproject.com/docs#drop-folder) - **Silent fact capture** — casually-dropped facts ("I prefer Rust over Go") get promoted to first-class memories with provenance back to where you said them. (Optional Claude Code hook; the one feature that uses a tiny Python script.) - **Multiple brains** — separate vaults/databases per project; switch via the dropdown or `Ctrl+K`. - **Per-folder brains** — drop a `.neurovault` file in a project directory to scope that folder's agent memory to its own brain (opt-in). - **Agent auto-start** — your MCP agent starts the memory backend for you on first use; no need to open the app first. - **Floating minitab + window modes** — shrink the whole app to a tiny always-on-top widget (status · start/pause · open), or **Minimize / Hide / Shrink to widget** from the top bar; bring it back with `Ctrl/Cmd+Shift+Space`. - **Open a folder as a vault** — point NeuroVault at an existing Obsidian vault; the folder stays in place. - **Notes-tree + graph share colours**, themes, resizable panels, and **signed one-click auto-update**. - **100% local. No telemetry, no account, no cloud.** Loopback-only server on `127.0.0.1:8765`, CORS-scoped to the app's own origins. ## Connect your agent (MCP) **Installed app (one click):** open **Settings → Connect Claude Code** and hit **Register automatically** — it merges NeuroVault into `~/.claude.json` (your existing login + config are preserved), then restart your Claude Code session. For **Claude Desktop**, the same panel generates the exact JSON snippet to paste. Full walkthrough in the [Quickstart](https://neurovault.dathproject.com/docs#quickstart). > **Tiers** — by default the agent loads the **`lite`** tier (8 tools). Switch to `standard` (20) or `full` (54, includes the graphify code tools) in **Settings → MCP** or via `~/.neurovault/mcp_tier.txt`. Fewer tools = less context the agent pays for up front. **Manually**, point your MCP client at the bundled native MCP server — `neurovault-server --mcp-only`, a Rust stdio↔HTTP bridge built on the official [rmcp](https://github.com/modelcontextprotocol/rust-sdk) SDK (no Python): ```json { "mcpServers": { "neurovault": { "command": "/Applications/NeuroVault.app/Contents/MacOS/neurovault-server", "args": ["--mcp-only"] } } } ``` (macOS path shown; on Windows/Linux it's the `neurovault-server` binary that ships next to the app. The Settings dialog fills in the exact path for you.) It forwards to the Rust HTTP server in the running app on `127.0.0.1:8765`. You don't need to open the app first — the MCP server **auto-starts the backend** if it isn't already running (disable with `NEUROVAULT_AUTOSTART=0`). Now say *"remember that I prefer Tauri over Electron"*; weeks later, ask *"what desktop framework do I like?"* and it recalls instantly. ## Automatic memory (zero effort) MCP memory has a known weakness: the agent only remembers if it *decides* to call `recall` — and models routinely don't. NeuroVault fixes this with **automatic recall** for Claude Code: relevant memories are injected into every prompt automatically, no tool call needed. Turn it on in **Settings → Automatic Memory (Claude Code)**, or from the terminal: ```bash neurovault-server hook install # wires ~/.claude/settings.json neurovault-server hook status neurovault-server hook uninstall ``` How it works: Claude Code [hooks](https://code.claude.com/docs/en/hooks) run NeuroVault on every prompt (`UserPromptSubmit`) and at session open (`SessionStart`). Each prompt is matched against your active brain with the full hybrid retriever; the top memories (relative-score filtered, deduplicated per session) are injected as compact background context. At session start you get a one-shot brain brief: core memory, top memories, open todos. Design guarantees: - **Fail-open.** If NeuroVault isn't running, the hooks print nothing and exit 0 — your Claude Code session is never blocked or slowed (hard 3.5 s budget). - **Signal only.** Trivial prompts are skipped, weak matches are dropped, and a memory is never injected twice in the same session — asking again surfaces the *next* most relevant memory instead. - **Reversible.** Install is idempotent and edits only NeuroVault's own entries in `settings.json` (a backup is written first); uninstall removes exactly those. ## Screenshots | | | |---|---| | | | | **Filters panel.** Every graph knob in one place — spread, edge-type filters, node size, layout, animations, grouping, time-lapse. Live, no re-render. | **Cmd+K palette.** One prompt, three sections — *Commands* (fuzzy), *Notes* (title search), *Memory* (semantic recall after 3+ chars). | | | | | **Semantic edges.** Toggle the inferred-similarity layer; `manual`, `entity`, and `semantic` links each get their own colour. | **Settings.** Theme, density, server controls, MCP connection diagnostics, and the update checker. | --- ## How it works ``` You write a note in the editor -> Auto-saved as markdown in your vault -> File watcher triggers the ingest pipeline -> Text chunked, embedded locally, entities extracted, knowledge graph updated You drop a fact in conversation ("I prefer Tauri 2.0 over Electron") -> A UserPromptSubmit hook runs it through a regex extractor -> 8 patterns catch preferences, decisions, deadlines, identities, stacks -> Each fact becomes a first-class kind='insight' engram -> With a wiki-link back to the original observation for provenance You ask the agent a question -> Agent calls recall() via MCP -> Hybrid search: semantic + BM25 + knowledge graph, fused via RRF -> Recent / contested decisions get a score bonus; dormant ones fade -> Top memories returned at a flat ~275 tokens regardless of vault size After meaningful exchanges -> Write-back extracts durable facts and saves them as new notes -> Strength decay reinforces what you keep using; unused notes fade ``` ## Why this is not RAG RAG is an answer-pipeline: chunk, embed, retrieve K chunks, stuff the context, generate, repeat. The corpus is dead data, retrieval has no memory of past retrievals, contradictions are invisible, provenance is a prayer. NeuroVault is a **knowledge layer**. It differs in five ways that map to what a living internal wiki needs: | What a wiki needs | RAG's answer | NeuroVault's answer | |---|---|---| | **Accumulate over time** | re-chunk, re-embed | Ebbinghaus strength decay + access reinforcement. Used facts stay strong; unused fade. | | **Structure** | flat chunks | Karpathy's 3-layer raw/wiki/schema pattern; engrams typed `note`/`source`/`quote`/`insight`/`observation`. | | **Link** | none | Three automatic link types (semantic, shared-entity, explicit `[[wikilinks]]`) + a force-directed graph. | | **Provenance** | cite the chunk | Silent fact capture stores `**Source:** [[observation-...]]` links back to the exact prompt where a fact was said. | | **Challenge / update** | none | Temporal fact tracking — a contradicting fact supersedes the old one, which then takes a recency penalty in retrieval. | ## Features **Multiple brains** — separate memory spaces, each with its own vault, database, and graph. Switch instantly via the dropdown or MCP. **Hybrid retrieval** — three signals merged via Reciprocal Rank Fusion: semantic vector similarity (50%), BM25 keywords (30%), knowledge-graph traversal (20%). A cross-encoder reranker runs by default for extra precision (toggle off in Settings). **Memory strength** — Ebbinghaus forgetting curve with access reinforcement. Frequently retrieved memories stay strong; unused ones fade. **Graph view** — force-directed visualization. Fill encodes category, a ring encodes health/strength, size encodes importance (Analytics mode). Click a node to open, drag to pin, click a cluster in the legend to frame it. **Drop-folder ingest** — a per-brain **`raw/`** folder (with a `README.md` guide inside); paste documents there and the connected agent converts them into clean notes (no bundled converters — the agent is the converter). Originals are kept in `raw/_done/`. **Silent fact capture** — a UserPromptSubmit hook pipes prompts through a regex extractor recognising 8 patterns (preferences, decisions, stacks, deadlines, identity, anti-preferences, deploy targets, explicit "remember that…"). Microseconds, no LLM call, bounded to 3 extractions/message, `` blocks stripped. **Session wake-up** — `session_start` returns layered context: L0 (~100 tokens, identity), L1 (~300 tokens, top active memories), L2 (on demand via `recall()`). **Brain diagnostic** — a one-click health scorecard for your vault. Distils the graph into five graded categories + a headline grade and a worst-first list of fixes. "Copy report" emits a plain-text scorecard you can paste to your agent, so it acts on the issues — the maintenance loop the agent is meant to own. ``` NeuroVault brain diagnostic — work Overall: B (84/100, 412 notes) Connectivity ██████████████████████░░ 88% Interlinking ███████████████░░░░░░░░░ 63% Cohesion ███████████████████████░ 94% Freshness ██████████████████░░░░░░ 74% Organization ████████████░░░░░░░░░░░░ 51% Top fixes: - 49 orphan notes with no links — connect or merge them - 201 unfiled notes in the root — sort into folders ``` --- ## Quick start (developers) **Prerequisites:** [Node.js](https://nodejs.org/) 20+, [Rust](https://rustup.rs/). That's it — the MCP server is a native Rust binary (`neurovault-server`), built alongside the app. ([Python](https://www.python.org/) + [uv](https://docs.astral.sh/uv/) are optional, only for the out-of-band advanced ingest helpers in `server/` — PDF/Zotero — not for MCP.) ```bash git clone https://github.com/sirdath/NeuroVault.git cd NeuroVault npm install # One terminal — the Tauri shell hosts the React frontend AND the # in-process Rust HTTP server on 127.0.0.1:8765. Nothing else to start. npx tauri dev # Release build (installer at src-tauri/target/release/bundle/): npx tauri build ``` **First run downloads** (once, then cached — instant after that): - the embedding model **BGE-small-en-v1.5** (~130 MB) to `~/.neurovault/.fastembed_cache/`, on first ingest/recall. The `sqlite-vec` (`vec0`) native extension ships **bundled** with the app — no separate install. On Intel macOS, run `npx tauri build` on an Intel Mac to get a native `.dmg`. ## MCP tools Exposed to any MCP-speaking agent via the native Rust MCP server — **54 tools**, gated by a **tier** system so agents only pay for the slice they use: `minimal` (3) · `lite` (8, the default) · `standard` (20) · `full` (54, includes the graphify code tools). Set it with `NEUROVAULT_MCP_TIER`, `~/.neurovault/mcp_tier.txt`, or Settings → MCP. Every tool takes an optional `brain` parameter to target a specific brain. Highlights: | Tool | What it does | |------|-------------| | `recall(q, mode, limit, rerank?)` | Hybrid search — semantic + BM25 + graph via RRF, rerank on by default. PageRank prior in Analytics mode. | | `recall_chunks(q, limit)` | Same retrieval, returns matching paragraphs instead of whole notes. Cheaper. | | `related(engram_id, hops, link_types?)` | Direct graph neighbours of an engram. ~50× cheaper than a fresh recall. | | `remember(content, title?, dedupe?)` | Save a memory (chunk + embed + entities + graph link). | | `list_inbox` / `read_inbox_file` / `mark_inbox_done` | Drop-folder wor … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [sirdath](https://github.com/sirdath) - **Source:** [sirdath/NeuroVault](https://github.com/sirdath/NeuroVault) - **License:** MIT - **Homepage:** https://neurovault.dathproject.com 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:** no - **Shell / process execution:** no - **Environment & secrets:** no - **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-sirdath-neurovault - Seller: https://agentstack.voostack.com/s/sirdath - 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%.