MCP HubMCP Hub
pinkpixel-dev

mem0-mcp

by: pinkpixel-dev

✨ mem0 MCP Server: A modern memory system for AI applications with flexible provider support (OpenAI, Ollama, etc.) and MCP protocol integration. Enables long-term memory for AI agents through a simple API or as a drop-in MCP server.

35created 12/03/2025
Visit
memory
AI

📌Overview

Purpose: The mem0 memory system is designed to provide flexible memory capabilities for AI applications, allowing integration either as a server (MCP) or as a direct library.

Overview: The mem0 framework supports multiple providers and offers both server-based and library integration options for efficient memory management. It's suitable for developers looking to enhance their applications with autonomous memory features that automatically store and retrieve relevant information.

Key Features:

  • Multi-Provider Support: Compatible with various AI providers like OpenAI, Anthropic, and Google, enabling users to leverage the best available options for memory capabilities.

  • Autonomous Memory: Automatically extracts, stores, and retrieves user information, enhancing user interaction without the need for explicit commands.

@pinkpixel/mem0-mcp MCP Server ✨

A Model Context Protocol (MCP) server that integrates with Mem0.ai to provide persistent memory capabilities for large language models (LLMs). It allows AI agents to store and retrieve information across sessions.

This server uses the mem0ai Node.js SDK for its core functionality.

Features 🧠

Tools

  • add_memory: Stores a piece of text content as a memory associated with a specific userId.
    Input: content (string, required), userId (string, required), sessionId (string, optional), agentId (string, optional), metadata (object, optional)
    Stores the provided text, enabling recall in future interactions.

  • search_memory: Searches stored memories based on a natural language query for a specific userId.
    Input: query (string, required), userId (string, required), sessionId (string, optional), agentId (string, optional), filters (object, optional), threshold (number, optional)
    Retrieves relevant memories based on semantic similarity.

  • delete_memory: Deletes a specific memory from storage by its ID.
    Input: memoryId (string, required), userId (string, required), sessionId (string, optional), agentId (string, optional)
    Permanently removes the specified memory.

Prerequisites 🔑

This server supports two storage modes:

  1. Cloud Storage Mode ☁️ (Recommended)

    • Requires a Mem0 API key (MEM0_API_KEY environment variable)
    • Memories are persistently stored on Mem0's cloud servers
    • No local database needed

  2. Local Storage Mode 💾

    • Requires an OpenAI API key (OPENAI_API_KEY environment variable)
    • Memories are stored in an in-memory vector database (non-persistent by default)
    • Data is lost when the server restarts unless configured for persistent storage

Installation & Configuration ⚙️

1. Using npx (Recommended for quick use)

Install the package globally using npm:

npm install -g @pinkpixel/mem0-mcp

Configure your MCP client to run the server using npx:

Cloud Storage Configuration (Recommended)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      },
      "disabled": false,
      "alwaysAllow": [
        "add_memory",
        "search_memory"
      ]
    }
  }
}

Local Storage Configuration (Alternative)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      },
      "disabled": false,
      "alwaysAllow": [
        "add_memory",
        "search_memory"
      ]
    }
  }
}

2. Running from Cloned Repository

Clone the repository, install dependencies, and build the server:

git clone https://github.com/pinkpixel-dev/mem0-mcp 
cd mem0-mcp
npm install
npm run build

Then, configure your MCP client to run the built script directly using node:

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/mem0-mcp/build/index.js" 
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      },
      "disabled": false,
      "alwaysAllow": [
        "add_memory",
        "search_memory"
      ]
    }
  }
}

Notes:

  • Replace /absolute/path/to/mem0-mcp/ with the actual absolute path to your cloned repository.
  • Use the build/index.js file, not the src/index.ts file.
  • The MCP server requires clean stdout for protocol communication — avoid libraries or code that write to stdout.

Default User ID (Optional Fallback)

Both the add_memory and search_memory tools require a userId argument to associate memories with a user. For convenience during testing or single-user scenarios, you can optionally set DEFAULT_USER_ID environment variable. If set and a userId is omitted in calls, the server uses this value.

