NeuroVault

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 · Website · [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

| 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:

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 →
• 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.

> 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 SDK (no Python):

{
  "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:

neurovault-server hook install     # wires ~/.claude/settings.json
neurovault-server hook status
neurovault-server hook uninstall

How it works: Claude Code 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 20+, Rust. That's it — the MCP server is a native Rust binary (neurovault-server), built alongside the app. (Python + uv are optional, only for the out-of-band advanced ingest helpers in server/ — PDF/Zotero — not for MCP.)

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
• Source: sirdath/NeuroVault
• License: MIT
• Homepage: https://neurovault.dathproject.com

Install and usage instructions live in the source repository linked above.