# 在 Codex 中使用 ReMe

[English](./README.md)

将 Codex 接入自己的 ReMe 服务，即可跨会话记住项目决策、个人偏好和待办事项。
ReMe 可以自动记录、召回记忆，并每天整理。记忆文件保存在你自己的 ReMe 工作区中。

下方为真实 Codex 桌面端截图，点击图片可查看原图。

## 开始前

- **Codex CLI >= 0.159.2**：用于安装和命令行使用，运行 `codex --version` 查看版本。
- **Codex 桌面端 >= 26.924.22138**：用于打开 MCP 设置表单和状态面板，可在 **关于（About）** 中查看版本。
  以上为本指南已验证的版本基线，更早版本未经验证。
- 启动 Codex 的环境中，`python3` 需要是 Python 3.11+，并安装 `fastmcp>=3.4.2`。
  即使 ReMe 在远程运行，Codex 所在机器也需要这个环境。检查命令：

  ```bash
  python3 -c "import sys, fastmcp; print(sys.version); print(fastmcp.__version__)"
  ```

  如未安装，执行 `python3 -m pip install "fastmcp>=3.4.2"`。
- 按[配置指南](../../docs/zh/configuration.md)配置 ReMe 用于提取记忆的模型。默认 BM25 检索不需要 embedding 模型。
- 准备本仓库的本地副本，用于安装。

## 1. 启动 ReMe 服务

```bash
pip install "reme-ai[core]"
reme start \
  workspace_dir=/absolute/path/to/reme-workspace \
  service.backend=http \
  service.host=127.0.0.1 \
  service.port=2333 \
  service.tool_error_on_failure=true \
  jobs.dream_cron.backend=base \
  jobs.dream_cron.enable_serve=false
```

保持服务运行。MCP 地址为 `http://127.0.0.1:2333/mcp`，必须能从 **Codex 所在机器**访问。
远程部署时填写实际可达的服务地址。`workspace_dir` 决定记忆文件存放位置。
未启用认证的服务应仅监听本机，或放在受保护的代理之后。

保留 `service.tool_error_on_failure=true`，以便写入失败后稍后重试。

这个示例由 Codex 管理每日整理。如果 ReMe 服务已有整理计划且希望继续使用，省略最后两项，
并在 Codex 中关闭 **Daily memory consolidation**。同一个工作区只在一处开启每日整理。

## 2. 安装 ReMe 并信任 Hook

将路径替换为仓库所在的绝对路径：

```bash
codex plugin marketplace add /absolute/path/to/ReMe/integrations/codex
codex plugin add reme@reme-codex
```

重启桌面客户端，或打开新的 CLI 会话。在已安装的 ReMe 详情中确认已启用。

[![Codex 中已安装的 ReMe 详情与 MCP 设置入口](./figures/plugin-installed.png)](./figures/plugin-installed.png)

