MCP 服务器

MCPSaver

Local MCP server for persistent, searchable agent memory using SQLite FTS5, replacing flat MEMORY.md files with efficient full-text search and workspace context caching.

README

MCPSaver

Local MCP server for persistent, searchable agent memory.

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.