docs(codex): expand setup guide and reserve screenshot slots

2026-10-13 04:01:35 +00:00 · 2026-09-30 15:33:14 +08:00 · 2026-09-30 15:33:14 +08:00 · ac55132249
commit ac55132249
parent cd0351c8ad
7 changed files with 463 additions and 213 deletions
--- a/.github/workflows/ci-docs.yml
+++ b/.github/workflows/ci-docs.yml
@ -16,6 +16,7 @@ on:
      - 'integrations/claude_code/README_ZH.md'
      - 'integrations/codex/README.md'
      - 'integrations/codex/README_ZH.md'
+      - 'integrations/codex/figures/**'
      - 'integrations/hermes_agent/README.md'
      - 'reme_studio/README*.md'
      - 'reme_studio/figures/**'
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@ -11,6 +11,7 @@ on:
      - "integrations/claude_code/README_ZH.md"
      - "integrations/codex/README.md"
      - "integrations/codex/README_ZH.md"
+      - "integrations/codex/figures/**"
      - "integrations/hermes_agent/README.md"
      - "README.md"
      - "README_ZH.md"
--- a/github-pages/scripts/generate-content.mjs
+++ b/github-pages/scripts/generate-content.mjs
@ -54,6 +54,18 @@ const externalDocumentRewrites = {
    ['src="docs/figure/', 'src="../figure/'],
    ["(docs/zh/", "(./"],
  ],
