MCP Memory Service

mcp存储器服务

AI代理管道的持久共享内存

AI代理的开源内存后端-- REST API、MCP、OAuth、CLI、仪表板一个自助服务，每种交通工具。 代理存储决策、共享因果知识图并检索 5毫秒内的上下文-无需云锁定或API成本。

适用于LangGraph·CrewAI·AutoGen·任何HTTP客户端·Claude Desktop·OpenCode

______________________________________________________________________

 ](https://pypi.org/project/mcp-memory-service/)  ](https://github.com/doobidoo/mcp-memory-service/stargazers)         

______________________________________________________________________

🎬 看实际效果


在YouTube上观看Web仪表板演练 -语义搜索、标签浏览器、文档接收、分析、质量评分和API文档，不到2分钟。

______________________________________________________________________

🌐 适用于claude.ai（浏览器）

与仅桌面MCP服务器不同， mcp内存服务支持远程mcp 用于原生claude.ai集成。

这意味着：

• ✅ 直接在浏览器中使用持久内存（不需要Claude Desktop）
• ✅ 适用于任何设备（笔记本电脑、平板电脑、手机）
• ✅ 企业就绪（OAuth 2.0+HTTPS+CORS）
• ✅ 自托管或云托管（您的选择）

5分钟设置：

# 1. Start server with Remote MCP enabled
MCP_STREAMABLE_HTTP_MODE=1 \
MCP_SSE_HOST=0.0.0.0 \
MCP_SSE_PORT=8765 \
MCP_OAUTH_ENABLED=true \
python -m mcp_memory_service.server

# 2. Expose via Cloudflare Tunnel (or your own HTTPS setup)
cloudflared tunnel --url http://localhost:8765
# → Outputs: https://random-name.trycloudflare.com

# 3. In claude.ai: Settings → Connectors → Add Connector
# Paste the URL: https://random-name.trycloudflare.com/mcp
# OAuth flow will handle authentication automatically

生产设置： 看 远程MCP设置指南 用于Let's Encrypt、nginx和防火墙配置。

______________________________________________________________________

为什么代理商需要这个

代理管道的关键功能：

• 框架-抽象REST API --76个端点，无需MCP客户端库
• 知识图谱 --代理人共享因果链，而不仅仅是事实
• X-Agent-ID 头球 --通过代理身份自动标记内存以进行范围检索
• conversation_id --绕过重复数据删除以实现增量会话存储
• SSE活动 --任何代理存储或删除内存时的实时通知
• 嵌入通过ONNX在本地运行 --内存永远不会离开您的基础架构

代理快速入门

pip install mcp-memory-service
MCP_ALLOW_ANONYMOUS_ACCESS=true memory server --http
# REST API running at http://localhost:8000

import httpx

BASE_URL = "http://localhost:8000"

# Store — auto-tag with X-Agent-ID header
async with httpx.AsyncClient() as client:
    await client.post(f"{BASE_URL}/api/memories", json={
        "content": "API rate limit is 100 req/min",
        "tags": ["api", "limits"],
    }, headers={"X-Agent-ID": "researcher"})
    # Stored with tags: ["api", "limits", "agent:researcher"]

# Search — scope to a specific agent
    results = await client.post(f"{BASE_URL}/api/memories/search", json={
        "query": "API rate limits",
        "tags": ["agent:researcher"],
    })
    print(results.json()["memories"])

框架特定指南： 文档/代理/

现实世界：具有共享内存的多代理集群

*“在我与其中一个集群代理一起处理我想让本地代理知道的事情后，集群代理会在内存条目中添加一个特殊标签，我的本地代理会将其识别为来自集群代理的消息。因此，他们最终将其用作通信桥——这非常令人愉快。”*

一个5代理的openclaw集群使用mcp内存服务作为共享状态 和 作为代理间消息传递总线，无需任何自定义协议。集群代理使用类似哨兵的标记来标记记忆 msg:cluster，并且本地代理对该标签进行过滤以接收跨集群信号。内存服务成为无需额外基础设施的协调层。

# Cluster agent stores a learning and flags it for the local agent
await client.post(f"{BASE_URL}/api/memories", json={
    "content": "Rate limit on provider X is 50 RPM — switch to provider Y after 40",
    "tags": ["api", "limits", "msg:cluster"],       # sentinel tag
}, headers={"X-Agent-ID": "cluster-agent-3"})

# Local agent polls for cluster messages
results = await client.post(f"{BASE_URL}/api/memories/search", json={
    "query": "messages from cluster",
    "tags": ["msg:cluster"],
})

这种模式-- 标签作为代理间信号 --它自然地从标记系统中出现，不需要额外的基础设施。

现实世界：带有Cloudflare隧道的自托管Docker堆栈

*“独立于会话的内存为人工智能工作流程增加了巨大的生活质量。基于文件的内存需要不断的训练。来自实时数据库的语义回忆则不然。将数据存储在我自己的硬件上，同时使其可以跨平台远程访问，这是一个我不知道自己需要的功能。”*

在Cloudflare隧道后使用Docker容器进行生产测试的自托管部署 AuthMCP网关 处理身份验证：

此设置的安全最佳实践：

• 使用Cloudflare ZeroTrust进行基于子网的访问控制（例如，允许Anthropic子网+您自己的IP）
• 添加 客户端IP地址筛选 所有Cloudflare API令牌（仪表板→ 我的资料→ API令牌→ Edit → 客户端IP地址过滤），以限制令牌泄漏时的滥用
• 如果使用IPv6，请将您的IPv6/64网络包含在列表中（默认情况下，Python更喜欢IPv6）
• 对于长时间运行的浏览器会话，请求 offline_access 授权接收轮换期间的范围 refresh_token （终身通过 MCP_OAUTH_REFRESH_TOKEN_EXPIRE_DAYS，默认30天）。如果没有此作用域，访问令牌是唯一的凭据--extend MCP_OAUTH_ACCESS_TOKEN_EXPIRE_MINUTES 最多 1440 （24小时），如果你需要更长的单次注射。

与备选方案的比较

与商业内存API

与MCP原生替代方案

为什么会出现基准缺口？ 两个独立因素：

1. 摄入粒度。 MemPalace将每个对话存储为一个单元（会话级别）。LongMemEval问“哪个会话包含答案？”——会话级存储在结构上回答了这个问题。mcp内存服务默认为翻转级存储（每条消息一个条目），这允许细粒度检索（“用户到底对X说了什么？”），但会将会话的信号分散到许多条目上。使用 memory_store_session （在v10.35.0中添加）使我们的得分达到 5时为86.0%.
2. 96.6%实际衡量的是什么。 根据第27期，MemPalace的标题编号是以“原始模式”生成的——以纯文本存储在ChromaDB中，默认嵌入。宫殿建筑（翼楼、房间、大厅）是 未激活 在该配置中；“大厅”仅作为元数据字符串存在，对排名没有影响。因此，96.6%是ChromaDB+默认嵌入基线，而不是MemPalace结构检索特征的衡量标准。与公布的数字进行直接的“苹果对苹果”架构比较是不可能的。

¹在MemPalace“原始模式”下测量（ChromaDB中的纯文本，默认嵌入）。每 问题#27在这种配置中，宫殿的结构特征被忽略了。 ²100%结果在部分调整的测试集上使用可选的LLM重新排序（约500个API调用）。清洁保持得分（由维护人员报告）： 5时相对误差为98.4%.

______________________________________________________________________

停止每次都向AI重新解释你的项目

当你开始新的聊天时，你的人工智能助手会忘记一切。使用50次工具后，上下文爆炸到50万个令牌——Claude速度减慢，您重新启动，现在它什么都不记得了。你花10分钟重新解释你的架构。 再一次。

MCP内存服务解决了这个问题。

它会自动捕获您的项目上下文、架构决策和代码模式。当你开始新的会话时，你的人工智能已经知道一切——无需重新解释，无需丢失上下文，无需浪费时间。

🎥 2分钟视频演示

Technical showcase: Performance, Architecture, AI/ML Intelligence & Developer Experience

⚡ 使用您最喜欢的AI工具

🤖 代理框架（REST API）

LangGraph · 船员AI · 自动生成 · 任何HTTP客户端 · OpenClaw/Nanobot · 自定义管道

🖥️ CLI和终端AI（MCP）

克劳德代码 · Gemini CLI · 双子座代码助手 · 开源代码 · Codex CLI · 鹅 · 教唆者 · GitHub Copilot 命令行工具 · 安培 · 继续 · 泽德 · 科迪

🎨 桌面和IDE（MCP）

克劳德桌面版 · VS Code · 光标 · 帆板运动 · 千码 · 光线投射 · 捷凯 · 雷普利特 · 源代码图 · 科多

💬 聊天界面（MCP）

ChatGPT （开发者模式）· claude.ai （通过HTTPS远程MCP）

与任何兼容MCP的客户端或HTTP客户端无缝协作 -无论您是在构建代理管道，还是在终端、IDE或浏览器中编码。

💡 新：ChatGPT现在支持MCP！启用开发人员模式以直接连接内存服务。 请参阅设置指南→

______________________________________________________________________

🚀 60秒内开始

不确定哪种设置符合您的需求？请参阅 安装指南 --决策树会在一分钟内引导你走上正确的道路。

1.安装：

pip install mcp-memory-service

2.配置您的AI客户端：

Claude Desktop

添加到您的配置文件中：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "memory": {
      "command": "memory",
      "args": ["server"]
    }
  }
}

