scriptoriumadmin/ReMe
1
0
Fork 0
mirror of https://github.com/agentscope-ai/ReMe.git synced 2026-10-12 03:50:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(codex): focus guides on connecting and using ReMe

Browse source
This commit is contained in:
huangsen 2026-09-30 17:46:37 +08:00
parent 47287c09a6
commit 5af9c0132d
2 changed files with 196 additions and 205 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

212
integrations/codex/README.md
View file

@ -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.
<!--
![Codex conversation supplying a fact to remember](./figures/memory-recorded.png)
@ -132,14 +120,13 @@ contains the fact. An acknowledgement by Codex alone is not evidence of a succes
Start a separate conversation B:
```text
For ReMe-Example-7319, when are the reviews and what is the verification phrase?
Use supplied ReMe memory and cite its source path. Do not call tools;
if no memory was supplied, say you do not know.
For ReMe-Example-7319, when are the reviews and what is the project keyword?
Use ReMe memory and include the source path in your answer.
```
Expect the correct time, phrase, and a ReMe source path such as `daily/...md`. **ReMe status** should
include `recall_found`. This tests automatic recall independently of explicit search tools.
For everyday use, you can also ask Codex to search past decisions with `reme_search`.
Expect Friday at 16:45 UTC, `amber-lynx-7319`, and a source path such as `daily/...md`.
To confirm automatic recall, check **Auto Memory → Recent activity** for **Relevant memory recalled**
(`recall_found`). A correct answer without that event does not confirm that automatic recall is enabled.
> **Screenshot placeholder — `memory-recalled.png`:** Separate conversation B with the recalled facts and source path.
@ -147,45 +134,40 @@ For everyday use, you can also ask Codex to search past decisions with `reme_sea
![Codex recalling memory in a separate conversation](./figures/memory-recalled.png)
-->
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. |
<details>
<summary>Timeout settings</summary>
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. |
</details>
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:
<details>
<summary>The status card is blank or reports a loading error</summary>
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.
</details>
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.

189
integrations/codex/README_ZH.md
View file

@ -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 会话中提供需要记住的事实](./figures/memory-recorded.png)
@ -128,13 +116,13 @@ Codex 的确认回复本身不能证明记忆已写入。
另建会话 B：
```text
ReMe-Example-7319 的评审时间和校验词是什么？
请根据已提供的 ReMe 记忆回答并引用来源路径。不要调用工具；
如果没有提供相关记忆，就说不知道。
ReMe-Example-7319 的评审时间和项目关键词是什么？
请根据 ReMe 记忆回答，并附上来源路径。
```
预期答复包含正确时间、校验词及 `daily/...md` 等来源路径；**ReMe status** 中应有 `recall_found`。
这样可以单独确认自动召回生效。日常使用时，也可以让 Codex 通过 `reme_search` 主动检索过去的决策。
预期答复包含每周五 16:45 UTC、`amber-lynx-7319`，以及 `daily/...md` 等来源路径。
要确认自动召回生效，再查看 **自动记忆 → 最近活动** 中的 **已召回相关记忆**（`recall_found`）。
仅答对问题、却没有这条活动记录，不能证明自动召回已开启。
> **截图槽位 — `memory-recalled.png`：** 独立会话 B 中的正确事实和 ReMe 来源路径。
@ -142,37 +130,38 @@ ReMe-Example-7319 的评审时间和校验词是什么？
![Codex 在独立会话中召回记忆](./figures/memory-recalled.png)
-->
验证后可调整批次大小，默认每五个完成轮次提交一次；不足一批时，也会在会话边界尝试提交。
失败或中断的批次保留在本地，供后续会话重试。短暂运行的 `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`。 |
<details>
<summary>超时设置</summary>
以下数值均以毫秒为单位，通常保留默认值；经常遇到请求超时时再调整。
| 字段 | 默认值 | 用途 |
| --- | --- | --- |
| Request timeout (ms) | `10000` | 检索和状态检查的等待时间，最多 `120000`。 |
| Background timeout (ms) | `3600000` | 记录和整理记忆的等待时间，最多 `3600000`。 |
| Shutdown timeout (ms) | `5000` | 退出等待设置；Codex 限制退出时的记忆提交最多等待两秒，调大此值也无法延长这段等待。 |
</details>
切换服务地址前，先等待待提交记录保存完成。尚未保存的记录仍关联原地址，需要切回原地址重试。
整理过程中修改的配置用于下一次整理。
## 排查与更新
@ -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 的机器上检查：
<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 服务或 Hook 是否正常，也不需要因此修改 `mcpUrl`、清空记忆或重装插件。
暂时可以在对话中要求“调用 `reme_status`，用文字展示返回的状态”，查看服务连接、队列和整理计划。
然后重启 Codex 并重新打开面板。暂时可以在对话中要求：“调用 `reme_status`，用文字展示返回的状态。”
诊断日志位于 `${CODEX_HOME:-~/.codex}/reme/hooks.log`，仅包含事件名、计数和错误类型，不记录对话正文。
尚未确认写入的对话数据另存于该目录。记录采用尽力交付：本地捕获前强制终止可能丢失轮次，
服务端处理成功但确认丢失时，重试也可能导致重复提取。
</details>
需要进一步排查时，查看 `~/.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。已保存的设置和待提交记忆会继续保留。