MCP 概览

将 XMemo 连接到您的 AI 环境

XMemo 为 Claude、ChatGPT、Codex、GitHub Copilot、OpenClaw、Hermes、DeepSeek Harness、Microsoft Agent Framework 以及开放的 AI 代理运行时提供持久化项目记忆。客户端可以直接连接托管的 Streamable HTTP 端点，也可以通过 @xmemo/client 内置的第一方 xmemo-mcp stdio 代理连接。

• claude.ai 上的 Claude 与 Claude Desktop (Axis A: Config supported; Evidence required for current client proof · Axis B: Manual MCP Configuration; Directory listing pending): 以自定义连接器方式连接 https://xmemo.dev/mcp 并使用 OAuth；连接器中无需 API key (/docs/mcp/claude)。
• Claude (Axis A: Config supported; Evidence required for current client proof · Axis B: Manual MCP Configuration): 为 Claude Code 与 Cowork 提供记忆工作流、生命周期检查点和跨 Agent 连续性 (/docs/mcp/claude-code)。
• ChatGPT (Axis A: Hosted beta pilot; Evidence required for any refreshed external claim · Axis B: Manual MCP Configuration; Marketplace pending): 记忆工作流与交互式工作区 (TODO Board, Ledger, Project Workspace) (/docs/mcp/chatgpt)。
• Codex (Axis A: Config supported; Evidence required · Axis B: Manual MCP Configuration): Skill 引导的项目记忆与 MCP 授权 (/docs/mcp/codex)。
• OpenClaw (Axis A: Released; Pilot tested · Axis B: Official Marketplace, Native Integration): Recall 优先的 Skill 指引加上 ClawHub 上的原生 OpenClaw 记忆插件 (/docs/connect/openclaw)。
• Hermes (Axis A: Released; Pilot tested · Axis B: Native Integration): PyPI 上的原生 Hermes 记忆插件 (hermes-xmemo)，支持会话检查点与自动捕获 (/docs/connect/hermes)。
• DeepSeek Harness (Axis A: Released; Pilot tested · Axis B: Native Integration): npm 上的原生 dsh 智能体治理插件 (dsh-xmemo)，用于 CLI 执行循环记忆 (/docs/connect/deepseek-harness)。
• Microsoft Agent Framework（可用状态：计划中，等待软件包发布 · 集成方式：原生集成）：独立的社区集成，支持 Python 上下文检索和选择性捕获；并非 Microsoft 官方产品或发行版（/docs/connect/microsoft-agent-framework）。
• GitHub Copilot & VS Code (Axis A: Config supported; Evidence required for current client proof · Axis B: Manual MCP Configuration): 面向 IDE 和 CLI 智能体的 MCP 集成 (/docs/mcp/copilot)。
• Gemini CLI (Axis A: Config supported; Evidence required for current client proof · Axis B: Manual MCP Configuration): OAuth 优先配置，无需在 settings.json 中放置 Bearer 凭据。

两个正交交付维度：可用性与分发模式

客户端集成沿两个独立维度进行分类：Axis A 代表经验就绪度与可用性状态（已发布、试点 / 需权益、或已计划），而 Axis B 则定义集成与分发模式（官方应用市场、社区目录、原生集成或手动 MCP 配置）。交付渠道并不决定可用性，路线图功能与生产运行时保持严格区分。

• Axis A (Availability / Evidence Status): 已发布（在生产环境中完全运行）、试点 / 需权益（需要托管测试版试点或商业权益）、已计划（需要明确前瞻性披露的路线图项目）。
• Axis B (Integration / Distribution Mode): 官方应用市场（平台厂商审核上架的列表，如 ClawHub 官方 Skill）、社区目录（第三方索引列表）、原生集成（嵌入式运行时支持）、手动 MCP 配置（用户配置的 JSON 片段）。

四种统一连接路径

选择与您的客户端架构和操作模型匹配的连接路径：

