# 快速开始

连接一个客户端，保存有用的上下文，稍后召回它，并将凭据排除在公共配置之外。

- Canonical: https://docs.xmemo.dev/zh/docs/quickstart
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: abd73d03ccf55170c5c85c4eb326e77c66fde0b1654ec463e46bfe8613eed6fd
- Edition-Digest: 6d7839742e18a16bf65621d48f10697a3a0bb9d50075083f6d64b651c341485c
- Source-Revision: sha256:cf650121954b22e4cd8c386342083e6a3a903c519472bb4b370f9e3c03b0c8b8

## 1. 选择客户端和认证方式

选择您的智能体客户端与首选连接路径。对于 Claude Code、Codex 及兼容智能体，请使用包含“直接要求智能体执行”的独立 Skill 安装器。对于 ChatGPT 等不支持 Skill 的客户端，请使用基于 OAuth 的托管 MCP。对于 Cursor 或 VS Code 等直接与无头运行环境，请使用带有 XMEMO_KEY 的 Direct MCP。专属客户端指南位于 /docs/mcp/claude-code、/docs/mcp/codex、/docs/connect/openclaw、/docs/mcp/chatgpt、/docs/mcp/cursor 与 /docs/mcp/copilot。

- 路径 1（Skill）：要求您的智能体为 Claude Code、Codex 与 OpenClaw (/docs/connect/openclaw) 安装独立的 XMemo Skill。
- 路径 2（OAuth MCP）：面向无 Skill 客户端（包括 ChatGPT (/docs/mcp/chatgpt) 与 Claude Desktop (/docs/mcp/overview)）的 OAuth 托管 MCP。
- 路径 3（Direct MCP）：针对 Cursor (/docs/mcp/cursor) 与 VS Code (/docs/mcp/copilot)，引用本地环境中的 ${XMEMO_KEY} 的 Direct Streamable HTTP MCP。
- 认证模式：OAuth（推荐，经浏览器批准）与 Direct MCP（环境变量 XMEMO_KEY）。
- 中间状态：选择客户端并复制配置仅为中间步骤，而非激活完成。

## 2. 配置客户端且不暴露 Token

