Local MCP server for persistent, searchable agent memory

Python 3.13+ MCP stdio SQLite FTS5 Debian 13 GPL v3+

Install

git clone https://github.com/cpntodd/MCPSaver.git && cd MCPSaver && uv sync

Requires Python >= 3.13 and uv. Dependencies are managed entirely through uv — no system-wide pip installs needed.

VS Code / Claude Desktop Configuration

Add to your MCP client config (mcp.json for VS Code):

{
    "servers": {
        "mcpsaver": {
            "type": "stdio",
            "command": "uv",
            "args": [
                "--directory", "/path/to/MCPSaver",
                "run", "mcpsaver"
            ]
        }
    }
}

Features

FTS5 Full-Text Search

SQLite FTS5 with porter stemming. Term-OR queries for broad recall across all lessons. Find relevant past corrections in ~50 tokens instead of reading an entire flat file.

Workspace Context Caching

Cache detected stack, linter, formatter, and file tree per workspace. Skip redundant project discovery at the start of every session.

Code Symbol Indexing

Index functions, classes, and methods with file paths. Query find_prior_art before writing new code to check if something similar already exists.

MEMORY.md Importer

Migrate from flat Markdown memory files. The import_memory_md tool parses the standard format and populates the SQLite database.

Local & Private

Everything runs locally over stdio. No network calls, no cloud storage, no API keys. Your agent memory stays on your machine in a single SQLite file.

Structured Lesson Types

Six lesson categories: convention, self_correction, human_correction, api_fact, decision, pattern. Tagged and timestamped for precise retrieval.

Why

Flat Markdown memory files force the agent to read the entire file to find one relevant lesson, burning thousands of tokens on irrelevant history. MCPSaver gives the agent queryable long-term memory with selective retrieval:

Operation Flat MEMORY.md MCPSaver
Find a past lesson Read entire file (~2000 tokens) search_memory("pytest fixture") (~50 tokens)
Load project context Run git status, read manifests (~500 tokens) get_workspace_context() (~30 tokens)
Record a new lesson Append to MEMORY.md manually record_lesson(...) (indexed, timestamped)
Check prior art Grep codebase (~300 tokens) find_prior_art(symbol="...") (~20 tokens)

Tools

MCPSaver exposes 9 MCP tools to the agent:

Tool Purpose
record_lesson Store a lesson, correction, or convention into persistent memory
search_memory Full-text search across all recorded lessons with FTS5
get_workspace_context Retrieve cached project context (stack, linter, file tree)
set_workspace_context Cache project context for future sessions
find_prior_art Search indexed code symbols for prior usage
index_symbols Index code symbols for a workspace
list_lessons List recent lessons with optional filters
get_stats Return memory database statistics
import_memory_md Import lessons from a flat MEMORY.md file

Architecture

flowchart LR A[Agent / LLM] -->|"JSON-RPC over stdio"| B[MCP Server] B --> C[(SQLite + FTS5)] B --> D[memory.db] subgraph MCPSaver B end subgraph Storage C D end C --> E[lessons table] C --> F[workspace_context table] C --> G[code_symbols table] C --> H[lessons_fts FTS5 index] B -->|"record_lesson"| E B -->|"search_memory"| H B -->|"get/set_workspace_context"| F B -->|"find_prior_art / index_symbols"| G

The MCP server speaks JSON-RPC over stdin/stdout. All data lives in a single SQLite file at ~/.local/share/mcpsaver/memory.db.