重新启动克劳德桌面。你的AI现在可以记住会话中的所有内容。

Claude Code

claude mcp add memory -- memory server

重新启动克劳德代码。记忆工具将自动出现。

OpenCode

启动HTTP API：

MCP_ALLOW_ANONYMOUS_ACCESS=true memory server --http

安装本地插件：

git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service
mkdir -p ~/.config/opencode/plugins
cp opencode/memory-plugin.js ~/.config/opencode/plugins/
cp opencode/memory-plugin.config.example.json ~/.config/opencode/memory-plugin.json

OpenCode会自动从以下位置加载本地插件 ~/.config/opencode/plugins/ 和 .opencode/plugins/.

看 OpenCode集成指南 对于配置、项目本地安装和当前限制。

当前的OpenCode集成作为本地插件目录的存储库文件提供。如果您只安装了PyPI包，请克隆一次存储库以复制插件文件。 插件默认为 http://127.0.0.1:8000但是 memoryService.endpoint 和 OPENCODE_MEMORY_ENDPOINT 允许您针对任何可访问的HTTP部署。

🌐 claude.ai (Browser — Remote MCP)

无需在客户端进行本地安装，直接在浏览器中运行：

# 1. Start server with Remote MCP
MCP_STREAMABLE_HTTP_MODE=1 \
MCP_SSE_HOST=0.0.0.0 \
MCP_OAUTH_ENABLED=true \
python -m mcp_memory_service.server

# 2. Expose publicly (Cloudflare Tunnel)
cloudflared tunnel --url http://localhost:8765

# 3. Add connector in claude.ai Settings → Connectors with the tunnel URL

看 远程MCP设置指南 用于Let's Encrypt、nginx和Docker的生产部署。

🔧 Advanced: Custom Backends & Team Setup

对于生产部署、团队协作或云同步：

git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service
python scripts/installation/install.py

从以下选项中选择：

• SQLite （本地、快速、单用户）
• 云耀 （云、多设备同步）
• 混合 （两者最佳：5ms本地+背景云同步）
• Milvus （专用矢量数据库——Milvus Lite文件、自托管或Zilliz Cloud）

ℹ️ 对于长期服务（MCP服务器、web后端、笔记本会话），更喜欢Docker Milvus或Zilliz Cloud而不是Milvus Lite。看 docs/milvus-backend.md 为什么。

______________________________________________________________________

🛠️ CLI服务器生命周期命令

此外 memory server --http （前台模式），CLI现在包括 用于后台HTTP管理的服务器生命周期命令：

# Start HTTP server in background (default host=127.0.0.1, port=8000)
memory launch

# Start on a custom port
memory launch --port 8192

# Check status and health
memory info --port 8192
memory health --port 8192

# View recent logs and stop server
memory logs --lines 50
memory stop --port 8192

