Openmemory MCP Troubleshooting

OpenMemory MCP故障排除指南

此存储库包含OpenMemory MCP Server与Claude Desktop和其他MCP客户端集成的全面故障排除文档。

常见错误：“服务器传输意外关闭”

这是设置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桌面正在运行
• 已安装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配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %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)

故障排除步骤

第一步：检查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密钥

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

问题2：Docker无法运行

症状：连接被拒绝错误 解决方案：启动Docker桌面并运行 make up 再次

问题3：港口冲突

症状：地址已在使用中错误 解决方案：使用端口8765或3001终止进程

问题4：未找到SSE客户端

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

问题5:CORS问题

症状：日志中的跨源错误 解决方案：确保使用 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等）
• web UI位于http://localhost:3001显示已连接的客户端

额外资源

• OpenMemory文档
• MCP文件
• 克劳德桌面MCP指南

贡献

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