Cursor

前置条件

使用带有 设置 -> 功能 -> MCP 或市场支持的 Cursor IDE。接口与前置条件：

• 具体接口：Cursor IDE (~/.cursor/mcp.json 或 设置 -> 功能 -> MCP)。
• 端点：https://xmemo.dev/mcp。
• 首选认证模式：Browser OAuth。
• 备选认证模式：适用于无头和容器环境的直接承载令牌。
• 账户：在 https://xmemo.dev 拥有有效的 XMemo 账户。

安装 / 设置

打开 Cursor 设置 -> 功能 -> MCP 或配置 ~/.cursor/mcp.json。对于无头操作，请使用带有环境变量令牌引用的直接配置块，而不是浏览器流程：

• OAuth 路径：仅配置托管 URL，并在首次使用时触发浏览器同意。
• 直接后备：将令牌保留在 XMEMO_KEY 中，切勿直接保留在设置文件中。
• 不要在同一条目中将 OAuth URL 配置与 Authorization 标头混用。

设置凭据

OAuth 路径无需密钥 — 在首次提示时完成 Browser OAuth。对于直接无头后备，请在 shell 环境中设置 XMEMO_KEY，切勿将令牌值粘贴到 Cursor 设置中：

# OAuth path: no XMEMO_KEY needed (browser prompt)
# Direct fallback:
export XMEMO_KEY='<your-xmemo-token>'

生成 / 确认 XMEMO_AGENT_INSTANCE_ID

经过审查的 Cursor OAuth 和直接代码片段不需要客户端实例标头。如果无头包装器提供 XMEMO_AGENT_INSTANCE_ID，请为每个本地配置文件生成一次并重复使用。

保留现有配置块

首选 OAuth 路径：在 ~/.cursor/mcp.json 中使用经过审查的仅 URL Cursor 配置进行基于浏览器的 OAuth 认证：

{
  "mcpServers": {
    "xmemo": {
      "url": "https://xmemo.dev/mcp"
    }
  }
}

直接后备配置块

直接无头后备：在无头或非交互式环境中运行 Cursor 时，配置引用本地环境中 ${env:XMEMO_KEY} 的 Authorization 标头：

{
  "mcpServers": {
    "xmemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}"
      }
    }
  }
}

重启客户端

编辑配置后重启 Cursor 或在 设置 -> 功能 -> MCP 中关闭再打开 MCP 服务器，以使更改生效。

使用真实的召回调用进行测试

使第一次 MCP 调用为只读。这是实际的召回调用，而不是健康检查占位符，并且它不会写入记忆。

recall({ query: "connection check", limit: 1 })

预期响应（字面形态）

成功的调用将返回以下公开的排序文本形态；引用和内容是来自授权记忆空间的真实值。

### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>

首个实用任务：合成记忆生命周期

在 Cursor Composer 或 Agent 模式内演练完整的合成记忆任务：

• 1. 保存合成事实：要求 Cursor 记住规范 ("Demo project timestamps use UTC.") 到 "projects/demo-onboarding/conventions"。
• 2. 无状态转换：启动新的 Cursor Composer 聊天或重新打开项目工作区。
• 3. 带溯源归属的召回：查询 "demo project timestamp format"。确认返回的 Reference 和 Location。
• 4. 修正记忆：使用有效 ID 调用 update_memory，以使用 ISO 8601 格式化时间戳。
• 5. 可选清理：在入门测试完成后，使用记忆 ID 调用 forget。

功能与配置文件工具

Cursor 可以访问 MCP 文档契约中为 cursor-plugin 配置文件定义的限定工具：

• 核心记忆工具：remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context, search_knowledge。
• 快照与冲突工具：create_restart_snapshot, restore_restart_snapshot, list_memory_versions, list_memory_conflicts, resolve_memory_conflict。
• 项目与规划工具：get_mcp_identity, get_project_context, get_timeline, list_memory_todos, complete_memory_todo, create_memory_todo, update_project_decision, update_project_todo, update_state。
• 云端技能与治理：recall_cloud_skill, save_cloud_skill, propose_write, propose_todo_mutation, propose_profile_mutation, query_audit, record_event, memory_stats。

限制与边界

Cursor 的操作边界与约束：

• 配置纯净性：不要在同一个服务器块中将仅 OAuth URL 的配置与 Authorization 标头混用。
• 工作区边界：记忆访问严格限制在经过身份验证的用户的工作区内。
• 无头令牌要求：直接 MCP 后备需要显式配置环境令牌。

常见错误

Cursor 可能会在其 OAuth 路径或其直接无头后备中失败：

• invalid_grant — OAuth 授权码无效、已过期或已被使用：重新连接 Cursor 并再次授权。
• 401 invalid_token — 直接后备令牌缺失、已过期或无效：在无头环境中验证 XMEMO_KEY。
• 403 insufficient_scope — 凭据未授予 memory:read：批准所需的范围或签发包含该范围的令牌。

更新与移除

Cursor 的维护流程：

• 更新：在 Cursor MCP 设置中关闭再打开服务器以重新加载工具 schema。
• 移除：从 ~/.cursor/mcp.json 中删除 xmemo 条目，或从 Cursor MCP 设置中将其移除。