桌面端请先添加并打开一个本地项目文件夹，再进入 **Settings → Hooks**。
如果出现主机选择，选择 **Local**，然后审核并信任 **所有 ReMe 条目**（目前共七个）。
CLI 请在项目目录启动 `codex`，再使用 `/hooks`。
完成这一步才能自动记录和召回。仅连接服务并不会启用这些能力。
升级后如条目发生变化，需要重新审核。参见 [Codex Hook 审核与信任说明](https://learn.chatgpt.com/docs/hooks#review-and-trust-hooks)。

[![Codex 设置中的七个 ReMe Hook 条目](./figures/hooks-trusted.png)](./figures/hooks-trusted.png)

## 3. 在 MCP 设置中连接服务

打开已安装的 ReMe 详情，找到 **reme MCP server** 卡片，点击齿轮设置图标（**Open MCP settings**）。
在这个表单中调整服务地址和记忆选项，无需手动编辑配置文件。

首次验证建议保存以下配置：

| 字段 | 值 |
| --- | --- |
| ReMe MCP address | `http://127.0.0.1:2333/mcp`，或实际可达地址 |
| Automatic recall | 开启 |
| Automatic memory capture | 开启 |
| Capture batch size | `1`，每次回复完成后记录 |
| Memory guidance language | `zh` 或 `en` |

先保存，再点击 **ReMe status**。在 **总览** 中确认服务显示 **健康**，并能看到 ReMe 版本。
若无法连接，展开 **连接详情** 核对地址，并确认服务正在运行。接下来尝试记录和召回一条记忆。

[![Codex 设置中的 ReMe 服务地址、自动记忆选项和 Dream 计划](./figures/mcp-settings.png)](./figures/mcp-settings.png)

截图使用 `http://127.0.0.1:2444/mcp`，请填写你自己的服务地址。

## 4. 记录并召回第一条记忆

新建会话 A，使用一组独立的项目名和校验词，例如：

```text
请记住这个项目决策：ReMe-Example-7319 每周五 16:45 UTC 进行评审，
项目关键词是 amber-lynx-7319。
```

Codex 回复后，保持会话打开，等待记录完成。打开 **ReMe status → 自动记忆 → 最近活动**，
查看是否出现 **记忆已保存**（`memory_saved`），并确认 **待提交轮数** 回到零。
也可以在 ReMe 工作区的 `daily/` 下阅读保存的笔记。
看到保存成功后再进行下一步；Codex 的确认回复本身不能证明记忆已写入。

[![会话 A 中提交项目决策并收到确认回复](./figures/memory-recorded.png)](./figures/memory-recorded.png)

另建会话 B：

```text
ReMe-Example-7319 的评审时间和项目关键词是什么？
请根据 ReMe 记忆回答，并附上来源路径。
```

预期答复包含每周五 16:45 UTC、`amber-lynx-7319`，以及 `daily/...md` 等来源路径。
要确认自动召回生效，再查看 **自动记忆 → 最近活动** 中的 **已召回相关记忆**（`recall_found`）。
仅答对问题、却没有这条活动记录，不能证明自动召回已开启。
如果不在最近五条活动中，点击 **查看全部 … 条活动**。

[![会话 B 中召回评审时间、关键词和 ReMe 来源路径](./figures/memory-recalled.png)](./figures/memory-recalled.png)

日常使用时，直接提问即可，例如“我们之前确定的发布流程是什么？”或“找一下我之前的代码评审偏好”。
首次验证后可调整 **Capture batch size**：默认每五次完成的回复记录一批；希望每次回复后尽快保存时，设为 `1`。
尤其在短暂的 CLI 会话中，请保持 Codex 打开，直到待提交记录保存完成。

## 5. 设置定时整理或立即整理

在 **Auto Dream** 分组中设置 **Daily memory consolidation**、**Auto Dream schedule**、
**Workspace timezone**，按需填写 **Auto Dream hint**，然后保存。默认 `0 23 * * *`、
`Asia/Shanghai`，即每天上海时间 23:00。仅支持 `分钟 小时 * * *` 的每日计划，例如每天 02:30 为
`30 2 * * *`。Hint 可以填写想优先保留的信息，例如“优先保留项目决策和未完成事项”。

打开 **ReMe status → 记忆整理**，查看下次运行时间和最近结果。
在计划时间保持 Codex 和 ReMe 运行；重启后不会补跑错过的计划。
多台机器共用同一个 ReMe 工作区时，只在其中一台开启每日整理。

需要立即整理时，等待 **待提交轮数** 回到零，再在 MCP 设置中点击
**Consolidate ReMe memory now**。该操作会更新记忆文件，关闭每日计划后仍可使用。
整理后到 **记忆整理** 页签查看结果。关闭计划不会停止已经开始的整理；如果出现超时，先检查状态再重试。

在对话中需要整理时，可以要求 Codex 调用 `reme_run_dream`。
同一个 Codex 配置下已有整理任务运行时，新的请求会提示正在整理。

## 6. 查看状态和调整使用偏好

从 MCP 设置打开 **ReMe status**，根据需要选择页签：

| 页签 | 查看什么 |
| --- | --- |
| 总览 | 服务是否健康、是否还有对话待保存；展开 **连接详情** 可查看服务地址。 |
| 自动记忆 | 记录和召回是否开启；展开 **最近活动** 查看保存、召回或失败记录。 |
| 记忆整理 | 下次什么时候整理、最近一次是否成功。 |
| 组件 | ReMe 的内存用量；排错时可展开 **服务详情**。 |

点击 **刷新** 更新状态。最近活动默认展示五条；展开单条活动可查看完整时间和诊断信息，
点击 **查看全部 … 条活动** 可浏览其余记录。

也可以在对话中要求：“调用 `reme_status`，用文字告诉我连接状态、
待保存记忆和下次整理时间。”

[![ReMe status 总览：服务健康，待提交轮数和会话数均为零](./figures/plugin-status.png)](./figures/plugin-status.png)

总览展示服务健康状态和待提交轮数；查看记录与召回活动时，切换到 **Auto Memory** 页签。

需要调整时，回到 **Open MCP settings** 修改并保存。新设置对后续活动生效，无需重新安装。
下面按表单中显示的名称列出常用选项。

| 字段 | 默认值 | 什么时候调整 |
| --- | --- | --- |
| ReMe MCP address | `http://127.0.0.1:2333/mcp` | 改为另一个 ReMe 服务地址。 |
| Automatic memory capture | 开启 | 关闭后暂停自动记录。 |
| Capture batch size | `5` | 设为 `1` 可在每次回复后保存；调大可将更多回复合并记录。 |
| Automatic recall | 开启 | 关闭后不再为新提问自动补充过去的记忆。 |
| Root agents only | 开启 | 如果也需要记录和召回子代理对话，可关闭。 |
| Memory guidance language | `en` | 选择 `zh` 使用中文记忆指引和状态文字；设置表单标签仍为英文。 |
| Search result limit | `5` | 调大可获取更多检索结果，最多 50 条。 |
| Minimum recall score | `0` | 调高可过滤掉得分较低的匹配结果。 |
| Daily memory consolidation | 开启 | 希望手动整理，或服务已有整理计划时关闭。 |
| Auto Dream schedule | `0 23 * * *` | 修改每日整理时间，例如 `30 2 * * *` 表示每天 02:30。 |
| Auto Dream hint | 空 | 填写整理记忆时希望优先保留的信息。 |
| Workspace timezone | `Asia/Shanghai` | 设置记忆日期和每日计划使用的时区，例如 `Europe/London`。 |

<details>
<summary>超时设置</summary>

以下数值均以毫秒为单位，通常保留默认值；经常遇到请求超时时再调整。

| 字段 | 默认值 | 用途 |
| --- | --- | --- |
| Request timeout (ms) | `10000` | 检索和状态检查的等待时间，最多 `120000`。 |
| Background timeout (ms) | `3600000` | 记录和整理记忆的等待时间，最多 `3600000`。 |
| Shutdown timeout (ms) | `5000` | 退出等待设置；Codex 限制退出时的记忆提交最多等待两秒，调大此值也无法延长这段等待。 |

</details>

切换服务地址前，先等待待提交记录保存完成。已入队的对话始终归属原地址，不会复制或提交到新服务；
尚未保存的记录需要切回原地址重试。
整理过程中修改的配置用于下一次整理。

## 排查与更新

| 现象 | 检查方式 |
| --- | --- |
| 找不到 MCP 设置 | 确认桌面端符合上述版本要求，再打开已安装的 ReMe 详情及 `reme` MCP 卡片；确认启用后重启。 |
| Hooks 设置一直加载或没有 ReMe | 先打开本地项目文件夹并选择本机，再重新进入 Hooks 设置；见下方说明。 |
| 升级后状态页打不开，`No such file or directory` 指向旧插件版本 | 完全退出并重新打开 Codex，再从 MCP 设置打开 ReMe status。关闭卡片或新建会话不会重新加载已有的 MCP 连接。 |
| 状态卡片空白，随后提示“插件功能未成功加载” | 检查 Codex 沙箱页面的网络访问；见下方说明。 |
| 连接健康，但没有记录或召回 | 检查全部 ReMe Hook 的信任状态、自动开关及最近活动；连接健康不代表 Hook 已执行。 |
| 记录一直在队列中 | 保持 Codex 和 ReMe 运行，检查 ReMe 模型配置和服务日志，并确认启动命令包含 `service.tool_error_on_failure=true`。 |
| 没有召回结果 | 先确认事实已保存，提问时带上项目名，再检查 **Search result limit** 和 **Minimum recall score**。 |
| Dream 未触发 | 查看保存的时区、下次运行时间、开关及 MCP 连接；离线期间错过的时点不会补跑。 |
| 升级后提示未知配置字段 | 备份 `~/.codex/reme/config.json`，对照[当前配置示例](plugins/reme/config.example.json)更新旧字段，再打开设置。 |
| Python 或 FastMCP 启动报错 | 检查 Codex 实际继承的 `python3` 环境，尤其是桌面端的启动环境。 |

<details>
<summary>Hooks 设置一直加载</summary>

Codex 需要项目目录来列出 Hook。请先在桌面端添加并打开一个本地文件夹，若有主机选择则选择
**Local**，然后重新进入 **Settings → Hooks**。如果 **Reload hooks** 可用，点击刷新。
安装或升级 ReMe 后，如果列表仍未更新，重启 Codex。

如果桌面端页面仍无法加载，可以在同一个项目目录使用 CLI：

```bash
cd /absolute/path/to/project
codex
```

输入 `/hooks`，查看 ReMe 条目及启用、信任状态。如果自定义过 `CODEX_HOME`，请使用与桌面端
相同的目录。桌面页一直加载本身不能证明 Hook 没有执行；记录和召回是否生效仍需通过 ReMe 最近活动确认。

</details>

<details>
<summary>状态卡片空白或提示加载失败</summary>

Codex 需要访问 `web-sandbox.oaiusercontent.com` 才能展示面板。在运行 Codex 的机器上检查：

```bash
curl -i --max-time 20 https://web-sandbox.oaiusercontent.com/mcp-app.html
```

若响应为公司网络或安全软件的拦截提示，请按其正规流程放行 `web-sandbox.oaiusercontent.com`，
然后重启 Codex 并重新打开面板。暂时可以在对话中要求：“调用 `reme_status`，用文字展示返回的状态。”

</details>

需要进一步排查时，查看 `~/.codex/reme/hooks.log`。如果设置过 `CODEX_HOME`，用该目录替换 `~/.codex`。
排错时不要直接删除 `reme/` 目录，其中还保存着你的配置和尚未写入的对话。

更新仓库后重新安装：

```bash
codex plugin remove reme@reme-codex
codex plugin add reme@reme-codex
```

重启 Codex 并重新审核发生变化的 Hook。已保存的设置和待提交记忆会继续保留。