使用说明

Persistent Memory MCP

Your coding tools forget. Persistent Memory MCP remembers.

Local-first persistent project memory and context compilation for MCP-compatible development agents.

Documentation · Quick start · Roadmap · Implementation status · Contribute

Release status — 2026-08-16: v0.3.0 has a fully validated immutable release candidate, but the public GitHub Release and PyPI publication are still pending. Until PyPI publication is verified, install from this repository instead of assuming pipx install persistent-memory-mcp is available publicly. See Releasing and Issue #53.

What is Persistent Memory MCP?

Persistent Memory MCP is an open-source Model Context Protocol server that gives coding assistants durable, searchable project memory. It stores architecture, technical decisions, tasks, warnings, repository evidence, checkpoints and continuation state so compatible clients can resume work without reconstructing the project from scratch.

The product is intentionally personal and local-first:

one local installation;
SQLite by default;
localhost-only Dashboard and Galaxy UI;
explicit owner/project isolation;
no automatic execution of repository code;
optional self-managed Supabase/PostgreSQL adapters;
no hosted team workspace, public collaborative dashboard or SaaS role hierarchy.

Core capabilities

Capability	What it provides
Durable project memory	Decisions, tasks, warnings, checkpoints, sessions and file context survive client restarts
Git-aware context	Bind memory and repository evidence to repository, branch and commit state
Context Packet v1	Versioned, provenance-aware context under a hard token budget
Progressive retrieval	Expand repository map → files → symbols → exact fragments instead of loading whole repos
Persistent symbol evolution	Track logical symbols across commits, moves and conservative rename matches
Context-quality gates	Detect retrieval, token-budget, provenance and safety regressions in CI
Operational map / Galaxy	Inspect bounded owner-scoped project risk and evidence relationships
Automatic continuation	Persist bounded resume-ready state for close, handoff and idle expiry
Deterministic pagination	Stable owner/project-scoped keyset pagination with bounded cursors
Verified backup	WAL-safe SQLite backup with integrity validation and SHA-256 manifest
Health diagnostics	Read-only SQLite integrity, foreign-key, disk and backup-readiness checks
Confirmed restore	Preview → signed confirmation → safety backup → atomic restore → verification/rollback
Versioned migrations	Explicit, backup-first, checksum-verified schema upgrades
Confirmed deletion	Exact scoped preview plus short-lived single-use confirmation
Private Dashboard	Localhost-only operational and maintenance UI
Application composition	Explicit `create_application(settings)` runtime composition boundary
Idempotent MCP Tool Registry	Centralized dynamic tool registration/replacement through public MCP APIs

Quick start

1. Install from the repository

Public PyPI publication is not yet complete. Use the validated source tree for now:

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

For a non-editable installation from the repository:

pip install "git+https://github.com/dannymaaz/memory-mcp.git"

After v0.3.0 is published and publicly smoke-tested on PyPI, the intended package command is:

pipx install persistent-memory-mcp

Do not rely on that PyPI command until Issue #53 records successful public installation evidence.

2. Initialize the local installation

memory-mcp init

The normal local database is:

~/.memory-mcp/memory.db

3. Check the installation

memory-mcp doctor
memory-mcp status
memory-mcp health

For full SQLite integrity validation:

memory-mcp health --full

4. Register it in an MCP client

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

The server uses stdio when launched by an MCP client. It can also be started manually:

memory-mcp serve

Optional storage adapters

SQLite is the default and recommended local path. Remote adapters are opt-in and self-managed:

pip install -e ".[supabase]"
pip install -e ".[postgresql]"

These adapters do not change the product into a hosted multi-user service.

MCP SDK compatibility

Current post-v0.3 main uses the installed MCP Python SDK v2 MCPServer API and constrains the dependency to:

mcp>=2,<3

The runtime has no local MCP fallback. Dynamic tools are registered or replaced through the public MCP v2 add_tool() / remove_tool() APIs, while the existing application-level handler/schema mirrors remain synchronized.

The immutable v0.3.0 release candidate is intentionally separate: it remains pinned to its already validated MCP v1 compatibility state and must not be rebuilt from current main. See MCP SDK compatibility and Issue #53.

Context Compiler

The completed Context Compiler phase adds five evidence-driven layers:

Context Packet + token accounting — PR #60 / Quality #226.
Progressive repository retrieval — PR #62 / Quality #235.
Persistent code provenance/symbol evolution — PR #64 / Quality #250.
Context-quality and adversarial regression gates — PR #66 / Quality #262.
Operational project map / risk-oriented Galaxy — PR #68 / Quality #282.

See:

Data-safety model

Persistent Memory MCP treats destructive local operations as explicit workflows, not hidden maintenance:

migrations are previewed and applied explicitly;
existing stale schemas fail closed on serve rather than auto-migrating;
restore requires a signed plan tied to the exact backup state;
restore creates a verified safety backup immediately before replacement;
deletion requires an exact preview and short-lived single-use confirmation;
backup verification uses SHA-256 manifests without storing memory contents in the manifest;
Dashboard maintenance remains bound to localhost.

See Upgrading, Releasing and Security Policy.

Upgrading from 0.2.0

Version 0.3.0 introduces explicit versioned SQLite migrations. Existing databases are never silently migrated on MCP startup.

Preview first:

memory-mcp-migrate --env ~/.memory-mcp/.env

Apply only after reviewing the plan:

memory-mcp-migrate --env ~/.memory-mcp/.env --apply --yes

The apply step creates a verified pre-migration backup before mutation. Keep the backup and its JSON manifest until the upgraded installation has been verified.

v0.3.0 release chain

The public v0.3.0 release must be created from the immutable release-only commit:

9e0a084dd9b179612082edef99e1c3c9bf563ffa

That commit was produced by PR #89 after Quality #361 passed the complete Ubuntu/Windows/macOS × Python 3.11–3.13 release matrix, release artifact checks and installed v0.2.0 upgrade validation.

Current main includes later post-v0.3 work — including the MCP v2 runtime migration — and must not be tagged as v0.3.0.

The repository-side PyPI workflow was merged in PR #91 after Quality #368. It requires the future v0.3.0 GitHub Release to resolve exactly to the immutable release commit, downloads its wheel/sdist/SHA256SUMS, verifies them and publishes those exact distributions through PyPI Trusted Publishing without rebuilding them.

Remaining release operations are tracked in Issue #53.

Development validation

The Quality workflow covers:

Ubuntu, Windows and macOS;
Python 3.11, 3.12 and 3.13;
compile and Ruff lint checks;
unit/integration tests;
agent evaluation regressions;
Context Compiler reference gates;
dependency audit including optional extras;
wheel/sdist build and metadata validation;
SHA-256 release checksums;
clean wheel installation;
installed v0.2.0 → candidate upgrade validation.

Run the core local checks with:

python -m compileall persistent_memory_mcp src tests
ruff check .
pytest -q

Documentation

Security

Do not report suspected vulnerabilities in a public issue. Follow SECURITY.md for private reporting guidance.

Contributing

Contributions are welcome when they preserve the local-first safety boundary and include appropriate deterministic tests. See CONTRIBUTING.md.

License

MIT — see LICENSE.