Memory MCP — Cross-Tool Project Context & Memory Server

A persistent, shared, selective memory layer for LLM clients (Claude, Cursor, ChatGPT, IDEs), built on the Model Context Protocol.

LLMs forget everything between sessions and across tools, so developers keep re-explaining their stack, project architecture, workflows, and decisions. Pasting old chats does not scale — it overflows the context window, replays past mistakes, leaks secrets, and goes stale the moment a decision changes.

Memory MCP is the brain on top of storage: it extracts durable facts from noisy conversations (like architecture, module responsibilities, workflows, decisions, and stack choices), deduplicates them, resolves conflicts as beliefs change, and surfaces only the handful of relevant facts for the current task — to every connected tool, automatically.

Storing text is the easy 10%. Memory MCP does the hard 90%: extract → dedupe → index → retrieve-the-right-bit → resolve conflicts → expire.

Why Not Just Paste Chats / Read a Flat File?

Related MCP server: CCCMemory MCP

Architecture

flowchart LR
    subgraph Clients["MCP Clients"]
        C1[Claude Desktop]
        C2[Cursor]
        C3[ChatGPT / IDEs]
    end
    C1 & C2 & C3 -->|MCP Protocol / stdio / SSE| SRV[FastMCP Server<br/>remember · recall · ingest]
    SRV --> MM[MemoryManager<br/>orchestrator]

    subgraph Write["Write path"]
        EX[Fact Extractor] --> PII[PII Filter] --> EMB[Embedder] --> DIS[Distiller<br/>dedup · conflict]
    end
    subgraph Read["Read path"]
        Q[Embed query] --> VS[(Vector Store)] --> RK[Ranker<br/>relevance+recency+importance] --> PK[Token-budget pack]
    end

    MM --> Write --> VS
    MM --> Read
    MM --> AUD[(Audit Log)]

Every component is designed with a pluggable interface and clean offline defaults, so the entire system runs out-of-the-box with zero configuration and zero API keys — then seamlessly upgrades in place when advanced backends are installed.

Quick Start

1. Installation

Clone the repository and install dependencies:

git clone https://github.com/mrunmayeekokitkar/Memory-MCP.git
cd Memory-MCP

# Install core dependencies (lightweight, zero cloud dependencies required)
pip install -r requirements.txt
pip install -e .

2. Run the Verification Demo

Walk through the entire 6-stage memory pipeline in your terminal:

python examples/demo.py

This demonstrates:

1. Conversation Ingestion & Distillation: Parsing multi-turn dialogue into structured facts.

2. Conflict Resolution: Changing a belief (e.g., Postgres → MySQL) supersedes old facts automatically.

3. Hybrid Ranked Recall: Fetching facts scored by relevance, recency, and importance.

4. PII Masking: Automatic redacting of phone numbers, emails, and credentials.

5. Scope & Project Isolation: Enforcing boundary checks across different projects.

6. Immutable Audit Trail: Chronological event logs for enterprise governance.

3. Run the Test Suite

Ensure full test coverage passes locally:

pytest -q

Connecting to MCP Clients

Running the Server

• Standard I/O (Default for desktop clients like Claude and Cursor):

  python -m memmcp.server
  # or via the console script:
  memmcp

• SSE Transport (Network / Remote HTTP transport):

  python -m memmcp.server --transport sse --host 127.0.0.1 --port 8000

Claude Desktop Configuration

Add the following to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "memory-mcp": {
      "command": "python",
      "args": ["-m", "memmcp.server"],
      "env": {
        "MEMMCP_DATA_DIR": "./.memmcp_data",
        "MEMMCP_EMBEDDING_PROVIDER": "hash",
        "MEMMCP_VECTOR_BACKEND": "numpy",
        "MEMMCP_EXTRACTION_PROVIDER": "rule",
        "MEMMCP_PII_POLICY": "redact"
      }
    }
  }
}

Restart Claude Desktop, and Memory MCP will appear under the hammer / tools icon.

MCP Tools Exposed to LLMs

Resources exposed:

• memmcp://stats: Real-time system statistics and vector index sizes.

• memmcp://audit: Tail of the security and mutation audit log.

Semantic Project Knowledge Engine

When configured with an LLM backend (openai or anthropic), Memory MCP categorizes and indexes project facts into 8 structured categories:

• Identity: User, team, and contributor preferences.

• Stack: Technology choices (frameworks, runtime versions, databases).

• Project: High-level purpose, architecture, and deployment targets.

• Modules: Module boundaries, component interfaces, and responsibilities.

• Workflows: CI/CD processes, deployment pipelines, testing routines.

• Decisions: Architectural Decision Records (ADRs) and design rationales.

• Domain: Project-specific vocabulary and business terminology.

• Status: Current milestones, active bugs, and technical debt.

Core Engineering & Algorithms

• Hybrid Ranking: Blends vector cosine similarity, half-life recency decay ($e^{-\lambda \Delta t}$), and user-assigned importance into a composite score, dynamically packed to fit token budgets.

• Fact Distillation & Conflict Detection: Automatically canonicalizes keys (user:database, stack:framework). When a contradicting assertion arrives, the engine supersedes prior facts while preserving historical audit records.

• Privacy & Security: Built-in regex engine with Luhn algorithm validation masks API keys, JWTs, emails, phone numbers, and payment details before data reaches the vector store.

• Hierarchical Scoping: Strict project and workspace partitioning prevents context leaks between unrelated projects.

Configuration Reference

Override any setting via .env or system environment variables:

Project Structure

Memory-MCP/
├── src/memmcp/
│   ├── server.py            # FastMCP server & tool endpoints
│   ├── memory_manager.py    # Core pipeline orchestrator
│   ├── config.py            # Environment-driven configuration
│   ├── models.py            # Pydantic models & data contracts
│   ├── scoping.py           # Project namespace & isolation logic
│   ├── embeddings/          # Pluggable embeddings (Hash, Local, OpenAI)
│   ├── store/               # Vector stores (Numpy, Chroma)
│   ├── retrieval/           # Ranking & token-budget packing
│   ├── extraction/          # Fact extraction, distillation & conflict judge
│   └── privacy/             # PII detection & append-only audit trail
├── tests/                   # Pytest test suite (87 tests)
├── examples/                # End-to-end demo and client configurations
├── pyproject.toml           # Build system and package metadata
├── requirements.txt         # Core dependencies
└── README.md                # Project documentation

License

This project is licensed under the MIT License.