AutoGineer
Generated banner for @pinkpixel/mem0-mcp MCP Server ✨
Generated logo for @pinkpixel/mem0-mcp MCP Server ✨

@pinkpixel/mem0-mcp MCP Server ✨

Memory serverOfficial Pink Pixel project

Created by Pink Pixel

Published in pinkpixel-dev/mem0-mcp. Publisher page

96 GitHub stars

What it is

A Model Context Protocol server that can store and retrieve memories for LLM context control
— the description by Pink Pixel

AutoGineer overview, from the brain’s own files

The mem0-mcp server acts as a bridge between AI agents and the Mem0 memory platform, enabling persistent, cross-session information storage. It supports multiple storage backends including Mem0 Cloud, self-hosted Supabase, and local in-memory storage. By implementing the Model Context Protocol, it allows agents to add, search, update, and manage memories using standardized tool calls, effectively extending an LLM's context window with relevant historical data.

How it works

Memory model: Hybrid

AutoGineer overview, from the brain’s own files

The server functions as an MCP provider that exposes memory management tools to an LLM. It uses the mem0ai SDK to handle data operations. Users can configure the server to store data in the cloud, a custom Supabase database, or locally. The system uses identifiers like userId, agentId, and appId to scope memories, with environment variable fallbacks for configuration. It supports both semantic and hybrid search to retrieve stored information.

Folders
FolderRoleFiles
srcsource-code6
.agentsfolder5

The agent reads

The agent writes

Requirements

Runtimes: Node.js

Databases: PostgreSQL

API keys (by name): MEM0_API_KEY, OPENAI_API_KEY

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Google Antigravity, Kiro, OpenCode, Amp, Roo Code, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. This brain runs code automatically: 1 script. Review package.json before opening the folder in Claude Code. No step below turns a hook on for you.

    • package.json: npm run build
  2. Not scanned by AutoGineerThe author’s MCP configuration (README.md) also starts it in a way AutoGineer does not offer. Read that file: AutoGineer did not scan that path; what it runs is listed under “This brain runs”. https://github.com/pinkpixel-dev/mem0-mcp/blob/7c29daec401b81d6200e4ff32f28ff73535db471/README.md
  3. Not scanned by AutoGineerThe author’s README also describes installing it from a clone of its repository. Read its install section: AutoGineer did not scan that path. https://github.com/pinkpixel-dev/mem0-mcp/blob/7c29daec401b81d6200e4ff32f28ff73535db471/README.md#3-running-from-cloned-repository
  4. Not scanned by AutoGineerThe author’s README also describes installing it from a clone of its repository. Read its install section: AutoGineer did not scan that path. https://github.com/pinkpixel-dev/mem0-mcp/blob/7c29daec401b81d6200e4ff32f28ff73535db471/README.md#parameter-configuration-
  5. Not scanned by AutoGineerThe author also offers https://github.com/pinkpixel-dev/mem0-mcp/tree/7c29daec401b81d6200e4ff32f28ff73535db471. https://github.com/pinkpixel-dev/mem0-mcp/tree/7c29daec401b81d6200e4ff32f28ff73535db471

  6. Created by Pink Pixel. Published in pinkpixel-dev/mem0-mcp. Licence: MIT License.

Usage

AutoGineer overview, from the brain’s own files

  • Install via Smithery for Claude Desktop or other MCP-compatible clients.
  • Configure environment variables for the chosen storage backend (Cloud, Supabase, or Local).
  • Provide system instructions to the agent to use specific memory scoping parameters.
  • Use tools like add_memory and search_memories to manage agent knowledge.
“Add a memory that I prefer concise technical summaries.”
The agent calls add_memory with the content, storing the preference associated with the current userId.
“What do you know about my project preferences?”
The agent calls search_memories to retrieve relevant stored information based on the current appId and userId.

Documentation by Pink Pixel

Image: Mem0 MCP Logo

Image: npm version Image: License: MIT Image: Node.js Image: TypeScript Image: MCP Image: Mem0 Image: Downloads Image: GitHub Stars Image: smithery badge

@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",
        "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!)

  1. Tool Parameters (highest priority) - Values provided by the LLM in tool calls

  2. Environment Variables (fallback) - Values from your MCP configuration

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
  }
}

Result: Uses session-123, different-agent, and special-project

