Memory MCP

What is Persistent Memory MCP?

Persistent Memory MCP is an open-source Model Context Protocol server that gives development assistants durable, searchable project memory. It stores architecture, technical decisions, tasks, warnings, file relationships, checkpoints and session state in a private local database so another compatible client can continue the work without asking you to explain the project again.

The intended product is personal and local-first: one local installation, one private dashboard and isolated memory for the projects owned by that installation. Remote team workspaces, shared memberships and multi-user roles are intentionally outside the product scope.

Before: “Can you explain the repository again?”
After: “The authentication refactor is in progress, RLS is the active risk, and the next task is token rotation.”

Related MCP server: memory-mcp

Why developers use it

Quick start

1. Install

pipx install persistent-memory-mcp

For development installs:

git clone https://github.com/dannymaaz/memory-mcp.git
cd memory-mcp
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\Activate.ps1
pip install -e .

2. Configure interactively

memory-mcp init

The setup command creates a private configuration, initializes the local SQLite database and generates an MCP configuration block for supported clients. The default local database is ~/.memory-mcp/memory.db.

Supabase and PostgreSQL adapters remain available for advanced self-managed storage, but the product direction and dashboard are local and personal.

3. Diagnose the installation

memory-mcp doctor
memory-mcp status

4. Add it to your MCP client

{
  "mcpServers": {
    "persistent-memory-mcp": {
      "command": "memory-mcp",
      "env": {
        "MEMORY_STORAGE_BACKEND": "sqlite",
        "OWNER_ID": "your-stable-local-identifier",
        "MEMORY_CONFIRMATION_SECRET": "your-private-confirmation-secret"
      }
    }
  }
}

The command starts over stdio automatically when your MCP client launches it. You can also run it manually with memory-mcp serve.

Natural-language examples

Resume this project and tell me where we left off.
Save the architecture decision we just made.
Show active warnings before changing authentication.
Search project memory for the database migration decision.
Preview deletion of these completed task records.
Execute the unchanged deletion plan with its confirmation token.

How it works

MCP client A ─────┐
MCP client B ─────┼── Model Context Protocol ── Persistent Memory MCP ── Local SQLite
MCP client C ─────┘                                      │
                                                         ├─ decisions
                                                         ├─ tasks
                                                         ├─ warnings
                                                         ├─ sessions
                                                         ├─ file memory
                                                         └─ checkpoints

The server detects repository context, resolves or creates the current project, stores structured memories and returns an optimized resume context to compatible clients.

Main MCP tools

Advanced tools remain available for checkpoints, timelines, retention, prompts, analytics, embeddings, code intelligence and file relationships.

Confirmed deletion safety model

Deletion is a two-phase local operation:

1. plan_memory_deletion returns a dry-run preview, exact record IDs, counts, fingerprint, expiry and confirmation token.

2. execute_memory_deletion revalidates owner/project scope and current records, rejects altered, expired or reused plans, and deletes only exact planned IDs.

Retention cleanup uses the same preview-and-confirm contract. No retention deletion runs automatically at startup. Audit events record operation metadata and counts without copying deleted content.

Privacy and security

• The dashboard binds only to localhost and rejects remote interfaces.

• The default database is a private SQLite file under the user's home directory.

• Every memory operation is scoped by owner and project.

• Sensitive values are redacted before persistence.

• Destructive operations require a short-lived confirmation tied to an exact plan.

• Keep local configuration and confirmation secrets private.

• Create verified backups before upgrades, migrations or destructive maintenance.

Product scope

Persistent Memory MCP is not a collaborative SaaS. Workspace invitations, team memberships, owner/admin/member/reader roles, public remote dashboards, billing and organization administration are out of scope.

Roadmap

• Persistent project, task, decision and warning memory

• Git-aware project resolution

• Cross-client session continuity foundation

• Semantic search with lexical fallback

• Import, export, timeline and retention foundations

• Interactive init, doctor and status commands

• Local SQLite starter mode

• Localhost-only visual memory dashboard

• Automatic nested secret redaction

• Provider-based embedding generation and reindexing

• Selective deletion and confirmed retention execution

• Verified local backup and restore workflow

• Dashboard pagination and operational summary cards

• Complete automatic continuation checkpoints

• Package publication, upgrades and MCP Registry release

Documentation

Public documentation covers installation, client configuration, architecture, data model, API reference, troubleshooting and English/Spanish guidance.

Visit: https://dannymaaz.github.io/memory-mcp/

Contributing

Contributions are welcome. Read CONTRIBUTING.md, open an issue, or submit a pull request.

License

MIT License. See LICENSE.

Author

Created and maintained by Danny Maaz.