使用说明

🧠 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个字符）跳过分块处理以实现最佳性能

🏗️ 建筑学

┌──────────────┐
│  Claude Code │  (Your IDE with MCP client)
└──────┬───────┘
       │ HTTP Stream (recommended): http://localhost:8080/mcp
       │ SSE (legacy): http://localhost:8080/sse
       │ + Token Authentication Headers
       ↓
┌──────────────┐
│  MCP Server  │  Port 8080 (FastMCP)
│  (Python)    │  • 13 MCP Tools (5 core + 8 intelligence)
│              │  • Token Validation
│              │  • Dual Transport Support
└──────┬───────┘
       │ HTTP REST API
       ↓
┌──────────────┐
│ Mem0 Server  │  Port 8000 (FastAPI)
│  (FastAPI)   │  • 28 REST Endpoints (13 core + 15 intelligence)
│              │  • Multi-LLM Support
│              │  • Vector + Graph Storage
│              │  • Memory Intelligence System
│              │  • Async/Await Architecture with Background Tasks
└──────┬───────┘
       │
   ┌───┴────┬──────────┬──────┐
   ↓        ↓          ↓      ↓
┌────────┐ ┌────┐  ┌─────┐ ┌──────┐
│Postgres│ │Neo4j│  │Auth │ │Ollama│
│pgvector│ │Graph│  │Token│ │ LLM  │
│Vector  │ │Intel-│  │Store│ │      │
│Search  │ │ligence│ │     │ │      │
└────────┘ └────┘  └─────┘ └──────┘

⚡ 异步架构

Mem0服务器采用FastAPI的异步/等待（async/await）架构以实现最佳性能：

非阻塞I/O： 并发处理多个请求，不阻塞
背景：Neo4j 同步 内存中的数据立即存储到PostgreSQL，然后异步同步到Neo4j
重试逻辑： 自动重试，采用指数退避策略（共尝试7次：1秒、2秒、4秒、8秒、16秒、32秒）
即时响应： API无需等待图表同步，即刻返回
容错性： 如果Neo4j同步失败，仍可通过PostgreSQL向量搜索访问内存数据

这种架构确保了即使在处理复杂的图操作时也能实现快速响应。

🚀 快速入门（5分钟）

先决条件

Docker 和 Docker Compose 已安装

docker --version
docker compose version

Ollama 服务器 使用模型（或OpenAI/Anthropic API密钥）

# On your Ollama server:
ollama pull qwen3:8b
ollama pull qwen3-embedding:8b

安装

# 1. Clone or copy this directory
cd /path/to/mem0-mcp

# 2. Create configuration file
cp .env.example .env

# 3. Edit .env with your Ollama server address (if needed)
nano .env  # Update OLLAMA_BASE_URL

# 4. Start everything!
./scripts/start.sh

就是这么简单！脚本将：

✅ 使用 pgvector 启动 PostgreSQL
✅ 启动Neo4j图数据库
✅ 启动Mem0 REST API服务器
✅ 启动Claude Code的MCP服务器
✅ 等待所有服务均恢复正常

设置身份验证

步骤1：运行数据库迁移

./scripts/migrate-auth.sh

步骤2：创建您的身份验证令牌

python3 scripts/mcp-token.py create \
  --user-id your.email@company.com \
  --name "Your Name" \
  --email your.email@company.com

这将输出您的令牌和设置说明。复制 MEM0_TOKEN 价值。

步骤3：添加到您的Shell配置文件中

将这些行添加到 ~/.zshrc 或者 ~/.bashrc：

export MEM0_TOKEN='mcp_abc123...'  # Your token from step 2
export MEM0_USER_ID='your.email@company.com'

然后重新加载：

source ~/.zshrc  # or ~/.bashrc

连接到Claude代码

推荐：使用Claude CLI（最简单）

# Add mem0 server with HTTP Stream transport (recommended)
claude mcp add mem0 http://localhost:8080/mcp/ -t http \
  -H "X-MCP-Token: ${MEM0_TOKEN}" \
  -H "X-MCP-UserID: ${MEM0_USER_ID}"

# Verify it's configured
claude mcp list

备选方案：手动配置

将此添加到您的Claude Code MCP配置文件中：

文件： ~/.config/claude-code/config.json

{
  "mcpServers": {
    "mem0": {
      "url": "http://localhost:8080/mcp/",
      "transport": "http",
      "headers": {
        "X-MCP-Token": "your-token-here",
        "X-MCP-UserID": "your.email@company.com"
      }
    }
  }
}

传统SSE传输（向后兼容）

# Using CLI
claude mcp add mem0 http://localhost:8080/sse/ -t http \
  -H "X-MCP-Token: ${MEM0_TOKEN}" \
  -H "X-MCP-UserID: ${MEM0_USER_ID}"

重要提示：

在URL中始终包含尾部斜杠： /mcp/ 或者 /sse/ (不是 /mcp 或者 /sse）
HTTP 流传输（/mcp/建议使用它，因为它是现代的MCP协议
上海证券交易所/sse/) 为保持向后兼容性而保留

重启Claude代码，你就可以开始使用了！