If LLM omits parameters:

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

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

  • Persistent by default - Your memories remain available across sessions and server restarts

  • No local database required - All data is stored on Mem0's servers

  • Higher retrieval quality - Uses Mem0's optimized search algorithms

  • Additional fields - Supports agent_id and threshold parameters

  • Fully managed - No setup or maintenance required

  • Requires - A Mem0 API key

Supabase Storage 🗄️

  • Persistent storage - Data is stored in your Supabase PostgreSQL database

  • Free tier available - Generous free tier for development and small projects

  • Self-hostable - Can run your own Supabase instance for complete control

  • SQL access - Direct database access for advanced queries and analytics

  • Scalable - Grows with your needs, from free tier to enterprise

  • Vector search - Uses pgvector extension for efficient similarity search

  • Real-time features - Built-in real-time subscriptions and webhooks

  • Requires - Supabase project setup and OpenAI API key for embeddings

Local Storage (OpenAI API) 💾

  • In-memory by default - Data is stored only in RAM and is not persistent long-term. While some caching may occur, you should not rely on this for permanent storage.

  • Data loss risk - Memory data will be lost on server restart, system reboot, or if the process is terminated

  • Recommended for - Development, testing, or temporary use only

  • For persistent storage - Use the Cloud Storage or Supabase options if you need reliable long-term memory

  • Uses OpenAI embeddings - For vector search functionality

  • Self-contained - All data stays on 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 🐞

Since MCP servers communicate over stdio, debugging can be challenging. Here are some approaches:

  1. Use the MCP Inspector: This tool can monitor the MCP protocol communication:

npm run inspector

  1. Console Logging: When adding console logs, always use console.error() instead of console.log() to avoid interfering with the MCP protocol

  2. Environment Files: Use a .env file for local development to simplify setting API keys and other configuration options

Technical Implementation Notes 🔧

1. Platform V3 Async Additions & Polling

Mem0 Cloud V3 addition is an asynchronous background task. When calling add_memory, the server submits the request to /v3/memories/add/ and receives an eventId.

  • Synchronous Polling (Default): The server polls the event status endpoint (/v1/event/{id}/) every 500ms for up to timeoutMs (default 15000ms) until the status becomes SUCCEEDED or FAILED. Once resolved, it returns the final outcome.

  • Asynchronous Execution: Pass "waitForCompletion": false to bypass polling. The server will immediately return the eventId and a PENDING status.

2. Nested V3 Filter Normalization

The Mem0 Cloud V3 search and list endpoints reject top-level scope IDs (user_id, agent_id, app_id, run_id) and return an HTTP 400 error. V3 requires these fields inside the nested filters object. To prevent breaking client configurations, this server automatically normalizes top-level scope variables (userId, agentId, appId, runId/sessionId) and merges them into the nested filters object under the hood before sending the API request.

3. Capability Gating

Different backends support different feature sets. Call get_memory_capabilities to get a structured capability matrix of the active backend.

  • Cloud Mode: Fully supports all features (apiVersion: "v3", async events, listing, audit histories, logical queries).

  • Supabase / Local Modes: Standard V1 vector interfaces. Unsupported cloud-specific tools (like get_memory_history or list_memories) will fail gracefully with clear feature-unavailable messages.

4. Logging & Protocol Stability

MCP servers communicate using JSON-RPC over stdout. Any unexpected library logs printed to stdout will corrupt the protocol channel and cause clients to crash. This server overrides the default console output methods (such as console.log) to redirect/mute standard logging, ensuring clean stdio communication.

Made with 💖 by Pink Pixel

CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

[0.8.0] - 2026-06-24

🚀 Phase 2 - Advanced Memory Operations & Safety Gates

  • Batch Memory Operations:

    • Implemented batch_update_memories for bulk updating multiple memory contents (cloud only).

    • Implemented batch_delete_memories supporting both cloud-native batch APIs and self-hosted iterative fallbacks (Supabase/Local).

    • Safety Gate: Added explicit confirmation requirement (confirm: true) to prevent accidental bulk deletions.

  • Memory Quality Evaluation:

    • Added rate_memory to submit ratings (positive, negative, very_negative) and text reasons on memory records (cloud only).

  • Manual Event Log Inspections:

    • Added get_memory_event and list_memory_events to retrieve history logs and status details of background async memory extraction tasks (cloud only).

  • Scoped Export Controls:

    • Added create_memory_export and get_memory_export to kick off and query structured exports using JSON Schema matching (cloud only).

  • Backend Capability Isolation:

    • Automatically restricts unsupported operations on self-hosted/local backends, failing gracefully with clear messages.

