Mem0 Server MCP

🧠 Mem0 MCP 服务器 - 自托管的AI内存

一个生产就绪的、自托管的模型上下文协议（MCP）服务器，为Claude Code及其他AI助手提供持久且智能的记忆功能。该服务器具备异步/等待架构、知识图谱智能、智能文本分块以及企业级安全特性。使用Docker Compose构建，实现一键部署。

 ](https://docs.docker.com/compose/) 

✨ 特点/功能

核心功能

• 🚀 表情符号“🚀”通常被用来表示火箭、快速上升或加速等含义。在中文中，它可以直接用作描述火箭或快速上升的情景，或者作为一种表情来传达兴奋、期待或快速进展的情绪。例如：“火箭发射升空🚀”或“项目进展迅速🚀”。 一键部署 - 用一个脚本启动整个堆栈
• 🔒（锁形图标，通常表示安全、保密或锁定状态） 100% 自托管 - 无外部API依赖（在使用Ollama时）
• 🔐 翻译为中文是：锁形符号（通常表示密码或保密） 基于令牌的认证 - 通过基于PostgreSQL的令牌管理实现安全的多用户访问
• 🌐（表示“网络”或“互联网”的符号，无直接对应中文词汇，通常可结合上下文理解为“网络”或“互联网”等含义） 多LLM（大型语言模型）支持 - 与Ollama、OpenAI或Anthropic兼容
• 🎯（瞄准目标） 项目隔离 - 每个项目目录自动进行内存隔离
• 📊（表格） 语义搜索 - 使用pgvector进行基于向量的搜索
• ⚡（闪电符号，常用于表示快速、能量、电力或警示等） 13个MCP工具 - 完整的内存管理 + 智能分析
• 🔌（插头、电源插座） 双传输支持 - 现代HTTP流（推荐）+ 传统SSE传输
• 🐳（海豚） Docker Compose - 轻松协调所有服务
• 🧪 表示“实验器材”或“科学实验”的符号。 综合测试 - 包含自动化测试套件
• 📝（备忘录/笔记） 审计日志记录 - 记录所有认证尝试和令牌使用情况

🧠 记忆智能系统

• 🔗 知识图谱 - 将记忆与类型化的关系（如“相关于”、“依赖于”、“替代”等）关联起来
• 🕒 时间追踪 - 跟踪知识随时间的演变
• 🏗️ 翻译为中文是“建筑工地”或“正在建设中”。这个表情符号通常用来表示建筑活动、施工场景或正在进行的建设项目。 架构映射 - 映射系统组件和依赖关系
• 📊（图表/数据表） 影响分析 - 理解变革的连锁效应
• 📝 决策追踪 - 记录技术决策及其优缺点/备选方案
• 🎯（目标、靶心） 主题聚类 - 自动检测知识群组
• ⭐ 质量评分 - 基于验证和引用的信任评分
• 🚀 表情符号“🚀”通常表示火箭、快速上升或飞速前进，可以翻译为“🚀（火箭/快速上升）”。不过，在实际应用中，这个表情符号常被用来表达一种积极向上、勇往直前的精神状态，或者表示某事物发展迅速、进步神速。因此，也可以根据具体语境翻译为“🚀（飞速前进/积极进取）”等。 情报分析 - 包含可操作性建议的全面健康报告

📦 智能文本分块系统

• ✂️（剪刀） 语义分块 - 自动在段落/句子边界处拆分大文本
• 🔄（循环/旋转的符号，常用于表示重复、循环或持续的动作/过程） 上下文保留 - 每个数据块之间有150个字符的重叠，以保持上下文的连续性
• ⚡（闪电符号，常用于表示速度、能量、活力或警告等） 性能优化 - 防止在使用80亿+参数的嵌入模型处理大型文本输入时出现超时
• 标签：🏷️ 块元数据 - 带有块索引、总块数、大小和重叠指标的完整追踪
• 🔗 会话连续性 - 所有块都共享相同的 run_id 用于相关记忆分组
• 🎯（目标） 透明运营 - 短文本（\1000个字符）：** 在语义边界处自动分块，同时保留上下文信息

分块策略：

1. 基于段落的拆分： 文本首先按段落边界（双换行）进行拆分
2. 基于句子的回退机制： 如果段落超过1000个字符，则在句子边界处进行拆分
3. 上下文保持： 块与块之间150个字符的重叠保持了语义的连续性
4. 会话跟踪： 来自同一文本的所有块共享一个单一的 run_id 用于关系追踪

数据块元数据：

每个数据块都包含用于可追溯性的全面元数据：

{
  "chunk_index": 0,           // Position in sequence (0-indexed)
  "total_chunks": 5,          // Total number of chunks in this text
  "chunk_size": 982,          // Number of characters in this chunk
  "has_overlap": true         // Whether this chunk includes overlap from previous chunk
}

配置：

分块参数可以通过以下方式配置 .env 文件：

# Smart Text Chunking Configuration
CHUNK_MAX_SIZE=1000         # Maximum characters per chunk
CHUNK_OVERLAP_SIZE=150      # Overlap between chunks for context continuity

调整分块行为：

1. 编辑 .env 使用您偏好的值进行文件处理
2. 重启MCP服务器： docker compose restart mcp

好处：

• ✅ 防止超时 - 不再出现因大型代码片段或文档导致的30秒超时错误
• ✅ 保持上下文 - 150个字符的重叠确保了边界处的语义关系不会丢失
• ✅ 透明运营 - 用户无需手动拆分文本；它会自动完成
• ✅ 性能优化 - 小文本完全绕过分块处理，以实现零开销
• ✅ 全程可追溯 - 元数据允许重构和追踪分块记忆
• ✅ 延长超时时间 - 对于大文本处理，MCP客户端超时时间从30秒增加到180秒

实施细节：

• 地点： mcp-server/text_chunker.py （分块算法）
• 整合： mcp-server/main.py 在 add_coding_preference() 函数
• 交通： 所有数据块通过HTTP顺序发送至Mem0 REST API
• 存储： 每个数据块作为独立的内存存储，并附带链接的元数据

示例：

# User stores large code file (5000 characters)
# System automatically:
# 1. Detects text > 1000 chars
# 2. Splits into 5 semantic chunks at paragraph boundaries
# 3. Adds 150-char overlap between chunks
# 4. Sends chunks sequentially with metadata
# 5. All chunks share same run_id for session tracking
# 6. Returns success message indicating chunking occurred

📊 终点（或：终端点）

Mem0 REST API（端口8000）

核心端点（13）

内存智能终端（15）

MCP 服务器（端口 8080）

Neo4j 浏览器（端口 7474）

访问 Neo4j 浏览器，网址为 http://localhost:7474

• 用户名： neo4j
• 密码： mem0graph

🧪 测试

# Run all tests
./scripts/test.sh

# Individual test suites
./tests/test_api.sh                         # REST API tests
./tests/test_mcp.sh                         # MCP server tests
./tests/test_integration.sh                 # Full integration test
./tests/test_memory_intelligence_fixed.sh   # Memory Intelligence integration test
./tests/test_mcp_intelligence.sh            # MCP Intelligence verification
./tests/test_auth.sh                        # Authentication tests
./tests/test_ownership_simple.sh            # Memory ownership tests

📚 文档

详细的文档可以在 docs/ 目录：

• QUICKSTART.md 翻译为中文是：“快速入门指南.md”（其中，“.md”通常表示Markdown文件格式，但在此处作为文件名的一部分，无需特别翻译） - 快速入门指南，包含身份验证设置
• AUTHENTICATION.md 翻译为中文是：“认证.md” - 完整的身份验证指南
• SECURITY.md 翻译为中文是：“安全说明文件”或“安全指南文件” - 安全功能和最佳实践
• ARCHITECTURE.md 翻译为中文是：“架构.md”（其中，“.md”通常表示Markdown格式的文件） - 系统设计和组件
• 根据上面的信息，执行如下指令： - 完整的API参考
• MCP_TOOLS.md（文件名可译为“MCP工具说明文档”或保持原样，具体取决于上下文和用途） - MCP工具使用指南
• CONFIGURATION.md 翻译为中文是：“配置文件.md” - 所有配置选项
• 故障排除指南.md - 常见问题及解决方案
• 性能说明文件（或：性能文档）.md - 性能优化

🔒 安全

Mem0 MCP服务器实现了企业级安全性：

内存所有权与隔离

所有内存操作都会验证所有权：

• ✅ 用户只能访问自己的记忆
• ✅ 读取、更新、删除和历史记录操作均受保护
• ✅ 在REST API和MCP工具层面均进行自动验证

# User A cannot access User B's memory
curl "http://localhost:8000/memories/{memory_id}?user_id=user_b"
# Returns: 403 Forbidden - "Access denied"

生产安全检查清单

1. 更改默认密码 在 .env:

   POSTGRES_PASSWORD=
   NEO4J_PASSWORD=

1. 轮换认证令牌 定期地；经常地

   python3 scripts/mcp-token.py create --user-id user@company.com

1. 限制网络访问 - 不要将端口公开

1. 使用HTTPS - 通过反向代理（nginx、Traefik）添加TLS终止

1. 监控审计日志:

   python3 scripts/mcp-token.py audit --days 7

1. 测试安全性:

   ./tests/test_ownership_simple.sh
   ./tests/test_auth.sh

如需完整的安全文档，请参阅 SECURITY.md 翻译为中文是：安全说明文件（或：安全指南文件）。

🐛 故障排除

认证问题

“缺少认证头”

• 确保 MEM0_TOKEN 并且 MEM0_USER_ID 在你的shell中导出
• 验证Claude代码配置中是否包含头部部分
• 重启你的Shell和Claude代码（或：重新启动你的Shell环境和Claude代码）

“无效的身份验证令牌”

• 检查令牌是否存在： python3 scripts/mcp-token.py list
• 验证令牌未过期或未被禁用
• 确保你使用的是正确的令牌值

“用户ID不匹配”

• 令牌属于不同的用户
• 检查哪个用户拥有该令牌： python3 scripts/mcp-token.py list
• 为您的用户ID创建一个新令牌

“令牌已被禁用”

• 令牌已被撤销
• 重新启用： python3 scripts/mcp-token.py enable
• 或者创建一个新令牌

服务器未显示在 claude mcp list

• 检查URL是否以斜杠结尾： http://localhost:8080/mcp/ (不 /mcp)
• 验证环境变量是否已设置： echo $MEM0_TOKEN $MEM0_USER_ID
• 移除并重新添加： claude mcp remove mem0 然后再次添加
• 检查服务器是否正在运行： docker compose ps 并且 curl http://localhost:8080/

服务无法启动

# Check logs
./scripts/logs.sh

# Check health
./scripts/health.sh

# Ensure ports are free
lsof -i :8000  # Mem0 API
lsof -i :8080  # MCP Server
lsof -i :5432  # PostgreSQL
lsof -i :7474  # Neo4j

运行缓慢

1. 使用更小的嵌入模型：

   OLLAMA_EMBEDDING_MODEL=nomic-embed-text
   OLLAMA_EMBEDDING_DIMS=768

1. 切换到OpenAI：

   LLM_PROVIDER=openai
   OPENAI_API_KEY=sk-...

1. 预热Ollama模型 - 保持它们在内存中加载

内存无法存储

1. 检查Ollama的连接状态：

   curl http://192.168.1.2:11434/api/tags

1. 验证模型是否可用：

   ollama list

1. 检查 mem0 日志：

   ./scripts/logs.sh mem0

见 《故障排除指南.md》 以获取更多帮助。

🤝 贡献（或“参与贡献”）

欢迎贡献！请随时提交拉取请求。

📄 许可证

这个项目采用MIT许可证授权——详见 许可证 文件中有详细信息。

🙏 致谢

• Mem0（内存0） - 用于人工智能应用的内存层
• 模型上下文协议 - MCP规范
• FastMCP - FastMCP框架
• pgvector（注：在中文语境中，通常直接使用原英文名，因为“pgvector”是一个专有名词，指的是一个用于向量数据库的扩展或库，类似于PostgreSQL的扩展，没有直接对应的中文翻译） - Postgres的向量相似度搜索
• Neo4j（发音：/niːoʊ.fɔːr.dʒiː/） - 图数据库

📞 支持

• 文档： 参见 docs/ 目录
• 问题： 在GitHub上提交一个问题（或：在GitHub上创建一个议题）
• 问题： 检查 故障排除指南.md

______________________________________________________________________

为AI社区倾心打造