Codex

前置条件

使用支持 Streamable HTTP MCP 和 Skill 执行的 OpenAI Codex CLI 或 Codex Desktop：

• 具体接口：Codex CLI 和 Codex Desktop (codex)。
• 运行时要求：独立 Skill 运行器需要 Node.js 22.22.0 或更高版本。
• 账户：在 https://xmemo.dev 拥有有效的 XMemo 账户。
• MCP 前置条件：在 ~/.codex/config.toml 中支持 bearer_token_env_var。

安装 / 设置

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

• 提示词：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.
• 默认安装路径：~/.codex/skills/xmemo-memory。
• 替代路径：使用 bearer_token_env_var 在 ~/.codex/config.toml 中配置直接 MCP 配置文件。

设置凭据

在运行操作之前配置您的凭据。在用于启动 Codex 的环境中设置 XMEMO_KEY。bearer_token_env_var 会读取该值而无需将令牌放入 config.toml 中。如果使用带有 --allow-plaintext 的交互式设备登录，请注意此标志会在此计算机上未加密存储凭据：

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

生成 / 确认 XMEMO_AGENT_INSTANCE_ID

客户端配置映射此安装的稳定实例身份。确认 env_http_headers 映射了 XMEMO_AGENT_INSTANCE_ID，并在各会话之间重复使用相同的非机密值。

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

保留现有配置块

使用经过审查的 Codex 配置块。保留 bearer_token_env_var 和 XMemo URL；切勿将密钥直接粘贴到 config.toml 中：

[mcp_servers.xmemo]
url = "https://xmemo.dev/mcp"
bearer_token_env_var = "XMEMO_KEY"

重启客户端

在写入配置文件、修改环境变量或安装 Skill 后重启 Codex，以便检测到新组件。

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

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

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. 无状态转换：打开一个新的 Codex 终端会话以验证跨会话的持久性。
• 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 工具)。

功能与配置文件工具

Codex 可以访问 MCP 文档契约中为 generic-public 配置文件定义的限定工具：

• 核心记忆工具：remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context。
• 工作区工具：get_mcp_identity, get_project_summary, project, todo, open_project_workspace, open_todo_board, ledger, open_ledger。

限制与边界

Codex 的操作边界与约束：

• 工作区隔离：操作严格限制在已登录用户的工作区内。
• 密钥处理：务必使用 bearer_token_env_var；切勿在 config.toml 中硬编码令牌。
• 分发范围：Codex 的非标准或第三方分支仍标记为未测试。

常见错误

使用以下恢复步骤排查常见的 Codex 问题：

• 401 invalid_token — XMEMO_KEY 缺失、已过期或无效：验证启动 Codex 的环境并重启。
• 403 insufficient_scope — 令牌缺少 memory:read 权限：生成具有所需范围的令牌。
• 错误的安装目标 — 验证 XMEMO_SKILL_DIR 是否已设置为 ~/.codex/skills/xmemo-memory。
• 需要重新加载 Skill — 重启 Codex 以确保内存中的 skills 重新加载。

更新与移除

Codex 的维护流程：

• 更新：重新运行安装程序命令以获取最新的 Skill 版本，或更新 MCP 端点 URL。
• 移除：删除 ~/.codex/skills/xmemo-memory 目录，或从 ~/.codex/config.toml 中移除 [mcp_servers.xmemo]。