[0.7.0] - 2026-06-24

🚀 MAJOR RELEASE - Platform V3 Modernization & Modular Architecture

  • Upgraded SDK & Protocol - Bumped mem0ai to 3.0.10 and @modelcontextprotocol/sdk to 1.29.0 for full compatibility with modern V3 memory pipelines.

  • Modular Adapter Pattern - Refactored the monolithic src/index.ts into a clean multi-file architecture with backend adapters:

    • types.ts: standard data contracts and interfaces.

    • base.ts: base abstract class interface.

    • cloud.ts: Platform V3 client integrations.

    • supabase.ts: self-hosted Supabase compatibility.

    • local.ts: local in-memory compatibility.

  • Async Polling for V3 Additions - Implemented automatic background polling (wait/poll with configurable timeout and waitForCompletion flag) for asynchronous memory processing events.

  • Scope Parameters Normalization - Automatically normalizes userId, agentId, appId, and runId/sessionId into V3 search/list query filters to bypass API changes without breaking client configuration.

  • Standardized Memory Tools Surface - Expanded the exposed tool set:

    • add_memory (Updated for async V3 and structural message payloads)

    • search_memories / search_memory (Search with hybrid retrieval and filters mapping)

    • list_memories (Paginated listings)

    • get_memory (Single record fetch)

    • update_memory (Deliberate memory editing)

    • delete_memory (Single record removal)

    • get_memory_history (Memory revision logs, cloud only)

    • get_memory_capabilities (Exposes feature matrix of active backend mode)

[0.6.1] - 2025-05-28

🔧 PATCH - Supabase Configuration Fix

  • Fixed embedder configuration - Corrected OpenAI API key reference for Supabase mode

  • Published to npmjs - Updated package available via npx for immediate testing

  • Confirmed functionality - Supabase storage mode tested and working with vector search

  • Memory operations verified - All tools (add_memory, search_memory, delete_memory) functional with Supabase

[0.6.0] - 2025-05-28

🚀 NEW FEATURE - Supabase Storage Mode

  • Added Supabase as a third storage option alongside Mem0 cloud and local storage

  • Persistent storage with free tier - Supabase offers generous free tier for development

  • Self-hostable option - Users can run their own Supabase instance for complete control

  • Vector search with pgvector - Efficient similarity search using PostgreSQL's pgvector extension

  • SQL access - Direct database access for advanced queries and analytics

🔧 Implementation Details

  • Storage mode priority: Cloud (MEM0_API_KEY) > Supabase (SUPABASE_URL + SUPABASE_KEY) > Local (OPENAI_API_KEY)

  • Environment variables: Added support for SUPABASE_URL and SUPABASE_KEY

  • Database setup: Comprehensive SQL migrations for memories and memory_history tables

  • Vector search function: Custom PostgreSQL function for similarity search with filtering

  • Full tool support: All three tools (add_memory, search_memory, delete_memory) work with Supabase

📝 Documentation Updates

  • Comprehensive Supabase setup guide with step-by-step SQL migrations

  • Configuration examples for all three installation methods (global, npx, cloned repo)

  • Storage mode comparison highlighting benefits of each option

  • Environment variable documentation for Supabase credentials

🎯 Benefits for Users

  • Free persistent storage - Alternative to paid Mem0 cloud service

  • Local control - Self-hosted option for privacy and compliance

  • Scalability - Grows from free tier to enterprise scale

  • Advanced features - Real-time subscriptions, webhooks, direct SQL access

  • No vendor lock-in - Open source PostgreSQL with standard SQL

[0.5.5] - 2025-05-28

✅ CONFIRMED WORKING - app_id and run_id Parameters

  • SUCCESS: Confirmed that app_id and run_id parameters are now working correctly!

  • Dashboard Behavior: Parameters appear in individual memory details (Event Details panel) as expected

  • API Version: Re-added version="v2" for add operations as recommended by Mem0 docs (v1 is deprecated)

  • UI Limitation: Mem0 dashboard doesn't show app_id/run_id in main list view by design - this is normal behavior

