Mem0 MCP Selfhosted

mem0 mcp自托管

自托管 mem0 Claude Code的MCP服务器。针对自托管的Qdrant+Neo4j+Ollama运行一个完整的内存服务器，您可以选择Anthropic（Claude）或Ollama作为主要的LLM。

使用 mem0ai 直接作为库的包，支持Claude的OAT令牌和完全本地的Ollama设置，并公开了11个MCP工具用于完全内存管理。

先决条件

Python>=3.10和 紫外线.

身份验证： 默认设置使用Claude（Anthropic）作为事实提取的LLM。不需要API密钥，服务器会自动使用您的ClaudeCode会话令牌。对于完全本地设置，请设置 MEM0_PROVIDER=ollama。参见 认证 高级选项。

快速开始

默认值（人为）

全局添加MCP服务器（可在所有项目中使用）：

claude mcp add --scope user --transport stdio mem0 \
  --env MEM0_USER_ID=your-user-id \
  -- uvx --from git+https://github.com/elvismdev/mem0-mcp-selfhosted.git mem0-mcp-selfhosted

所有默认设置都是开箱即用的：Qdrant on localhost:6333Ollama嵌入 localhost:11434 随着 bge-m3 （1024调暗）。通过以下方式覆盖任何默认值 --env （参见 配置).

uvx 在隔离环境中自动下载、安装和运行服务器，无需手动安装。当MCP连接开始时，Claude Code会按需启动它。

服务器自动从以下位置读取OAT令牌 ~/.claude/.credentials.json，无需手动配置令牌。

完全本地化（Ollama）

对于没有云依赖的完全本地设置，请将Ollama用于主要的LLM和嵌入：

claude mcp add --scope user --transport stdio mem0 \
  --env MEM0_PROVIDER=ollama \
  --env MEM0_LLM_MODEL=qwen3:14b \
  --env MEM0_USER_ID=your-user-id \
  -- uvx --from git+https://github.com/elvismdev/mem0-mcp-selfhosted.git mem0-mcp-selfhosted

MEM0_PROVIDER=ollama 级联到主要的LLM和图LLM提供商。相同的基础设施默认值适用（Qdrant on localhost:6333, bge-m3 嵌入）。按服务覆盖（例如。 MEM0_LLM_URL, MEM0_EMBED_URL)在需要时仍然工作。

或者通过创建将其添加到单个项目中 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "mem0": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/elvismdev/mem0-mcp-selfhosted.git", "mem0-mcp-selfhosted"],
      "env": {
        "MEM0_PROVIDER": "ollama",
        "MEM0_LLM_MODEL": "qwen3:14b",
        "MEM0_USER_ID": "your-user-id"
      }
    }
  }
}

试试看

重新启动克劳德代码，然后：

> Search my memories for TypeScript preferences
> Remember that I prefer Hatch for Python packaging
> Show me all entities in my knowledge graph

CLAUDE.md集成

将这些规则添加到项目的 CLAUDE.md （或 ~/.claude/CLAUDE.md 全局使用），因此Claude Code在整个会话中主动使用内存工具：

# MCP Servers

- **mem0**: Persistent memory across sessions. At the start of each session, `search_memories` for relevant context before asking the user to re-explain anything. Use `add_memory` whenever you discover project architecture, coding conventions, debugging insights, key decisions, or user preferences. Use `update_memory` when prior context changes. Save information like: "This project uses PostgreSQL with Prisma", "Tests run with pytest -v", "Auth uses JWT validated in middleware". When in doubt, save it, future sessions benefit from over-remembering.

这为Claude Code提供了在会话期间主动搜索和保存记忆的行为指令。为了获得最佳效果，请结合 克劳德代码挂钩，CLAUDE.md规则告诉克劳德 *如何使用* 内存工具在会话中期，而钩子处理 *自动的* 在会话边界进行注入和保存。

克劳德代码挂钩

会话挂钩在会话边界自动调用内存，在启动时注入内存，并在退出时保存摘要。这会自动发生，无需手动调用工具。

这两个钩子都是非致命的，如果mem0不可访问或发生任何错误，Claude代码将正常继续。

安装

在项目中安装挂钩：

mem0-install-hooks

