OpenMemory MCP Troubleshooting Guide

OpenMemory MCP 故障排查指南

本仓库包含 OpenMemory MCP 服务与 Claude Desktop 及其他 MCP 客户端集成的全面故障排查文档。

常见错误：“Server transport closed unexpectedly”

设置 OpenMemory MCP 时最常见的错误：

2025-05-30T19:18:27.723Z [info] [openmemory] Server transport closed unexpectedly, this is likely due to the process exiting early.
2025-05-30T19:18:27.724Z [error] [openmemory] Server disconnected.

前提条件

开始故障排查前，请确保已准备好：

• Docker Desktop 正在运行
• 已安装 Node.js 和 npm
• OpenAI API 密钥
• Git

设置流程

1. 克隆并设置 OpenMemory

# Clone the repository
git clone https://github.com/mem0ai/mem0.git
cd openmemory

# Create and configure the .env file
cd api
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY
echo "OPENAI_API_KEY=your_actual_api_key_here" > .env
cd ..

# Build Docker images
make build

# Start all services
make up

# Start the frontend
cp ui/.env.example ui/.env
make ui

2. 确认服务正在运行

# Check Docker containers
docker ps | grep openmemory

# You should see:
# - openmemory-api-1
# - openmemory-postgres-1
# - openmemory-qdrant-1

# Test API endpoint
curl http://localhost:8765/health
curl http://localhost:8765/docs

# Test SSE endpoint
curl -N -H "Accept: text/event-stream" http://localhost:8765/mcp/claude/sse/ian

3. 配置 Claude Desktop

编辑 Claude Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

添加 OpenMemory 配置：

{
  "mcpServers": {
    "openmemory": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "http://localhost:8765/mcp/claude/sse/ian"
      ]
    }
  }
}

重要：记忆格式指南

使用 OpenMemory 存储记忆时，请遵循以下指南以获得最佳效果：

✅ 应该：

• 使用不带特殊格式的纯文本
• 保持记忆简洁，并使用自然的句子形式
• 将复杂信息拆分为逻辑片段（摘要 + 详情）
• 使用连贯的段落，而非列表
• 让每条记忆聚焦于单个主题或概念

❌ 不应该：

• 使用 Markdown 格式（粗体、斜体、标题）
• 创建编号列表或项目符号列表
• 添加换行或复杂结构
• 编写特别长的条目
• 使用特殊字符或格式符号

示例——良好的记忆格式：

Ian has 18 MCP servers installed in Claude Desktop for various automation and development tasks. The servers include applescript_execute for Mac system control, context7-mcp for documentation lookup, desktop-commander for file operations, and other tools for browser automation, task management, and screen capture.

示例——较差的记忆格式：

Ian's MCP Servers:
1. **applescript_execute** - Mac system control
2. **context7-mcp** - Documentation lookup
3. **desktop-commander** - File operations
... (long formatted list)

故障排查步骤

步骤 1：检查 Docker 日志

# Check API logs for errors
docker logs openmemory-api-1 --tail 50

# Check for specific errors
docker logs openmemory-api-1 2>&1 | grep -i error

步骤 2：验证 API 密钥

# Check if API key is set in the container
docker exec openmemory-api-1 env | grep OPENAI_API_KEY

步骤 3：测试 SSE 连接

创建测试文件 test-sse.js：

const EventSource = require('eventsource');
const es = new EventSource('http://localhost:8765/mcp/claude/sse/ian');

es.onopen = () => console.log('Connected to SSE');
es.onmessage = (event) => console.log('Message:', event.data);
es.onerror = (err) => console.error('Error:', err);

setTimeout(() => {
  es.close();
  console.log('Connection closed');
}, 10000);

运行它：

npm install eventsource
node test-sse.js

步骤 4：尝试其他配置

如果标准配置不起作用，请尝试以下替代方案：

选项 1：使用包装脚本

创建 /Users/ian/openmemory-mcp.sh：

#!/bin/bash
exec npx -y @modelcontextprotocol/server-sse http://localhost:8765/mcp/claude/sse/ian

使其可执行：

chmod +x /Users/ian/openmemory-mcp.sh

更新 Claude 配置：

{
  "mcpServers": {
    "openmemory": {
      "command": "/Users/ian/openmemory-mcp.sh",
      "args": []
    }
  }
}

选项 2：使用环境变量

{
  "mcpServers": {
    "openmemory": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse@latest",
        "http://localhost:8765/mcp/claude/sse/ian"
      ],
      "env": {
        "NODE_ENV": "production",
        "DEBUG": "mcp:*"
      }
    }
  }
}

步骤 5：检查端口是否可用

# Check if port 8765 is in use
lsof -i :8765

# Check if port 3001 is in use (UI)
lsof -i :3001

常见问题及解决方案

问题 1：缺少 API 密钥

症状：服务启动后立即断开连接 解决方案：确保在 openmemory/api/.env 中设置了 OPENAI_API_KEY

问题 2：Docker 未运行

症状：出现连接被拒绝错误 解决方案：启动 Docker Desktop，然后再次运行 make up

问题 3：端口冲突

症状：出现地址已被占用错误 解决方案：终止占用端口 8765 或 3001 的进程

问题 4：找不到 SSE 客户端

症状：出现命令未找到错误 解决方案：全局安装：npm install -g @modelcontextprotocol/server-sse

问题 5：CORS 问题

症状：日志中出现跨域错误 解决方案：确保 localhost 使用 http:// 而非 https://

快速诊断脚本

创建 diagnose.sh：

#!/bin/bash

echo "=== OpenMemory MCP Diagnostics ==="
echo

echo "1. Checking Docker..."
if docker ps > /dev/null 2>&1; then
    echo "✓ Docker is running"
    echo "   OpenMemory containers:"
    docker ps | grep openmemory | awk '{print "   - " $NF}'
else
    echo "✗ Docker is not running"
fi
echo

echo "2. Checking API..."
if curl -s http://localhost:8765/health > /dev/null 2>&1; then
    echo "✓ API is responding"
else
    echo "✗ API is not responding"
fi
echo

echo "3. Checking UI..."
if curl -s http://localhost:3001 > /dev/null 2>&1; then
    echo "✓ UI is accessible"
else
    echo "✗ UI is not accessible"
fi
echo

echo "4. Checking SSE endpoint..."
timeout 2 curl -s -N -H "Accept: text/event-stream" http://localhost:8765/mcp/claude/sse/ian > /dev/null 2>&1
if [ $? -eq 124 ]; then
    echo "✓ SSE endpoint is streaming"
else
    echo "✗ SSE endpoint is not working"
fi
echo

echo "5. Checking npm/npx..."
if command -v npx > /dev/null 2>&1; then
    echo "✓ npx is available"
else
    echo "✗ npx is not found"
fi

使其可执行并运行：

chmod +x diagnose.sh
./diagnose.sh

正常运行示例

配置正确后，你应该能在 Claude Desktop 中看到：

• OpenMemory 出现在 MCP 服务列表中
• 可以使用记忆工具（add_memory、search_memory 等）
• http://localhost:3001 上的 Web UI 显示已连接的客户端

其他资源

• OpenMemory 文档
• MCP 文档
• Claude Desktop MCP 指南

贡献

如果你发现其他问题或解决方案，请提交 PR，帮助其他人！