🧠 Mem0 MCP 服务器 - 自托管的AI内存
一个生产就绪的、自托管的模型上下文协议（MCP）服务器，为Claude Code及其他AI助手提供持久且智能的记忆功能。该服务器具备异步/等待架构、知识图谱智能、智能文本分块以及企业级安全特性。使用Docker Compose构建，实现一键部署。
✨ 特点/功能
核心功能
- 🚀 表情符号“🚀”通常被用来表示火箭、快速上升或加速等含义。在中文中，它可以直接用作描述火箭或快速上升的情景，或者作为一种表情来传达兴奋、期待或快速进展的情绪。例如：“火箭发射升空🚀”或“项目进展迅速🚀”。 一键部署 - 用一个脚本启动整个堆栈
- 🔒（锁形图标，通常表示安全、保密或锁定状态） 100% 自托管 - 无外部API依赖（在使用Ollama时）
- 🔐 翻译为中文是：锁形符号（通常表示密码或保密） 基于令牌的认证 - 通过基于PostgreSQL的令牌管理实现安全的多用户访问
- 🌐（表示“网络”或“互联网”的符号，无直接对应中文词汇，通常可结合上下文理解为“网络”或“互联网”等含义） 多LLM（大型语言模型）支持 - 与Ollama、OpenAI或Anthropic兼容
- 🎯（瞄准目标） 项目隔离 - 每个项目目录自动进行内存隔离
- 📊（表格） 语义搜索 - 使用pgvector进行基于向量的搜索
- ⚡（闪电符号，常用于表示快速、能量、电力或警示等） 13个MCP工具 - 完整的内存管理 + 智能分析
- 🔌（插头、电源插座） 双传输支持 - 现代HTTP流（推荐）+ 传统SSE传输
- 🐳（海豚） Docker Compose - 轻松协调所有服务
- 🧪 表示“实验器材”或“科学实验”的符号。 综合测试 - 包含自动化测试套件
- 📝（备忘录/笔记） 审计日志记录 - 记录所有认证尝试和令牌使用情况
🧠 记忆智能系统
- 🔗 知识图谱 - 将记忆与类型化的关系（如“相关于”、“依赖于”、“替代”等）关联起来
- 🕒 时间追踪 - 跟踪知识随时间的演变
- 🏗️ 翻译为中文是“建筑工地”或“正在建设中”。这个表情符号通常用来表示建筑活动、施工场景或正在进行的建设项目。 架构映射 - 映射系统组件和依赖关系
- 📊（图表/数据表） 影响分析 - 理解变革的连锁效应
- 📝 决策追踪 - 记录技术决策及其优缺点/备选方案
- 🎯（目标、靶心） 主题聚类 - 自动检测知识群组
- ⭐ 质量评分 - 基于验证和引用的信任评分
- 🚀 表情符号“🚀”通常表示火箭、快速上升或飞速前进，可以翻译为“🚀（火箭/快速上升）”。不过，在实际应用中，这个表情符号常被用来表达一种积极向上、勇往直前的精神状态，或者表示某事物发展迅速、进步神速。因此，也可以根据具体语境翻译为“🚀（飞速前进/积极进取）”等。 情报分析 - 包含可操作性建议的全面健康报告
📦 智能文本分块系统
- ✂️（剪刀） 语义分块 - 自动在段落/句子边界处拆分大文本
- 🔄（循环/旋转的符号，常用于表示重复、循环或持续的动作/过程） 上下文保留 - 每个数据块之间有150个字符的重叠，以保持上下文的连续性
- ⚡（闪电符号，常用于表示速度、能量、活力或警告等） 性能优化 - 防止在使用80亿+参数的嵌入模型处理大型文本输入时出现超时
- 标签：🏷️ 块元数据 - 带有块索引、总块数、大小和重叠指标的完整追踪
- 🔗 会话连续性 - 所有块都共享相同的
run_id用于相关记忆分组 - 🎯（目标） 透明运营 - 短文本（\1000个字符）：** 在语义边界处自动分块，同时保留上下文信息
分块策略：
- 基于段落的拆分： 文本首先按段落边界（双换行）进行拆分
- 基于句子的回退机制： 如果段落超过1000个字符，则在句子边界处进行拆分
- 上下文保持： 块与块之间150个字符的重叠保持了语义的连续性
- 会话跟踪： 来自同一文本的所有块共享一个单一的
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调整分块行为：
- 编辑
.env使用您偏好的值进行文件处理 - 重启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）
| 终点 | 方法 | 描述 |
|---|---|---|
/health | GET | 健康检查 |
/docs | GET | OpenAPI 文档 |
/memories | POST | 创建内存 |
/memories | GET | 获取所有记忆 |
/memories/{id} | GET | 获取特定内存 |
/memories/{id} | PUT | 更新内存 |
/memories/{id} | DELETE | 删除内存 |
/memories/{id}/history | GET | 获取历史记录 |
/search | POST | 语义搜索 |
/reset | POST | 重置所有记忆 |
/configure | POST | 配置 Mem0 |
内存智能终端（15）
| 终点 | 方法 | 描述 | ||
|---|---|---|---|---|
/graph/link | POST | 将记忆与人际关系联系起来 | ||
/graph/related/{id} | GET | 获取相关记忆（图遍历） | ||
/graph/path | GET | 查找记忆之间的路径 | ||
/graph/evolution/{topic} | GET | 跟踪知识演变 | ||
/graph/superseded | GET | 查找过时的记忆 | ||
/graph/thread/{id} | GET | 获取对话线程 | ||
/graph/component | POST | 创建组件节点 | ||
/graph/component/dependency | POST | 链接组件依赖项 | ||
/graph/component/link-memory | POST | 将链接内存绑定到组件 | ||
/graph/impact/{name} | GET | 分析组件影响 | ||
/graph/decision | 帖子 | 列出利弊以做出决定 | ||
/graph/decision/{id} | GET | 获取决策理由 | ||
/graph/communities | GET | 检测内存社区 | ||
/graph/trust-score/{id} | GET | 计算信任分数 | ||
/graph/intelligence | GET | 🚀（译文： | GET | 箭头发射） 全面情报分析 |
MCP 服务器（端口 8080）
| 终点 | 描述 |
|---|---|
/mcp | HTTP 流端点（推荐） |
/sse | SSE 终端点（旧版） |
/ | 健康检查 |
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"生产安全检查清单
- 更改默认密码 在
.env:
POSTGRES_PASSWORD=
NEO4J_PASSWORD=- 轮换认证令牌 定期地；经常地
python3 scripts/mcp-token.py create --user-id user@company.com- 限制网络访问 - 不要将端口公开
- 使用HTTPS - 通过反向代理（nginx、Traefik）添加TLS终止
- 监控审计日志:
python3 scripts/mcp-token.py audit --days 7- 测试安全性:
./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运行缓慢
- 使用更小的嵌入模型：
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
OLLAMA_EMBEDDING_DIMS=768- 切换到OpenAI：
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...- 预热Ollama模型 - 保持它们在内存中加载
内存无法存储
- 检查Ollama的连接状态：
curl http://192.168.1.2:11434/api/tags- 验证模型是否可用：
ollama list- 检查 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社区倾心打造