使用说明

@pinkpixel/mem0 mcp mcp服务器✨

一种集成了以下功能的模型上下文协议（MCP）服务器 Mem0.ai 为LLM提供持久存储能力。它允许AI代理跨会话存储和检索信息。

此服务器使用 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 （字符串）

先决条件🔑

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

云存储模式 ☁️ （推荐用于生产）
- 需要a 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安装

通过以下方式自动安装Claude Desktop的Mem0内存服务器史密瑟里:

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

基础存储配置（全局安装）

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

数据库存储配置（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克隆。

克隆存储库、安装依赖项并构建服务器：

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

上层存储配置（克隆存储库）

{
  "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和匿名密钥

2.运行SQL迁移

在Supabase SQL编辑器中运行以下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匿名密钥
OPENAI_API_KEY：您的OpenAI API密钥（用于嵌入）

Supabase模式的好处

✅ 持久化存储 -数据在服务器重启后仍然存在 ✅ 免费套餐可用 -丰富的免费开发层 ✅ 可自我托管 -可以运行自己的Supabase实例 ✅ 可扩展的 -随着您的需求而成长 ✅ SQL访问 -直接访问数据库以进行高级查询 ✅ 实时功能 -内置实时订阅

参数配置🎯

了解Mem0参数

服务器使用四个关键参数来组织和范围内存：

userId -标识用户（必填）
agentId -标识进行工具调用的LLM/代理（可选）
appId -标识用户的项目/应用程序- 这控制了项目范围！ （可选）
sessionId -标识对话会话（映射到 run_id 在Mem0中）（可选）

环境变量回退🔄

MCP服务器支持用户标识和项目设置的环境变量回退：

DEFAULT_USER_ID：在工具调用中未提供后备用户ID时
DEFAULT_AGENT_ID：用于标识LLM/代理的回退代理ID
DEFAULT_APP_ID：用于项目范围界定的后备应用程序ID

优先级顺序（重要！）

刀具参数 （最高优先级）-LLM在工具调用中提供的值
环境变量 （回退）-来自MCP配置的值

行为示例：

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

如果LLM提供参数：

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

如果LLM省略了参数：

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

结果：用途 john-doe, my-assistant，以及 my-project

控制LLM行为

为确保使用环境变量，请指示LLM：

“使用环境中配置的默认用户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 PostgreSQL数据库中
免费套餐可用 -为开发和小型项目提供丰富的免费层
自助式 -可以运行自己的Supabase实例以实现完全控制
SQL访问 -直接访问数据库以进行高级查询和分析
可扩展的 -随着您的需求而增长，从免费版到企业版
向量搜索 -使用pgvector扩展进行高效的相似性搜索
实时功能 -内置实时订阅和webhooks
需要 -Subabase项目设置和用于嵌入的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检查器：此工具可以监控MCP协议通信：

npm run inspector

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

技术实施说明🔧

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

添加Mem0 Cloud V3是一个异步后台任务。通话时 add_memory，服务器将请求提交给 /v3/memories/add/ 并接收 eventId.

同步轮询（默认）： 服务器轮询事件状态终结点(/v1/event/{id}/)每500毫秒最多 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 对象。为了防止破坏客户端配置，此服务器会自动规范顶级作用域变量(userId, agentId, appId, runId/sessionId)并将它们合并到嵌套中 filters 对象，然后再发送API请求。

3.能力门控

不同的后端支持不同的功能集。呼叫 get_memory_capabilities 以获得活动后端的结构化能力矩阵。

云模式： 完全支持所有功能(apiVersion: "v3"、异步事件、列表、审计历史、逻辑查询）。
Supabase/本地模式： 标准V1矢量接口。不支持的云专用工具（如 get_memory_history 或 list_memories)将优雅地失败，并显示明确的功能不可用消息。

4.日志记录和协议稳定性

MCP服务器通过JSON-RPC进行通信 stdout。任何意外的库日志都会打印到 stdout 将损坏协议通道并导致客户端崩溃。此服务器覆盖默认设置 console 输出方法（例如 console.log)重定向/静音标准日志记录，确保干净的stdio通信。

由...制作💖 由粉红色像素