或全局安装（所有项目）：

mem0-install-hooks --global

这将钩子条目添加到 .claude/settings.json安装程序是幂等的，运行两次不会创建重复项。

运作原理

会话开始时，上下文挂钩使用两个查询（项目架构+最近会话摘要）搜索mem0，按内存ID进行重复数据消除，并将结果格式化为 # mem0 Cross-Session Memory 头球这些是通过钩子注射的 additionalContext 响应字段。

会话停止，stop钩子读取JSONL转录，提取最后6条用户/助理消息（通过有界双端队列的滑动窗口），构建摘要提示，并调用 memory.add(infer=True) 提取原子事实。在钩子中强制禁用Graph，以保持在15s/30s的超时预算内。

入口点

挂钩+CLAUDE.md

Hooks和CLAUDE.md是互补的层，可以最好地协同工作：

仅钩子就可以让你被动回忆（记忆在启动时出现）和被动保存（摘要在退出时保存）。CLAUDE.md指令添加了活动的会话中期行为，CLAUDE在遇到新主题时搜索相关记忆，并立即保存重要发现，而不是等待会话结束。

为了获得最佳体验，请同时使用两者。钩子确保内存在会话边界自动流入和流出，而CLAUDE.md确保CLAUDE在会话期间积极使用内存工具。

认证

服务器使用优先级回退链解析Anthropic令牌：

在Claude Code中，优先级2总是获胜，只要您登录，凭据文件就存在。这意味着 ANTHROPIC_API_KEY （优先级3）从未达到。要覆盖Claude代码中的OAT令牌，请使用 MEM0_ANTHROPIC_TOKEN （优先级1）。 ANTHROPIC_API_KEY 仅适用于非Claude Code部署（Docker、CI、独立）。

OAT令牌 (sk-ant-oat...)使用您的Claude订阅。服务器会自动检测令牌类型并相应地配置SDK。OAT令牌在到期前会自动刷新：服务器会主动检查令牌的生命周期，并在接近到期时（默认值：30分钟）通过Anthropic OAuth端点进行刷新。在身份验证失败时，会启动一个三步防御策略，利用Claude Code的凭据文件，通过OAuth进行自我刷新，然后等待重试，因此长时间运行的会话可以无缝地在令牌轮换中生存。

API密钥 (sk-ant-api...)使用标准的按使用付费计费。

工具

内存工具（9核）

图形工具

提示

服务器注册了一个 memory_assistant MCP提示为Claude提供了有效使用内存工具的快速入门指南。

参数

所有工具都使用Pydantic Annotated[type, Field(description=...)] 用于自文档化参数模式。常见模式：

• user_id 默认为 MEM0_USER_ID 未提供env-var时
• enable_graph 覆盖默认值 MEM0_ENABLE_GRAPH 每次呼叫
• filters 支持结构化运算符： {"key": {"eq": "value"}}, {"AND": [...]}
• 所有响应都是JSON字符串，通过 json.dumps(result, ensure_ascii=False)

配置

所有配置都是通过环境变量进行的。创建一个 .env 文件或在MCP配置中设置它们。

认证

LLM

嵌入器

矢量存储（Qdrant）

图形库（Neo4j）

服务器

建筑

Claude Code
  |
  ├── MCP stdio/SSE/streamable-http
  │     |
  │     ├── env.py               ← Centralized env var readers (whitespace-safe)
  │     ├── auth.py              ← Hybrid token fallback chain + OAT self-refresh
  │     ├── llm_anthropic.py     ← Custom Anthropic LLM provider (OAT + structured outputs)
  │     ├── llm_ollama.py        ← Custom Ollama LLM provider (restored tool-calling)
  │     ├── config.py            ← Env vars → MemoryConfig dict (provider + URL cascades)
  │     ├── helpers.py           ← Error wrapper, concurrency lock, safe bulk-delete, monkey-patches
  │     ├── graph_tools.py       ← Direct Neo4j Cypher queries (lazy driver)
  │     ├── llm_router.py        ← Split-model graph LLM router (gemini_split)
  │     ├── __init__.py          ← Telemetry suppression (before any mem0 import)
  │     └── server.py            ← FastMCP orchestrator (11 tools + prompt)
  │           |
  │           ├── mem0ai Memory class
  │           │     ├── Vector: LLM fact extraction → Ollama embed → Qdrant
  │           │     └── Graph: LLM entity extraction (tool calls) → Neo4j
  │           |
  │           └── Infrastructure
  │                 ├── Qdrant          ← Vector store
  │                 ├── Ollama          ← Embeddings
  │                 ├── Neo4j           ← Knowledge graph (optional)
  │                 └── Anthropic/Ollama ← Main LLM (configurable)
  |
  └── Session Hooks (subprocess, not MCP)
        |
        └── hooks.py             ← Cross-session memory (SessionStart + Stop hooks)
              ├── context_main()   → Injects memories as additionalContext on startup/compact
              ├── stop_main()      → Saves session summary to mem0 on exit
              └── install_main()   → CLI to patch .claude/settings.json

