Claude Code

前置条件

在本地终端中使用 Claude Code CLI (claude)。运行时与前置条件：

• 具体接口：Claude Code CLI (claude)。
• 运行时要求：独立 Skill 运行器需要 Node.js 22.22.0 或更高版本。
• 账户：在 https://xmemo.dev 拥有有效的 XMemo 账户。
• 替代 MCP 前置条件：本地环境中支持带有承载令牌的 Streamable HTTP 传输。

安装 / 设置

推荐路径使用所有者选择的提示词将独立的 XMemo Skill 安装到 Claude Code 的 skills 目录中。要求 Claude Code 中的智能体执行安装：

• 提示词：Install the standalone XMemo Skill into your skills directory: run the installer from https://xmemo.dev/skill/install (on Windows, https://xmemo.dev/skill/install.ps1) with XMEMO_SKILL_DIR set to your skills directory plus /xmemo-memory. Run the doctor command it prints to verify the installation, then reload your skills and follow the Skill's first-run steps. Follow your normal safety checks and do not use elevated privileges.
• 默认安装路径：~/.claude/skills/xmemo-memory。
• 替代路径：通过 claude mcp add 或带有 https://xmemo.dev/mcp 的 .mcp.json 注册直接 Streamable HTTP MCP。

设置凭据

在运行命令之前，配置您的凭据存储路径。优先从机密存储或本地 shell 环境设置 XMEMO_KEY。如果使用带有 --allow-plaintext 的交互式设备登录，请注意此标志会在此计算机上未加密存储凭据：

export XMEMO_KEY='<your-xmemo-token>'
# Interactive alternative (stores credential unencrypted on this machine):
# node ~/.claude/skills/xmemo-memory/scripts/xmemo-skill.mjs login --allow-plaintext

生成 / 确认 XMEMO_AGENT_INSTANCE_ID

为每个本地 Claude Code 安装生成一个非机密值，将其保存在 git 之外，并在各会话之间重复使用，以保持实例归属稳定。

export XMEMO_AGENT_INSTANCE_ID='<stable-local-instance-id>'
# Persist and reuse this value for the same local install

保留现有配置块

对于直接 MCP 环境，请使用经过审查的 Claude Code 配置块。保留 Authorization 变量引用；切勿将令牌占位符替换为真实的机密：

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

重启客户端

在更改环境变量、配置文件或安装 Skill 后重启 Claude Code，以便所有组件干净地加载到内存中。

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

在写入数据之前，请先发出只读请求以验证连接性。此检查不会修改记忆状态。

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

预期响应（字面形态）

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

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

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

验证记忆持久性、无状态会话转换、归属源的召回和修正：

• 1. 保存合成事实：node scripts/xmemo-skill.mjs remember --content "Demo project timestamps use UTC." --path "projects/demo-onboarding/conventions" (或 MCP remember 工具)。
• 2. 无状态转换：打开一个新的 Claude Code 终端会话以验证跨会话的持久性。
• 3. 带溯源归属的召回：node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" (或 MCP recall 工具)。在返回的输出中验证 Reference 和 Location。
• 4. 修正记忆：node scripts/xmemo-skill.mjs update --id <active-memory-id> --content "Demo project timestamps use UTC with ISO 8601 formatting." (或 MCP update_memory 工具)。
• 5. 可选清理：node scripts/xmemo-skill.mjs forget --id <active-memory-id> --confirm (或 MCP forget 工具)。

功能与配置文件工具

Claude Code 可以访问 MCP 文档契约中为 claude-plugin 和 claude-public 配置文件定义的限定工具：

• 核心记忆工具：remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context。
• 项目与上下文工具：get_mcp_identity, get_project_context, project, todo, update_state。
• 会话连续性：create_restart_snapshot, restore_restart_snapshot, record_event, create_pending_decision, resolve_decision。

限制与边界

Claude Code 的操作边界与约束：

• 工作区边界：记忆访问严格限制在授权用户的工作区内。
• 桌面隔离：Claude Code CLI 配置独立于 Claude Desktop Cowork 设置。
• claude.ai 上的 Claude 与 Claude Desktop：通过自定义连接器和 OAuth 连接；参见 [Claude (claude.ai)](/docs/mcp/claude)。
• 密钥处理：切勿将明文令牌提交到 git，也不要将密钥粘贴到已签入的配置文件中。

常见错误

通过以下步骤排查常见的连接和授权问题：

• 401 invalid_token — XMEMO_KEY 缺失、已过期或无效：验证环境令牌或重新运行设备登录。
• 403 insufficient_scope — 令牌缺少 memory:read 或 memory:write 范围：签发具有所需权限的令牌。
• 错误的安装目标 — 验证 XMEMO_SKILL_DIR 是否已设置为 ~/.claude/skills/xmemo-memory。
• 需要重新加载 Skill — 退出 Claude Code (/exit) 并重新启动以重新加载内存中的 skills。

更新与移除

更新或卸载集成的流程：

• 更新：重新运行安装程序提示词以获取最新的 Skill 软件包版本。
• 移除：删除 ~/.claude/skills/xmemo-memory，或运行 claude mcp remove xmemo 以移除直接 MCP 配置。