MemMCP

🤔 The Problem with Agentic Memory

When dozens of autonomous agents operate in parallel, standard vector memory stores break down:

• Race conditions: Simultaneous writes cause index corruption.

• Data duplication: Agents save the same observations repeatedly, polluting context windows.

• Context hallucination: Lexical keywords are ignored in favor of vague semantic matches.

Related MCP server: agent-memory

💡 The MemMCP Solution

MemMCP is a lightweight, zero-latency, local memory daemon. It runs silently over STDIO via the Model Context Protocol, offering a robust engine that guarantees:

• ACID-Compliant State: Backed by SQLite in Write-Ahead Log (WAL) mode.

• Deduplication Gate: Uses Bloom-Filter idempotency tracking to drop duplicate records before vectorization.

• Hybrid RRF Retrieval: Blends FAISS vector search with SQLite FTS5 lexical keyword matching under Reciprocal Rank Fusion (RRF).

⚡ Quick Start

Prerequisites

• Python 3.11+

• uv (recommended for package management) or standard pip

1. Clone & Install

git clone https://github.com/axtontc/MemMCP.git
cd MemMCP

# Sync virtual environment using uv (fastest)
uv sync

# Or using pip
python -m venv .venv
.venv/Scripts/activate  # On Windows
source .venv/bin/activate  # On Linux/macOS
pip install .

2. Verify with the Test Suite

Ensure everything is working correctly:

# Run unit tests
uv run python -m pytest tests/test_memmcp.py -v

# Run E2E STDIO integration tests
uv run python tests/e2e_test.py

🔌 MCP Integration (Cursor & Claude)

MemMCP integrates seamlessly into MCP-compatible editors and clients like Cursor or Claude Desktop.

1. Claude Desktop Config

Add the following to your claude_desktop_config.json (located at %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "memmcp": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/absolute/path/to/MemMCP",
        "run",
        "python",
        "src/server.py"
      ],
      "env": {
        "MEMMCP_DB_PATH": "C:/absolute/path/to/memmcp.db",
        "MEMMCP_LOG_PATH": "C:/absolute/path/to/memory_wal.log"
      }
    }
  }
}

2. Cursor IDE Config

1. Navigate to Settings → Features → MCP.

2. Click + Add New MCP Server.

3. Fill out the dialog:

   • Name: memmcp

   • Type: command

   • Command: uv --directory "C:/path/to/MemMCP" run python src/server.py

4. Click Save.

🏗 Architecture

graph TD
    A[MCP Client / Agent] --> B{Bloom-Filter Idempotency}
    B -->|Duplicate Request| C[Fast Return / Drop]
    B -->|New Request| D[SentenceTransformer Vectorizer]
    D --> E[FAISS Vector Matching]
    D --> F[SQLite FTS5 Keyword Match]
    E & F --> G[Reciprocal Rank Fusion RRF]
    G --> H[SQLite WAL Transaction Ledger]
    H --> I[XML-Bounded RAG Output]
    I --> J[MCP Response]

    style A fill:#1a1a2e,stroke:#0969DA,color:#fff
    style B fill:#16213e,stroke:#0969DA,color:#fff
    style E fill:#0f3460,stroke:#2ea043,color:#fff
    style F fill:#0f3460,stroke:#2ea043,color:#fff
    style G fill:#1a1a2e,stroke:#F5A800,color:#fff
    style H fill:#1a1a2e,stroke:#F5A800,color:#fff

Key Subsystems

🛠 MCP Tool Reference

MemMCP automatically registers the following tools with the connected LLM:

store_memory

Saves a single string memory block.

• Arguments:

  • content (string, required): The memory string to store.

  • idempotency_key (string, optional): A unique key to prevent duplicate writes.

• Returns: A confirmation string containing the generated unique memory ID.

store_memories_batch

Stores multiple memories atomically in a single transaction, rebuilding the vector index only once at the end of the batch.

• Arguments:

  • memories (array of strings, required): List of memory strings to insert.

• Returns: A JSON array of generated memory IDs.

recall_memories

Retrieves memories matching a search query using Reciprocal Rank Fusion.

• Arguments:

  • query (string, required): The search text.

  • limit (integer, optional): Maximum number of memories to return (default: 5).

• Returns: A JSON array of matching records containing ID, content, and scores.

📖 API & Core Functions Reference

src/database.py

These functions manage SQLite connection states, memory inserts, and migrations:

src/retrieval.py

These functions run queries against the semantic and keyword indices:

📊 Comparison

🧰 Tech Stack

• Language: Python 3.11+

• Vector Search: FAISS CPU

• Embeddings: sentence-transformers (all-MiniLM-L6-v2)

• Database: SQLite 3 (WAL mode + FTS5 full-text extension)

• Dev tools: pytest, pytest-asyncio, Ruff, mypy

🗺️ Roadmap

• SentencesTransformer semantic vector indexing

• Full-Text-Search FTS5 keyword matching

• Deduplication gate with Bloom filters

• Reciprocal Rank Fusion (RRF) blending algorithm

• Distributed Replication — Sync memory states across swarm nodes using Raft consensus

• Multi-tenant Spaces — Provide isolated user space environments and custom credentials keys

• Timeline Visualizer Dashboard — Open-source local dashboard showing memories timeline maps

🤝 Contributing & Security

Contributions are welcome! Please read our Contributing Guide and Code of Conduct before submitting pull requests.

For reporting security vulnerabilities, please refer to SECURITY.md.

🔗 Related Projects

MemMCP belongs to a suite of interconnected AI agent utilities:

📜 License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details. Copyright (c) 2026 Axton Carroll.