图形内存和配额

图形内存为 默认情况下禁用 (MEM0_ENABLE_GRAPH=false)为了保护你的克劳德配额。每 add_memory 启用图形后，会触发3个额外的LLM调用，用于实体提取、关系生成和冲突解决。

使用Ollama进行图形操作

要消除图操作的Claude配额使用，请使用本地Ollama模型：

MEM0_ENABLE_GRAPH=true
MEM0_GRAPH_LLM_PROVIDER=ollama
MEM0_GRAPH_LLM_MODEL=qwen3:14b

Qwen3:14b具有0.971的工具调用F1（几乎与GPT-4的0.974匹配），并在~7-8GB的VRAM中运行，采用Q4_K_M量化。

使用Gemini进行图形操作

谷歌的Gemini 2.5 Flash Lite是图形操作最便宜的选择，同时保持了很强的实体提取准确性：

MEM0_ENABLE_GRAPH=true
MEM0_GRAPH_LLM_PROVIDER=gemini
MEM0_GRAPH_LLM_MODEL=gemini-2.5-flash-lite
GOOGLE_API_KEY=your-google-api-key

使用分割模型获得最佳精度

这 gemini_split 提供程序根据操作将图形管道调用路由到不同的LLM。实体提取（调用1和2）转到Gemini以获得速度和成本；矛盾检测（呼叫3）的准确性由Claude负责。

MEM0_ENABLE_GRAPH=true
MEM0_GRAPH_LLM_PROVIDER=gemini_split
GOOGLE_API_KEY=your-google-api-key
MEM0_GRAPH_CONTRADICTION_LLM_PROVIDER=anthropic
MEM0_GRAPH_CONTRADICTION_LLM_MODEL=claude-opus-4-6

248个测试用例的基准结果：Gemini在实体提取方面的得分为85.4%（Claude为79.1%），而Claude在矛盾检测方面的得分是100%（Gemini为80%）。拆分模型结合了两者的优点。

运输方式

对于远程部署，MCP SDK>=1.23.0默认启用DNS重新绑定保护。

发展

# Install with dev dependencies
pip install -e ".[dev]"

# Run unit tests
python3 -m pytest tests/unit/ -v

# Run contract tests (validates mem0ai internal API assumptions)
python3 -m pytest tests/contract/ -v

# Run integration tests (requires live Qdrant + Neo4j + Ollama)
python3 -m pytest tests/integration/ -v

# Run all tests
python3 -m pytest tests/ -v

测试结构

• tests/unit/ --具有模拟依赖关系的纯单元测试（env、auth、config、配置矩阵、并发性、MCP协议、助手、钩子、LLM提供者、图形工具、LLM路由器、服务器）
• tests/contract/ --验证关于mem0ai内部的假设（模式检测不变性， vector_store.client 访问路径， LlmFactory 注册幂等性）
• tests/integration/ --针对真实Qdrant+Neo4j+Ollama的实时基础设施测试（内存生命周期、图操作、批量操作、钩子）。标记为 @pytest.mark.integration.

合同测试捕捉到以下方面的突破性变化 mem0ai 在投入生产之前进行升级。

遥测

所有mem0ai遥测被抑制。 os.environ["MEM0_TELEMETRY"] = "false" 在包导入时间设置，早于任何时间 mem0 模块已加载。没有发送PostHog事件。

许可证

麻省理工学院