+  "integrations/codex/README.md": [
+    ["(./README_ZH.md)", "(/zh/integrations/codex)"],
+    ["(../../docs/en/configuration.md)", "(/en/configuration)"],
+    ["(./figures/README.md)", "(https://github.com/agentscope-ai/ReMe/blob/main/integrations/codex/figures/README.md)"],
+    ["(./figures/", "(/figures/codex/"],
+  ],
+  "integrations/codex/README_ZH.md": [
+    ["(./README.md)", "(/en/integrations/codex)"],
+    ["(../../docs/zh/configuration.md)", "(/zh/configuration)"],
+    ["(./figures/README.md)", "(https://github.com/agentscope-ai/ReMe/blob/main/integrations/codex/figures/README.md)"],
+    ["(./figures/", "(/figures/codex/"],
+  ],
  "integrations/dsh/README.md": [
    ["(./README_ZH.md)", "(/zh/integrations/dsh)"],
    ["(./figures/", "(/figures/dsh/"],
@ -235,6 +247,10 @@ for (const [destination, source] of externalDocuments) {
  sourceMap[destination] = source;
 }

+await cp(path.join(repoDir, "integrations/codex/figures"), path.join(outputDir, "public/figures/codex"), {
+  recursive: true,
+  filter: (source) => !source.endsWith(".md"),
+});
 await cp(path.join(repoDir, "integrations/dsh/figures"), path.join(outputDir, "public/figures/dsh"), {
  recursive: true,
 });
--- a/github-pages/tests/generated-content.test.mjs
+++ b/github-pages/tests/generated-content.test.mjs
@ -148,6 +148,7 @@ test("tracks every generated input in documentation CI and deployment", async ()
    "integrations/claude_code/README_ZH.md",
    "integrations/codex/README.md",
    "integrations/codex/README_ZH.md",
+    "integrations/codex/figures/**",
    "integrations/hermes_agent/README.md",
    "integrations/dsh/README*.md",
    "integrations/dsh/figures/**",
--- a/integrations/codex/README.md
+++ b/integrations/codex/README.md
@ -2,167 +2,261 @@

 [中文说明](./README_ZH.md)

-Start a ReMe service, then install the ReMe plugin in Codex. This is the supported integration
-for this host. The plugin bundles automatic recall, completed-turn recording, MCP tools, and the
-`reme-memory` skill in one installation. ReMe manages durable memory and consolidation in your workspace.
+Give Codex memory across conversations: start your own ReMe service, install the ReMe plugin, and
+configure it through the native MCP settings form. The plugin recalls relevant history before a
+prompt and records completed conversations. Your ReMe workspace owns the durable memory files.

-The plugin and its marketplace are maintained in `integrations/codex/` and installed from
-this checkout. Keep the ReMe service running while using the plugin.
+## Before you start

-```text
-Start ReMe → Install the ReMe plugin → Use memory in Codex
+- **Codex:** a client supporting local plugins, command hooks, and hook trust review. The native
+  settings form also requires the `openai/settings` MCP extension. CLI 0.145.0 supports hooks and
+  tools but does not render that form.
+- **Plugin runtime:** Python 3.11+ available as `python3`, with FastMCP >= 3.4.2. Both the bundled
+  MCP server and the hooks use this environment, even if ReMe runs elsewhere.
+- **ReMe:** a running HTTP service with MCP enabled and `search`, `auto_memory`, and `health_check`
+  exposed. Configure a model for memory extraction using the [ReMe configuration guide](../../docs/en/configuration.md).
+  Default BM25 recall does not require an embedding model.
+- **Source:** a local checkout of this repository. The plugin and its marketplace live in
+  `integrations/codex/`; install from that checkout.
+
+Check the Python environment from which you launch Codex:
+
+```bash
+python3 -c "import sys, fastmcp; print(sys.version); print(fastmcp.__version__)"
 ```

-## Requirements
-
- Python 3.11+ available as `python3` in the host's environment, with FastMCP >= 3.4.2 (included with ReMe).
- Codex CLI 0.145.0 or a compatible client supporting local plugins, command hooks, and hook trust review.
- A graphical host supporting the `openai/settings` MCP extension for the native settings UI. CLI 0.145.0 supports hooks and tools but does not render this UI.
- A running ReMe HTTP service exposing `search`, `auto_memory`, and `health_check`, with MCP enabled.
- A working model configuration on the ReMe server for memory extraction. Default BM25 recall does not need embeddings.
+If the host environment does not include FastMCP, install it there with
+`python3 -m pip install "fastmcp>=3.4.2"`.

 ## 1. Start ReMe

 ```bash
 pip install "reme-ai[core]"
-reme start workspace_dir=/absolute/path/to/workspace service.backend=http
+reme start \
+  workspace_dir=/absolute/path/to/reme-workspace \
+  service.backend=http \
+  service.host=127.0.0.1 \
+  service.port=2333
 ```

-The default endpoint is `http://127.0.0.1:2333`, with MCP at `/mcp`. Keep the unauthenticated HTTP
-service on loopback or behind a protected proxy. Different workspaces isolate different memory
-scopes; sharing one workspace between hosts is intentional cross-agent recall.
+Keep this service running. Its MCP address is `http://127.0.0.1:2333/mcp`. If you choose a different
+port, set the same address in the plugin in step 3. The address must be reachable **from the machine
+running Codex**; `127.0.0.1` refers to that machine.

-## 2. Install the plugin
+The plugin does not start ReMe. Keep the unauthenticated HTTP service on loopback or behind a
+protected proxy. The service's `workspace_dir` determines which memory files it reads and writes.

-Register this repository-local marketplace, then install its plugin:
+## 2. Install the plugin and trust its hooks
+
+Register the marketplace using the absolute path to your checkout, then install the plugin:

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

-Start Codex and review and trust the four ReMe hooks (`SessionStart`, `SessionEnd`,
-`UserPromptSubmit`, and `Stop`) in `/hooks`, then open a new conversation.
-The installation loads the bundled hooks, MCP connection, and skill together. After plugin updates,
-reinstall it and review any changed hook definitions.
+> **Screenshot placeholder — `plugin-installed.png`:** Capture the actual plugin detail page with the ReMe name, enabled state, and `reme` MCP server card.

-This package uses the supported `.codex-plugin/plugin.json` and `.mcp.json` layout.
-Codex 0.159.2 and desktop runtime 0.158.0-alpha.2.1 omit this plugin's hooks when a root
-`plugin.json` selects the portable loader, even with an explicit hook declaration. Keep the
-Codex layout until native hook discovery is verified with the portable loader.
+<!--
+![ReMe installed and enabled in Codex](./figures/plugin-installed.png)
+-->

-## 3. Use memory in Codex
+Restart the desktop client, or start a new Codex CLI session. Open the host's Hook settings
+(`/hooks` in the CLI), find **ReMe / `reme@reme-codex`**, and review all four hooks:

-In a new conversation, ask “Check whether ReMe is available.” The installed plugin's tools check
-the running service; `/mcp` shows the plugin's connection status. Then use Codex normally:
-the plugin recalls relevant memory before prompts and records completed turns in batches of five.
-For an explicit query, ask “What did we decide about Project Juniper? Cite the memory sources.”
-
-Automatic recording sends completed user/assistant text to the configured ReMe service.
-Set `auto_memory` to `false` for recall-only use.
-
-## Configure through MCP settings
-
-Open the installed ReMe MCP server's settings in a host that supports `openai/settings`.
-The native form exposes the service address, automatic recall and memory switches, batch size,
-recall limits, timeouts, and timezone. Save changes, then use **Check connection** to call
-`health_check` on the saved address without sending conversation content. The settings remain
-available when ReMe is offline, so a wrong address can be corrected there.
-
-Settings are atomically saved to `${CODEX_HOME:-$HOME/.codex}/reme/config.json`, outside the plugin
-cache. The next MCP tool call and hook invocation use the new values without a reconnect or reinstall.
-An in-flight call keeps its original endpoint and settings. Disabling `auto_memory` pauses capture
-and queued retries; explicit memory tools remain available.
-
-| Option | Default | Meaning |
+| Hook | What it does | Required state |
 | --- | --- | --- |
-| `mcp_url` | `http://127.0.0.1:2333/mcp` | MCP address for both explicit tools and automatic hooks; custom paths are supported |
+| `UserPromptSubmit` | Recalls relevant memory before your prompt | Enabled and trusted |
+| `Stop` | Captures the completed turn and submits due memory batches | Enabled and trusted |
+| `SessionStart` | Retries pending batches from earlier sessions | Enabled and trusted |
+| `SessionEnd` | Attempts a short final flush | Enabled and trusted |
+
+> **Screenshot placeholder — `hooks-trusted.png`:** Show all four ReMe hooks and their enabled/trusted state in the desktop settings or CLI `/hooks`.
+
+<!--
+![The four ReMe hooks enabled and trusted in Codex](./figures/hooks-trusted.png)
+-->
+
+Installing a plugin does not automatically trust its hooks. Until reviewed, the MCP connection can
+work while automatic recall and recording remain inactive. See the [Codex hook trust guide](https://learn.chatgpt.com/docs/hooks#review-and-trust-hooks).
+
+After updating the checkout, run `codex plugin add reme@reme-codex` again and restart the host.
+Review changed hook definitions if prompted, then open a new conversation. User settings are stored
+outside the plugin cache and survive upgrades.
+
+## 3. Configure the ReMe MCP connection
+
+In the desktop client's plugin directory, open the **installed ReMe plugin**. Find its `reme` MCP
+server card and select the settings control labeled **Open MCP settings**. Open that connection's
+ReMe settings form. Labels and placement can vary by host version; this is the MCP connection's
+settings entry, separate from the plugin enable switch and Hook trust settings.
+
+For a first test:
+
+1. Set **ReMe MCP address** (`mcp_url`) to your service's full MCP URL, including `/mcp`.
+2. Enable **Automatic recall** (`auto_recall`) and **Automatic memory** (`auto_memory`).
+3. Set **Turns per memory batch** (`memory_interval`) to `1` so one completed turn triggers a write.
+4. Save the form, then select **Check connection**. In the tested desktop client, the result appears
+   in a tooltip on the button; hover over it to see the ReMe version and `healthy` status.
+
+> **Screenshot placeholder — `mcp-settings.png`:** Show the MCP URL, automatic switches, batch size, and the Check connection result tooltip in the native form.
+
+<!--
+![Native ReMe MCP settings and a successful connection check](./figures/mcp-settings.png)
+-->
+
+**A healthy connection verifies service access. It does not verify Hook loading, trust, or memory
+extraction.** Continue with the two-conversation test below. The connection check does not send
+conversation content to ReMe.
+
+If you cannot find the form, confirm that you opened the installed plugin's MCP connection and that
+its process started successfully. A client without `openai/settings` support has no native form;
+see [Configuration reference](#configuration-reference) for the user-owned settings file.
+
+## 4. Verify recording and recall in separate conversations
+
+Keep both automatic switches enabled and use `memory_interval=1`. Choose a unique test project
+name so an older test cannot satisfy the recall check.
+
+**Conversation A — record a fact:**
+
+```text
+Remember this confirmed decision for ReMe-Hook-Local-6502:
+release reviews happen Friday at 16:45 UTC;
+the verification phrase is amber-lynx-6502.
+Do not use tools or skills or write files yourself; just acknowledge the facts.
+```
+
+Wait for the final reply and the Stop hook to finish. Check the local plugin log:
+
+```bash
+tail -n 10 "${CODEX_HOME:-$HOME/.codex}/reme/hooks.log"
+```
+
+A `memory_saved` event means ReMe acknowledged the batch. Also inspect the ReMe workspace's `daily/`
+notes. A successful batch leaves `.done` receipts under the plugin's `reme/queue/` directory;
+pending `.json` files remain until acknowledged. Do not delete pending files to clear an error.
+
+> **Screenshot placeholder — `memory-recorded.png`:** Capture conversation A with its fact and final reply. This shows the conversation; verify delivery separately with `memory_saved` and a receipt as described above.
+
+<!--
+![The test fact and final acknowledgement in Codex conversation A](./figures/memory-recorded.png)
+-->
+
+**Conversation B — start a new conversation, then recall:**
+
+```text
+For ReMe-Hook-Local-6502, what is the review time and verification phrase?
+Cite only supplied memory, including its source path.
+Do not use tools or skills; if no memory is supplied, say you do not know.
+```
+
+The expected result includes **Friday at 16:45 UTC**, **amber-lynx-6502**, and a source path from
+ReMe. Use a new conversation so the answer cannot come from the first conversation's context.
+
+> **Screenshot placeholder — `memory-recalled.png`:** Capture conversation B with its question, recalled review time, verification phrase, and ReMe source path.
+
+<!--
+![Codex automatically recalls the test fact in a new conversation with a ReMe source](./figures/memory-recalled.png)
+-->
+
+After testing, keep `memory_interval=1` for per-turn writes or restore the default `5` to batch turns.
+For explicit retrieval, ask “What did we decide about this project? Cite ReMe sources.” The bundled
+`reme-memory` skill and MCP tools remain available alongside automatic hooks.
+
+## Configuration reference
+
+Change settings in the MCP form. The next hook or MCP tool call uses saved changes without a
+reconnect; an in-flight call keeps its original settings. The form remains available when the
+upstream ReMe service is offline, so you can correct its address.
+
+| Setting | Default | Effect |
+| --- | --- | --- |
+| `mcp_url` | `http://127.0.0.1:2333/mcp` | Shared MCP URL for explicit tools and hooks; custom paths supported |
 | `auto_recall` | `true` | Search before a user prompt |
-| `auto_memory` | `true` | Queue and submit completed turns; false also disables retries |
-| `recall_limit` | `5` | Search result limit |
+| `auto_memory` | `true` | Capture and submit completed turns; false also pauses queued retries |
+| `memory_interval` | `5` | Completed turns per batch; `1` submits each turn |
+| `recall_limit` | `5` | Maximum search results |
 | `recall_min_score` | `0` | Minimum recall score |
-| `recall_timeout` | `5` | Foreground MCP timeout in seconds, at most 10 |
-| `request_timeout` | `600` | Memory-write and MCP request timeout in seconds, at most 600 |
-| `memory_interval` | `5` | Completed turns per batch; use 1 for immediate per-turn writes |
-| `shutdown_timeout` | `2` | Total best-effort exit drain budget in seconds, at most 2 |
 | `context_max_chars` | `8000` | Maximum recalled payload characters |
+| `recall_timeout` | `5` | Recall timeout in seconds; greater than 0, at most 10 |
+| `request_timeout` | `600` | Memory/tool timeout in seconds; greater than 0, at most 600 |
+| `shutdown_timeout` | `2` | Exit flush budget in seconds; greater than 0, at most 2 |
 | `timezone` | `Asia/Shanghai` | Daily batch timezone; match the ReMe workspace |

-The JSON file remains user-owned and can also be edited directly; only overrides are required.
-See [config.example.json](plugins/reme/config.example.json) for a complete example. Remove a field
-from the file to restore its default. Unknown fields and invalid values fail validation; hooks skip
-work and log `hook_failed` instead of falling back to another service. UI updates reject invalid
-values without replacing the saved file.
+For recall-only use, turn off `auto_memory` and leave `auto_recall` on. To pause both automatic
+behaviors, turn off both switches. Explicit MCP tools remain available.

-Existing configurations keep working. The deprecated `api_url` field is accepted on read but is
-no longer used and is removed on the next UI save. All operations use `mcp_url`. Standard `/mcp`
-endpoints retain existing queue and receipt identities. Pending queues from a custom legacy
-`api_url` remain untouched: they are not automatically retargeted. Address changes never forward
-old pending conversations to the new service; switch back to the original endpoint to retry its queue.
+Settings are saved atomically to `${CODEX_HOME:-$HOME/.codex}/reme/config.json`. You can also edit
+this user-owned file directly; only overrides are needed. See [config.example.json](plugins/reme/config.example.json).
+Remove a field to restore its default. Invalid values and unknown keys are rejected; failed UI
+saves leave the previous file intact. Do not edit the installed plugin cache to configure ReMe.

-Both the host-managed MCP server and short-lived hooks require FastMCP in the host's `python3`
-environment. If ReMe runs elsewhere, install it with `python3 -m pip install "fastmcp>=3.4.2"`.
-The plugin does not launch ReMe. Its native form follows the pinned
-[OpenAI MCP Extensions settings contract](https://github.com/openai/mcp-extensions/blob/node-v0.1.0/docs/spec.md#structured-settings).
-Clients without that extension can still use tools and hooks, but have no native settings form.
+Changing `mcp_url` never forwards old queued conversations to the new service. Switch back to the
+original address to retry its queue. The legacy `api_url` key is accepted on read, no longer used,
+and removed on the next UI save. Existing standard `/mcp` queue identities are preserved; custom
+legacy HTTP queues remain untouched.

-## Lifecycle and failure behavior
+## Troubleshooting

- `UserPromptSubmit` calls `search` synchronously with a short timeout. Results are bounded and
-  wrapped in `<reme-context>` as untrusted historical evidence. A failure does not reject the prompt.
- Synchronous `Stop` hooks extract only the completed user/final-assistant text from the
-  hook's local transcript, then submit `auto_memory` batches through MCP. Tool output,
-  reasoning, and injected ReMe context are excluded. The server does not need access to host files.
- Session and message IDs are stable and host-scoped. Repeated Stops are deduplicated. Per-session
-  process locks serialize writes; batches never mix dates. Subagent events and hook continuations
-  are excluded. No extra background daemon, package download, or ReMe process is started.
- Queues and acknowledgement receipts live under the host's `reme/queue/`, separate from the
-  plugin cache and namespaced by endpoint. A failed or timed-out write stays queued. `SessionStart`
-  retries pending work synchronously; `SessionEnd` attempts a short drain.
- Codex 0.145.0 skips hooks marked `async`, so this adapter deliberately uses synchronous hooks.
-  A due memory batch or a startup retry can delay completion by up to `request_timeout`.
-  Claude Code uses its own native asynchronous adapter.
- Shutdown and delivery are best-effort. A host killed before the Stop hook captures a turn can
-  lose that turn. A lost MCP acknowledgement can cause a retry; stable message IDs prevent duplicate
-  source messages, but memory extraction is **at least once**, not exactly once. Short residual
-  batches survive for the next session when shutdown has insufficient time.
- Queue files contain source conversation text; retain them until delivery completes. Logs in
-  `reme/hooks.log` contain event/error types only. Disabling `auto_memory` retains pending files.
- Daily `auto_dream` consolidation remains owned by the ReMe service. Unlike OpenClaw's long-lived
-  Gateway adapter, these short-lived hook processes do not run their own scheduler.
+Work through **connection → Hook state → recording → fresh-conversation recall** in that order.

-## Verify and troubleshoot
+| Symptom | Check or action |
+| --- | --- |
+| Cannot find ReMe settings | Open the installed plugin's `reme` MCP card → **Open MCP settings**. Confirm the host supports the native form and the MCP process starts. |
+| Check connection shows a spinner but no chat reply | Hover over the button for the result tooltip. `healthy` and the ReMe version indicate a successful service check. |
+| Connection is healthy, but nothing is recorded or recalled | Check that all four ReMe hooks are listed, enabled, and trusted. Installation and MCP health do not grant hook trust. |
+| ReMe is absent from the Hook list | Update the checkout, reinstall the plugin, and restart the host. See the compatibility notes below. |
+| Hook is listed but awaiting review | Review and trust its current definition, then start a new conversation. |
+| `hook_failed` or MCP startup failure | Check the host's Python 3.11+/FastMCP environment, saved configuration, service reachability, and ReMe server logs. |
+| No note after one turn | Set `memory_interval=1`, enable `auto_memory`, and wait for the final reply and Stop hook. ReMe also needs a working extraction model. |
+| `capture_skipped` | Update to the current plugin. The hook needs a supported local transcript and final assistant message; current and legacy Codex event formats are supported. |
+| `retry_failed` or pending queue files | Restore the original service/model connection and open a new session to retry. Keep the pending files. |
+| Notes exist but recall misses them | Use a new conversation, enable `auto_recall`, check the service address/workspace, allow indexing to finish, and inspect recall limits and score filters. Try an explicit ReMe search to isolate retrieval from the hook. |

-1. Check that `/hooks` lists all four ReMe hooks and that each is enabled and trusted. Then use
-   **Check connection** in the MCP settings. A healthy result verifies the service connection;
-   it does not verify hook loading or execution.
-2. For a quick test, set `memory_interval` to `1`, then start a new conversation and ask the agent to
-   remember a synthetic fact, such as “Project Juniper reviews are on Thursday.”
-3. Wait for the write and inspect `reme/hooks.log` for `memory_saved` and the ReMe workspace's `daily/`.
-4. Start a separate conversation and ask for that fact. Confirm recall is from ReMe, with source paths.
+The log records status and exception types, not conversation text. Successful recall and idle
+hooks do not necessarily create log entries; the absence of `hooks.log` alone does not prove
+that no hook ran. Queue files do contain the source conversation text.

-The installed plugin provides both automatic memory and explicit search/read and health checks.
-If its tools are missing, check that the plugin is installed and enabled, the service is running,
-and `service.jobs` exposes the required jobs. If ReMe is missing from `/hooks`, reinstall the current
-plugin and restart the host. If listed but awaiting review, trust its current definitions.
-If trusted hooks fail, check that the hook environment's `python3` is Python 3.11+ with FastMCP installed.
+## Memory behavior and compatibility

-Capture reads Codex rollout JSONL `event_msg` records: legacy `user_message` / final `agent_message`,
-and newer `item_completed` events containing `UserMessage` / final `AgentMessage` text blocks.
-`response_item` records are excluded, including injected context and duplicate messages. The hook requires
-`transcript_path` and `last_assistant_message`. Missing or unsupported transcripts are skipped rather
-than guessed. Codex transcript formats are not a stable public interface. Check `capture_skipped` or
-`hook_failed` events when recall works but recording does not.
+- Recalled text is bounded and wrapped in `<reme-context>` as untrusted historical evidence.
+  Only completed user/final-assistant text is recorded; tools, reasoning, subagents, commentary,
+  and injected memory are excluded. ReMe does not need access to Codex transcript files.
+- Stable session/message IDs, per-session locks, and receipts prevent repeated Stops from
+  duplicating delivered source messages. Failed writes remain queued by service and session.
+- Hooks are synchronous for compatibility with Codex 0.145.0, which skips asynchronous hooks.
+  A due batch or startup retry can delay completion up to `request_timeout`. Session exit has a
+  short, best-effort drain budget; remaining batches survive for the next session.
+- Delivery is best-effort and extraction is at least once. Killing the host before capture can
+  lose a turn; a lost acknowledgement can cause extraction to be retried.
+- Durable memory and daily consolidation belong to the ReMe service. The plugin starts no
+  separate daemon or scheduler.

-In Codex 0.145.0, an unattended `codex exec` MCP call can return `user cancelled MCP tool call`
-when approval cannot be collected. Verify explicit tools in an interactive session and approve the
-specific call. Trusted automatic hooks act as MCP clients themselves; they do not request per-call model tool approval.
+This package uses `.codex-plugin/plugin.json` and `.mcp.json`. In native checks, Codex 0.159.2 and
+desktop runtime 0.158.0-alpha.2.1 omitted these hooks when a root portable `plugin.json` was present,
+even with explicit hook declarations. Retain the current Codex package layout. The parser supports
+both legacy `user_message` / final `agent_message` and newer `item_completed` conversation events;
+`response_item` records are excluded. See the [hook adapter](plugins/reme/hooks/auto_memory.py).

-## Source and validation
+CLI 0.145.0 may return `user cancelled MCP tool call` for an explicit tool call when an unattended
+session cannot collect approval. Verify such calls interactively. Automatic hooks use the trust
+review described above.

-Run `pytest tests/unit/test_coding_agent_plugins.py tests/unit/test_codex_plugin_mcp.py -v` from the ReMe checkout. Tests isolate host
-state and mock service calls. With a runtime supporting `hooks/list`, run
-`REME_CODEX_BIN=/path/to/codex pytest tests/integration/test_codex_plugin_install.py -v`
-to install into an isolated profile and verify hook discovery before trust, without model calls or hook execution.
-Native hook behavior is described in the [Codex hook reference](https://learn.chatgpt.com/docs/hooks).
+## Maintainer checks
+
+See the [screenshot checklist](./figures/README.md) for the five genuine screenshot slots and replacement steps.
+Both languages share the same PNG files; text placeholders remain visible until screenshots are added.
+
+```bash
+pytest tests/unit/test_coding_agent_plugins.py tests/unit/test_codex_plugin_mcp.py -v
+REME_CODEX_BIN=/path/to/codex pytest tests/integration/test_codex_plugin_install.py -v
+```
+
+The native installation test requires `hooks/list`, uses an isolated profile, and verifies all
+four hooks before trust without model calls or hook execution. For documentation changes, run
+`npm test` and `npm run build` in `github-pages/`.
+
+References: [Codex hooks](https://learn.chatgpt.com/docs/hooks),
+[OpenAI MCP settings contract](https://github.com/openai/mcp-extensions/blob/node-v0.1.0/docs/spec.md#structured-settings).
 ReMe is developed at [agentscope-ai/ReMe](https://github.com/agentscope-ai/ReMe) under Apache-2.0.
--- a/integrations/codex/README_ZH.md
+++ b/integrations/codex/README_ZH.md
@ -2,138 +2,242 @@

 [English](./README.md)

-先启动 ReMe 服务，再在 Codex 中安装 ReMe 插件，即可使用长期记忆。这是本宿主支持的集成方式。
-插件统一安装自动召回、完成轮次记录、MCP 工具和内置 `reme-memory` Skill；ReMe 服务负责工作区中的记忆存储与整理。
+先启动自己的 ReMe 服务，再安装 ReMe 插件，通过原生 MCP 设置界面配置，即可让 Codex 跨会话使用记忆。
+插件在提交消息前召回相关历史，在完成对话后自动记录。持久记忆保存在你掌控的 ReMe 工作区文件中。

-插件与本地 marketplace 维护在 `integrations/codex/`，从仓库安装。
-使用插件期间，保持 ReMe 服务运行。
+## 开始前准备

-```text
-启动 ReMe 服务 → 安装 ReMe 插件 → 在 Codex 中使用记忆
+- **Codex：**宿主需支持本地插件、命令 Hook 和 Hook 信任审核。原生配置表单还需支持
+  `openai/settings` MCP 扩展。CLI 0.145.0 支持 Hook 和工具，但不渲染该表单。
+- **插件运行环境：**宿主的 `python3` 为 Python 3.11+，已安装 FastMCP >= 3.4.2。
+  插件内的 MCP Server 和 Hook 都使用此环境，即使 ReMe 服务运行在其他环境或机器上。
+- **ReMe：**HTTP 服务已启动并启用 MCP，开放 `search`、`auto_memory` 和 `health_check`。
+  按 [ReMe 配置指南](../../docs/zh/configuration.md) 配置记忆提取模型。默认 BM25 召回不需要 Embedding 模型。
+- **源码：**本地有 ReMe 仓库副本。插件及 marketplace 位于 `integrations/codex/`，从该目录安装。
+
+在启动 Codex 的 Python 环境中检查依赖：
+
+```bash
+python3 -c "import sys, fastmcp; print(sys.version); print(fastmcp.__version__)"
 ```

-## 环境要求
-
- 宿主环境中有 Python 3.11+，可通过 `python3` 执行，并已安装 FastMCP >= 3.4.2（ReMe 自带此依赖）。
- Codex CLI 0.145.0 或兼容版本，支持插件、`UserPromptSubmit`、`Stop`、同步命令 Hook 和 `last_assistant_message`。
- 原生配置界面需要支持 `openai/settings` MCP 扩展的图形宿主；CLI 0.145.0 支持 Hook 和工具，但不渲染该界面。
- 已启动 ReMe HTTP 服务，开放 `search`、`auto_memory`、`health_check`，并启用 MCP。
- ReMe 服务端有可用于自动记忆提取的模型配置。默认 BM25 召回不要求 Embedding。
+如果宿主环境缺少 FastMCP，在该环境执行 `python3 -m pip install "fastmcp>=3.4.2"`。

 ## 1. 启动 ReMe 服务

 ```bash
 pip install "reme-ai[core]"
-reme start workspace_dir=/absolute/path/to/workspace service.backend=http
+reme start \
+  workspace_dir=/absolute/path/to/reme-workspace \
+  service.backend=http \
+  service.host=127.0.0.1 \
+  service.port=2333
 ```

-默认地址为 `http://127.0.0.1:2333`，MCP 路径为 `/mcp`。HTTP 服务没有内建 API Key 鉴权，
-应保持 loopback 监听或部署受保护的代理。不同 workspace 隔离记忆；不同宿主使用同一 workspace 时会共享召回。
+保持服务运行，MCP 地址为 `http://127.0.0.1:2333/mcp`。如果使用其他端口，在第 3 步填写对应地址。
+地址必须能**从运行 Codex 的机器访问**；`127.0.0.1` 指向的是这台机器。

-## 2. 安装 ReMe 插件
+插件不会启动 ReMe。HTTP 服务没有内建鉴权，请保持 loopback 监听或置于受保护的代理之后。
+服务的 `workspace_dir` 决定读写哪一份记忆文件。

-添加仓库内的本地 marketplace，再安装插件：
+## 2. 安装插件并信任 Hook
+
+使用仓库的绝对路径添加 marketplace，再安装插件：

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

-启动 Codex，在 `/hooks` 中检查并信任 ReMe 的四个 Hook（`SessionStart`、`SessionEnd`、
-`UserPromptSubmit`、`Stop`），然后新建会话。
-插件安装会一并加载 Hook、MCP 连接和内置 Skill。更新后重新安装插件，并审核有变化的 Hook。
+> **截图待补 — `plugin-installed.png`:** 截取真实 Codex 插件详情，保留 ReMe 名称、启用状态和 `reme` MCP Server 卡片。

-本插件使用受支持的 `.codex-plugin/plugin.json` 与 `.mcp.json` 布局。
-在 Codex 0.159.2 和桌面运行时 0.158.0-alpha.2.1 中，根目录 `plugin.json` 会选择 portable
-加载器，导致本插件的 Hook 被遗漏，显式声明 Hook 路径也不能解决。确认 portable 加载器能通过
-原生 Hook 发现验证前，保留 Codex 布局。
+<!--
+![Codex 中已安装并启用的 ReMe 插件](./figures/plugin-installed.png)
+-->

-## 3. 在 Codex 中使用记忆
+重启桌面客户端，或启动新的 Codex CLI 会话。打开宿主的 Hook 设置（CLI 中使用 `/hooks`），
+找到 **ReMe / `reme@reme-codex`**，审核以下四个 Hook：

-在新会话中询问“检查 ReMe 是否可用”，由已安装插件的工具检查服务连接；也可通过 `/mcp` 查看插件连接状态。
-之后正常使用 Codex：插件在消息提交前自动召回相关记忆，每完成五轮对话分批记录一次。
-需要主动查询时，可以询问“之前关于 Juniper 项目做了什么决定？请附上记忆来源”。
+| Hook | 作用 | 所需状态 |
+| --- | --- | --- |
+| `UserPromptSubmit` | 在提交消息前召回相关记忆 | 已启用、已信任 |
+| `Stop` | 捕获已完成的对话轮次，提交达到条件的记忆批次 | 已启用、已信任 |
+| `SessionStart` | 重试之前会话中尚未提交的批次 | 已启用、已信任 |
+| `SessionEnd` | 在短时间预算内尝试最后一次刷新 | 已启用、已信任 |

-自动记录会把完成的用户/助手文本发送到配置的 ReMe 服务；仅需召回时，将 `auto_memory` 设为 `false`。
+> **截图待补 — `hooks-trusted.png`:** 截取四个 ReMe Hook 及其已启用、已信任状态；桌面设置页或 CLI `/hooks` 均可。

-## 通过 MCP 设置界面配置
+<!--
+![Codex 中已启用并信任的四个 ReMe Hook](./figures/hooks-trusted.png)
+-->

-在支持 `openai/settings` 的宿主中，打开已安装的 ReMe MCP Server 设置。
-原生表单提供服务地址、自动召回与记录开关、批次大小、召回限制、超时和时区。
-保存后点击 **Check connection**，会在已保存地址调用 `health_check`，不发送对话内容。
-ReMe 服务离线时仍可读取和修改设置，因此可以在此修正错误地址。
+安装插件不会自动授予 Hook 信任。未完成审核时，MCP 连接可能正常，但自动召回和记录不会执行。
+宿主规则见 [Codex Hook 信任说明](https://learn.chatgpt.com/docs/hooks#review-and-trust-hooks)。

-配置原子保存到 `${CODEX_HOME:-$HOME/.codex}/reme/config.json`，位于插件缓存之外，升级后保留。
-下一次 MCP 工具调用和 Hook 调用直接使用新配置，无需重新连接或重装。
-正在执行的调用继续使用原来的地址与配置。关闭 `auto_memory` 会暂停自动捕获与队列重试，显式工具仍可使用。
+更新仓库后，再执行一次 `codex plugin add reme@reme-codex`，重启宿主；如提示 Hook 定义有变化，
+重新审核后新建会话。用户配置保存在插件缓存之外，升级会保留。
+
+## 3. 配置 ReMe MCP 连接
+
+在桌面客户端的插件目录中打开**已安装的 ReMe 插件**，找到 `reme` MCP Server 卡片，
+点击标为 **Open MCP settings** 的设置入口，再打开该连接的 ReMe 配置表单。
+不同宿主版本的文字和位置可能不同；这里调整的是 MCP 连接的配置，插件启用开关和 Hook 信任位于各自的设置入口。
+
+首次验证时：
+
+1. 将 **ReMe MCP address**（`mcp_url`）设为完整的 ReMe MCP 地址，包括 `/mcp`。
+2. 开启 **Automatic recall**（`auto_recall`）和 **Automatic memory**（`auto_memory`）。
+3. 将 **Turns per memory batch**（`memory_interval`）设为 `1`，使一轮完成的对话即可触发写入。
+4. 保存后点击 **Check connection**。已验证的桌面客户端通过按钮上的提示浮层显示结果；
+   将鼠标停在按钮上，可看到 ReMe 版本和 `healthy` 状态。
+
+> **截图待补 — `mcp-settings.png`:** 截取原生设置表单，保留 MCP 地址、两个自动开关、批次大小和 Check connection 的健康结果浮层。
+
+<!--
+![ReMe 原生 MCP 设置与连接健康结果](./figures/mcp-settings.png)
+-->
+
+**连接健康仅代表服务可达，不代表 Hook 已加载、已信任或记忆提取成功。**
+继续执行下方的双会话验证。连接检查不会向 ReMe 发送对话内容。
+
+找不到表单时，先确认进入的是已安装插件的 MCP 连接，并确认 MCP 进程启动成功。
+不支持 `openai/settings` 的客户端没有原生表单；用户配置文件的位置见[配置项参考](#配置项参考)。
+
+## 4. 在两个独立会话中验证记录与召回
+
+保持两个自动开关开启，并设 `memory_interval=1`。每次验证使用一个新的测试项目名，
+避免旧测试的记忆让本次召回看似成功。
+
+**会话 A：记录一条事实。**
+
+```text
+请记住 ReMe-Hook-Local-6502 的已确认决定：
+发布评审在每周五 16:45 UTC，校验短语为 amber-lynx-6502。
+不要调用工具、使用 Skill 或自行写入文件，只需确认这些事实。
+```
+
+等待最终回复和 Stop Hook 执行完成，查看本机插件日志：
+
+```bash
+tail -n 10 "${CODEX_HOME:-$HOME/.codex}/reme/hooks.log"
+```
+
+`memory_saved` 表示 ReMe 已确认收到该批次，同时检查 ReMe 工作区 `daily/` 下的笔记。
+成功提交后，插件的 `reme/queue/` 目录会留下 `.done` 收据；未确认的批次仍为 `.json` 文件。
+不要通过删除待提交文件来消除错误。
+
+> **截图待补 — `memory-recorded.png`:** 截取会话 A 的测试事实及最终回复。此图展示对话；是否交付成功仍需以上述 `memory_saved` 和收据为准。
+
+<!--
+![Codex 测试会话 A 中的事实输入及最终确认](./figures/memory-recorded.png)
+-->
+
+**会话 B：新建独立会话后召回。**
+
+```text
+ReMe-Hook-Local-6502 的评审时间和校验短语是什么？
+只引用已提供的记忆，并附来源文件路径。
+不要调用工具或使用 Skill；没有提供记忆就说不知道。
+```
+
+预期回答包含**每周五 16:45 UTC**、**amber-lynx-6502** 和 ReMe 来源路径。
+必须使用新会话，避免直接从会话 A 的上下文得到答案。
+
+> **截图待补 — `memory-recalled.png`:** 截取独立会话 B 的提问和回答，保留评审时间、校验短语及 ReMe 来源路径。
+
+<!--
+![Codex 在新会话中自动召回测试事实并引用 ReMe 文件](./figures/memory-recalled.png)
+-->
+
+验证后，可保留 `memory_interval=1` 逐轮提交，或恢复默认值 `5` 批量提交。
+需要主动查询时，可询问“之前关于这个项目做了什么决定？请附上 ReMe 来源”。
+内置 `reme-memory` Skill 和 MCP 工具也可用于显式检索。
+
+## 配置项参考
+
+在 MCP 表单中修改并保存。下一次 Hook 或 MCP 工具调用即使用新配置，无需重新连接；
+正在执行的调用沿用原配置。上游 ReMe 服务离线时，表单仍可用，可以修正连接地址。

 | 配置项 | 默认值 | 作用 |
 | --- | --- | --- |
-| `mcp_url` | `http://127.0.0.1:2333/mcp` | 显式工具和自动 Hook 共用的 MCP 地址，支持自定义路径 |
-| `auto_recall` | `true` | 用户提交消息时自动检索 |
-| `auto_memory` | `true` | 自动捕获与提交；关闭后也不重试已有队列 |
+| `mcp_url` | `http://127.0.0.1:2333/mcp` | 显式工具和 Hook 共用的 MCP 地址，支持自定义路径 |
+| `auto_recall` | `true` | 用户提交消息前自动检索 |
+| `auto_memory` | `true` | 自动捕获和提交已完成轮次；关闭后也暂停队列重试 |
+| `memory_interval` | `5` | 每批完成的对话轮数；设为 `1` 则逐轮提交 |
 | `recall_limit` | `5` | 检索结果上限 |
 | `recall_min_score` | `0` | 自动召回最低分数 |
-| `recall_timeout` | `5` | 前台 MCP 超时秒数，最大 10 |
-| `request_timeout` | `600` | 写入与 MCP 请求超时秒数，最大 600 |
-| `memory_interval` | `5` | 每批完成的对话轮数；设为 1 则逐轮提交 |
-| `shutdown_timeout` | `2` | 退出时尽力刷新队列的总秒数，最大 2 |
 | `context_max_chars` | `8000` | 召回正文字符上限 |
-| `timezone` | `Asia/Shanghai` | 批次按此时区分日，应与 ReMe workspace 一致 |
+| `recall_timeout` | `5` | 召回超时秒数，大于 0、最大 10 |
+| `request_timeout` | `600` | 记忆写入和工具调用超时秒数，大于 0、最大 600 |
+| `shutdown_timeout` | `2` | 退出刷新预算秒数，大于 0、最大 2 |
+| `timezone` | `Asia/Shanghai` | 批次按此时区分日，应与 ReMe 工作区一致 |

-JSON 配置仍由用户掌控，也可直接编辑，只需写入要覆盖的选项。
-完整示例见 [config.example.json](plugins/reme/config.example.json)；从文件移除某项即可恢复其默认值。
-未知字段和无效值会使校验失败，Hook 跳过并记录 `hook_failed`，不会回退到其他服务。
-界面保存无效值时会返回错误，保留原配置文件。
+只需召回时，关闭 `auto_memory` 并保持 `auto_recall` 开启。暂停所有自动行为时，关闭两个开关。
+显式 MCP 工具仍然可用。

-已有配置仍可读取。旧 `api_url` 字段不再参与请求，下次在界面保存时会移除；所有操作统一使用 `mcp_url`。
-标准 `/mcp` 地址继续使用原来的队列和收据标识。自定义旧 `api_url` 下的待提交记录原样保留，
-不会自动迁移目标地址。切换地址不会把旧对话发往新服务；切回原地址可继续重试该地址的队列。
+配置原子保存到 `${CODEX_HOME:-$HOME/.codex}/reme/config.json`。该文件由用户掌控，也可直接编辑，
+只需保存要覆盖的选项，完整示例见 [config.example.json](plugins/reme/config.example.json)。
+移除配置项即可恢复默认值。无效值和未知字段会被拒绝，界面保存失败时保留原文件。
+请通过此配置调整插件，不要修改安装缓存。

-宿主管理的 MCP Server 和短生命周期 Hook 都依赖宿主 `python3` 环境中的 FastMCP。
-如果 ReMe 运行在其他环境，请执行 `python3 -m pip install "fastmcp>=3.4.2"`。插件不会启动 ReMe 服务。
-原生表单遵循固定版本的
-[OpenAI MCP Extensions 设置协议](https://github.com/openai/mcp-extensions/blob/node-v0.1.0/docs/spec.md#structured-settings)。
-不支持该扩展的宿主仍可使用工具和 Hook，但不会显示原生设置表单。
+修改 `mcp_url` 不会把旧队列中的对话发往新服务；切回原地址后可以继续重试。
+旧 `api_url` 字段仍可读取，但不再使用，下次界面保存时会移除。标准 `/mcp` 的队列标识保持兼容，
+自定义旧 HTTP 地址下的队列原样保留。

-## 生命周期与失败行为
+## 常见问题

- `UserPromptSubmit` 在短超时范围内同步调用 `search`，用 `<reme-context>` 包裹有长度限制的结果，明确其为不可信历史数据。失败不阻止用户消息。
- 同步 `Stop` Hook 从本地 transcript 提取完成轮次的用户与最终助手文本，通过 MCP 分批调用 `auto_memory`。工具输出、推理内容和注入的 ReMe 上下文不作为对话来源。服务端无需读取宿主文件。
- 使用带宿主命名空间的稳定会话和消息 ID，重复 Stop 去重；每个会话串行提交，跨日拆分批次。排除子 Agent 事件和 Hook 续写。插件不启动独立守护进程，也不自动下载依赖或启动 ReMe。
- 队列与确认收据保存在宿主的 `reme/queue/`，按服务地址隔离；失败或超时不会丢弃队列。`SessionStart` 同步重试，`SessionEnd` 在短时间预算内同步尝试刷新。
- 退出刷新是尽力而为：宿主在捕获前被强制结束时可能丢失该轮。MCP 确认丢失时可能重复提取；稳定消息 ID 避免重复存储来源，但记忆提取是至少一次语义。未满批次或未及时完成的任务留待下次会话处理。
- 队列包含原始对话文本，请在交付完成前保留。`reme/hooks.log` 仅记录事件及异常类型。关闭 `auto_memory` 保留队列且停止重试。
- `auto_dream` 整理继续由 ReMe 服务管理。与 OpenClaw 常驻 Gateway 不同，短生命周期 Hook 不另建定时调度器。
+按**服务连接 → Hook 状态 → 记录 → 新会话召回**的顺序排查。

-Codex 0.145.0 会跳过设置了 `async` 的 hook，因此本适配器使用同步 hook。达到批次阈值时的写入和启动时的重试，最多会等待 `request_timeout` 秒；Claude Code 则使用其独立的原生异步适配器。
+| 现象 | 检查或处理 |
+| --- | --- |
+| 找不到 ReMe 设置 | 打开已安装插件的 `reme` MCP 卡片 → **Open MCP settings**，确认宿主支持原生表单且 MCP 进程启动成功。 |
+| Check connection 转圈后没有聊天回复 | 将鼠标停在按钮上查看提示浮层；ReMe 版本与 `healthy` 表示服务检查成功。 |
+| 连接 healthy，但记录和召回都没发生 | 检查四个 ReMe Hook 是否均已加载、启用且信任。安装插件和连接健康不会自动授予 Hook 信任。 |
+| Hook 列表中没有 ReMe | 更新仓库，重新安装插件并重启宿主；兼容性说明见下文。 |
+| Hook 已列出但等待审核 | 审核并信任当前定义，再新建会话。 |
+| `hook_failed` 或 MCP 启动失败 | 检查宿主的 Python 3.11+/FastMCP 环境、保存的配置、服务连通性和 ReMe 服务端日志。 |
+| 对话一轮后没有笔记 | 设 `memory_interval=1`，开启 `auto_memory`，等待最终回复及 Stop Hook。ReMe 还需要可用的记忆提取模型。 |
+| `capture_skipped` | 升级到当前插件。记录需要本地 transcript 和最终助手消息；当前支持新旧 Codex 对话事件格式。 |
+| `retry_failed` 或存在待提交队列 | 恢复原服务及模型连接，新建会话触发重试，保留待提交文件。 |
+| 已有笔记，但新会话没有召回 | 开启 `auto_recall`，核对地址和工作区，等待索引更新，检查召回数量及分数过滤。可显式调用 ReMe 搜索，区分检索问题和 Hook 问题。 |

-## 验证与排查
+日志只记录状态和异常类型，不记录对话内容。成功召回或空闲 Hook 不一定写日志；
+仅凭 `hooks.log` 不存在，不能判断 Hook 从未执行。队列文件则包含来源对话文本。

-1. 在 `/hooks` 中确认 ReMe 的四个 Hook 均已加载、启用且信任，再在 MCP 设置中点击
-   **Check connection**。健康结果只验证服务连接，不代表 Hook 已加载或执行。
-2. 快速验证时把 `memory_interval` 设为 `1`，新建会话，要求记住一条合成事实，例如“Juniper 项目每周四评审”。
-3. 等待写入，检查 `reme/hooks.log` 的 `memory_saved`，以及 ReMe workspace 的 `daily/` 笔记。
-4. 再新建一个独立会话，询问该事实，并确认回答附有 ReMe 来源路径。
+## 记忆行为与兼容性

-自动记忆和显式检索、阅读、健康检查均由已安装的插件提供。工具缺失时，检查插件是否已安装并启用、
-ReMe 服务是否运行，以及 `service.jobs` 是否开放所需 Job。`/hooks` 中没有 ReMe 时，重新安装当前插件并
-重启宿主；已列出但待审核时，信任当前 Hook 定义。已信任的 Hook 执行失败时，检查 Hook 环境中的
-`python3` 是否为 Python 3.11+，并已安装 FastMCP。
+- 召回内容有长度上限，以 `<reme-context>` 包裹并标为不可信历史证据。
+  只记录完成轮次的用户与最终助手文本；排除工具输出、推理、子 Agent、中间回复和注入的记忆。
+  ReMe 不需要访问 Codex 的 transcript 文件。
+- 稳定的会话／消息 ID、会话锁和收据避免重复 Stop 再次交付同一条来源消息。
+  写入失败时，队列按服务地址及会话保留。
+- 为兼容会跳过异步 Hook 的 Codex 0.145.0，插件采用同步 Hook。
+  达到批次条件或启动重试时，可能等待至 `request_timeout`。退出时仅尽力刷新，剩余批次留待下一会话。
+- 交付是尽力而为，记忆提取采用至少一次语义。宿主在捕获前被强制结束可能丢失该轮；
+  确认响应丢失可能导致再次提取。
+- 持久记忆和每日整理由 ReMe 服务管理，插件不启动额外守护进程或调度器。

-记录要求 Hook 提供 `transcript_path` 和 `last_assistant_message`，读取 rollout 的 `event_msg`：
-旧版 `user_message` / 最终 `agent_message`，以及新版 `item_completed` 中的
-`UserMessage` / 最终 `AgentMessage` 文本块。排除 `response_item` 中的注入上下文和重复消息，不读取私有推理。
-Codex transcript 不是稳定公开接口；未知格式或缺失文件会跳过并记录状态，不猜测对话。
-召回正常但未记录时，检查 `capture_skipped`、`hook_failed`。
+插件采用 `.codex-plugin/plugin.json` 与 `.mcp.json` 布局。原生验证发现，Codex 0.159.2 和
+桌面运行时 0.158.0-alpha.2.1 在存在根目录 portable `plugin.json` 时会遗漏本插件的 Hook，
+显式声明也无效，因此保留当前 Codex 布局。解析器同时支持旧版 `user_message` / 最终 `agent_message`
+和新版 `item_completed` 对话事件，排除 `response_item`。实现见 [Hook 适配器](plugins/reme/hooks/auto_memory.py)。

-在 Codex 0.145.0 中，无人值守的 `codex exec` 无法收集工具审批时，MCP 调用可能返回 `user cancelled MCP tool call`。请在交互会话中批准具体调用来验证显式工具。已信任的自动 Hook 自身作为 MCP 客户端调用服务，不逐次请求模型工具审批。
+CLI 0.145.0 无人值守会话无法收集显式工具调用审批时，可能返回 `user cancelled MCP tool call`。
+请在交互会话中验证这类调用；自动 Hook 使用前文所述的信任审核机制。

-## 源码与验证
+## 维护者验证

-在 ReMe 仓库运行 `pytest tests/unit/test_coding_agent_plugins.py tests/unit/test_codex_plugin_mcp.py -v`。测试使用隔离目录和模拟服务。
-使用支持 `hooks/list` 的运行时，执行
-`REME_CODEX_BIN=/path/to/codex pytest tests/integration/test_codex_plugin_install.py -v`，
-可在隔离配置目录安装插件，验证信任前的 Hook 发现行为，不调用模型或执行 Hook。
-宿主行为以 [Codex Hook 文档](https://learn.chatgpt.com/docs/hooks) 为准。
+五个真实截图槽位及替换方式见[截图清单](./figures/README.md)。中英文说明共用同一组 PNG；
+补图前保留文字槽位，不显示缺失图片。
+
+```bash
+pytest tests/unit/test_coding_agent_plugins.py tests/unit/test_codex_plugin_mcp.py -v
+REME_CODEX_BIN=/path/to/codex pytest tests/integration/test_codex_plugin_install.py -v
+```
+
+原生安装测试需要运行时支持 `hooks/list`，使用隔离配置目录，验证信任前的四个 Hook 发现行为，
+不调用模型或执行 Hook。文档修改后，在 `github-pages/` 运行 `npm test` 和 `npm run build`。
+
+参考：[Codex Hook 文档](https://learn.chatgpt.com/docs/hooks)、
+[OpenAI MCP 设置协议](https://github.com/openai/mcp-extensions/blob/node-v0.1.0/docs/spec.md#structured-settings)。
 ReMe 在 [agentscope-ai/ReMe](https://github.com/agentscope-ai/ReMe) 开发，采用 Apache-2.0 许可证。
--- a/integrations/codex/figures/README.md
+++ b/integrations/codex/figures/README.md
@ -0,0 +1,33 @@
+# Codex screenshot checklist / 截图清单
+
+Use real Codex screenshots only. The English and Chinese guides share these PNG files.
+仅使用真实 Codex 界面截图；中英文说明共用以下 PNG 文件，不使用示意图或重绘的界面。
+
+| Filename / 文件名 | Capture / 拍摄内容 |
+| --- | --- |
+| `plugin-installed.png` | Installed ReMe plugin detail: name, enabled state, and `reme` MCP card. / 已安装的 ReMe 插件详情：名称、启用状态及 MCP 卡片。 |
+| `hooks-trusted.png` | All four ReMe hooks enabled and trusted, in desktop settings or CLI `/hooks`. / 四个 ReMe Hook 均已启用、已信任，可使用桌面设置或 CLI。 |
+| `mcp-settings.png` | Native MCP form: URL, auto switches, batch size, and successful Check connection tooltip. / 原生 MCP 表单：地址、自动开关、批次大小及连接健康浮层。 |
+| `memory-recorded.png` | Conversation A: the test fact and final acknowledgement, without explicit tool calls. / 会话 A：测试事实及最终确认，不显式调用工具。 |
+| `memory-recalled.png` | Separate conversation B: recall question, correct fact, and ReMe source path. / 独立会话 B：召回问题、正确事实和 ReMe 来源路径。 |
+
+## Add the screenshots / 补图步骤
+
+1. Save the original PNG files in this directory using the names above. Keep text readable;
+   include enough of the Codex interface to identify the page. Crop unrelated conversations and account details.
+   将 PNG 原图按以上文件名放入本目录，保持文字清晰并保留可辨认的 Codex 界面，裁去无关对话和账号信息。
+2. In both `../README.md` and `../README_ZH.md`, find the matching screenshot placeholder,
+   remove its visible blockquote, and remove the `<!--` / `-->` around the image line.
+   在两份说明中找到对应槽位，删除可见的占位引用块，并移除图片行外的 HTML 注释标记。
+3. Keep the Markdown image path relative, such as `./figures/mcp-settings.png`.
+   The documentation build copies these files and rewrites the path for the website.
+   保留相对图片路径；文档构建会复制图片并转换为站点路径。
+4. From `github-pages/`, run `npm test` and `npm run build`, then preview both language pages.
+   在 `github-pages/` 执行上述检查，并预览中英文页面。
+
+Use the same unique test project and facts for both conversation screenshots. Keep the
+connection, trust, and memory checks separate: an acknowledgement alone does not prove a successful write.
+两张对话截图使用同一组独立测试事实。连接健康、Hook 信任和记忆交付分别验证；仅有确认回复不能证明写入成功。
+
+MCP settings require a desktop host that supports the native form; a CLI capture cannot substitute for this image.
+MCP 设置图需在支持原生表单的桌面宿主中截取，不能用 CLI 输出代替。