MCPSaver

Local MCP server for persistent, searchable agent memory.

<img src="assets/banner.gif" alt="MCPSaver banner" width="100%">

Full landing page: cpntodd.github.io/MCPSaver

MCPSaver replaces flat MEMORY.md files with a SQLite database behind a Model Context Protocol (MCP) server. It provides full-text search (FTS5), workspace context caching, and code symbol indexing -- all running locally over stdio.

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)

Install

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

Requires Python >= 3.13.

VS Code Configuration

Add to your VS Code mcp.json (User or Workspace settings):

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

Or use the Claude Desktop / Cursor equivalent for your MCP client.

Tools

record_lesson

Store a lesson, convention, or correction into persistent memory.

record_lesson(
    lesson_type: "convention" | "self_correction" | "human_correction" | "api_fact" | "decision" | "pattern",
    context: string,
    correction: string,
    mistake?: string,
    pattern?: string,
    tags?: string[],
    workspace?: string
)

search_memory

Full-text search across all lessons using SQLite FTS5 with porter stemming.

search_memory(
    query: string,
    limit?: int (default 10),
    tags?: string[]
)

get_workspace_context / set_workspace_context

Cache and retrieve project metadata (stack, linter, formatter, file tree).

get_workspace_context(workspace: string)
set_workspace_context(
    workspace: string,
    stack?: string[],
    linter?: string,
    formatter?: string,
    test_runner?: string,
    file_tree?: string,
    conventions?: object
)

find_prior_art / index_symbols

Search indexed code symbols to find prior usage of functions, classes, or patterns.

find_prior_art(
    workspace: string,
    symbol?: string,
    kind?: string,
    limit?: int
)

index_symbols(
    workspace: string,
    symbols: [{symbol, kind?, file_path, line?, snippet?}],
    clear_first?: bool
)

list_lessons

List recent lessons with optional type/workspace filters.

get_stats

Return summary statistics about the memory database.

import_memory_md

Import existing MEMORY.md flat files into the SQLite database.

Architecture

~/.local/share/mcpsaver/memory.db   <-- SQLite database (auto-created)
    |
    +-- lessons           <-- Core lessons table (all memory entries)
    +-- lessons_fts       <-- FTS5 full-text index (porter stemming)
    +-- workspace_context <-- Cached project metadata per workspace
    +-- code_symbols      <-- Indexed code symbols per workspace

Storage

All data lives in ~/.local/share/mcpsaver/memory.db. Nothing leaves the machine. The MCP server communicates exclusively over stdio with no network access.

License

GPL-3.0-or-later

---

(c) 2026 cpntodd