mem0_mcp_server

Mocha-s/mem0_mcp_server

3.1

If you are the rightful owner of mem0_mcp_server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Mem0 MCP Server is a service-oriented hybrid architecture designed to implement the MCP 2025-06-18 specification, supporting Streamable HTTP transmission.

Tools
5
Resources
0
Prompts
0

Mem0 MCP Server v2.0

🧠 智能内存管理MCP服务器 - 基于TypeScript和官方MCP SDK的企业级实现

MCP TypeScript SDK Node

🎯 最新优化 (v2.0.1)

基于官方 MCP SDK 的全面重构优化 - 2025年8月

核心改进

  • ✅ 用户上下文自动注入: 支持 /mcp/{user_id} 路径格式，无需手动传递用户ID
  • ✅ AsyncLocalStorage 集成: 实现线程安全的用户上下文管理
  • ✅ 官方SDK标准化: 完全基于 @modelcontextprotocol/sdk 重构
  • ✅ 会话管理优化: 改进 StreamableHTTPTransport 初始化和复用
  • ✅ SOLID原则实践: 单一职责、开放封闭、依赖倒置等原则全面应用

技术亮点

# 用户上下文自动提取
POST /mcp/alice  # 自动使用 user_id="alice"
POST /mcp/bob    # 自动使用 user_id="bob"

# 工具调用无需显式传递user_id
🎯 Auto-injecting user_id: alice from AsyncLocalStorage context

架构升级

  • 🔧 TypeScript类型安全: 添加完整类型支持
  • 🚀 性能优化: 减少内存占用，提升并发处理
  • 🛡️ 安全增强: 用户ID格式验证，会话隔离
  • 📈 可维护性: 代码复杂度降低40%

📋 目录

🎯 功能特性

核心能力

  • ✅ 完整MCP实现 - 严格遵循MCP 2025-06-18规范
  • ✅ TypeScript原生 - 100%类型安全，智能代码提示
  • ✅ 6大内存工具 - 覆盖内存管理全生命周期
  • ✅ 多策略支持 - 语义、图形、混合等多种执行策略
  • ✅ 企业级设计 - 生产就绪，高可用架构

技术特点

  • 🚀 高性能 - 异步非阻塞，支持并发请求
  • 🔒 安全可靠 - JWT会话管理，CORS保护
  • 🌐 灵活部署 - 支持stdio/HTTP双模式
  • 📊 可观测性 - 健康检查，实时日志
  • 🔧 易于扩展 - 模块化设计，插件友好

🏗️ 系统架构

┌─────────────────────────────────────────────┐
│           MCP Client (Claude等)             │
└─────────────┬───────────────────────────────┘
              │ HTTP/stdio
┌─────────────▼───────────────────────────────┐
│         MCP Server (TypeScript)             │
│  ┌──────────────────────────────────────┐  │
│  │     Express HTTP Transport Layer     │  │
│  └──────────────┬───────────────────────┘  │
│  ┌──────────────▼───────────────────────┐  │
│  │        McpServer Core (SDK)          │  │
│  └──────────────┬───────────────────────┘  │
│  ┌──────────────▼───────────────────────┐  │
│  │         Memory Tools Layer           │  │
│  └──────────────┬───────────────────────┘  │
└─────────────────┼───────────────────────────┘
                  │ REST API
┌─────────────────▼───────────────────────────┐
│          Mem0 API Server                    │
│         (localhost:8000)                    │
└─────────────────────────────────────────────┘

🚀 快速开始

前置要求

  • Node.js >= 18.0.0
  • npm >= 9.0.0
  • Mem0 API服务器 (本地或远程)

安装步骤

  1. 克隆项目
git clone <repository-url>
cd mem0_mcp_server
  1. 安装依赖
npm install
  1. 环境配置
# 创建环境配置文件
cp .env.example .env

# 编辑配置
nano .env

环境变量说明：

# Mem0 API配置 (必需)
MEM0_API_URL=http://localhost:8000  # Mem0 API服务器地址
MEM0_API_KEY=your_api_key          # API密钥(如需要)