• 路径 1（直接要求智能体执行 — 独立 Skill）：面向兼容的智能体 (Claude Code, Codex)。通过 https://xmemo.dev/skill/install 将经过验证的 Skill 安装到客户端的 skills 目录中。
• 路径 2（基于 OAuth 的托管 MCP）：面向桌面端与托管客户端 (ChatGPT, claude.ai 与 Claude Desktop 上的 Claude 自定义连接器, Cursor, VS Code Copilot)。直接连接 https://xmemo.dev/mcp，无需手动处理 token。
• 路径 3（使用 XMEMO_KEY 的直接 MCP）：面向 headless runner 和 CI 环境。通过本地环境变量基于 Streamable HTTP 安全传递 Bearer token。
• 路径 4（第一方 stdio 代理 — xmemo-mcp）：面向仅支持 stdio 的桌面客户端、未使用自定义连接器的 Claude Desktop 配置，或缺乏直接 Streamable HTTP 支持的工具。官方 @xmemo/client CLI 包提供 xmemo-mcp（可通过 npx -y -p @xmemo/client xmemo-mcp 或 xmemo mcp serve 运行）作为自包含的本地 stdio 代理，桥接到托管服务 (https://xmemo.dev)。

OAuth 客户端配置

托管 URL 就是完整配置；grant 提供 scopes。

{
  "servers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp"
    }
  }
}

直接 token 配置

无法完成 OAuth 的 headless runner 会改为从 environment 读取 token。

{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "transport": "streamable-http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "${XMEMO_AGENT_ID}",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

第一方 stdio 代理配置 (xmemo-mcp)

对于 Claude Desktop，请优先使用自定义连接器和 OAuth (/docs/mcp/claude)；此 API key 配置是备选方案。对于仅支持 stdio 的客户端，官方 @xmemo/client CLI 包附带了 xmemo-mcp 作为独立的本地 stdio 代理，桥接到托管服务 (https://xmemo.dev)。请粘贴你的真实 API key，Claude Desktop 不展开 ${env:...} 变量：

{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "@xmemo/client",
        "xmemo-mcp"
      ],
      "env": {
        "XMEMO_KEY": "<your-xmemo-api-key>",
        "XMEMO_URL": "https://xmemo.dev"
      }
    }
  }
}

按配置文件限定的工具表面

可用工具根据 config/mcp-documentation-contract.json 中的客户端功能按配置文件进行限定：

• Cursor 配置文件 (cursor-plugin): 提供用于冲突解决、快照和 Cloud Skills 的工具。
• ChatGPT 配置文件 (chatgpt-public): 提供用于交互式工作区 (TODO Board, Ledger, Project Workspace) 的工具。
• Claude 公共配置文件 (claude-public): 提供用于项目记忆、账本摘要和主动召回的工具。
• Claude 插件配置文件 (claude-plugin): 提供用于快照、决策记录和项目连续性的工具。
• 通用公共配置文件 (generic-public): 为标准 MCP 客户端提供工具。

候选集成与未验证的分发

XMemo 通过经过验证的证据跟踪新兴的客户端集成和编辑器扩展。以下候选路径仍未验证或有待维护者审查；不声明任何市场可用性或官方认可：

• VS Code 原生扩展 (xmemo-vscode): 源码仓库 (yonro/xmemo-vscode @ bf08e7c237, v0.1.1) 与 CI 工作流存在，但 Visual Studio Marketplace 发布尚未确认，且 Open VSX 返回 404。用户应通过经过验证的托管 MCP 或 Copilot Chat 配置 (/docs/mcp/copilot) 连接 VS Code，而非使用未经检验的扩展包。
• Cindy Ghost Plugin (xmemo-cindy-plugin): Ghost 插件候选方案 (yonro/xmemo-cindy-plugin @ 0cbbac5a53, v1.0.0) 仍有待维护者审查，未观察到公开的 GitHub Releases 或经过验证的分发渠道。
• Shared Skills Package (@xmemo/skills): 虽然仓库源码存在，但公开 npm 查询返回 404；请改用经过验证的独立 Skill (@xmemo/skill)。

让 runner 自行完成配置

autonomous runner 可以获取自己的 preset，而不是让人手动输入 identity values。

curl -s https://xmemo.dev/api/v1/mcp/config/autonomous-agent