📝 Research Findings

  • Mem0 stores app_id and run_id as first-class fields, not in metadata

  • Dashboard UI focuses on user/agent groupings; app_id/run_id appear in memory details and are fully queryable

  • Parameters are working correctly - the "missing" display in main list was expected behavior

  • All memory operations now use proper API versions and endpoints

🎯 Status

  • ✅ Project scoping via app_id - WORKING

  • ✅ Session tracking via run_id - WORKING

  • ✅ Agent identification via agent_id - WORKING

  • ✅ Memory organization and filtering - WORKING

[0.5.3] - 2025-05-28

🔧 Fixed

  • API Endpoint Corrections:

    • Add Memory: Uses /v1/memories/

    • Search Memory: Uses /v1/memories/search/ with version=v2 parameter

    • Delete Memory: Uses /v1/memories/{id}/

  • Fixed delete endpoint URL from /v2/memories/{id} to /v1/memories/{id}/

[0.5.2] - 2025-05-28

🔧 Fixed

  • API Call Priority: Now prioritizes direct REST API calls over Node.js SDK when app_id or run_id parameters are provided

  • Enhanced Parameter Support: Ensures app_id and run_id parameters are properly passed to Mem0 API for project scoping and session tracking

  • Better Debugging: Added specific logging when using direct API calls for parameter-sensitive operations

📝 Technical Details

  • Modified both add_memory and search_memory methods to use direct REST API calls when app_id or sessionId parameters are present

  • The Node.js SDK appears to have limitations with certain parameters, so direct API calls ensure full parameter support

  • Maintains backward compatibility while ensuring all parameters work correctly

  • Added fallback logic to SDK if direct API calls fail

[0.5.1] - 2025-05-28

📝 Documentation

  • Updated README with comprehensive parameter configuration guide

  • Added system prompt recommendations for LLM usage

  • Enhanced examples showing correct parameter usage

  • Clarified that org_id/project_id are auto-assigned by Mem0

[0.5.0] - 2025-05-28

🎯 BREAKING CHANGE - Correct Parameter Implementation

  • MAJOR FIX: Replaced incorrect orgId/projectId parameters with correct Mem0 API parameters

  • Parameter Mapping:

    • agentId - The LLM/agent making the tool call

    • userId - The user's identifier

    • appId - The user's project/application (this controls project scope!)

    • sessionId - Maps to run_id for session tracking

  • Environment Fallbacks: Added DEFAULT_AGENT_ID and DEFAULT_APP_ID environment variables

  • API Compliance: Now uses correct Mem0 API parameters (app_id, agent_id, run_id) instead of non-functional org/project IDs

🔧 Fixed

  • Root Cause: org_id and project_id are set by Mem0 automatically and cannot be changed by users

  • Correct Scope Control: app_id is what actually controls the user's project scope in Mem0

  • Parameter Precedence: Tool parameters take precedence over environment variable defaults

  • Enhanced Logging: Added comprehensive parameter resolution logging for debugging

📝 Technical Details

  • Removed all references to orgId/projectId (these are auto-assigned by Mem0)

  • Implemented proper app_id parameter for project scoping

  • Updated tool schemas to reflect correct parameter names and descriptions

  • Added fallback logic for DEFAULT_AGENT_ID and DEFAULT_APP_ID environment variables

  • Updated direct REST API calls to use correct parameter names

[0.4.2] - 2025-05-28

🔧 Fixed

  • CRITICAL FIX: Added fallback to direct REST API calls when Node.js SDK doesn't properly handle org_id/project_id parameters

  • SDK Limitation Workaround: Node.js SDK appears to ignore org_id/project_id parameters, so we now use direct REST API calls as fallback

  • Enhanced Error Handling: Added comprehensive error handling with automatic fallback from SDK to direct API calls

  • Better Debugging: Added detailed logging for both SDK attempts and direct API calls to help identify issues

📝 Technical Details

  • When cloudClient.add() or cloudClient.search() fails or ignores org/project parameters, automatically falls back to direct REST API calls

  • Direct API calls use proper https://api.mem0.ai/v1/memories/ endpoints with full parameter support

  • Maintains backward compatibility while ensuring org_id and project_id parameters work correctly

  • Added comprehensive request/response logging for debugging