Example configuration with DEFAULT_USER_ID:

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123" 
      }
    }
  }
}

Or when running directly with node:

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "node",
      "args": [
        "path/to/mem0-mcp/build/index.js"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123" 
      }
    }
  }
}

Cloud vs. Local Storage 🔄

Cloud Storage (Mem0 API)

  • Persistent by default — memories remain available across sessions and restarts
  • No local database required — data stored on Mem0's servers
  • Higher retrieval quality with optimized search algorithms
  • Supports additional fields like agent_id and threshold
  • Requires a Mem0 API key

Local Storage (OpenAI API)

  • In-memory by default — not persistent long-term
  • Data lost on server restart or process termination
  • Recommended for development, testing, or temporary use
  • Use Cloud Storage for reliable long-term memory
  • Uses OpenAI embeddings for vector search
  • Data remains local to your machine
  • Requires an OpenAI API key

Development 💻

Clone the repository and install dependencies:

git clone https://github.com/pinkpixel-dev/mem0-mcp 
cd mem0-mcp
npm install

Build the server:

npm run build

For development with auto-rebuild on file changes:

npm run watch

Debugging 🐞

Debugging MCP servers communicating over stdio can be challenging. Here are some tips:

  1. Use the MCP Inspector tool to monitor MCP protocol communication:
npm run inspector

  1. Use console.error() instead of console.log() for logging to avoid interfering with the protocol.

  2. Use a .env file during local development for simple configuration of API keys and environment variables.

Technical Implementation Notes 🔧

Advanced Mem0 API Parameters

When using Cloud Storage mode, you can include advanced parameters in the metadata object during add_memory calls for enhanced memory management:

  • includes, excludes: Preferences for memory content
  • infer: Whether to infer memories or store messages directly (default: true)
  • output_format: Format version (default v1.0 deprecated, v1.1 recommended)
  • custom_categories: List of category names and descriptions
  • custom_instructions: Project-specific memory handling guidelines
  • immutable: Mark memory as immutable (default: false)
  • expiration_date: Expiry date (YYYY-MM-DD)
  • org_id, project_id: IDs for organizational context
  • version: Memory version (v2 recommended)

Example metadata:

{
  "content": "Important information to remember",
  "userId": "user123",
  "sessionId": "project-abc",
  "metadata": {
    "includes": "important context",
    "excludes": "sensitive data",
    "immutable": true,
    "expiration_date": "2025-12-31",
    "custom_instructions": "Prioritize this memory for financial questions",
    "version": "v2"
  }
}

Advanced Parameters for search_memory

The Mem0 search API supports rich filtering via the filters parameter:

  • filters: Complex filters with logical and comparison operators
  • top_k: Number of top results to return (default 10)
  • fields: Specific response fields
  • rerank, keyword_search, filter_memories: Various boolean options
  • threshold: Minimum similarity threshold (default 0.3)
  • org_id, project_id: Organizational filters

Supported operators in filters include: in, gte, lte, gt, lt, ne, icontains.

Example filter usage:

{
  "query": "What are Alice's hobbies?",
  "userId": "user123",
  "filters": {
    "AND": [
      {
        "user_id": "alice"
      },
      {
        "agent_id": {"in": ["travel-agent", "sports-agent"]}
      }
    ]
  },
  "threshold": 0.5,
  "top_k": 5
}

This searches memories related to Alice's hobbies with specified agents, returning up to 5 results with similarity above 0.5.

For more details, see the Mem0 API documentation.

SafeLogger

The MCP server includes a SafeLogger that redirects console.log calls from the mem0ai library to stderr to keep stdout clean for MCP communication. It intercepts logs from mem0ai and the server itself, preserving protocol integrity.

Environment Variables

  • MEM0_API_KEY: API key for cloud storage
  • OPENAI_API_KEY: API key for local storage (embeddings)
  • DEFAULT_USER_ID: Default user ID fallback

Made with ❤️ by Pink Pixel