MemVault - Local-First Agent Memory

MemVault

The Shared Memory Layer for Every AI Agent You Run

Not "agent learns to search memory" — memory finds the agent.

MCP Native · Hybrid Retrieval · Auto-Injection · Zero-Config Sync

Open Source · Self-Hosted · Private · MIT Licensed

English · 简体中文

If MemVault solves a real problem for you, a star helps others find it.

[⭐ Star on GitHub](https://github.com/dreamor/memvault) · [Report Bug](https://github.com/dreamor/memvault/issues/new)

curl -fsSL https://raw.githubusercontent.com/dreamor/memvault/master/scripts/install.sh | bash

---

Every AI agent session starts from scratch. Claude Desktop doesn't know what Cursor just learned. DeepSeek Harness (dsh) doesn't know what you told Claude Code yesterday. Whatever agent you're running — international or domestic, IDE plugin or CLI harness — it forgets your preferences every time you start a new conversation.

You've been manually repeating context — project conventions, personal preferences, past decisions — across agents that should already know. This isn't a limitation of the models. It's a missing infrastructure layer.

MemVault is that layer. A lightweight, self-hosted memory router that sits between your agents and their context. It speaks plain MCP — no MemVault-specific SDK, no per-agent API integration. Any MCP-compatible agent, from any vendor, automatically shares the same persistent memory the moment it connects.

Who it's for:

• Anyone running an MCP-capable agent — Claude Code, Claude Desktop, Cursor, Cline, Continue, DeepSeek Harness (dsh), or any other MCP client, domestic or international — who wants preferences, project context, and past decisions to persist across sessions without repeating yourself
• Multi-agent power users running several of the above side by side, on different models, from different vendors — all sharing the same memory without configuration
• Platform teams deploying AI-assisted workflows where consistency matters across a mixed agent fleet: code review conventions, architecture decisions, project-specific preferences
• Anyone tired of telling their AI the same thing twice — MemVault works the way your brain should: you say it once, it's there when you need it, no matter which agent is asking

[Quick Start](#quick-start) · [How It Works](#how-it-works) · [What MemVault Gives You](#what-memvault-gives-you) · [Why MemVault](#why-memvault) · [MCP Server](#mcp-server) · [CLI Reference](#cli-reference) · [Integrations](#integrations) · [Architecture](#architecture) · [Project Status](#project-status) · [Testing](#testing) · [Documentation](#documentation) · [Contributing](#contributing) · [License](#license)

---

Quick Start

Don't install MemVault by hand — paste this one prompt into Claude Code, Codex, Cursor, dsh, or any other MCP-capable agent. It points the agent at a machine-readable install guide, so the agent does the whole setup itself:

Install MemVault as your long-term memory and wire it into this agent. Fetch and follow https://raw.githubusercontent.com/dreamor/memvault/master/docs/AGENT-INSTALL.md — install the binaries, register MemVault as an MCP server for this host, and verify recall works. Then keep saving my preferences, project decisions, and lessons from each session so my next agent starts with them instead of from scratch.

Or install manually:

# Install (Linux / macOS): official script, auto-verifies SHA-256

curl -fsSL https://raw.githubusercontent.com/dreamor/memvault/master/scripts/install.sh | bash export PATH="$HOME/.memvault/bin:$PATH"

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File scripts\install.ps1

Homebrew (Apple Silicon):

brew install dreamor/tap/memvault

Or from crates.io:

cargo install memvault-cli memvault-mcp

The installers auto-start the local REST backend (host of the Web

Dashboard). Open it, or start it on demand:

memvault-cli dashboard

Save a MUST-level preference (injected as instruction, agent must follow)

memvault-cli save --content "User prefers Python" --priority MUST --type preference \ --instruction "Use Python for code, not Java" --tags "coding,python"

Search across all memory (hybrid: keyword + semantic when embedding is enabled)

memvault-cli search --query "Python"

See what context gets injected when a specific agent connects

memvault-cli session-start --agent-id claude-desktop --context "Help me write code"

Extract structured memories from free text

memvault-cli extract --text "I prefer dark mode. Our project uses Rust." --save

Auto-generate agent instruction files from memory

memvault-cli sync

All in one: dedup, decay, archive stale memories

memvault-cli dedup && memvault-cli decay

System requirements:

- Prebuilt Linux binaries (install script / GitHub release): glibc ≥ 2.39 + GLIBCXX_3.4.31 (GCC 13-era runtime — Ubuntu 24.04+ / Fedora 40+ / Arch). Release builds are pinned to Ubuntu 24.04 runners, and the release workflow gates the highest glibc/GLIBCXX symbol version every binary may require plus a startup smoke test, so this floor cannot silently drift upward (0.6.9 shipped x86_64 binaries requiring glibc 2.43 that way). TLS is rustls, so no OpenSSL dependency. Ubuntu 22.04 / RHEL or EL8/EL9 users: use the Docker image (dreamor/memvault) or build from source.

- Building from source (cargo install / cargo build): links fastembed's prebuilt ONNX Runtime static library and needs a GCC 13-class toolchain. Older toolchains (e.g. GCC 8, CentOS 7/8-era libstdc++) fail at link time with missing C++20/23 stdlib symbols (std::format, std::to_chars). macOS / Windows (MSVC) / Homebrew / Docker are unaffected.

Verify your install in 5 seconds:

memvault-cli --version

memvault 0.6.12

sanity check: list saved memories (verifies DB is healthy)

memvault-cli list

Local Ollama Demo (Zero Cost, Stays on Your Machine)

MemVault is plug-and-play with a local Ollama: unconfigured LLM extraction (full-text understanding / failure reflection / relation extraction) auto-detects a local Ollama; embeddings use the local model with the ollama or auto provider.

# 1. Install and start Ollama

brew install ollama && brew services start ollama # or the official installer

2. Pull models

ollama pull nomic-embed-text # embeddings, 768-dim (default for ollama/auto) ollama pull qwen2.5:3b-instruct # chat: LLM extraction/reflection (default qwen2.5:7b, use 3b on small machines)

3. (Optional) Pin the providers explicitly — persist them in ~/.memvault/.env

(shell exports also work — env vars take precedence over the file — but the file survives reboots)

mkdir -p ~/.memvault cat >> ~/.memvault/.env <<'EOF' MEMVAULT_EMBEDDING_PROVIDER=ollama MEMVAULT_LLM_EXTRACTION_PROVIDER=ollama MEMVAULT_LLM_EXTRACTION_MODEL=qwen2.5:3b-instruct EOF

4. Verify

memvault-cli status # Embedding provider: configured and reachable memvault-cli save --content "Build server IP is 10.20.30.40" # output (embedded int8) memvault-cli outcome --task "Deploy trading service" --status failure --cause "Disk space insufficient" --task-type deploy

→ Lesson (Llm): ... means failure reflection ran through the local LLM (not the rule-based fallback)

With no configuration at all (neither env vars nor ~/.memvault/.env), LLM extraction auto-detects a local Ollama and enables itself (default model qwen2.5:7b; pull it in advance with ollama pull qwen2.5:7b, or point MEMVAULT_LLM_EXTRACTION_MODEL at an installed model). Embeddings still default to the in-process native embedder; set MEMVAULT_EMBEDDING_PROVIDER=auto in ~/.memvault/.env to prefer Ollama and fall back to native when it isn't running. The native model's first launch downloads the weights from HuggingFace silently in the background — the server/dashboard come up immediately and hot-swap to semantic search once the download finishes, so a fresh install never blocks on it (set MEMVAULT_EMBEDDING_PROVIDER=none to run pure keyword and skip the download).

---

How It Works

MemVault is a pipeline, not a single script. Every stage below is a shipping module:

Agent connects (MCP stdio/SSE)

│ ▼ ┌───────────────────┐ │ Agent Router │ ← match agent type/tag → filter relevant memory │ (Agent Registry) │ └────────┬──────────┘ │ ▼ ┌───────────────────┐ │ Memory Retrieval │ ← keyword (BM25) + vector (embedding) + RRF fusion │ (3 search modes) │ synonym expansion · scoring · soft filtering └────────┬──────────┘ │ ▼ ┌───────────────────┐ │ Auto-Injection │ ← MUST-level → instruction prompt │ │ REFERENCE → context resource │ │ NORMAL → search result └────────┬──────────┘ │ ▼ Agent receives context ──→ makes better decisions

• Storage: SQLite with bundled FTS5 (full-text search); embeddings stored int8-quantized (~1/4 the size of f32 at near-identical ranking quality, legacy f32 rows still readable)
• Retrieval: BM25 keyword search over FTS5 with CJK bigram tokenization (Chinese two-character words match correctly) and tiered match fallback (strict → relaxed unigram → synonym OR; relaxations are reported, never silent), local-first embedding (in-process native by default — switch to local Ollama or any OpenAI-compatible model), RRF fusion with per-result recall provenance (kw#2/vec#5), synonym expansion, relevance scoring, soft intent filtering
• Pipeline: Automatic entity extraction, delta-write on save (near-duplicates skipped, similar memories absorb only the residual), semantic deduplication, time-based decay, archive of stale memories
• Sync: Zero-invasion file generation — memvault-cli sync produces CLAUDE.md, AGENTS.md, etc. directly from database contents

---

What MemVault Gives You

• Auto-Injected Context: Session start automatically pulls relevant memory by agent identity — MUST-level rules land as instructions, not just chat history
• Hybrid Retrieval: BM25 + vector + RRF fusion with synonym expansion, relevance scoring, and per-result provenance (which path recalled each memory, at what rank) — available via CLI, MCP tool, and REST API
• Explainable Injection: every candidate dropped on the way into an agent's context is recorded with a reason (budget, caps, intent/type penalties) — "why didn't the agent get this memory?" always has an answer
• MUST Enforcement: MUST-priority memories are never filtered or truncated. Always in context, always obeyed — trust comes from provenance (human-authored/r