安装独立 Skill 或使用托管 MCP 端点 (https://xmemo.dev/mcp) 配置您的客户端。对于 Skill 客户端，请将官方安装提示词作为主要复制操作提供给智能体，或手动运行规范安装脚本。对于 Direct MCP，请从本地环境或密钥库中引用 ${XMEMO_KEY}。切勿将明文 Bearer Token 硬编码到客户端配置文件或版本控制系统中。

- 路径 1（要求智能体执行）：将独立 XMemo Skill 安装到您的 skills 目录：从 https://xmemo.dev/skill/install（Windows 请使用 https://xmemo.dev/skill/install.ps1）运行安装程序，并将 XMEMO_SKILL_DIR 设置为您的 skills 目录加上 /xmemo-memory。运行其输出的 doctor 命令以验证安装，随后重新加载 skills 并遵循 Skill 的首次运行步骤。遵守正常的安全检查，请勿使用提升的管理员权限。
- 手动复制备用路径：显式设置 XMEMO_SKILL_DIR 后运行 'curl -fsSL https://xmemo.dev/skill/install | sh'（Windows PowerShell: 'irm https://xmemo.dev/skill/install.ps1 | iex'）。
- OAuth 客户端：配置 https://xmemo.dev/mcp 并在浏览器中批准 memory:read 和 memory:write 权限。
- Direct MCP：在配置中引用 ${XMEMO_KEY}；将真实 Token 保留在本地环境或密钥存储中。
- 零密钥暴露：配置文件绝不得包含未加密的 Bearer Token。

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

## 3. 通过只读检查验证连接

在写入数据之前，务必通过只读请求验证连通性。安装、认证与激活是截然不同的里程碑。对于独立 Skill，请执行安装程序打印的 doctor 命令。在登录之前，请选择您的凭据路径：建议从密钥库提供 XMEMO_KEY 或使用托管凭据。如果使用带有 --allow-plaintext 的交互式设备登录，请注意该标志会将凭据未加密存储在当前计算机上。认证完成后请验证状态。对于 MCP 客户端，get_mcp_identity 确认客户端可连通服务器且 memory:read 作用域有效。

- Skill doctor 命令：node scripts/xmemo-skill.mjs doctor --anonymous（检查运行时与连接）。
- Skill 凭据替代方案：从密钥存储提供 XMEMO_KEY 或使用托管凭据。
- Skill 设备登录：node scripts/xmemo-skill.mjs login --allow-plaintext（打开浏览器验证；注意 --allow-plaintext 会将凭据未加密保存在此计算机上）。
- Skill 认证校验：node scripts/xmemo-skill.mjs auth status --verify（确认凭据有效性）。
- MCP 工具：get_mcp_identity()（或 limit 为 1 的 recall）。
- 权限门禁：memory:read。
- 成功信号：身份元数据确认服务器可达且已获授权。

```ts
get_mcp_identity()
```

## 4. 保存一条明确的合成事实

记录一条合成项目约定以验证 memory:write 下的写入能力。为该记忆指定特定路径，以便后续查询能够在项目范围内正确定位。请针对您的集成界面使用语法正确的调用格式。

- Skill 命令：node scripts/xmemo-skill.mjs remember --content "Demo project timestamps use UTC." --path "projects/demo-onboarding/conventions"。
- MCP 工具：使用包含明确合成内容的 remember。
- 路径范围：projects/demo-onboarding/conventions。
- 成功信号：回执以 'Saved to XMemo.' 开头，并包含分配的 ID 和 Location。

```ts
remember({
  content: "Demo project timestamps use UTC.",
  path: "projects/demo-onboarding/conventions"
})
```

## 5. 打开全新的客户端会话

启动新的对话线程或重启客户端以清除内存中的临时上下文。这种无状态过渡确保下一次召回检验的是服务端持久化能力，而非本地对话历史的重放。

- 操作：在客户端中关闭或重置当前对话会话。
- 上下文重置：清除临时客户端上下文以保证无状态测试。
- 持久化验证：随后的召回将直接向远程存储发起查询。

## 6. 带溯源召回事实

从全新会话中查询已存储的项目约定。激活的严格定义是完成首次经过验证的带溯源记忆召回——复制配置或检查代码片段仅属于中间设置步骤。

- Skill 命令：node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" --limit 1。
- MCP 工具：使用查询 'demo project timestamp format' 调用 recall。
- 回执格式：以 '### XMemo Memory Results:' 开头的文本输出，显示 Reference、Location、可选的 Created/Updated/Revision 以及具体内容。
- 成功信号：首次经过验证的带溯源召回标志着真正激活完成。

```ts
recall({
  query: "demo project timestamp format",
  limit: 1
})
```

## 7. 使用 update_memory 修正约定

当项目约定发生演进或需要进一步澄清时，使用从召回结果中返回的精确有效记忆 ID 或 Reference 来更新该记忆。对于 Skill 客户端，请使用 update 命令。对于 MCP 客户端，请使用 update_memory。可选的清理操作由用户通过 forget 自行决定。

- Skill 命令：node scripts/xmemo-skill.mjs update --id "mem_01hxyz..." --content "Demo project timestamps use UTC with ISO 8601 formatting."。
- MCP 工具：传入有效 memory_id 调用 update_memory。
- 版本修订记录：在保留不可变历史记录的同时取代前一版本。
- 可选清理：如需删除，运行 'node scripts/xmemo-skill.mjs forget --id mem_01hxyz... --confirm' (Skill) 或调用 forget (MCP)。
- 成功信号：回执以 'XMemo memory updated.' 开头，并显示 Reference 和 Revision。

```ts
update_memory({
  memory_id: "mem_01hxyz...",
  content: "Demo project timestamps use UTC with ISO 8601 formatting."
})
```

## 恢复指引：剪贴板访问被拒绝

如果浏览器拒绝访问剪贴板或权限被阻止，请手动选中代码块内的代码片段文本，并使用 Ctrl+C（或 Cmd+C）进行复制。所有代码块均提供 tabIndex=0 以支持键盘滚动与文本选择。

- 症状：浏览器阻止自动剪贴板复制或权限请求失败。
- 操作：点击或使用 Tab 键聚焦到代码容器内，并使用 Ctrl+C 或 Cmd+C 复制。
- 验证：粘贴的配置内容与页面展示的代码片段完全一致。

## 恢复指引：认证已过期或权限不足

如果客户端收到 HTTP 401 Unauthorized、HTTP 403 Forbidden 或 SetupRequiredMCPError，说明您的认证 Token 已过期或缺少必要的权限范围。

- 症状：调用工具时发生 HTTP 401、HTTP 403 或 SetupRequiredMCPError。
- 操作：通过 OAuth 重新认证，或在本地环境中设置 XMEMO_KEY。
- 验证：确认 Token 同时授予了 memory:read 和 memory:write 权限范围。

## 恢复指引：客户端中看不到工具

如果配置后 XMemo 工具未出现在客户端面板中，可能是配置文件包含语法错误，或者 MCP 连接进程需要重启。

- 症状：客户端显示 0 个可用工具，或无法识别 XMemo MCP 服务器。
- 操作：查看客户端开发者日志，校验 JSON 语法，并重启客户端。
- 验证：客户端日志中显示 MCP 初始化与工具发现成功。

## 恢复指引：召回结果为空

如果 recall 未返回匹配的记忆（'No matching memories found' 或 'No strong memory match'），请验证步骤 4 中的写入是否成功完成，并检查您的搜索查询词。

- 症状：recall 返回文本消息提示未找到匹配的记忆。
- 操作：检查查询关键词（'timestamp'、'UTC'）并确认路径范围。
- 验证：在召回前确认 remember 返回了以 'Saved to XMemo' 开头的回执。

## 恢复指引：更新时记忆 ID 未知

如果 update_memory 因 memory_id 未知或无效而拒绝调用，请勿臆测标识符。

- 症状：update_memory 返回错误提示找不到 memory_id。
- 操作：先调用 recall 获取有效的记忆 Reference，并将其作为 memory_id 传入。
- 验证：将 recall 返回的活跃记忆 Reference 传递给 update_memory。

## 恢复指引：安装目标路径错误

如果安装程序将脚本直接保存到了智能体的 skills 根目录，而非隔离的 skill 子目录下，智能体将无法找到 scripts/xmemo-skill.mjs 或可能加载未就绪的安装文件。

- 症状：查找 scripts/xmemo-skill.mjs 报错，或文件被直接解压到了 skills 根目录中。
- 操作：显式将 XMEMO_SKILL_DIR 设置为您的 skills 目录加上 /xmemo-memory（例如：export XMEMO_SKILL_DIR="$HOME/.claude/skills/xmemo-memory"）。
- 验证：SKILL.md 与 scripts/xmemo-skill.mjs 直接位于 xmemo-memory 文件夹内。

## 恢复指引：缺少 Node 22.22.0 运行时

独立 Skill 需要 Node.js >= 22.22.0。如果缺少 node 或当前使用的是更低版本，doctor 与 skill 操作将会失败。

- 症状：提示 'command not found: node'、启动时运行时错误，或 node -v 报告的版本低于 22.22.0。
- 操作：使用 nvm（nvm install 22.22.0 && nvm use 22.22.0）或操作系统包管理器安装或切换到 Node.js 22.22.0 或更高版本。
- 验证：运行 'node -v' 并确认输出为 v22.22.0 或更高版本。

## 恢复指引：需要重新加载 Skill

如果已安装 Skill 且 doctor 检查通过，但智能体在当前活跃会话中未列出 XMemo 工具或操作，则需要重新加载智能体的内存 Skill 缓存。

- 症状：安装后智能体报告不知道 XMemo skills。
- 操作：重启智能体会话以重新加载内存中的 skills。
- 验证：向智能体提问 'what skills are available?' 并确认列出了 xmemo-memory。

## 恢复指引：登录流程被中断

如果设备登录过程被中断、超时，或在输入验证码之前被关闭，凭据将不会被写入磁盘。

- 症状：在批准前关闭了浏览器、一次性验证码已过期，或 'auth status --verify' 报告 auth_valid: false。
- 操作：若未从密钥库使用 XMEMO_KEY 或托管凭据，请重新运行 'node scripts/xmemo-skill.mjs login --allow-plaintext'（该命令会将凭据未加密保存在此计算机上），打开显示的 URL 并在过期前输入验证码。
- 验证：运行 'node scripts/xmemo-skill.mjs auth status --verify' 并确认 'status: ok' 且 'auth_valid: true'。

## 托管 XMemo 快速开始

先从托管 XMemo 服务和以下连接路径开始。自托管、Docker、Supabase 和 Python 包安装是开发者参考资料，不是托管用户的第一路径。

### 让你的智能体安装

将此提示粘贴给你信任且会遵守正常安全检查的智能体。

```
请将独立版 XMemo Skill 安装到您的 skills 目录：从 https://xmemo.dev/skill/install（Windows 下为 https://xmemo.dev/skill/install.ps1）运行安装程序，并将 XMEMO_SKILL_DIR 设置为您的 skills 目录加上 /xmemo-memory。运行其输出的 doctor 命令验证安装，然后重新加载您的 skills 并按照 Skill 的首次运行步骤操作。请遵守常规安全检查，不要使用提升权限。
```

### OAuth 客户端

当宿主支持 OAuth 时，ChatGPT、OpenAI 应用审核、VS Code 和 GitHub Copilot 使用这条路径。添加托管 MCP URL，批准 memory:read 和 memory:write，不要把 XMEMO_KEY 粘贴进客户端配置。

```
MCP URL: https://xmemo.dev/mcp
Scopes: memory:read memory:write
```

### 使用 XMEMO_KEY 的直接 MCP

仅当客户端或无头 runner 无法完成 OAuth 时使用这条路径。把 XMEMO_KEY 存在本地环境或密钥库中，在配置里保留托管 MCP URL，绝不要把真实 token 粘贴到公开文档或聊天中。

```
MCP URL: https://xmemo.dev/mcp
Token source: XMEMO_KEY environment variable
Optional identity: XMEMO_AGENT_INSTANCE_ID
```

### 账号控制

首次连接后，通过账号入口查看保存了什么、检查 agent 归因，并在扩大试点前找到删除/导出或支持路径。

```
Account entry: https://xmemo.dev/login
```