feat(plugin/codex): add lifecycle hooks (recall, capture, pre-compact) to codex-memory-plugin

docs/en/agent-integrations/01-overview.md

@@ -9,7 +9,8 @@ OpenViking can act as the long-term memory and context backend for many agent ru
 | **Claude Code** | [Claude Code Memory Plugin](./02-claude-code.md) — auto-recall + auto-capture via hooks, no MCP tool calls required from the model |
 | **OpenClaw** | [OpenClaw Plugin](./03-openclaw.md) — context-engine + hooks + tools + runtime manager, deep lifecycle integration |
 | **LangChain / LangGraph** | [LangChain and LangGraph](./05-langchain-langgraph.md) — session context backend, chat history, retriever, `viking_*` tools, LangGraph store, and middleware for agent workflows |
-| **Codex / OpenCode** | [Other community plugins](./04-other-plugins.md) — MCP-only and tool-mechanism variants |
+| **Codex** | [Codex Memory Plugin](./04-other-plugins.md#codex-memory-plugin) — lifecycle hooks for auto-recall, incremental capture, and pre-compact commit |
+| **OpenCode** | [Other community plugins](./04-other-plugins.md) — explicit-tool and context-injection variants |
 | **Cursor / Trae / Manus / Claude Desktop / ChatGPT / …** | [MCP Integration Guide](../guides/06-mcp-integration.md) — point any MCP-compatible client at the built-in `/mcp` endpoint |
 | **Hermes Agent (Nous Research)** | [Hermes — OpenViking memory provider](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking) — first-class OpenViking memory provider, no plugin install needed |
 
@@ -18,7 +19,7 @@ OpenViking can act as the long-term memory and context backend for many agent ru
 Some integrations go beyond what a generic MCP client can do:
 
 - **Generic MCP clients** call OpenViking on demand through tools the model decides to invoke. Setup is one config snippet.
-- **Hooks-based plugins** (Claude Code, OpenClaw) drive recall and capture from runtime lifecycle events — every prompt, every turn, session start/end, compact, subagent spawn. The model doesn't need to "remember to recall."
+- **Hooks-based plugins** (Claude Code, Codex, OpenClaw) drive recall and capture from runtime lifecycle events — every prompt, every turn, session start/end, compact, subagent spawn. The model doesn't need to "remember to recall."
 - **SDK integrations** (LangChain/LangGraph) wire OpenViking into framework-native abstractions such as retrievers, tools, chat history, stores, and middleware.
 
 For agents whose runtime exposes hooks, middleware, or a context-engine slot, the native integration path is usually the better default.

docs/en/agent-integrations/04-other-plugins.md

@@ -2,20 +2,93 @@
 
 The repo also ships several community/experimental plugins beyond the headline Claude Code and OpenClaw integrations. They differ in target runtime, integration depth, and maintenance status — read each one's README before adopting.
 
-## Codex Memory MCP Server
+## Codex Memory Plugin
 
 Source: [examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin)
 
-A minimal MCP-only server for [Codex](https://github.com/openai/codex). Intentionally narrow scope:
+[Codex](https://github.com/openai/codex) integration with lifecycle hooks and explicit MCP tools. It follows the same install-first shape as the [Claude Code integration](./02-claude-code.md), but uses Codex hook events.
 
-- no lifecycle hooks
-- no background capture worker
-- no writes to `~/.codex`
-- no checked-in build output
+### Install
 
-Codex gets four explicit memory tools: `find`, `remember`, plus a couple more.
+Recommended one-line installer:
 
-If you only need explicit memory operations from Codex (no auto-recall or auto-capture), this is the simplest option.
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)
+```
+
+It installs from a local `openviking-plugins-local` marketplace, enables `openviking-memory@openviking-plugins-local`, sets `features.plugin_hooks = true`, and uses `~/.openviking/ovcli.conf` for the OpenViking connection when present.
+
+Manual setup:
+
+```bash
+node --version    # >= 22
+codex --version   # >= 0.124.0
+codex features list | grep codex_hooks
+```
+
+Enable plugin lifecycle hooks:
+
+```toml
+[features]
+plugin_hooks = true
+```
+
+From an OpenViking checkout:
+
+```bash
+mkdir -p /tmp/ov-codex-mp/.claude-plugin
+ln -s "$(pwd)/examples/codex-memory-plugin" /tmp/ov-codex-mp/openviking-memory
+cat > /tmp/ov-codex-mp/.claude-plugin/marketplace.json <<'EOF'
+{
+  "name": "openviking-plugins-local",
+  "plugins": [
+    { "name": "openviking-memory", "source": "./openviking-memory" }
+  ]
+}
+EOF
+
+codex plugin marketplace add /tmp/ov-codex-mp
+cat >> ~/.codex/config.toml <<'EOF'
+
+[plugins."openviking-memory@openviking-plugins-local"]
+enabled = true
+EOF
+```
+
+For local development, pre-populate Codex's cache so it resolves immediately:
+
+```bash
+INSTALL_DIR=~/.codex/plugins/cache/openviking-plugins-local/openviking-memory
+mkdir -p "$INSTALL_DIR"
+cp -R "$(pwd)/examples/codex-memory-plugin" "$INSTALL_DIR/0.4.0"
+```
+
+`npm install && npm run build` is only required when editing the TypeScript MCP server source; the checked-in plugin already includes `servers/memory-server.js`.
+
+### Configure
+
+Use `~/.openviking/ovcli.conf`, shared with the `ov` CLI:
+
+```jsonc
+{
+  "url": "https://ov.example.com",
+  "api_key": "<your-key>",
+  "account": "default",
+  "user": "<your-user>"
+}
+```
+
+Environment variables win over files. Use `OPENVIKING_CLI_CONFIG_FILE` for an alternate `ovcli.conf`; `OPENVIKING_API_KEY` and `OPENVIKING_BEARER_TOKEN` are equivalent.
+
+### What it does
+
+- Auto-recall on `UserPromptSubmit`
+- Incremental capture on `Stop`
+- Commit before compaction on `PreCompact`
+- Orphan cleanup on `SessionStart` startup/clear
+- Manual MCP tools: `openviking_recall`, `openviking_store`, `openviking_forget`, `openviking_health`
+
+Full behavior and validation details are in the [plugin README](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin).
 
 ## OpenCode plugins
 

examples/codex-memory-plugin/.codex-plugin/plugin.json

@@ -1,14 +1,32 @@
 {
   "name": "openviking-memory",
-  "description": "Explicit OpenViking memory tools for Codex via MCP.",
+  "version": "0.4.0",
+  "description": "Long-term semantic memory for Codex, powered by OpenViking. Recall on UserPromptSubmit, incremental add_message on Stop (per turn), commit on PreCompact, and active-window heuristic + idle-TTL sweep on SessionStart (source=startup|clear).",
+  "author": {
+    "name": "OpenViking",
+    "url": "https://github.com/volcengine/OpenViking"
+  },
+  "repository": "https://github.com/volcengine/OpenViking",
+  "license": "Apache-2.0",
+  "keywords": [
+    "memory",
+    "openviking",
+    "semantic-search",
+    "long-term-memory",
+    "context-engine",
+    "codex"
+  ],
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./.mcp.json",
   "interface": {
     "displayName": "OpenViking Memory",
-    "shortDescription": "OpenViking memory tools for Codex",
-    "longDescription": "Adds explicit OpenViking MCP tools for manual memory recall, store, forget, and health checks.",
+    "shortDescription": "Long-term semantic memory for Codex",
+    "longDescription": "Hooks Codex's lifecycle to keep an external semantic memory: recall relevant memories on each UserPromptSubmit; on every Stop (turn end) append the new user/assistant turns to a long-lived OpenViking session keyed by codex session_id; on PreCompact commit that session so OV's extractor produces durable memories before context is summarized; on SessionStart(source=clear) commit any orphaned prior session before /clear discards it. Also exposes explicit MCP tools (openviking_recall, openviking_store, openviking_forget, openviking_health) for manual use.",
     "developerName": "OpenViking",
-    "category": "productivity",
+    "category": "Productivity",
     "capabilities": [
       "Memory recall",
+      "Auto memory capture",
       "Manual memory storage",
       "Manual memory deletion"
     ],

examples/codex-memory-plugin/.gitignore

@@ -1,2 +1,5 @@
 node_modules/
-servers/
+servers/*.mjs
+servers/*.js
+!servers/memory-server.js
+*.tsbuildinfo

examples/codex-memory-plugin/.mcp.json

@@ -3,9 +3,11 @@
     "openviking-memory": {
       "command": "node",
       "args": [
-        "servers/memory-server.js"
+        "${CODEX_PLUGIN_ROOT}/scripts/start-memory-server.mjs"
       ],
-      "cwd": "."
+      "env": {
+        "OPENVIKING_CONFIG_FILE": "${OPENVIKING_CONFIG_FILE}"
+      }
     }
   }
 }