mcp-memory-vault

# mcp-memory-vault

MCP server that gives any agent persistent memory — namespaced facts with tags, SQLite FTS5 full-text search, TTL expiry and zero external dependencies.

Why

Agents forget everything the moment a session ends. User preferences, project decisions, environment quirks, customer details — all gone, re-learned (or re-asked) every single time. mcp-memory-vault fixes that with a tiny local SQLite vault: any MCP client (Claude Desktop, Claude Code, or your own agent) can store facts as it works and recall them in any later session with ranked full-text search. Facts can be scoped by namespace, labeled with tags, and given a TTL so short-lived context expires on its own. Everything runs locally on the Python standard library — no external services, no API keys, no vector database.

Related MCP server: persistent-kb-mcp

Tools

How it works

flowchart LR
    A[Agent / MCP client] -- stdio --> S[server.py<br/>FastMCP wiring]
    S --> C[core.py<br/>MemoryVault]
    C -- "purge expired (every op)" --> DB[(SQLite WAL<br/>~/.mcp-memory-vault/memories.db)]
    DB -- triggers keep in sync --> FTS[FTS5 index<br/>memories_fts]
    C -- "recall: MATCH + bm25" --> FTS
    C -. "no FTS5 in this build?<br/>LIKE fallback (AND terms)" .-> DB

Every read or write first purges expired rows, so TTLs need no background process. If the local SQLite build lacks FTS5, the vault detects it at startup and falls back to a term-wise LIKE search — memory_stats tells you which mode is active. Set the MEMORY_VAULT_DB environment variable to relocate the database file.

Quickstart

pip install -e .

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "memory-vault": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Claude Code:

claude mcp add memory-vault -- python /absolute/path/to/server.py

Example session

A support agent learns something today and uses it next week — in a completely new session.

Session 1 (Monday):

User: Heads up — ACME told us they only want production deploys on Fridays. Keep that in mind.

Agent: Noted — I'll store that so I remember it in future sessions.

Calls remember(content="Customer ACME prefers deploys on Fridays", namespace="support", tags=["customer", "deploy"], source="user note 2026-07-20")

→ {"id": 14, "deduplicated": false, "message": "Stored memory 14 in namespace 'support'."}

Agent: Saved. I'll recall ACME's Friday-only deploy preference whenever deployment scheduling comes up.

Session 2 (a week later, fresh context):

User: ACME's fix is ready. When should we ship it?

Agent: Let me check what I know about ACME's deploy preferences.

Calls recall(query="ACME deploy", namespace="support")

→ {"count": 1, "search_mode": "fts5", "hits": [{"id": 14, "snippet": "Customer [ACME] prefers [deploys] on Fridays", "tags": ["customer", "deploy"], "age": "1 week ago"}]}

Agent: ACME prefers deploys on Fridays (noted a week ago from your message). Today is Wednesday — I'd schedule the release for this Friday.

Development

pip install -e ".[dev]"
python -m pytest

Tests exercise core.py directly and run without the mcp package installed.

License

MIT