# MCPSaver

**Local MCP server for persistent, searchable agent memory.**

[![Python](https://img.shields.io/badge/Python-3.13%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-stdio-f09040?style=flat-square)](https://modelcontextprotocol.io)
[![SQLite](https://img.shields.io/badge/SQLite-FTS5-003B57?style=flat-square&logo=sqlite&logoColor=white)](https://sqlite.org/fts5.html)
[![License](https://img.shields.io/badge/license-GPL%20v3%2B-BD0000?style=flat-square)](LICENSE)

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

> Full landing page: [cpntodd.github.io/MCPSaver](https://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

```bash
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):

```json
{
    "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