📖 使用方法

基本命令

# Start the stack
./scripts/start.sh

# View logs
./scripts/logs.sh          # All services
./scripts/logs.sh mem0     # Specific service

# Check health
./scripts/health.sh

# Run tests
./scripts/test.sh

# Stop the stack
./scripts/stop.sh

# Restart
./scripts/restart.sh

# Clean all data (⚠️  destructive)
./scripts/clean.sh

与Claude代码一起使用

一旦连接成功，您可以在Claude Code中使用这些命令：

"Store this code in memory: [your code snippet]"
"Search my memories for Python functions"
"Show all my stored coding preferences"
"Delete memory with ID [id]"
"Show history of memory [id]"

可用的MCP工具

核心内存工具（5）

添加编码偏好 - 存储代码片段和实现细节
搜索编码偏好设置 - 通过记忆进行语义搜索
获取所有编码偏好设置 - 检索所有存储的记忆
删除内存 - 通过ID删除特定内存
获取内存历史记录 - 查看更改历史

记忆智能工具（8）

链接记忆 - 在记忆之间建立类型化的关联（构建知识图谱）
获取相关记忆 - 图遍历以发现连接的上下文
分析内存智能 🚀 - 火箭/飞速前进 改变游戏规则者 综合情报报告，包含健康评分、集群分析及建议
创建组件 - 地图系统架构及其组件节点
链接组件依赖 - 定义组件之间的依赖关系
分析组件影响 - 分析变化的连锁效应
创建决策 - 记录技术决策及其优缺点/备选方案
获取决策理由 - 检索决策背景和推理过程

所有工具都会自动使用您MCP配置头中的身份验证凭据。

利用记忆智能

"Link these two memories as related"
"Show me all memories related to authentication"
"Analyze my project's knowledge graph health"
"Create a component called Database with type Infrastructure"
"What would be impacted if I change the Authentication component?"
"Record this decision: Use PostgreSQL, pros: ACID compliance, cons: complexity"

🔐 认证管理

令牌管理

# List all tokens
python3 scripts/mcp-token.py list

# List tokens for specific user
python3 scripts/mcp-token.py list --user-id john.doe@company.com

# Create a new token
python3 scripts/mcp-token.py create \
  --user-id john.doe@company.com \
  --name "John Doe" \
  --email john.doe@company.com

# Revoke (disable) a token
python3 scripts/mcp-token.py revoke mcp_abc123

# Re-enable a token
python3 scripts/mcp-token.py enable mcp_abc123

# Delete a token permanently
python3 scripts/mcp-token.py delete mcp_abc123

# View audit log
python3 scripts/mcp-token.py audit --days 30

# View user statistics
python3 scripts/mcp-token.py stats john.doe@company.com

测试认证

./tests/test_auth.sh

这个测试包括：缺少头部信息、无效令牌、用户ID不匹配、有效的身份验证、令牌撤销以及重新启用。

🔧 配置

大型语言模型（LLM）提供商

Ollama（默认 - 免费，自托管）

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://192.168.1.2:11434
OLLAMA_LLM_MODEL=qwen3:8b
OLLAMA_EMBEDDING_MODEL=qwen3-embedding:8b
OLLAMA_EMBEDDING_DIMS=4096

支持的模型：

LLM llama3、qwen3、mistral、phi3等。
嵌入（或表示）： qwen3-embedding（4096维），nomic-embed-text（768维），all-minilm（384维）

OpenAI（云服务 - 付费）

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-proj-...
OPENAI_LLM_MODEL=gpt-4o
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
OPENAI_EMBEDDING_DIMS=1536

Anthropic（云端 - 收费，仅限大型语言模型）

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

# Still need embeddings from Ollama or OpenAI:
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
OLLAMA_EMBEDDING_DIMS=768

项目隔离

控制每个项目的内存隔离方式：

# Auto mode (recommended) - Auto-detect project from directory
PROJECT_ID_MODE=auto

# Manual mode - Set explicitly per project
PROJECT_ID_MODE=manual
DEFAULT_USER_ID=my_project_name

# Global mode - Share all memories
PROJECT_ID_MODE=global
DEFAULT_USER_ID=shared_memory

性能调优

为了提高性能，请使用更小的嵌入模型：

# Fast: 768 dimensions (enables HNSW indexing)
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
OLLAMA_EMBEDDING_DIMS=768

# Slower but more accurate: 4096 dimensions (HNSW disabled)
OLLAMA_EMBEDDING_MODEL=qwen3-embedding:8b
OLLAMA_EMBEDDING_DIMS=4096

注： pgvector的HNSW索引仅限于2000维。对于更高维度，系统会自动禁用HNSW（速度较慢但仍可使用）。

智能文本分块

MCP服务器通过智能语义分块技术自动处理大文本输入，以防止超时并优化性能。

工作原理：

短文本（≤1000个字符）： 直接发送到Mem0 API（快速路径，无分块开销）
大文本（>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	🚀（译文：

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=<strong-password>
NEO4J_PASSWORD=<strong-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 <token>
或者创建一个新令牌

服务器未显示在 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社区倾心打造