NeuroVault

Local-first AI memory for Claude and any MCP agent

Claude forgets you after every conversation. NeuroVault doesn't.

Download · Documentation · Website · Connect your agent

NeuroVault is a local-first memory layer for AI agents. It sits between your Markdown notes and supported AI clients and gives them durable recall across sessions. Your notes stay as plain .md files and the local database is rebuildable; selected context reaches only the AI providers you deliberately connect, under the data flow described in PRIVACY.md.

The open local core follows the Core Covenant: no required account, no remote kill switch, durable Markdown ownership, and no sale or model training on vault data.

Not RAG-in-a-trenchcoat. A structured, updatable, inspectable knowledge base an AI can read, write, and challenge. Why this is not RAG ↓

The app

Download & install

Latest release: github.com/sirdath/NeuroVault/releases/latest

1. Download the installer for your platform and run it.
2. Notes are saved as plain markdown in ~/.neurovault/.

macOS 14 (Sonoma) is a hard floor. The bundled sqlite-vec extension is built for macOS 14+, and it loads on every brain open — on macOS 11–13 the app launches and then cannot open any database. Intel Macs are not supported at all, including building from source: the only vec0 build we ship is arm64, so an Intel build gets a library it cannot load.

Verify the download before first launch

Every release publishes SHA-256 checksums and Sigstore build provenance. Compare the downloaded file with the checksum in its release before opening it.

macOS artifacts are signed with a Developer ID certificate and notarized by Apple, so Gatekeeper accepts them as software from an identified developer. macOS may still show its standard one-time confirmation that an app was downloaded from the internet. If macOS instead says an official .dmg is damaged or cannot be verified, do not disable quarantine or bypass the warning — delete the file and report the release URL and checksum through the project security process.

Windows artifacts are not code-signed yet. SmartScreen will say "Windows protected your PC" and show the publisher as unknown. That is expected for now, not a sign of tampering — an Authenticode certificate is on the roadmap. Verify the SHA-256 checksum against the release, then choose More info → Run anyway. If you would rather not, use the macOS build, a Linux build, or build from source.

🐧 Linux

The AppImage runs without warnings — run chmod +x neurovault_*.AppImage first if your file manager doesn't mark it executable.

Updates — NeuroVault installs signed updates in place from the top-bar Update button. Checks are manual by default; you can explicitly enable a launch check in Settings → General. Update requests never include vault content or a stable install identifier, and updates never touch data under ~/.neurovault/.

What you get

• Graphify your codebase — point NeuroVault at a repo and it becomes part of your active vault: 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 connected AI 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. NeuroVault does not upload source while building the graph.
• 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]].
• Import inbox — drag a file onto the window to copy it into a private staging area without changing the original. Connected workflows can turn staged material into indexed notes. 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, run by the same native neurovault-server binary — no Python.)
• Multiple vaults — separate files and databases per project; switch from the vault picker or command palette.
• Per-folder boundaries — drop a .neurovault file in a project directory to scope that folder's connected memory to its own vault (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.
• Local-first, with an exact network contract. No NeuroVault account or telemetry. The server is loopback-only on 127.0.0.1:8765; selected context leaves the Mac only through AI providers you deliberately connect, and model/update downloads are disclosed in PRIVACY.md.

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 (21) or full (55, 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 goes through Ambient Recall: the full hybrid retriever (semantic + BM25 + graph, fused, then a cross-encoder reranker) followed by a precision gate that decides whether anything is trustworthy enough to inject. Injected memories arrive as compact, sanitized background context with IDs, source paths, and a one-line "why". At session start you get a one-shot vault brief: core memory, top memories, open tasks.

Ambient Recall prefers silence over weak context. Vector search always has some nearest neighbor, so an ungated injector would decorate every prompt with plausible-but-useless notes. The gate requires an absolute cross-encoder score floor (raised further for vague prompts, relaxed slightly for exact file/symbol/error matches) and a margin over the runner-up — when confidence is low it injects nothing, and that's a success, not a failure. Every decision (inject or silent, with all scores) is logged to ~/.neurovault/logs/ambient_recall.jsonl.

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). The installed hook command is wrapped so even a broken or stale binary can't block a prompt.
• Signal only. Trivial prompts are skipped before any network call, gated memories need real relevance scores, and a memory is never injected twice in the same session.
• Reversible. Install is idempotent and edits only NeuroVault's own entries in settings.json (a backup is written first); uninstall removes exactly those.
• Tunable. Thresholds, budgets, strict mode, and per-vault overrides live in ~/.neurovault/ambient.json; debug any prompt with neurovault-server ambient test "your prompt" — it prints the candidate table, every score, and the gate's reasoning. Details: docs/ambient-recall.md.

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:

