Mem0 Mcp

本地服务

pinkpixel.dev记忆与知识9618 周前更新

代码仓库访问官网

关于 Mem0 Mcp

Mem0 MCP 是基于 mem0ai Node.js SDK 的 MCP 服务，为 LLM 和 AI Agent 提供跨会话的持久化记忆。它支持云端、Supabase 和本地三种存储模式，适合需要长期记忆的应用开发者。

主要功能

01add_memory、search_memories 等记忆读写工具
02支持语义与 BM25 混合搜索
03按 userId、agentId、appId、sessionId 划分记忆范围
04三种存储模式：云端、Supabase、本地
05支持批量更新、批量删除与导出任务

适用场景

01为 AI Agent 保存用户偏好并在后续会话中检索
02在自托管环境中用 Supabase 存储记忆数据
03在开发测试阶段用本地向量存储验证记忆功能

MCP 相关

该项目是一个 MCP 服务，向 MCP 客户端暴露记忆的增删改查、搜索和历史查询等工具。

#agent #database #storage #memory #mcp #assistant #persistent-memory #memory-management #llm #llm-memory #mem0 #mem0ai #model-context-protocol #mcp-server #modelcontextprotocol #model-context-protocol-servers

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

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

启动命令npx -y @pinkpixel/mem0-mcp

需要配置的环境变量

MEM0_API_KEY密钥

DEFAULT_USER_ID

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@pinkpixel/mem0-mcpstdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

@pinkpixel/mem0-mcp MCP 服务 ✨

一个与 Mem0.ai 集成的模型上下文协议（MCP）服务，为大模型提供持久记忆能力。它允许 AI Agent 跨会话存储和检索信息。

该服务使用 mem0ai Node.js SDK 实现核心功能。

功能 🧠

现代化与高级工具（v0.8.0）

add_memory：从文本内容或结构化消息数组中存储记忆。
- 输入： content（字符串）或 messages（角色/内容对象数组）、userId（字符串）、runId / sessionId（字符串）、agentId（字符串）、appId（字符串）、metadata（对象）、infer（布尔值）、customInstructions（字符串）、waitForCompletion（布尔值，默认值：true）、timeoutMs（数字，默认值：15000）
- 行为： Cloud V3 的新增操作为异步执行。默认情况下，此工具会轮询后台队列直至操作完成。传入 waitForCompletion: false 可立即获取 eventId。
search_memories：使用语义与 BM25 混合筛选条件搜索记忆。
- 输入： query（字符串）、userId（字符串）、runId / sessionId（字符串）、agentId（字符串）、appId（字符串）、filters（对象）、threshold（数字）、topK（数字）、rerank（布尔值）、referenceDate（字符串）
- 行为： 自动将范围变量嵌套到 V3 的 filters 块中，以防止 API 验证错误。
search_memory：与旧版本兼容的 search_memories 别名。
list_memories：按标识符范围分页列出记忆记录。
- 输入： userId（字符串）、runId / sessionId（字符串）、agentId（字符串）、appId（字符串）、filters（对象）、page（数字）、pageSize（数字）
get_memory：根据 ID 获取单条记忆记录。
- 输入： memoryId（字符串）
update_memory：修改现有记忆的文本或元数据。
- 输入： memoryId（字符串）、text（字符串）、metadata（对象）
delete_memory：根据 ID 删除指定的记忆记录。
- 输入： memoryId（字符串）
get_memory_history：获取记忆修订的审计跟踪记录（仅限云端）。
- 输入： memoryId（字符串）
get_memory_capabilities：显示当前后端存储模式的功能矩阵和支持标记。
- 输入： 无
batch_update_memories：批量更新多条记忆的文本内容（仅限云端）。
- 输入： updates（由 { memoryId: string, text: string } 对象组成的数组）
batch_delete_memories：批量删除多条记忆。
- 输入： memoryIds（字符串数组）、confirm（布尔值，必须为 true 才会执行）
rate_memory：提交对记忆记录的质量反馈评价（仅限云端）。
- 输入： memoryId（字符串）、feedback（字符串：positive、negative、very_negative）、reason（字符串，可选）
get_memory_event：手动获取特定后台事件任务的详细信息（仅限云端）。
- 输入： eventId（字符串）
list_memory_events：列出后台记忆处理事件的历史日志（仅限云端）。
- 输入： page（数字）、pageSize（数字）
create_memory_export：启动异步记忆导出查询任务（仅限云端）。
- 输入： schema（对象）、filters（对象，可选）、exportInstructions（字符串，可选）
get_memory_export：获取记忆导出任务的状态和下载元数据（仅限云端）。
- 输入： exportId（字符串）

先决条件 🔑

