diff --git a/integrations/codex/README.md b/integrations/codex/README.md index f6e7dbda..e27d92f2 100644 --- a/integrations/codex/README.md +++ b/integrations/codex/README.md @@ -2,9 +2,9 @@ [中文说明](./README_ZH.md) -Connect Codex to your ReMe service to remember facts, preferences, and decisions across conversations. -Relevant memories are recalled before a prompt, completed conversations are recorded automatically, -and daily notes can be consolidated on a schedule. Your ReMe workspace owns the durable Markdown files. +Connect Codex to your ReMe service to remember project decisions, preferences, and unfinished work +across conversations. ReMe can automatically record and recall memories, and organize them each day. +Your memory files stay in your own ReMe workspace. ## Before you start @@ -39,13 +39,11 @@ Keep the service running. Its MCP address is `http://127.0.0.1:2333/mcp`; it mus **the machine running Codex**. Use your service's actual address when it runs elsewhere. `workspace_dir` determines where your memory lives. Keep an unauthenticated service on loopback or behind a protected proxy. -Keep `service.tool_error_on_failure=true`: failed memory jobs must fail their MCP calls so unacknowledged -writes remain queued for retry. A successful health check does not verify this setting. +Keep `service.tool_error_on_failure=true` so failed writes can be retried later. -The last two options stop ReMe's built-in Dream timer so Codex can schedule consolidation. They use -existing service configuration and require no ReMe code changes. If your service already manages -consolidation and you want to keep that schedule, omit those options and turn off **Daily memory -consolidation** (`autoDreamEnabled`) in Codex. Choose one scheduler for a shared workspace. +This example lets Codex manage daily consolidation. If your ReMe service already has a schedule +you want to keep, omit the last two options and turn off **Daily memory consolidation** in Codex. +Enable daily consolidation in only one place for the same workspace. ## 2. Install ReMe and trust its Hooks @@ -64,18 +62,8 @@ Restart the desktop app, or start a new CLI session. Open the installed ReMe ent ![ReMe installed and enabled in Codex](./figures/plugin-installed.png) --> -In Codex's Hooks settings, review and trust **every ReMe entry**. In the CLI, use `/hooks`. -There are seven handlers across five events: - -| Event | Purpose | -| --- | --- | -| `UserPromptSubmit` | Recall relevant memory before the prompt. | -| `Stop` | Save the completed turn locally, then deliver due batches in the background; two entries. | -| `SubagentStop` | The same two entries for subagents, used only when `rootAgentsOnly=false`. | -| `SessionStart` | Retry pending writes in the background. | -| `SessionEnd` | Attempt a short final delivery; preserve unfinished batches. | - -Untrusted Hooks do not run. Installing or connecting the MCP server does not grant Hook trust. +In Codex's Hooks settings, review and trust **every ReMe entry** (currently seven). In the CLI, use `/hooks`. +This enables automatic recording and recall. A healthy service connection alone does not enable them. After an update, review any changed entries again. See [Codex Hook review and trust](https://learn.chatgpt.com/docs/hooks#review-and-trust-hooks). > **Screenshot placeholder — `hooks-trusted.png`:** All seven ReMe entries enabled and trusted in Codex Hooks settings or `/hooks`. @@ -87,21 +75,21 @@ After an update, review any changed entries again. See [Codex Hook review and tr ## 3. Connect through MCP settings Open the installed ReMe entry, find its **reme MCP server** card, and choose **Open MCP settings**. -This is the editable form for the service address and memory options. +Use this form to change the service address and memory options. You do not need to edit a configuration file. For a first test, save these values: | Field | Value | | --- | --- | -| ReMe MCP address (`mcpUrl`) | `http://127.0.0.1:2333/mcp`, or your reachable service address | -| Automatic recall (`autoRecall`) | On | -| Automatic memory capture (`autoMemoryEnabled`) | On | -| Capture batch size (`autoMemoryInterval`) | `1` | -| Memory guidance language (`language`) | `en` or `zh` | +| ReMe MCP address | `http://127.0.0.1:2333/mcp`, or your reachable service address | +| Automatic recall | On | +| Automatic memory capture | On | +| Capture batch size | `1` to record after each completed reply | +| Memory guidance language | `en` or `zh` | -Save before using an action. Click **ReMe status** to open the status panel. Its Connection section checks the saved service -address and shows the ReMe version and `healthy` when reachable. This verifies service access; -recording and recall still need the conversation test below. +Save, then click **ReMe status**. In **Overview**, check that the service is **Healthy** and the ReMe +version is shown. If it is unavailable, expand **Connection details** to check the address and confirm +that your service is running. Next, try recording and recalling a memory. > **Screenshot placeholder — `mcp-settings.png`:** Actual native form with the address, capture switches, batch size, and the single ReMe status entry. @@ -109,21 +97,21 @@ recording and recall still need the conversation test below. ![ReMe MCP settings and connection result](./figures/mcp-settings.png) --> -## 4. Verify memory across two conversations +## 4. Try your first memory Start a fresh conversation A. Use a unique project and phrase, for example: ```text -Remember this confirmed project decision: ReMe-Example-7319 reviews happen Friday -at 16:45 UTC. The verification phrase is amber-lynx-7319. -Do not use tools or write files yourself; just acknowledge the facts. +Remember this project decision: ReMe-Example-7319 reviews happen Friday +at 16:45 UTC. The project keyword is amber-lynx-7319. ``` -Keep the conversation open while recording finishes. In MCP settings, **ReMe status** should show -`memory_saved` and zero queued turns. In your ReMe workspace, confirm a `daily/` Markdown note -contains the fact. An acknowledgement by Codex alone is not evidence of a successful write. +After Codex replies, keep the conversation open while recording finishes. Open **ReMe status → +Auto Memory → Recent activity** and look for **Memory saved** (`memory_saved`). **Queued turns** +should return to zero. You can also read the saved note under `daily/` in your ReMe workspace. +Wait for the saved status before continuing; Codex's acknowledgement alone does not confirm recording. -> **Screenshot placeholder — `memory-recorded.png`:** Conversation A with the test fact and acknowledgement, without explicit tool calls. +> **Screenshot placeholder — `memory-recorded.png`:** Conversation A with the project decision and acknowledgement. -After verification, adjust the batch size for normal use; the default is five completed turns. -Short batches are also attempted at session boundaries. Failed or interrupted deliveries remain -queued locally for a later session. A short-lived `codex exec` can exit before background delivery -finishes; keep a session open when checking automatic writes. +For everyday use, ask naturally: “What did we decide about this project's release process?” or +“Find my earlier preferences for code reviews.” You can adjust **Capture batch size** after the first +check; the default is five completed replies. Use `1` if you want each reply recorded promptly. +Keep Codex open until queued turns are saved, especially during short CLI sessions. ## 5. Schedule or run memory consolidation In **Auto Dream**, set **Daily memory consolidation**, **Auto Dream schedule**, **Workspace timezone**, and optionally **Auto Dream hint**, then save. Defaults are `0 23 * * *` and `Asia/Shanghai`: daily at 23:00. Only the daily form `minute hour * * *` is supported; for 02:30 use `30 2 * * *`. -The hint guides how ReMe consolidates existing daily notes into durable memory. +Use the hint to emphasize what to retain, for example: “Prioritize project decisions and unresolved tasks.” -**ReMe status** shows the active schedule, timezone, next run, and latest result. The schedule runs -while Codex keeps the ReMe MCP connection alive. Closing Codex stops the timer; missed occurrences -are not replayed on startup. Multiple sessions sharing one `CODEX_HOME` use one scheduler. Separate -profiles or machines need their own coordination: enable only one scheduler for the same ReMe workspace. +Open **ReMe status → Consolidation** to check the next run and latest result. Keep Codex and ReMe +running at the scheduled time; missed runs are not made up after restarting. If several machines +use the same ReMe workspace, enable daily consolidation on only one of them. -For an immediate run, wait until pending writes are delivered, then click **Consolidate now (updates -memory files)** or explicitly ask Codex to use `reme_run_dream`. This updates existing memory files. -It remains available with the schedule disabled. Turning the schedule off does not cancel a request -already sent to ReMe; a timeout also does not prove that server-side processing has stopped. +To organize your memories now, wait for **Queued turns** to reach zero, then click **Consolidate now +(updates memory files)** in MCP settings. This updates your memory files and also works when the daily +schedule is off. Check **Consolidation** for the result. Turning off the schedule does not stop an +already-started run; after a timeout, check its status before trying again. -## 6. Inspect status and adjust settings +## 6. Check status and customize ReMe -Click **ReMe status** to open a dedicated panel from MCP settings. Connection checks and memory -status share this one entry. Four tabs organize the panel: **Overview**, **Auto Memory**, -**Consolidation**, and **Components**. They show service health and the pending queue; -capture settings, queued turns/sessions, recall and recent activity; Dream scheduling and results; -and component memory estimates plus process RSS. Click **Refresh** to check again; -connection details, recent activity, usage notes, and raw service details expand when needed. Narrow cards use a -single content column and two rows of tabs. The initial view uses the opening call's result without -a second request. The panel follows the host theme and the saved `language` setting. +Open **ReMe status** from MCP settings and choose the tab for what you want to check: -You can also ask Codex to call `reme_status` in a conversation. Hosts without an App view receive -the same status as text. Opening or refreshing the panel does not record or consolidate memory. -Component health and indexed-document counts are not exposed by the current ReMe MCP response; -the panel shows the available memory estimates without substituting other counts. -Queue and activity information remain available when the service is unreachable. Hook trust is -checked separately in Codex's Hooks settings. +| Tab | What to check | +| --- | --- | +| Overview | Is ReMe healthy? Are any conversation turns waiting to be saved? Expand **Connection details** to see the service address. | +| Auto Memory | Are recording and recall enabled? Expand **Recent activity** to check the latest saves, recalls, or failures. | +| Consolidation | When will memories next be organized, and did the last run succeed? | +| Components | How much memory is ReMe using? Expand **Service details** when troubleshooting. | + +Click **Refresh** for an updated view. If you prefer a text answer, ask Codex: +“Call `reme_status` and summarize my connection, pending memories, and next consolidation.” > **Screenshot placeholder — `plugin-status.png`:** Real ReMe status panel or `reme_status` output with connection health, queued turns, recent activity, and the next Dream run. @@ -193,28 +175,39 @@ checked separately in Codex's Hooks settings. ![ReMe delivery and consolidation status in Codex](./figures/plugin-status.png) --> -| Setting | Default | Meaning | -| --- | --- | --- | -| `mcpUrl` | `http://127.0.0.1:2333/mcp` | Full ReMe MCP URL. | -| `autoRecall` | `true` | Recall relevant memory before each prompt. | -| `autoMemoryEnabled` | `true` | Record completed user/assistant turns. | -| `autoMemoryInterval` | `5` | Completed turns per batch, from 1 to 1000. | -| `rootAgentsOnly` | `true` | Exclude subagent recall and recording. | -| `searchLimit` | `5` | Maximum search results, from 1 to 50. | -| `recallMinScore` | `0` | Minimum search score, nonnegative. | -| `language` | `en` | `en` or `zh` for memory guidance and local results; form labels stay in English. | -| `autoDreamEnabled` | `true` | Enable daily consolidation while the MCP connection is alive. | -| `dreamCron` | `0 23 * * *` | Daily consolidation time. | -| `dreamHint` | Empty | Guidance for scheduled and manual consolidation. | -| `timezone` | `Asia/Shanghai` | IANA timezone for memory dates and the daily schedule. | -| `requestTimeoutMs` | `10000` | Foreground request budget, from 1000 to 120000 ms. | -| `backgroundTimeoutMs` | `3600000` | Memory extraction and consolidation budget, from 1000 to 3600000 ms. | -| `shutdownTimeoutMs` | `5000` | Shutdown budget, from 100 to 60000 ms. Codex's `SessionEnd` limit restricts exit delivery to at most 2 seconds. | +Change options in **Open MCP settings**, then save. New settings apply to subsequent activity; you do +not need to reinstall. Common adjustments are listed below using the names shown in the form. -Saved settings apply to subsequent calls without reinstalling. They live outside the plugin cache, -in `${CODEX_HOME:-~/.codex}/reme/config.json`. See [the complete configuration example](plugins/reme/config.example.json). -Changing `mcpUrl` does not send old queued conversations to the new service; switch back to the old -address to retry them. Settings changed during consolidation apply to subsequent runs. +| Field | Default | When to change it | +| --- | --- | --- | +| ReMe MCP address | `http://127.0.0.1:2333/mcp` | Connect to a different ReMe service. | +| Automatic memory capture | On | Turn off to pause automatic recording. | +| Capture batch size | `5` | Set to `1` to save after each completed reply; increase to group more replies per save. | +| Automatic recall | On | Turn off to stop adding past memories to new prompts. | +| Root agents only | On | Turn off if you also want subagent conversations recorded and recalled. | +| Memory guidance language | `en` | Choose `zh` for Chinese guidance and status text. Settings labels remain English. | +| Search result limit | `5` | Increase to retrieve more results, up to 50. | +| Minimum recall score | `0` | Increase to filter out lower-scoring matches. | +| Daily memory consolidation | On | Turn off if you prefer manual organization or already have a service schedule. | +| Auto Dream schedule | `0 23 * * *` | Set the daily time, for example `30 2 * * *` for 02:30. | +| Auto Dream hint | Empty | Describe which information to prioritize when organizing memory. | +| Workspace timezone | `Asia/Shanghai` | Set your timezone, such as `Europe/London`, for memory dates and the daily schedule. | + +
+Timeout settings + +These values are in milliseconds. Keep the defaults unless requests regularly time out. + +| Field | Default | Use | +| --- | --- | --- | +| Request timeout (ms) | `10000` | Wait time for searches and status checks; maximum `120000`. | +| Background timeout (ms) | `3600000` | Wait time for recording and consolidation; maximum `3600000`. | +| Shutdown timeout (ms) | `5000` | Exit wait setting. Codex limits final memory delivery to at most two seconds, so increasing this cannot extend that wait. | + +
+ +Before changing the service address, let pending turns finish saving. Any remaining turns stay associated +with the previous address; switch back to retry them. Changes made during consolidation apply to the next run. ## Troubleshooting and updates @@ -223,30 +216,31 @@ address to retry them. Settings changed during consolidation apply to subsequent | No MCP settings entry | Open the installed ReMe detail and its `reme` MCP card in the latest desktop app; confirm it is enabled and restart. | | Blank status card followed by a plugin feature loading error | Check network access to the Codex sandbox page; see below. | | Connection healthy, no recording or recall | Review every ReMe Hook; check the auto switches and recent activity. Health does not prove Hook execution. | -| Turns stay queued | Check the ReMe model and service logs, keep the session open, and confirm `service.tool_error_on_failure=true`. Retry happens at a later Hook. | -| Recall is empty | First confirm the fact exists in `daily/`, use its unique identifier, and inspect `searchLimit` and `recallMinScore`. | +| Turns stay queued | Keep Codex and ReMe running. Check the ReMe model configuration and service logs, and confirm the startup command includes `service.tool_error_on_failure=true`. | +| Recall is empty | Confirm the fact was saved, mention its project name in your question, and check **Search result limit** and **Minimum recall score**. | | Dream did not run | Check the saved timezone, next run, schedule switch, and live MCP connection. Offline times are skipped. | -| Unknown configuration fields after upgrading | Back up `reme/config.json`, then replace obsolete fields using the current configuration example and reopen MCP settings. Old field names are not supported. | +| Unknown configuration fields after upgrading | Back up `~/.codex/reme/config.json`, compare it with the [current configuration example](plugins/reme/config.example.json), and update obsolete fields before reopening settings. | | Python or FastMCP startup error | Check the `python3` environment inherited by Codex, including the desktop app. | -The panel serves its HTML and status data over local MCP, but Codex desktop also loads its own sandbox page. -If the card stays blank and the Codex client logs contain `guest_load_failed`, `ERR_UNEXPECTED`, or -`MCP sandbox RPC timed out`, check access from the machine running Codex: +
+The status card is blank or reports a loading error + +Codex needs access to `web-sandbox.oaiusercontent.com` to display the panel. Check access from the +machine running Codex: ```bash curl -i --max-time 20 https://web-sandbox.oaiusercontent.com/mcp-app.html ``` If the response reports a corporate network or security software block, follow its approved process to allow -`web-sandbox.oaiusercontent.com`, including the page's static assets on that domain. Restart Codex and reopen the panel -after access is restored. This loading error alone does not establish whether ReMe or its Hooks are healthy and does -not call for changing `mcpUrl`, clearing memory, or reinstalling the plugin. Meanwhile, ask in a conversation: -“Call `reme_status` and show the returned status as text” to inspect the connection, queue, and consolidation schedule. +`web-sandbox.oaiusercontent.com`. Restart Codex and reopen the panel after access is restored. +Meanwhile, ask in a conversation: “Call `reme_status` and show the returned status as text.” -Content-free diagnostics are in `${CODEX_HOME:-~/.codex}/reme/hooks.log`; they include event names, -counts, and error classes, not conversation content. Pending conversation data is stored separately -in that directory until acknowledged. Delivery is best effort: forced termination before local -capture can lose a turn, and a lost acknowledgement can cause extraction to be retried. +
+ +For further diagnosis, check `~/.codex/reme/hooks.log`. If you set `CODEX_HOME`, use that directory +instead of `~/.codex`. Avoid deleting `reme/` while troubleshooting: it also contains your settings +and conversations still waiting to be saved. To update, refresh your checkout and reinstall: @@ -255,6 +249,4 @@ codex plugin remove reme@reme-codex codex plugin add reme@reme-codex ``` -Restart Codex and review changed Hooks. Your saved settings and pending writes remain outside the -installation cache. The [screenshot checklist](./figures/README.md) lists the six real Codex captures -reserved above; both language guides share the same images. +Restart Codex and review changed Hooks. Your saved settings and pending memories are preserved. diff --git a/integrations/codex/README_ZH.md b/integrations/codex/README_ZH.md index 49712240..b1db002c 100644 --- a/integrations/codex/README_ZH.md +++ b/integrations/codex/README_ZH.md @@ -2,8 +2,8 @@ [English](./README.md) -将 Codex 接入自己的 ReMe 服务，即可跨会话记住事实、偏好和决策：提问前自动召回相关记忆， -对话完成后自动记录，并按日整理记忆。长期记忆保存在你自己的 ReMe 工作区 Markdown 文件中。 +将 Codex 接入自己的 ReMe 服务，即可跨会话记住项目决策、个人偏好和待办事项。 +ReMe 可以自动记录、召回记忆，并每天整理。记忆文件保存在你自己的 ReMe 工作区中。 ## 开始前 @@ -37,12 +37,10 @@ reme start \ 远程部署时填写实际可达的服务地址。`workspace_dir` 决定记忆文件存放位置。 未启用认证的服务应仅监听本机，或放在受保护的代理之后。 -保留 `service.tool_error_on_failure=true`：记忆任务失败时，MCP 调用也必须报告失败， -尚未确认写入的对话才能留在队列中重试。连接健康不能证明这个选项已开启。 +保留 `service.tool_error_on_failure=true`，以便写入失败后稍后重试。 -最后两项配置关闭 ReMe 自带的 Dream 定时任务，让 Codex 负责定时触发；使用现有服务配置即可， -无需修改 ReMe 代码。如果服务已有整理计划且希望继续使用，省略这两项，并在 Codex 中关闭 -**Daily memory consolidation**（`autoDreamEnabled`）。同一个工作区保留一个调度来源。 +这个示例由 Codex 管理每日整理。如果 ReMe 服务已有整理计划且希望继续使用，省略最后两项， +并在 Codex 中关闭 **Daily memory consolidation**。同一个工作区只在一处开启每日整理。 ## 2. 安装 ReMe 并信任 Hook @@ -61,18 +59,8 @@ codex plugin add reme@reme-codex ![Codex 中已安装并启用 ReMe](./figures/plugin-installed.png) --> -在 Codex 的 Hooks 设置中，审核并信任 **所有 ReMe 条目**；CLI 可使用 `/hooks`。 -共七个处理条目，分属五类事件： - -| 事件 | 用途 | -| --- | --- | -| `UserPromptSubmit` | 提问前召回相关记忆。 | -| `Stop` | 先在本地保存已完成轮次，再后台提交到期批次；共两个条目。 | -| `SubagentStop` | 子代理的两个对应条目，仅在 `rootAgentsOnly=false` 时使用。 | -| `SessionStart` | 后台重试待提交的记录。 | -| `SessionEnd` | 在有限退出时间内尝试提交，保留未完成批次。 | - -未信任的 Hook 不会执行。安装成功或 MCP 连接正常，都不等于 Hook 已获信任。 +在 Codex 的 Hooks 设置中，审核并信任 **所有 ReMe 条目**（目前共七个）；CLI 可使用 `/hooks`。 +完成这一步才能自动记录和召回。仅连接服务并不会启用这些能力。 升级后如条目发生变化，需要重新审核。参见 [Codex Hook 审核与信任说明](https://learn.chatgpt.com/docs/hooks#review-and-trust-hooks)。 > **截图槽位 — `hooks-trusted.png`：** Codex Hooks 设置或 `/hooks` 中，七个 ReMe 条目均已启用、已信任。 @@ -84,20 +72,20 @@ codex plugin add reme@reme-codex ## 3. 在 MCP 设置中连接服务 打开已安装的 ReMe 详情，找到 **reme MCP server** 卡片，点击 **Open MCP settings**。 -服务地址、自动记忆开关等均在这个原生表单中调整。 +在这个表单中调整服务地址和记忆选项，无需手动编辑配置文件。 首次验证建议保存以下配置： | 字段 | 值 | | --- | --- | -| ReMe MCP address（`mcpUrl`） | `http://127.0.0.1:2333/mcp`，或实际可达地址 | -| Automatic recall（`autoRecall`） | 开启 | -| Automatic memory capture（`autoMemoryEnabled`） | 开启 | -| Capture batch size（`autoMemoryInterval`） | `1` | -| Memory guidance language（`language`） | `zh` 或 `en` | +| 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 版本及 `healthy`。这说明服务可访问；记录和召回还需要通过下一步的对话验证。 +先保存，再点击 **ReMe status**。在 **总览** 中确认服务显示 **健康**，并能看到 ReMe 版本。 +若无法连接，展开 **连接详情** 核对地址，并确认服务正在运行。接下来尝试记录和召回一条记忆。 > **截图槽位 — `mcp-settings.png`：** 真实原生表单，保留服务地址、自动开关、批次大小及唯一的 ReMe status 入口。 @@ -105,21 +93,21 @@ codex plugin add reme@reme-codex ![ReMe MCP 设置与连接结果](./figures/mcp-settings.png) --> -## 4. 用两个独立会话验证记忆 +## 4. 记录并召回第一条记忆 新建会话 A，使用一组独立的项目名和校验词，例如： ```text -请记住这个已确认的项目决策：ReMe-Example-7319 每周五 16:45 UTC 进行评审， -校验词是 amber-lynx-7319。 -不要调用工具或自己写文件，只需确认这些事实。 +请记住这个项目决策：ReMe-Example-7319 每周五 16:45 UTC 进行评审， +项目关键词是 amber-lynx-7319。 ``` -保持会话打开，等待自动记录完成。在 MCP 设置中点击 **ReMe status**，应看到 `memory_saved`， -待提交轮数为零；同时检查 ReMe 工作区的 `daily/` Markdown 文件中出现了这条事实。 -Codex 的确认回复本身不能证明记忆已写入。 +Codex 回复后，保持会话打开，等待记录完成。打开 **ReMe status → 自动记忆 → 最近活动**， +查看是否出现 **记忆已保存**（`memory_saved`），并确认 **待提交轮数** 回到零。 +也可以在 ReMe 工作区的 `daily/` 下阅读保存的笔记。 +看到保存成功后再进行下一步；Codex 的确认回复本身不能证明记忆已写入。 -> **截图槽位 — `memory-recorded.png`：** 会话 A 中的测试事实和确认回复，不包含显式工具调用。 +> **截图槽位 — `memory-recorded.png`：** 会话 A 中的项目决策和确认回复。 -验证后可调整批次大小，默认每五个完成轮次提交一次；不足一批时，也会在会话边界尝试提交。 -失败或中断的批次保留在本地，供后续会话重试。短暂运行的 `codex exec` 可能在后台写入完成前退出； -验证自动记录时，应保持会话运行。 +日常使用时，直接提问即可，例如“我们之前确定的发布流程是什么？”或“找一下我之前的代码评审偏好”。 +首次验证后可调整 **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 将现有日常记录整理为长期记忆。 +`30 2 * * *`。Hint 可以填写想优先保留的信息，例如“优先保留项目决策和未完成事项”。 -**ReMe status** 会展示计划、时区、下次运行时间和最近结果。只有 Codex 保持 ReMe MCP 连接时， -定时任务才会触发；关闭 Codex 后停止计时，重启时不补跑错过的时点。同一 `CODEX_HOME` 下的多个会话 -共用一个调度器；不同配置目录或机器需自行协调，同一个 ReMe 工作区仅启用一处定时整理。 +打开 **ReMe status → 记忆整理**，查看下次运行时间和最近结果。 +在计划时间保持 Codex 和 ReMe 运行；重启后不会补跑错过的计划。 +多台机器共用同一个 ReMe 工作区时，只在其中一台开启每日整理。 -需要立即整理时，先等待待提交记录完成，再点击 **Consolidate now (updates memory files)**， -或明确让 Codex 调用 `reme_run_dream`。该操作会更新已有记忆文件，关闭定时开关后仍可手动执行。 -关闭定时开关不会取消已经发给 ReMe 的请求；超时也不代表服务端已停止处理。 +需要立即整理时，等待 **待提交轮数** 回到零，再在 MCP 设置中点击 +**Consolidate now (updates memory files)**。该操作会更新记忆文件，关闭每日计划后仍可使用。 +整理后到 **记忆整理** 页签查看结果。关闭计划不会停止已经开始的整理；如果出现超时，先检查状态再重试。 -## 6. 查看状态和调整配置 +## 6. 查看状态和调整使用偏好 -点击 **ReMe status**，从 MCP 设置打开独立状态面板。连接检查和记忆状态共用这一个入口， -面板分为 **总览、自动记忆、记忆整理、组件** 四个页签，分别展示连接健康与待提交队列， -记录开关、批次和队列、召回及最近活动，Dream 计划和结果，以及组件内存估算与进程 RSS。 -点击 **刷新** 可重新检查；连接详情、最近活动、使用说明和原始服务详情按需展开。 -窄卡片使用单列内容和两行页签。首次展示直接使用打开时返回的结果，不重复请求；面板适配宿主主题及保存的 `language`。 +从 MCP 设置打开 **ReMe status**，根据需要选择页签： -也可以在对话中让 Codex 调用 `reme_status`；不展示 App 的宿主仍会收到文字结果。 -打开或刷新面板不会记录或整理记忆。服务不可达时仍可查看本地队列与活动。 -当前 ReMe MCP 响应不包含组件级健康和索引文档数量，面板仅展示可获取的内存估算，不用其他计数替代。 -Hook 是否可信，需另到 Codex 的 Hooks 设置中检查。 +| 页签 | 查看什么 | +| --- | --- | +| 总览 | 服务是否健康、是否还有对话待保存；展开 **连接详情** 可查看服务地址。 | +| 自动记忆 | 记录和召回是否开启；展开 **最近活动** 查看保存、召回或失败记录。 | +| 记忆整理 | 下次什么时候整理、最近一次是否成功。 | +| 组件 | ReMe 的内存用量；排错时可展开 **服务详情**。 | + +点击 **刷新** 更新状态。也可以在对话中要求：“调用 `reme_status`，用文字告诉我连接状态、 +待保存记忆和下次整理时间。” > **截图槽位 — `plugin-status.png`：** 真实 ReMe status 面板或 `reme_status` 输出，保留连接健康、待提交轮数、最近活动和下次 Dream 时间。 @@ -180,28 +169,39 @@ Hook 是否可信，需另到 Codex 的 Hooks 设置中检查。 ![Codex 中的 ReMe 写入和整理状态](./figures/plugin-status.png) --> -| 配置项 | 默认值 | 含义 | -| --- | --- | --- | -| `mcpUrl` | `http://127.0.0.1:2333/mcp` | 完整 ReMe MCP 地址。 | -| `autoRecall` | `true` | 每次提问前自动召回。 | -| `autoMemoryEnabled` | `true` | 自动记录完成的用户/助手轮次。 | -| `autoMemoryInterval` | `5` | 每批完成轮数，范围 1–1000。 | -| `rootAgentsOnly` | `true` | 排除子代理的召回与记录。 | -| `searchLimit` | `5` | 最多返回的检索结果数，范围 1–50。 | -| `recallMinScore` | `0` | 检索最低得分，不小于零。 | -| `language` | `en` | 记忆指引和本地结果使用 `en` 或 `zh`；设置表单标签仍为英文。 | -| `autoDreamEnabled` | `true` | MCP 连接存活期间启用每日整理。 | -| `dreamCron` | `0 23 * * *` | 每日整理时间。 | -| `dreamHint` | 空 | 定时和手动整理使用的指导文字。 | -| `timezone` | `Asia/Shanghai` | 记忆日期及每日计划采用的 IANA 时区。 | -| `requestTimeoutMs` | `10000` | 前台请求超时，范围 1000–120000 毫秒。 | -| `backgroundTimeoutMs` | `3600000` | 记忆提取与整理超时，范围 1000–3600000 毫秒。 | -| `shutdownTimeoutMs` | `5000` | 退出等待时间，范围 100–60000 毫秒；受 Codex `SessionEnd` 限制，退出提交最多等待 2 秒。 | +需要调整时，回到 **Open MCP settings** 修改并保存。新设置对后续活动生效，无需重新安装。 +下面按表单中显示的名称列出常用选项。 -保存后对后续调用生效，无需重新安装。配置保存在插件缓存之外： -`${CODEX_HOME:-~/.codex}/reme/config.json`。完整字段见[配置示例](plugins/reme/config.example.json)。 -修改 `mcpUrl` 不会将旧队列中的对话发给新服务；切回原地址后才能重试这些记录。 -整理进行期间修改的配置用于后续运行。 +| 字段 | 默认值 | 什么时候调整 | +| --- | --- | --- | +| 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`。 | + +
+超时设置 + +以下数值均以毫秒为单位，通常保留默认值；经常遇到请求超时时再调整。 + +| 字段 | 默认值 | 用途 | +| --- | --- | --- | +| Request timeout (ms) | `10000` | 检索和状态检查的等待时间，最多 `120000`。 | +| Background timeout (ms) | `3600000` | 记录和整理记忆的等待时间，最多 `3600000`。 | +| Shutdown timeout (ms) | `5000` | 退出等待设置；Codex 限制退出时的记忆提交最多等待两秒，调大此值也无法延长这段等待。 | + +
+ +切换服务地址前，先等待待提交记录保存完成。尚未保存的记录仍关联原地址，需要切回原地址重试。 +整理过程中修改的配置用于下一次整理。 ## 排查与更新 @@ -210,28 +210,28 @@ Hook 是否可信，需另到 Codex 的 Hooks 设置中检查。 | 找不到 MCP 设置 | 在最新版桌面端打开已安装的 ReMe 详情及 `reme` MCP 卡片；确认启用后重启。 | | 状态卡片空白，随后提示“插件功能未成功加载” | 检查 Codex 沙箱页面的网络访问；见下方说明。 | | 连接健康，但没有记录或召回 | 检查全部 ReMe Hook 的信任状态、自动开关及最近活动；连接健康不代表 Hook 已执行。 | -| 记录一直在队列中 | 检查 ReMe 模型配置和服务日志，保持会话运行，并确认 `service.tool_error_on_failure=true`；后续 Hook 会尝试重试。 | -| 没有召回结果 | 先确认事实已在 `daily/` 中，使用独立项目名查询，再检查 `searchLimit` 和 `recallMinScore`。 | +| 记录一直在队列中 | 保持 Codex 和 ReMe 运行，检查 ReMe 模型配置和服务日志，并确认启动命令包含 `service.tool_error_on_failure=true`。 | +| 没有召回结果 | 先确认事实已保存，提问时带上项目名，再检查 **Search result limit** 和 **Minimum recall score**。 | | Dream 未触发 | 查看保存的时区、下次运行时间、开关及 MCP 连接；离线期间错过的时点不会补跑。 | -| 升级后提示未知配置字段 | 备份 `reme/config.json`，按当前配置示例替换旧字段，再打开 MCP 设置；不支持旧字段名。 | +| 升级后提示未知配置字段 | 备份 `~/.codex/reme/config.json`，对照[当前配置示例](plugins/reme/config.example.json)更新旧字段，再打开设置。 | | Python 或 FastMCP 启动报错 | 检查 Codex 实际继承的 `python3` 环境，尤其是桌面端的启动环境。 | -状态面板通过本地 MCP 提供 HTML 和状态数据，但 Codex 桌面端还需要加载自己的沙箱页面。 -如果卡片空白，且 Codex 客户端日志出现 `guest_load_failed`、`ERR_UNEXPECTED` 或 -`MCP sandbox RPC timed out`，可在运行 Codex 的机器上检查： +
+状态卡片空白或提示加载失败 + +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 服务或 Hook 是否正常，也不需要因此修改 `mcpUrl`、清空记忆或重装插件。 -暂时可以在对话中要求“调用 `reme_status`，用文字展示返回的状态”，查看服务连接、队列和整理计划。 +然后重启 Codex 并重新打开面板。暂时可以在对话中要求：“调用 `reme_status`，用文字展示返回的状态。” -诊断日志位于 `${CODEX_HOME:-~/.codex}/reme/hooks.log`，仅包含事件名、计数和错误类型，不记录对话正文。 -尚未确认写入的对话数据另存于该目录。记录采用尽力交付：本地捕获前强制终止可能丢失轮次， -服务端处理成功但确认丢失时，重试也可能导致重复提取。 +
+ +需要进一步排查时，查看 `~/.codex/reme/hooks.log`。如果设置过 `CODEX_HOME`，用该目录替换 `~/.codex`。 +排错时不要直接删除 `reme/` 目录，其中还保存着你的配置和尚未写入的对话。 更新仓库后重新安装： @@ -240,5 +240,4 @@ codex plugin remove reme@reme-codex codex plugin add reme@reme-codex ``` -重启 Codex 并重新审核发生变化的 Hook。设置和待提交记录位于安装缓存之外，会继续保留。 -[截图清单](./figures/README.md)列出了上面的六处真实 Codex 截图槽位，中英文共用图片。 +重启 Codex 并重新审核发生变化的 Hook。已保存的设置和待提交记忆会继续保留。