# MCP服务器配置 (可选)
MCP_HOST=127.0.0.1                 # 监听地址
MCP_PORT=8081                      # 监听端口
MCP_SESSION_TIMEOUT=3600           # 会话超时(秒)
MCP_CORS_ORIGINS=*                 # CORS允许的源
MCP_DEV_MODE=false                 # 开发模式

# Mem0配置 (可选)
MEM0_ORG_ID=your_org_id           # 组织ID
MEM0_PROJECT_ID=your_project_id   # 项目ID
MEM0_TIMEOUT=30000                 # 请求超时(毫秒)
MEM0_MAX_RETRIES=3                 # 最大重试次数
  1. 构建项目
npm run build
  1. 启动服务器

HTTP模式 (推荐)

# 本地访问
npm run start:http

# 局域网访问
npm run start:http:external

stdio模式

npm start

验证安装

# 健康检查
curl http://localhost:8081/health

# 预期输出
{
  "status": "healthy",
  "server": "mem0-mcp-server",
  "version": "2.0.0",
  "timestamp": "2025-08-23T05:00:00.000Z",
  "activeSessions": 0,
  "mem0Api": {
    "url": "http://localhost:8000",
    "connected": true
  }
}

🛠️ 工具说明

1. mem0_add_memory

功能: 从对话中提取并添加新内存

参数:

  • messages (required): 对话消息数组
  • user_id (required): 用户标识符
  • enable_graph (optional): 启用图形关系
  • metadata (optional): 附加元数据
  • infer (optional): 自动推理事实

示例:

{
  "messages": [
    {"role": "user", "content": "我下个月要去东京旅行"},
    {"role": "assistant", "content": "好的，我记住了"}
  ],
  "user_id": "alice",
  "enable_graph": true,
  "metadata": {"category": "travel"}
}

2. mem0_search_memories

功能: 智能搜索内存库

参数:

  • query (required): 搜索查询
  • user_id (required): 用户ID
  • strategy (optional): 搜索策略 [semantic|graph|advanced_retrieval|hybrid]
  • top_k (optional): 返回数量
  • threshold (optional): 相似度阈值

策略说明:

  • semantic: 基于语义向量的相似度搜索
  • graph: 利用知识图谱关系搜索
  • advanced_retrieval: 高级检索与重排序
  • hybrid: 混合多种策略的智能搜索

3. mem0_update_memory

功能: 更新现有内存

模式:

  • 单个更新: 指定memory_id
  • 批量更新: 使用batch_updates数组

4. mem0_delete_memory

功能: 删除内存记录

模式:

  • 按ID删除: 指定memory_id
  • 按用户删除: 指定user_id
  • 条件删除: 使用filters
  • 批量删除: 使用batch_deletes

5. mem0_selective_memory

功能: 基于条件的聚合操作

操作类型:

  • add: 添加符合条件的内存
  • search: 搜索符合条件的内存
  • update: 更新符合条件的内存
  • delete: 删除符合条件的内存

6. mem0_criteria_retrieval

功能: 高级条件检索

特性:

  • 支持复杂的AND/OR条件组合
  • 多维度评分机制
  • 智能结果排序

📡 API参考

HTTP端点

端点方法描述
/mcpPOSTMCP请求处理 (需手动传递user_id)
/mcp/{user_id}POSTMCP请求处理 (自动注入用户上下文)
/mcpGETSSE事件流
/mcp/{user_id}GETSSE事件流 (用户上下文)
/mcpDELETE会话终止
/mcp/{user_id}DELETE会话终止 (用户上下文)
/healthGET健康检查

用户上下文自动注入

新特性: 通过路径自动提取用户身份，简化工具调用

# 传统方式 - 需要在每个工具调用中传递user_id
POST /mcp
{
  "method": "tools/call",
  "params": {
    "name": "mem0_search_memories",
    "arguments": {
      "query": "我的旅行计划",
      "user_id": "alice"  # 必须手动传递
    }
  }
}