[0.4.1] - 2025-05-28

🔧 Fixed

  • CRITICAL FIX: Removed organizationId and projectId from client-level initialization to fix environment variable fallbacks

  • Parameter Override Issue: Client-level org/project settings were overriding per-request parameters, preventing environment variables and tool parameters from working

  • Enhanced Debugging: Added comprehensive logging to track parameter resolution and API call options

  • Environment Variable Fallbacks: ORG_ID and PROJECT_ID environment variables now work correctly when tool parameters are omitted

📝 Technical Details

  • Removed organizationId and projectId from MemoryClient constructor options

  • Client-level settings were preventing per-request org_id and project_id parameters from taking effect

  • Added detailed logging to help debug parameter resolution issues

  • Environment variable fallback logic now works as intended

[0.4.0] - 2025-01-27

🔧 Fixed

  • BREAKING FIX: Fixed client initialization issue where org_id and project_id set at client level were overriding per-request values

  • API Parameter Format: Changed API method parameters from camelCase to snake_case to match Mem0 REST API specification

    • userId → user_id

    • orgId → org_id

    • projectId → project_id

    • agentId → agent_id

    • sessionId → session_id

    • customCategories → custom_categories

    • customInstructions → custom_instructions

    • outputFormat → output_format

    • expirationDate → expiration_date

    • topK → top_k

    • keywordSearch → keyword_search

    • filterMemories → filter_memories

  • Client Initialization: Now properly sets organizationId and projectId at client level using camelCase (as expected by JavaScript SDK)

  • Environment Variable Fallbacks: ORG_ID and PROJECT_ID environment variable fallbacks now work properly when explicit parameters are not provided

🚀 Improved

  • Enhanced error messages to include API response details for better debugging

  • Added comprehensive parameter validation and logging

  • Improved client initialization logging to show which parameters are being used

📝 Notes

  • This version fixes the core issue where organization and project IDs were not being properly passed to the Mem0 API

  • Users should now see their memories properly scoped to their organization and project

  • Environment variable fallbacks (ORG_ID, PROJECT_ID) will now work as expected when tool parameters are omitted

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.3.9] - 2025-01-27

Fixed

  • CRITICAL FIX: Fixed organization and project ID parameters not working properly

    • Changed from snake_case (org_id, project_id) to camelCase (organizationId, projectId) for JavaScript client compatibility

    • Fixed environment variable fallbacks (ORG_ID, PROJECT_ID) not working due to incorrect parameter names

    • Updated all API calls to use correct JavaScript/Node.js parameter naming convention

    • This resolves issues where explicit org/project parameters were ignored and environment defaults weren't applied

Technical Details

  • Updated add_memory, search_memory, and delete_memory methods to use camelCase parameters

  • Fixed parameter mapping: userId, organizationId, projectId, sessionId, agentId

  • Fixed advanced parameters: outputFormat, customCategories, customInstructions, expirationDate, topK, keywordSearch, filterMemories

  • Maintains backward compatibility with environment variable names

[0.3.8] - 2025-05-28

Fixed

  • 🐛 CRITICAL BUG FIX: Fixed DEFAULT_USER_ID environment variable not being used as fallback when userId parameter is omitted

    • 🐛 Also fixed issue with PROJECT_ID and ORG_ID variables not being used as fallback when projectId and orgId parameters are omitted during tool use

[0.3.7] - 2025-05-28

Documentation

  • 📚 Enhanced README: Added comprehensive section explaining environment variable fallback behavior

  • 🎯 Clarified priority order: Tool parameters override environment variables

  • 📝 Added detailed examples showing when defaults are used vs. overridden

  • 💡 Provided guidance on instructing LLMs to use configured defaults

  • 🔍 Added GitHub issue comment explaining fallback behavior to user

Changed

  • 📖 Improved documentation clarity for environment variable usage patterns

[0.3.6] - 2025-05-28

Fixed

  • 🐛 CRITICAL BUG FIX: Fixed DEFAULT_USER_ID environment variable not being used as fallback when userId parameter is omitted

  • ✅ All three tools (add_memory, search_memory, delete_memory) now properly use DEFAULT_USER_ID as fallback

  • 🔧 Updated tool schemas to make userId parameter optional with clear fallback documentation

  • 📝 Improved error messages to indicate when DEFAULT_USER_ID environment variable is missing

  • 🎯 Resolves GitHub issue #3 where environment variables were not taking effect

