mem0-mcp

mem0-mcp

MCP server exposing Mem0 v2 API for AI agents to store, retrieve, and search long-term memories using semantic search through the standardized MCP protocol.

Overview

Mem0-MCP Server is a self-hosted MCP (Model Context Protocol) server that bridges AI agents with persistent memory storage. It enables intelligent context retention across conversations and sessions using Mem0's AsyncMemory API.

Key Features:

• MCP Protocol Integration - Exposes Mem0 functionality via MCP tools
• Semantic Memory Search - Similarity-based memory retrieval with vector search
• Multi-Tenant Isolation - User/Agent/Session scoped memory isolation
• Flexible Transport - stdio for local agents, SSE for remote connections
• Configuration Management - Pydantic-based validation with environment variable support

Documentation

Quick Start

Installation

# Clone and install
git clone https://github.com/your-org/mem0-mcp.git
cd mem0-mcp
uv sync

# Set environment variables
export OPENAI_API_KEY="your-api-key"

Configuration

Create ~/.config/mem0-mcp-server/settings.json:

{
  "vector_store": {
    "provider": "redis",
    "config": {
      "redis_url": "redis://localhost:6379"
    }
  },
  "llm": {
    "provider": "openai",
    "config": {
      "model": "gpt-4o"
    }
  },
  "embedder": {
    "provider": "openai",
    "config": {
      "model": "text-embedding-3-small"
    }
  }
}

Running the Server

# SSE Transport (remote connections)
uv run python -m mcp_server.main

# stdio Transport (local AI agents)
export MCP_TRANSPORT=stdio
uv run python -m mcp_server.main

MCP Tools

Usage Example

# Add memory
result = await client.call_tool("add_memory", {
    "messages": [{"role": "user", "content": "I prefer dark mode"}],
    "user_id": "alice"
})

# Search memories
result = await client.call_tool("search_memories", {
    "query": "theme preferences",
    "filters": {"user_id": "alice"},
    "limit": 5
})

Architecture

AI Agent → FastMCP Server → MemoryManager → Mem0 AsyncMemory → Redis
              │                                  │
              ├── SafeLogger (stdout/stderr)    │
              ├── Transport (stdio/SSE)        │
              └── Config (Pydantic validation)  │

Components:

• COMP-1: ConfigLoader - Configuration loading and validation
• COMP-2: FastMCP Server - MCP protocol server
• COMP-3: MemoryManager - Memory operations with multi-tenant isolation
• COMP-4: MCP Tools - Tool definitions
• COMP-5: SafeLogger - Output stream separation

Configuration

Parameter Precedence

Configuration values are resolved in order:

1. Tool parameters (direct)
2. Environment variables (with MCP_ prefix)
3. Config file values
4. Hardcoded defaults

Environment Variables

Deployment

Docker

# Using docker-compose
docker-compose up -d

# Using Makefile
make docker-up      # Start services with docker compose
make docker-down    # Stop services
make docker-logs    # Show logs

Services:

See Deployment → Docker for detailed configuration.

Kubernetes

# Using Helm chart
helm install mem0-mcp ./charts/mem0-mcp-server

Development

Run multiple commands: make install && make lint && make typecheck && make test

See Makefile for all available commands including Docker management (docker-up, docker-down, docker-logs, etc.).

Project Structure

mem0-mcp/
├── src/mcp_server/
│   ├── __init__.py          # FastMCP singleton
│   ├── lifespan.py          # Resource lifecycle
│   ├── transport.py         # Transport selection
│   ├── memory/
│   │   ├── manager.py        # MemoryManager
│   │   └── lifespan.py       # AsyncMemory lifecycle
│   ├── config/
│   │   ├── settings.py       # Pydantic models
│   │   └── loader.py        # Config file loading
│   ├── tools/
│   │   ├── add_memory.py
│   │   ├── search_memories.py
│   │   └── ...
│   └── utils/
│       └── safe_logger.py   # Output separation
├── doc/
│   ├── api/                 # API reference
│   ├── patterns/            # Pattern guides
│   ├── examples/            # Usage examples
│   └── architecture/        # Architecture docs
├── tests/
├── Makefile
├── Dockerfile
└── docker-compose.yml

License

MIT License