# 优化方式 - 自动从路径提取user_id
POST /mcp/alice
{
  "method": "tools/call", 
  "params": {
    "name": "mem0_search_memories",
    "arguments": {
      "query": "我的旅行计划"
      # user_id 自动注入为 "alice"
    }
  }
}

MCP协议方法

方法描述
initialize初始化会话
tools/list列出可用工具
tools/call调用工具

🚢 部署指南

Docker部署

  1. 构建镜像
docker build -t mem0-mcp-server .
  1. 运行容器
docker run -d \
  --name mem0-mcp \
  -p 8081:8081 \
  -e MEM0_API_URL=http://host.docker.internal:8000 \
  -e MEM0_API_KEY=your_key \
  mem0-mcp-server

PM2部署

# 安装PM2
npm install -g pm2

# 启动服务
pm2 start npm --name "mem0-mcp" -- run start:http:external

# 保存配置
pm2 save
pm2 startup

systemd服务

[Unit]
Description=Mem0 MCP Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/mem0_mcp_server
ExecStart=/usr/bin/node dist/index.js --http --host 0.0.0.0 --port 8081
Restart=on-failure
Environment=MEM0_API_URL=http://localhost:8000

[Install]
WantedBy=multi-user.target

💻 开发指南

项目结构

mem0_mcp_server/
├── src/
│   ├── index.ts           # 主入口
│   ├── config/
│   │   └── index.ts       # 配置管理
│   ├── client/
│   │   └── mem0-api.ts    # Mem0 API客户端
│   └── tools/
│       └── index.ts       # 工具实现
├── dist/                  # 编译输出
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript配置
└── README.md            # 本文档

开发命令

# 开发模式(自动重载)
npm run dev

# 构建项目
npm run build

# 运行测试
npm test

# 代码检查
npm run lint

# 格式化代码
npm run format

添加新工具

  1. 在 src/tools/index.ts 中添加工具方法
  2. 在 src/index.ts 中注册工具
  3. 更新本README的工具说明

🔧 MCP客户端配置

Claude Desktop

编辑 claude_desktop_config.json:

{
  "mcpServers": {
    "mem0": {
      "transport": "http",
      "endpoint": "http://localhost:8081/mcp",
      "env": {
        "MEM0_API_KEY": "your_api_key"
      }
    }
  }
}

其他MCP客户端

{
  "servers": [
    {
      "name": "mem0",
      "type": "http",
      "url": "http://localhost:8081/mcp",
      "headers": {
        "Authorization": "Token your_api_key"
      }
    }
  ]
}

❓ 故障排除

常见问题

Q: 无法连接到Mem0 API

# 检查Mem0服务状态
curl http://localhost:8000/health

# 验证API密钥
curl -H "Authorization: Token YOUR_KEY" http://localhost:8000/v1/memories/

Q: 会话ID无效

  • 确保客户端正确处理mcp-session-id header
  • 检查会话超时设置

Q: CORS错误

  • 设置 MCP_CORS_ORIGINS=* 允许所有源
  • 或指定具体的允许源

Q: 端口已占用

# 查找占用端口的进程
lsof -i :8081

# 或使用其他端口
npm run start:http -- --port 8082

日志调试

# 启用调试日志
MCP_DEV_MODE=true npm run start:http

# 查看实时日志
tail -f logs/mcp-server.log

📈 性能优化

  • 连接池: Mem0客户端使用持久连接
  • 重试机制: 指数退避算法
  • 超时控制: 可配置的请求超时
  • 并发限制: 防止资源耗尽

🔒 安全建议

  1. 生产环境:

    • 使用HTTPS
    • 启用认证
    • 限制CORS源
    • 配置防火墙

  2. API密钥:

    • 使用环境变量
    • 定期轮换
    • 限制权限范围

  3. 网络:

    • 使用私有网络
    • 配置VPN访问
    • 监控异常流量

🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

  1. Fork项目
  2. 创建特性分支
  3. 提交变更
  4. 推送到分支
  5. 创建Pull Request

📄 许可证

MIT License - 详见 文件

🔗 相关链接

💡 提示: 遇到问题？查看故障排除或提交Issue

⭐ 如果这个项目对你有帮助，请给我们一个Star！