Changed

  • 📋 Made userId parameter optional in all tool schemas since DEFAULT_USER_ID provides fallback

  • 🔄 Enhanced parameter validation logic to use environment variable fallbacks consistently

[0.3.5] - 2025-05-28

Security

  • 🔒 CRITICAL: Fixed high severity security vulnerabilities in dependencies

  • 🛡️ Updated axios from 1.7.7 to 1.9.0 to address SSRF and credential leakage vulnerability (GHSA-jr5f-v2jv-69x6)

  • 🛡️ Updated undici from 5.28.5 to 7.10.0 to address denial of service vulnerability (GHSA-cxrh-j4jr-qwg3)

  • ⚙️ Added npm overrides in package.json to ensure secure dependency versions

  • ✅ All security vulnerabilities resolved - npm audit now shows 0 vulnerabilities

Changed

  • 📦 Added dependency overrides for axios and undici to maintain security compliance

  • 🔧 Enhanced package.json with security-focused dependency management

[0.3.4] - 2025-05-23

Added

  • ✨ Added support for orgId and projectId as parameters in all tools (add_memory, search_memory, delete_memory)

  • 🚀 Added comprehensive support for advanced Mem0 API parameters:

    • add_memory: includes, excludes, infer, outputFormat, customCategories, customInstructions, immutable, expirationDate

    • search_memory: topK, fields, rerank, keywordSearch, filterMemories

  • 📊 Parameter-provided orgId and projectId now take precedence over environment variables for better user control

  • 🔧 Enhanced configuration generator with ORG_ID and PROJECT_ID prompts for easier setup

  • 🌟 Added global installation support with mem0-mcp command

  • 📚 Added comprehensive installation documentation with three methods: global install, npx, and local build

  • 🎯 Enhanced configuration generator with global install option

  • 📋 Updated all README configuration examples to show complete environment variables

Changed

  • 🔧 Updated TypeScript interfaces to include all new parameters

  • 📝 Enhanced tool schemas with detailed descriptions for all new parameters

  • 🏗️ Improved parameter handling logic with proper fallbacks

Removed

  • 🧹 Removed unused tiktoken-node dependency to clean up the project

## [0.3.3] - 2025-04-22

Fixed

  • ✅ Resolved version mismatch between package.json and source code (now both 0.3.3)

  • 🔧 Fixed configuration generator indentation issues and removed unused session ID environment variables

  • 📝 Clarified that session IDs are tool parameters, not environment variables

0.3.2 - 2025-04-20

Fixed

  • Fixed issue with threshold parameter in search_memory tool when using cloud storage mode. The parameter is now properly handled to ensure it's never passed as null to the Mem0 API, which was causing errors for some users.

0.3.0 - 2025-04-05

Added

  • ✨ Added delete_memory tool to remove specific memories by ID.

  • ☁️ Implemented support for Mem0 Cloud API using MEM0_API_KEY.

  • 🏢 Added optional support for ORG_ID and PROJECT_ID environment variables for Cloud API scoping.

  • 🔄 Added dynamic switching between Cloud API (if MEM0_API_KEY is present) and local in-memory storage (if OPENAI_API_KEY is present).

0.2.7 - 2025-04-08

Added

  • New MCP tool: delete_memory for removing specific memories by ID

  • Comprehensive documentation for advanced Mem0 API parameters

  • Detailed explanation of filters and comparison operators for the search functionality

Fixed

  • Fixed mapping between sessionId and run_id in search functionality for cloud API

  • Clarified in-memory storage limitations in documentation

0.2.5 - 2025-04-05

Fixed

  • Implemented SafeLogger class to selectively redirect console.log calls from mem0ai library to stderr without breaking MCP protocol

  • Fixed critical issue where stdout writes from internal libraries were disrupting the MCP communication protocol

  • Added environment variable configurations to minimize debug logging from libraries

  • Improved error handling and cleanup on process exit

0.1.7 - 2025-04-05

Fixed

  • Fixed MCP communication by removing all console logging that was interfering with the stdout protocol channel.

0.1.6 - 2025-04-05

