# Mem0 Mcp

> ✨ mem0 MCP Server: A memory system using mem0 for AI applications with model context protocl (MCP) integration. Enables long-term memory for AI agents as a drop-in MCP server.

- **Type:** MCP server
- **Install:** `agentstack add mcp-pinkpixel-dev-mem0-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [pinkpixel-dev](https://agentstack.voostack.com/s/pinkpixel-dev)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [pinkpixel-dev](https://github.com/pinkpixel-dev)
- **Source:** https://github.com/pinkpixel-dev/mem0-mcp
- **Website:** https://pinkpixel.dev

## Install

```sh
agentstack add mcp-pinkpixel-dev-mem0-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[](https://badge.fury.io/js/@pinkpixel%2Fmem0-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](https://mem0.ai)
[](https://www.npmjs.com/package/@pinkpixel/mem0-mcp)
[](https://github.com/pinkpixel-dev/mem0-mcp)
[](https://smithery.ai/server/@pinkpixel-dev/mem0-mcp-server)

# @pinkpixel/mem0-mcp MCP Server ✨

A Model Context Protocol (MCP) server that integrates with [Mem0.ai](https://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](https://smithery.ai/server/@pinkpixel-dev/mem0-mcp-server):

```bash
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:

```bash
npm install -g @pinkpixel/mem0-mcp
```

After global installation, you can run the server directly:

```bash
mem0-mcp
```

Configure your MCP client to use the global command:

#### Cloud Storage Configuration (Global Install)

```json
{
  "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)

```json
{
  "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)

```json
{
  "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)

```json
{
  "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)

```json
{
  "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)

```json
{
  "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:

```bash
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)

```json
{
  "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)

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

#### Local Storage Configuration (Cloned Repository)

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

**Important Notes:**
1. Replace `/absolute/path/to/mem0-mcp/` with the actual absolute path to your cloned repository
2. Use the `build/index.js` file, not the `src/index.ts` file
3. The MCP server requires clean stdout for protocol communication - any libraries or code that writes to stdout may interfere with the protocol

## Supabase Setup 🗄️

If you choose to use Supabase storage mode, you'll need to set up your Supabase database with the required table.

### 1. Create a Supabase Project

1. Go to [supabase.com](https://supabase.com) and create a new project
2. Note your project URL and anon key from the project settings

### 2. Run SQL Migrations

Run these SQL commands in your Supabase SQL Editor:

```sql
-- Enable the vector extension
create extension if not exists vector;

-- Create the memories table
create table if not exists memories (
  id text primary key,
  embedding vector(1536),
  metadata jsonb,
  created_at timestamp with time zone default timezone('utc', now()),
  updated_at timestamp with time zone default timezone('utc', now())
);

-- Create the vector similarity search function
create or replace function match_vectors(
  query_embedding vector(1536),
  match_count int,
  filter jsonb default '{}'::jsonb
)
returns table (
  id text,
  similarity float,
  metadata jsonb
)
language plpgsql
as $$
begin
  return query
  select
    t.id::text,
    1 - (t.embedding  query_embedding) as similarity,
    t.metadata
  from memories t
  where case
    when filter::text = '{}'::text then true
    else t.metadata @> filter
  end
  order by t.embedding  query_embedding
  limit match_count;
end;
$$;

-- Create the memory_history table for history tracking
create table if not exists memory_history (
  id text primary key,
  memory_id text not null,
  previous_value text,
  new_value text,
  action text not null,
  created_at timestamp with time zone default timezone('utc', now()),
  updated_at timestamp with time zone,
  is_deleted integer default 0
);
```

### 3. Set Environment Variables

Add these to your MCP configuration:

- `SUPABASE_URL`: Your Supabase project URL (e.g., `https://your-project.supabase.co`)
- `SUPABASE_KEY`: Your Supabase anon key
- `OPENAI_API_KEY`: Your OpenAI API key (for embeddings)

### Benefits of Supabase Mode

✅ **Persistent Storage** - Data survives server restarts
✅ **Free Tier Available** - Generous free tier for development
✅ **Self-Hostable** - Can run your own Supabase instance
✅ **Scalable** - Grows with your needs
✅ **SQL Access** - Direct database access for advanced queries
✅ **Real-time Features** - Built-in real-time subscriptions

## Parameter Configuration 🎯

### Understanding Mem0 Parameters

The server uses four key parameters to organize and scope memories:

1. **`userId`** - Identifies the user (required)
2. **`agentId`** - Identifies the LLM/agent making the tool call (optional)
3. **`appId`** - Identifies the user's project/application - **this controls project scope!** (optional)
4. **`sessionId`** - Identifies the conversation session (maps to `run_id` in Mem0) (optional)

### Environment Variable Fallbacks 🔄

The MCP server supports environment variable fallbacks for user identification and project settings:

- `DEFAULT_USER_ID`: Fallback user ID when not provided in tool calls
- `DEFAULT_AGENT_ID`: Fallback agent ID for identifying the LLM/agent
- `DEFAULT_APP_ID`: Fallback app ID for project scoping

#### **Priority Order (Important!)**
1. **Tool Parameters** (highest priority) - Values provided by the LLM in tool calls
2. **Environment Variables** (fallback) - Values from your MCP configuration

#### **Example Behavior:**
```json
// Your MCP config
"env": {
  "DEFAULT_USER_ID": "john-doe",
  "DEFAULT_AGENT_ID": "my-assistant",
  "DEFAULT_APP_ID": "my-project"
}
```

**If LLM provides parameters:**
```json
{
  "tool": "add_memory",
  "arguments": {
    "content": "Remember this",
    "userId": "session-123",        // ← Overrides DEFAULT_USER_ID
    "agentId": "different-agent",   // ← Overrides DEFAULT_AGENT_ID
    "appId": "special-project"      // ← Overrides DEFAULT_APP_ID
    // sessionId omitted           // ← No fallback, will be undefined
  }
}
```
**Result**: Uses `session-123`, `different-agent`, and `special-project`

**If LLM omits parameters:**
```json
{
  "tool": "add_memory",
  "arguments": {
    "content": "Remember this"
    // All IDs omitted - uses environment variables
  }
}
```
**Result**: Uses `john-doe`, `my-assistant`, and `my-project`

#### **Controlling LLM Behavior**
To ensure your environment variables are used, instruct your LLM:
- *"Use the default user ID configured in the environment"*
- *"Don't specify userId, agentId, or appId parameters"*
- *"Let the server use the configured defaults"*

#### **System Prompt Recommendation**
For best results, include instructions in your system prompt like:

```
When creating memories, use:
- agentId: "my-assistant"
- appId: "my-project"
- sessionId: "current-conversation-id"
```

Example configuration using `DEFAULT_USER_ID`:

```json
{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "ORG_ID": "your-org-id",
        "PROJECT_ID": "your-project-id"
      }
    }
  }
}
```

Or when running directly with `node`:

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

```json
{
  "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"
      }
    }
  }
}
```

## Storage Mode Comparison 🔄

### Cloud Storage (Mem0 API) ☁️
* **Persistent by default** - Your memories remain available across sessions and server restarts
* **No local database required** - All data is stored on Mem

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [pinkpixel-dev](https://github.com/pinkpixel-dev)
- **Source:** [pinkpixel-dev/mem0-mcp](https://github.com/pinkpixel-dev/mem0-mcp)
- **License:** MIT
- **Homepage:** https://pinkpixel.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-pinkpixel-dev-mem0-mcp
- Seller: https://agentstack.voostack.com/s/pinkpixel-dev
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.