此服务支持三种存储模式：

云存储模式 ☁️（推荐用于生产环境）
- 需要 Mem0 API 密钥（通过 MEM0_API_KEY 环境变量提供）
- 记忆会持久存储在 Mem0 的云服务端
- 无需本地数据库
- 完整支持所有功能，包括高级筛选和搜索
Supabase 存储模式 🗄️（推荐用于自托管）
- 需要 Supabase 凭据（SUPABASE_URL 和 SUPABASE_KEY 环境变量）
- 需要用于嵌入的 OpenAI API 密钥（OPENAI_API_KEY 环境变量）
- 记忆会持久存储在你的 Supabase 数据库中
- 提供免费套餐，可自托管
- 需要进行初始数据库设置（下方提供 SQL 迁移）
本地存储模式 💾（仅用于开发/测试）
- 需要 OpenAI API 密钥（通过 OPENAI_API_KEY 环境变量提供）
- 记忆存储在内存向量数据库中（默认不持久化）
- 除非配置了持久化存储，否则服务重启时数据会丢失

安装与配置 ⚙️

你可以通过以下三种主要方式运行此服务：

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 Mem0 Memory Server：

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

1. 全局安装（推荐频繁使用时选择）

全局安装此软件包，并使用 mem0-mcp 命令：

npm install -g @pinkpixel/mem0-mcp

全局安装后，你可以直接运行服务：

mem0-mcp

配置 MCP 客户端以使用全局命令：

云存储配置（全局安装）

{
  "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 存储配置（全局安装）

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

本地存储配置（全局安装）

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

2. 使用 `npx`（推荐偶尔使用时选择）

配置 MCP 客户端（例如 Claude Desktop、Cursor、Cline、Roo Code 等），以使用 npx 运行服务：

云存储配置（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 存储配置（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"
      }
    }
  }
}

本地存储配置（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. 从克隆的仓库运行

注意：此方法要求你先使用 git clone 克隆仓库。

克隆仓库、安装依赖并构建服务：

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

然后，配置 MCP 客户端，使用 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",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Supabase 存储配置（克隆的仓库）

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

本地存储配置（克隆的仓库）

{
  "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"
      ]
    }
  }
}

重要说明：

将 /absolute/path/to/mem0-mcp/ 替换为你克隆仓库的实际绝对路径
使用 build/index.js 文件，而不是 src/index.ts 文件
MCP 服务需要保持 stdout 清洁以进行协议通信；任何向 stdout 写入内容的库或代码都可能干扰协议

Supabase 设置 🗄️

如果选择使用 Supabase 存储模式，需要在 Supabase 数据库中设置所需的数据表。

1. 创建 Supabase 项目

前往 supabase.com 并创建一个新项目
在项目设置中记下项目 URL 和 anon 密钥

2. 运行 SQL 迁移

在 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. 设置环境变量

将以下变量添加到 MCP 配置中：

SUPABASE_URL：你的 Supabase 项目 URL（例如，https://your-project.supabase.co）
SUPABASE_KEY：你的 Supabase anon 密钥
OPENAI_API_KEY：你的 OpenAI API 密钥（用于嵌入）

Supabase 模式的优势

✅ 持久化存储 - 服务重启后数据仍会保留
✅ 提供免费套餐 - 为开发提供慷慨的免费额度
✅ 可自托管 - 可以运行自己的 Supabase 实例
✅ 可扩展 - 随需求增长而扩展
✅ SQL 访问 - 直接访问数据库以执行高级查询
✅ 实时功能 - 内置实时订阅功能

参数配置 🎯

了解 Mem0 参数

服务器使用四个关键参数来组织和限定记忆的范围：

userId - 标识用户（必填）
agentId - 标识发起工具调用的大模型/Agent（可选）
appId - 标识用户的项目/应用程序——此参数用于控制项目范围！（可选）
sessionId - 标识对话会话（在 Mem0 中对应 run_id）（可选）

环境变量回退 🔄

MCP 服务支持通过环境变量回退来设置用户标识和项目配置：

DEFAULT_USER_ID：工具调用未提供用户 ID 时使用的回退值
DEFAULT_AGENT_ID：用于标识大模型/Agent 的回退 Agent ID
DEFAULT_APP_ID：用于限定项目范围的回退 App ID

优先级顺序（重要！）

工具参数（最高优先级）——大模型在工具调用中提供的值
环境变量（回退值）——MCP 配置中的值

示例行为：

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

如果大模型提供参数：

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

结果：使用 session-123、different-agent 和 special-project

如果大模型省略参数：

{
  "tool": "add_memory",
  "arguments": {
    "content": "Remember this"
    // All IDs omitted - uses environment variables
  }
}

