Prerequisites 🔑

This server supports three storage modes:

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

Local Storage Configuration (Cloned Repository)

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

-- 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!)

Example Behavior:

// Your MCP config
"env": {
  "DEFAULT_USER_ID": "john-doe",
  "DEFAULT_AGENT_ID": "my-assistant",
  "DEFAULT_APP_ID": "my-project"
}

If LLM provides parameters:

{

  "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

  }

}

If LLM omits parameters:

{

  "tool": "add_memory",

  "arguments": {

    "content": "Remember this"

    // All IDs omitted - uses environment variables

  }

}

Controlling LLM Behavior

System Prompt Recommendation

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

Example configuration using 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",
        "ORG_ID": "your-org-id",
        "PROJECT_ID": "your-project-id"
      }
    }
  }
}

Or when running directly with node:

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

{
  "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) ☁️

Supabase Storage 🗄️

Local Storage (OpenAI API) 💾