Changed

  • Reverted search_memory tool description and schema to explicitly require userId, removing misleading "optional" phrasing related to the DEFAULT_USER_ID fallback.

  • Added documentation to README.md explaining the DEFAULT_USER_ID environment variable and its use as a server-side fallback for search_memory if the userId argument is omitted (though providing userId in the call is recommended).

0.1.5- 2025-04-05

Fixed

  • Resolved issue where memories were not being stored correctly due to unconfigured default database (Qdrant). Explicitly configured mem0ai client to use the in-memory vector store by default, ensuring basic functionality works out-of-the-box.

0.1.0 - 2025-04-05

Added

  • Initial functional Node.js/TypeScript implementation of @pinkpixel/mem0-mcp.

  • Integration with mem0ai Node.js SDK.

  • MCP tools: mem0_add_memory and mem0_search_memory.

  • Requires OPENAI_API_KEY environment variable.

  • Configuration for npm publishing under @pinkpixel scope.

  • README.md with description, features, prerequisites, and installation instructions.

  • Standard LICENSE (MIT), CHANGELOG.md, and .gitignore.

28 files · 21 not served here

Advantages

  • Persistent storage ensures data survives server restarts when using Cloud or Supabase modes. evidence: README.md
  • Supports multiple storage backends, offering flexibility between managed cloud services and self-hosted databases. evidence: README.md

Limitations

  • Local storage mode is non-persistent by default and loses data upon server restart. evidence: README.md
  • Requires external API keys (Mem0, OpenAI, or Supabase) depending on the selected storage mode. evidence: README.md

Security

Risk level: Medium risk

This brain runs

Agent instructions that run or fetch something (5)

  • .agents/skills/mem0-api/SKILL.md: **Mem0 OSS** (self-hosted) — run your own vector store, LLM, and embedder stack
  • .agents/skills/mem0-api/SKILL.md: **API Key:** Get from [app.mem0.ai/dashboard/api-keys](https://app.mem0.ai/dashboard/api-keys) · uses the network
  • .agents/skills/mem0-api/SKILL.md: npx mcp-add \
  • .agents/skills/mem0-api/SKILL.md: const res = await fetch(`https://api.mem0.ai/v1/event/${eventId}/`, { · uses the network
  • .agents/skills/mem0-mcp-modernization/SKILL.md: Official install source is the repository and published package only;

MCP servers (11)

  • README.md (mem0-mcp): mem0-mcp
  • README.md (mem0-mcp): mem0-mcp
  • README.md (mem0-mcp): mem0-mcp
  • README.md (mem0-mcp): npx -y @pinkpixel/mem0-mcp
  • README.md (mem0-mcp): npx -y @pinkpixel/mem0-mcp
  • README.md (mem0-mcp): npx -y @pinkpixel/mem0-mcp
  • README.md (mem0-mcp): node /absolute/path/to/mem0-mcp/build/index.js
  • README.md (mem0-mcp): node /absolute/path/to/mem0-mcp/build/index.js
  • README.md (mem0-mcp): node /absolute/path/to/mem0-mcp/build/index.js
  • README.md (mem0-mcp): npx -y @pinkpixel/mem0-mcp
  • README.md (mem0-mcp): node path/to/mem0-mcp/build/index.js

Package scripts (1)

  • package.json (prepare): npm run build
  • Medium risk: runs-instruction-instruction-network (.agents/skills/mem0-api/SKILL.md:52)
  • Medium risk: runs-instruction-instruction-network (.agents/skills/mem0-api/SKILL.md:243)
  • Medium risk: runs-mcp-server-unpinned-runner (README.md:169)
  • Medium risk: runs-mcp-server-unpinned-runner (README.md:191)
  • Medium risk: runs-mcp-server-unpinned-runner (README.md:215)
  • Medium risk: runs-mcp-server-unpinned-runner (README.md:485)
  • Low risk: network-instructions (.agents/skills/mem0-api/SKILL.md:42)

Attribution and licence

Created by
Pink Pixel
Publisher
Pink Pixel (Official Pink Pixel project)
Source
pinkpixel-dev/mem0-mcp · commit 7c29dae
Licence
MIT License (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Pink Pixel.

Install from source

21 of its files are not served here, so there is no ZIP. pinkpixel-dev/mem0-mcp at 7c29dae