@pinkpixel/mem0-mcp MCP Server ✨

A Model Context Protocol (MCP) server that integrates with Mem0.ai to provide persistent memory capabilities for 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 🧠

Modernized & Advanced Tools (v0.8.0)

• add_memory: Stores a memory from text content or structured message arrays.
  • Inputs: content (string) or messages (array of role/content objects), userId (string), runId / sessionId (string), agentId (string), appId (string), metadata (object), infer (boolean), customInstructions (string), waitForCompletion (boolean, default: true), timeoutMs (number, default: 15000)
  • Behavior: Cloud V3 additions are asynchronous. By default, this tool polls the background queue until completed. Pass waitForCompletion: false to get the eventId immediately.
• search_memories: Searches memories using semantic and BM25 hybrid filters.
  • Inputs: query (string), userId (string), runId / sessionId (string), agentId (string), appId (string), filters (object), threshold (number), topK (number), rerank (boolean), referenceDate (string)
  • Behavior: Automatically nests scope variables inside the V3 filters block to prevent API validation errors.
• search_memory: Backward-compatible alias for search_memories.
• list_memories: Paginated listing of memory records scoped by identifiers.
  • Inputs: userId (string), runId / sessionId (string), agentId (string), appId (string), filters (object), page (number), pageSize (number)
• get_memory: Retrieves a single memory record by its ID.
  • Inputs: memoryId (string)
• update_memory: Modifies the text or metadata of an existing memory.
  • Inputs: memoryId (string), text (string), metadata (object)
• delete_memory: Deletes a specific memory record by ID.
  • Inputs: memoryId (string)
• get_memory_history: Retrieves the audit trail of memory revisions (cloud only).
  • Inputs: memoryId (string)
• get_memory_capabilities: Exposes the feature matrix and support flags of the active backend storage mode.
  • Inputs: None
• batch_update_memories: Performs bulk updates of text contents for multiple memories (cloud only).
  • Inputs: updates (array of { memoryId: string, text: string } objects)
• batch_delete_memories: Performs bulk deletions of multiple memories.
  • Inputs: memoryIds (array of strings), confirm (boolean, must be true to execute)
• rate_memory: Submits quality feedback evaluation for a memory record (cloud only).
  • Inputs: memoryId (string), feedback (string: positive, negative, very_negative), reason (string, optional)
• get_memory_event: Manually retrieves details of a specific background event job (cloud only).
  • Inputs: eventId (string)
• list_memory_events: Lists history logs of background memory processing events (cloud only).
  • Inputs: page (number), pageSize (number)
• create_memory_export: Initiates an asynchronous memory export query job (cloud only).
  • Inputs: schema (object), filters (object, optional), exportInstructions (string, optional)
• get_memory_export: Retrieves status and download metadata of a memory export job (cloud only).
  • Inputs: exportId (string)

Prerequisites 🔑

This server supports three storage modes:

1. Cloud Storage Mode ☁️ (Recommended for production)

   • Requires a Mem0 API key (provided as MEM0_API_KEY environment variable)
   • Memories are persistently stored on Mem0's cloud servers
   • No local database needed
   • Full feature support with advanced filtering and search

2. Supabase Storage Mode 🗄️ (Recommended for self-hosting)

   • Requires Supabase credentials (SUPABASE_URL and SUPABASE_KEY environment variables)
   • Requires OpenAI API key (OPENAI_API_KEY environment variable) for embeddings
   • Memories are persistently stored in your Supabase database
   • Free tier available, self-hostable option
   • Requires initial database setup (SQL migrations provided below)

3. Local Storage Mode 💾 (Development/testing only)

   • Requires an OpenAI API key (provided as 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 ⚙️

You can run this server in three main ways:

Installing via Smithery

To install Mem0 Memory Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @pinkpixel-dev/mem0-mcp-server --client claude

1. Global Installation (Recommended for frequent use)

Install the package globally and use the mem0-mcp command:

npm install -g @pinkpixel/mem0-mcp

After global installation, you can run the server directly:

mem0-mcp

Configure your MCP client to use the global command:

Cloud Storage Configuration (Global Install)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "mem0-mcp",
      "args": [],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Supabase Storage Configuration (Global Install)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "mem0-mcp",
      "args": [],
      "env": {
        "SUPABASE_URL": "YOUR_SUPABASE_PROJECT_URL",
        "SUPABASE_KEY": "YOUR_SUPABASE_ANON_KEY",
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Local Storage Configuration (Global Install)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "mem0-mcp",
      "args": [],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      }
    }
  }
}

2. Using npx (Recommended for occasional use)

Configure your MCP client (e.g., Claude Desktop, Cursor, Cline, Roo Code, etc.) to run the server using npx:

Cloud Storage Configuration (npx)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Supabase Storage Configuration (npx)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "SUPABASE_URL": "YOUR_SUPABASE_PROJECT_URL",
        "SUPABASE_KEY": "YOUR_SUPABASE_ANON_KEY",
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Local Storage Configuration (npx)

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

3. Running from Cloned Repository

Note: This method requires you to git clone the repository first.

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:

Cloud Storage Configuration (Cloned Repository)

{
  "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",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Supabase Storage Configuration (Cloned Repository)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/mem0-mcp/build/index.js"
      ],
      "env": {
        "SUPABASE_URL": "YOUR_SUPABASE_PROJECT_URL",
        "SUPABASE_KEY": "YOUR_SUPABASE_ANON_KEY",
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE"