Memanto MCP

Memanto MCP 服务

mcp-name: io.github.moorcheh-ai/memanto

为任何兼容 MCP 的 Agent 提供持久语义记忆。

此软件包将 Memanto 的记忆原语—— remember、recall、answer 等——作为 Model Context Protocol (MCP) 工具提供，让任何 MCP 客户端（Claude Desktop、Cursor、Windsurf、Cline、Continue、Goose、 自定义 Agent 等）只需一行配置即可接入长期记忆。

一个 Moorcheh API 密钥 → 在共享同一命名空间的所有 Agent 之间提供类型化语义记忆， 检索耗时低于 90 ms、具备冲突检测，且摄取零延迟。

---

安装

pip install memanto-mcp

需要 Python 3.10+、memanto>=0.2.13、mcp>=1.2,<2，以及一个 Moorcheh API 密钥 （免费套餐：每月 100K 次操作）。

快速开始（Claude Desktop）

1. 从控制台获取 Moorcheh API 密钥。
2. 编辑 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "memanto": {
      "command": "memanto-mcp",
      "env": {
        "MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
        "MEMANTO_DEFAULT_AGENT_ID": "my-assistant"
      }
    }
  }
}

3. 重启 Claude Desktop。让它*“记住我喜欢简洁的 回答”——然后在明天开启一个全新的聊天，问它“我喜欢什么？”*。

首次调用会自动创建 my-assistant Agent 和命名空间；之后的每次调用都会复用同一份持久记忆。

快速开始（Cursor / Windsurf / Cline / Continue / Goose）

大多数客户端都使用符合 标准 MCP 格式的配置文件。 几乎无需修改，同一段 JSON 就能使用：

{
  "mcpServers": {
    "memanto": {
      "command": "memanto-mcp",
      "env": {
        "MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
        "MEMANTO_DEFAULT_AGENT_ID": "cursor-workspace"
      }
    }
  }
}

客户端	配置路径
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json（macOS）/ %APPDATA%\Claude\claude_desktop_config.json（Windows）
Cursor	~/.cursor/mcp.json（或项目专属的 .cursor/mcp.json）
Windsurf	~/.codeium/windsurf/mcp_config.json
Cline（VS Code）	~/.config/Code/User/globalStorage/cline.cline/settings/cline_mcp_settings.json
Continue	~/.continue/config.json → experimental.modelContextProtocolServers
Goose	~/.config/goose/config.yaml

可用工具

服务默认注册 7 个记忆工具。设置 MEMANTO_EXPOSE_ADMIN=true 还可启用 4 个 Agent 管理工具。

记忆工具（始终启用）

工具	Agent 应在何时调用
remember	保存一条新事实／偏好／决定／目标／指令。
batch_remember	一次调用保存最多 100 条记忆（例如，从文档中提取）。
recall	语义搜索——在要求用户重复提供稳定信息之前，务必先在此处查询。
recall_recent	“我们刚才决定了什么？”——按时间倒序，无需查询。
recall_as_of	查询某一时间点的记忆——“我们在 2025-11-01 知道什么？”
recall_changed_since	差异查询——“从我上次查询后新增了什么？”
answer	RAG：基于 Agent 的记忆合成有据可依的大模型回答。

Agent 管理工具（可选启用）

设置 MEMANTO_EXPOSE_ADMIN=true 后启用：

工具	用途
create_agent	创建新的记忆命名空间。
list_agents	列出 API 密钥可见的所有 Agent。
get_agent	查询 Agent 的元数据。
delete_agent	移除 Agent 的本地元数据。

remember / batch_remember 接受的记忆类型： fact、preference、goal、decision、artifact、learning、event、 instruction、relationship、context、observation、commitment、 error。

来源值：explicit_statement、inferred、corrected、 validated、observed、imported。

来源归属

source 用于标明是谁写入了记忆，以便按写入者归属和筛选召回结果。 它是开放的：user、agent、tool、system，或特定写入者，例如 cursor、codex、claude_code、mem0。标签最多可包含 64 个字母、数字、.、_ 或 -，以确保 #source:<value> 可用作筛选条件。

工具调用未提供 source 时，服务会将写入归属为初始化握手中已连接的 MCP 客户端（cursor、codex、claude-ai 等）；若客户端未发送名称，则回退为 mcp-agent。 因此，共用一个 Agent 的两个编辑器在召回时仍可区分，无需额外配置。

配置

所有配置均通过环境变量设置（加载顺序：进程环境变量 → 工作目录中的 .env 文件）。

变量	必填	默认值	描述
MOORCHEH_API_KEY	是	—	Moorcheh API 密钥。
MEMANTO_DEFAULT_AGENT_ID	建议设置	无	默认 Agent。设置后，工具调用可以省略 agent_id。
MEMANTO_AGENT_PATTERN	否	tool	自动创建默认 Agent 时使用的模式（support／project／tool）。
MEMANTO_AGENT_AUTO_CREATE	否	true	首次使用时，若默认 Agent 不存在，则创建该 Agent。非默认 Agent 必须已存在。
MEMANTO_SESSION_DURATION_HOURS	否	服务端默认值（6）	会话有效时长，单位为小时。
MEMANTO_EXPOSE_ADMIN	否	false	注册 4 个 Agent 管理工具。
MEMANTO_MCP_TRANSPORT	否	stdio	stdio、sse 或 streamable-http。
MEMANTO_MCP_HOST	否	127.0.0.1	sse/http 传输的绑定主机。
MEMANTO_MCP_PORT	否	8765	sse/http 传输的绑定端口。
MEMANTO_MCP_LOG_LEVEL	否	INFO	日志级别（日志始终发送到 stderr）。

CLI 参数（memanto-mcp --transport sse --port 9000）优先于环境变量。

通过 HTTP / SSE 运行

对于远程客户端或多进程设置，可通过网络传输运行服务：

# Streamable HTTP (recommended modern transport)
memanto-mcp --transport streamable-http --host 0.0.0.0 --port 8765

# Server-Sent Events (older, still widely supported)
memanto-mcp --transport sse --host 0.0.0.0 --port 8765

然后，将客户端指向 http://your-host:8765/mcp（或所选传输所声明的路径）。在生产部署中，应配合反向代理和身份验证；服务自身会使用你的 API 密钥向上游 Moorcheh 进行身份验证，但不会对传入的 MCP 客户端进行身份验证。

工作原理

┌──────────────┐    MCP/stdio    ┌──────────────────┐    Moorcheh API    ┌─────────────┐
│ Claude / IDE │ ──────────────► │  memanto-mcp     │ ────────────────► │   Moorcheh  │
│   (client)   │ ◄────────────── │  (this package)  │ ◄──────────────── │   Service   │
└──────────────┘    tool calls   └──────────────────┘    HTTPS+API key   └─────────────┘
                                          │
                                          └─ uses memanto.cli.client.SdkClient
                                             (same client the Memanto CLI uses)

• 启动时会验证设置；API 密钥会在首次工具调用时延迟验证。
• 对于指定 Agent 的首次记忆工具调用，服务会确保该 Agent 存在（必要时自动创建），并激活 JWT 会话。会话会在过期前自动续期，因此长时间运行的 MCP 连接不会在对话中途遇到会话过期错误。
• 服务会在关闭时有意保持会话有效：JWT 会话受 TTL 限制，其他 Memanto 客户端（CLI、REST）可能需要共享这些会话。

以编程方式嵌入

如果你正在构建自定义 MCP 主机，或要将此服务接入更大的进程，可以自行构造 FastMCP 实例：

from memanto_mcp import MCPServerSettings, build_server

settings = MCPServerSettings()  # reads env / .env
mcp = build_server(settings)

# Add your own tools alongside Memanto's, then run.
mcp.run(transport="stdio")

故障排除

症状	解决方法
configuration error: MOORCHEH_API_KEY is required	在 MCP 客户端配置的 env 块中设置此环境变量。
Agent '…' does not exist and MEMANTO_AGENT_AUTO_CREATE is disabled	重新启用自动创建，或调用一次 create_agent（管理工具）／memanto agent create <id>。
客户端中始终不显示工具	确认客户端支持 MCP，且配置路径正确。查看客户端的 MCP 日志：服务启动时输出的 stderr 行（前缀为 memanto_mcp）会显示在那里。
stdio 模式下输出乱码	你这边有内容写入了 stdout——该通道专用于 JSON-RPC。请将日志改为写入 stderr。服务自身只会写入 stderr。
首次调用缓慢	冷启动开销：SDK 导入和首次会话激活。后续调用会复用活动会话。

许可证

MIT — 与 Memanto 项目相同。请参阅 LICENSE。

链接

• Memanto — 记忆 Agent 本身
• Moorcheh — 底层无需索引的语义数据库
• Model Context Protocol spec
• Anthropic MCP Python SDK