结果：使用 john-doe、my-assistant 和 my-project

控制大模型行为

若要确保使用环境变量，请向大模型提供以下指示：

“使用环境中配置的默认用户 ID”
“不要指定 userId、agentId 或 appId 参数”
“让服务器使用已配置的默认值”

系统提示词建议

为获得最佳效果，请在系统提示词中加入类似以下指示：

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

使用 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"
      }
    }
  }
}

或者直接使用 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"
      }
    }
  }
}

存储模式对比 🔄

云存储（Mem0 API）☁️

默认持久化 - 记忆在不同会话和服务器重启后仍然可用
无需本地数据库 - 所有数据都存储在 Mem0 服务器上
检索质量更高 - 使用 Mem0 优化的搜索算法
支持更多字段 - 支持 agent_id 和 threshold 参数
全托管 - 无需设置或维护
需要 - Mem0 API 密钥

Supabase 存储 🗄️

持久化存储 - 数据存储在 Supabase PostgreSQL 数据库中
提供免费套餐 - 为开发和小型项目提供充足的免费额度
可自托管 - 可运行自己的 Supabase 实例，完全掌控数据
SQL 访问 - 可直接访问数据库，执行高级查询和分析
可扩展 - 随需求增长，从免费套餐扩展至企业级
向量搜索 - 使用 pgvector 扩展实现高效的相似度搜索
实时功能 - 内置实时订阅和 Webhook
需要 - 配置 Supabase 项目，并提供用于嵌入的 OpenAI API 密钥

本地存储（OpenAI API）💾

默认在内存中存储 - 数据仅存储在 RAM 中，不会长期持久保存。虽然可能会进行一些缓存，但不应依赖此方式进行永久存储。
存在数据丢失风险 - 服务器重启、系统重启或进程终止时，记忆数据都会丢失
推荐用途 - 仅用于开发、测试或临时使用
持久化存储 - 如需可靠的长期记忆，请使用云存储或 Supabase 选项
使用 OpenAI 嵌入 - 用于向量搜索功能
独立运行 - 所有数据都保留在本机
需要 - OpenAI API 密钥

开发 💻

克隆仓库并安装依赖项：

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

构建服务器：

npm run build

若要在文件更改时自动重新构建，请用于开发：

npm run watch

调试 🐞

由于 MCP 服务通过 stdio 通信，调试可能颇具挑战。以下是一些可行的方法：

使用 MCP Inspector：此工具可监控 MCP 协议通信：

npm run inspector

控制台日志：添加控制台日志时，请始终使用 console.error() 而不是 console.log()，以免干扰 MCP 协议
环境文件：本地开发时使用 .env 文件，以简化 API 密钥和其他配置选项的设置

技术实现说明 🔧

1. 平台 V3 异步添加与轮询

Mem0 Cloud V3 添加操作是一个异步后台任务。调用 add_memory 时，服务会向 /v3/memories/add/ 提交请求，并收到一个 eventId。

同步轮询（默认）： 服务每隔 500ms 轮询一次事件状态端点（/v1/event/{id}/），最多等待 timeoutMs（默认 15000ms），直到状态变为 SUCCEEDED 或 FAILED。任务完成后，会返回最终结果。
异步执行： 传入 "waitForCompletion": false 可跳过轮询。服务会立即返回 eventId 和 PENDING 状态。

2. 嵌套 V3 筛选条件规范化

Mem0 Cloud V3 搜索和列表端点会拒绝顶层作用域 ID（user_id、agent_id、app_id、run_id），并返回 HTTP 400 错误。V3 要求将这些字段放在嵌套的 filters 对象中。为了避免破坏客户端配置，此服务会在发送 API 请求前，自动将顶层作用域变量（userId、agentId、appId、runId/sessionId）规范化，并在底层将其合并到嵌套的 filters 对象中。

3. 能力门控

不同后端支持的功能集各不相同。调用 get_memory_capabilities 可获取当前后端的结构化能力矩阵。

云模式： 全面支持所有功能（apiVersion: "v3"、异步事件、列表、审计历史记录、逻辑查询）。
Supabase / 本地模式： 标准 V1 向量接口。不支持的云端专属工具（例如 get_memory_history 或 list_memories）会优雅失败，并给出明确的功能不可用提示。

4. 日志与协议稳定性

MCP 服务使用 stdout 通过 JSON-RPC 通信。任何意外输出到 stdout 的库日志都会破坏协议通道，导致客户端崩溃。此服务会覆盖默认的 console 输出方法（例如 console.log），以重定向或屏蔽标准日志，确保 stdio 通信干净无误。

由 Pink Pixel 倾情打造 💖

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。