Features

Multiple vaults — separate memory spaces, each with its own Markdown boundary, database, and graph. Switch instantly via the dropdown or a connected agent.

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-vault 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, <private> 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()).

Vault 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 vault 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. No Python is needed to build or run anything. (The only Python in the repo is offline tooling the app never invokes: the eval/ retrieval harness, the docs/benchmarks/ report mergers, and two icon generators in scripts/.)

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. The macOS build we ship is arm64 and macOS 14+ only: that is the deployment target of the bundled extension, and it is loaded on every brain open. Building on an Intel Mac does not produce a working app — the repo carries only the arm64 vec0.dylib, so an x86_64 build gets a library it cannot load. Intel support needs an x86_64 (or universal) vec0 build first.

MCP tools

Exposed to any MCP-speaking agent via the native Rust MCP server — 55 tools, gated by a tier system so agents only pay for the slice they use: minimal (3) · lite (8, the default) · standard (21) · full (55, 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:

Architecture

Full technical reference map — the whole system on one page: topology, the hybrid retrieval core, ingest, storage, the 55-tool MCP surface, and why every path is on-device (no external model calls, no paid path).

+-------------------------------------------------+
|  Tauri 2 desktop app (React 19 + TypeScript)    |
|  Editor / Graph / Sidebar / Command palette     |
+-----------------------+-------------------------+
                        | Tauri commands  +  HTTP :8765
+-----------------------v-------------------------+
|  In-process Rust backend                        |
|  - axum HTTP server (the MCP server talks here) |
|  - hybrid retriever (semantic + BM25 + graph)   |
|  - fastembed-rs (BGE-small ONNX, local)         |
|  - notify file watcher                          |
+-----------------------+-------------------------+
                        | SQL + vec0
+-----------------------v-------------------------+
|  SQLite + sqlite-vec  (~/.neurovault/...)       |
|  brain.db, vault/*.md, raw/, assets/, cache/    |
+-------------------------------------------------+

External:
  + neurovault-server --mcp-only — native Rust stdio<->HTTP MCP server
    (rmcp; bundled binary). Your agent spawns it per session; no Python.
    The same binary also serves the Claude Code lifecycle hooks
    (`neurovault-server hook …`). No Python anywhere in the product.

Markdown in vault/ and inputs in raw/ are canonical; everything in cache/ and brain.db is rebuildable. If the index breaks, rebuild from the files. You own your memories. Full layout + privacy details: PRIVACY.md.

Tech stack

Performance

Retrieval quality — measured on the full 470-question LongMemEval benchmark (long multi-session histories, facts that get updated and contradicted, temporal reasoning), using NeuroVault's real recall() path (cross-encoder reranker on, the default) with 100% on-device embeddings:

The right memory lands in the top 5 results 97% of the time, in the top 10 99% — running entirely on your machine, no cloud, no API keys. This is retrieval recall (was the right memory retrieved), not end-to-end QA accuracy. Reproducible: full harness + a per-question receipt in docs/benchmarks/, plus the isolated reranker A/B in docs/benchmarks/ANALYSIS-2026-07-02-miss5-forensics.md.

Cost — on-device embeddings and retrieval cost effectively nothing (your own machine, no per-call API). The retrieval engine and application are open source; the exact optional network flows are documented in PRIVACY.md.

Keyboard shortcuts

On Windows and Linux, use Ctrl in place of ⌘.

Documentation

Full docs — quickstart, the graph view, drop-folder ingest, architecture, and the HTTP API — live at neurovault.dathproject.com/docs.

In the repo:

• Troubleshooting & data — install warnings, MCP setup, backup/move/export, recovering a corrupt index.
• How NeuroVault works — the architecture and retrieval pipeline in depth.
• HTTP API · Contributing · Privacy · Security.

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md and CODE_OF_CONDUCT.md. Security reports: SECURITY.md.

License

MIT © NeuroVault contributors.