这些命令经过优化，可快速启动并避免加载繁重的机器学习 依赖关系，除非需要。

⚠️ 安全说明：默认情况下，服务器绑定到 127.0.0.1 （仅限本地主机）。 要公开网络上的服务器或允许远程访问，您可以使用 --host 0.0.0.0 或设置 MCP_HTTP_HOST=0.0.0.0然而， 这暴露了 API到您的网络 并且只应在受信任的环境中进行 生产中的正确身份验证和防火墙规则。对于不可信网络， 使用TLS终止（HTTPS反向代理）或VPN覆盖。

______________________________________________________________________

💡 为什么你需要这个

问题

解决方案

结果： 零重新解释。零上下文丢失。只是持续、智能的协作。

______________________________________________________________________

🌐 SHODH生态系统兼容性

MCP内存服务 完全兼容 随着 SHODH统一内存API规范v1.0.0，实现整个SHODH生态系统的无缝互操作性。

兼容实现

统一架构支持

所有SHODH实现共享相同的内存模式：

• ✅ 情感元数据: emotion, emotional_valence, emotional_arousal
• ✅ 情景记忆: episode_id, sequence_number, preceding_memory_id
• ✅ 来源追踪: source_type, credibility
• ✅ 质量评分: quality_score, access_count, last_accessed_at

互操作性示例： 从mcp内存服务导出内存→ 进口到劣质cloudflare→ 跨设备同步→ 完整保存emotional_valence、episode_id和所有规范字段。

______________________________________________________________________

✨ 快速启动功能

🧠 持久内存 -上下文通过语义搜索在会话中生存 🔍 智能检索 –使用AI嵌入自动查找相关上下文 ⚡ 5ms速度 –即时上下文注入，无延迟 🔄 多客户端 –适用于超过25个AI应用程序 ☁️ 云同步 –可选的Cloudflare后端用于团队协作 🔒 隐私第一 –本地优先，您可以控制您的数据 📊 Web仪表板 –可视化和管理记忆 http://localhost:8000 🧬 知识图谱 –内存关系的交互式D3.js可视化 🏠 Homelab质量评分 –在任何与OpenAI兼容的端点（Ollama、LiteLLM、vLLM）得分 🔗 实体抽取 –自动将@提及、#标签、URL和文件路径从内存内容链接到可查询的实体图 💡 洞察卡 –整合可以检测记忆语料库中的模式、趋势和知识差距，并将其作为结构化的见解呈现出来 🏷️ 标签匹配过滤 – tag_match=AND/OR 上 memory_search 用于精确的多标签查询

Homelab/自托管质量评分 （v10.45.0+）：设置 MCP_QUALITY_AI_PROVIDER=openai-compatible 使用本地LLM而不是ONNX或云API为内存打分：

MCP_QUALITY_AI_PROVIDER=openai-compatible
MCP_QUALITY_AI_BASE_URL=http://localhost:11434/v1   # Ollama
MCP_QUALITY_AI_MODEL=qwen2.5:7b-instruct
# MCP_QUALITY_AI_API_KEY=ollama                     # optional

推荐型号： qwen2.5:7b-instruct （奥拉马）， mlx-community/Qwen2.5-7B-Instruct-4bit （MLX）或通过LiteLLM代理的任何指令模型。在终点失败时，评分会自动回落到隐式信号。

码头工人 :quality-cpu 标签 --对于想要内置本地ONNX质量评分的用户(ms-marco-MiniLM-L-6-v2 和 nvidia-quality-classifier-deberta)无需自行管理一次性ONNX导出，也无需发货 torch/transformers 在他们的容器中：

docker pull doobidoo/mcp-memory-service:quality-cpu

这 :quality-cpu 图像在构建时预导出两个模型，仅在发货时预导出 onnxruntime 在运行时——部署时没有PyTorch依赖关系。看 了解详情。

🖥️ 仪表板预览

8个仪表板选项卡： 仪表板•搜索•浏览•文档•管理•分析•质量•API文档

📖 看 Web仪表板指南 以获取完整的文档。

______________________________________________________________________

最新版本： v10.57.3 （2026年5月14日）

Milvus:last_通过访问跟踪 _access 侧面收集

新增内容：

• feat(milvus): _access 侧收集记录检索命中时间戳，修复遗忘引擎的 access_boost （倒退到 updated_at), count_all_memories(stale_days=N) （被默默地忽略了），和 memory_quality(action="maintain") 陈旧检测。即发即弃via asyncio.create_task 具有优雅的退化（PR#925，@henry201605）。关闭#923。

______________________________________________________________________

以前的版本:

• v10.57.2 -修复（deps）：将pymilvus\

Migration to v9.0.0 (upgrading from v8.x)

⚡ 太长，读不下去了：无需手动迁移-升级会自动进行！

重大变更：

• 内存类型本体：传统类型自动迁移到新的分类法（任务→观察，注意→观察）
• 不对称关系：仅定向边（不再双向）

迁移过程：

1. 停止您的MCP服务器
2. 更新到最新版本(git pull 或 pip install --upgrade mcp-memory-service)
3. 重新启动服务器-启动时运行自动迁移：

- 数据库架构迁移（009010） - 内存类型软验证（传统类型→ 观察） - 无需标签迁移（向后兼容）

安全：迁移是幂等的，可以安全地重新运行

突破性变化1：记忆类型本体

• 传统内存类型（任务、注释、标准）已弃用
• 新的正式分类法：5种基本类型（观察、决策、学习、错误、模式），21个子类型
• 移民是 自动的 服务器重新启动时--无需手动操作

突破性变化2：不对称关系

• 不对称关系（原因、修复、支持、遵循）现在只存储有向边
• 对称关系（相关、矛盾）继续存储双向边
• 数据库迁移（010）在启动时自动运行

如果您的代码期望对非对称关系进行双向存储：

# OLD behavior (no longer applies):
result = storage.find_connected(memory_id, relationship_type="causes")

# NEW: use direction parameter explicitly
result = storage.find_connected(
    memory_id,
    relationship_type="causes",
    direction="both"
)

______________________________________________________________________

📚 文档和资源

• 代理集成指南 🆕 – LangGraph、CrewAI、AutoGen、HTTP通用
• OpenCode集成 🆕 – 用于内存检索和上下文注入的本地插件
• 远程MCP设置（claude.ai） 🆕 – 通过HTTPS+OAuth实现浏览器集成
• 安装指南 –所有用例的决策树+分步路径
• 配置指南 –后端选项和定制
• 架构概述 –引擎盖下的工作原理
• 团队设置指南 OAuth和云协作
• 知识图谱仪表板 🆕 – 交互式图形可视化指南
• 内存类型本体 🆕 – 内置分类和 MCP_CUSTOM_MEMORY_TYPES env 是
• 故障排除 –常见问题和解决方案
• API 参考 –程序化使用
• 维基 –完整的文件
•  –AI驱动的文档助理
• MCP入门套件 –使用此项目中的模式构建自己的MCP服务器

______________________________________________________________________

🤝 贡献

我们欢迎捐款！看 贡献.md 作为指导方针。

快速开发设置：

git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service
pip install -e .  # Editable install
pytest tests/      # Run test suite

______________________________________________________________________