Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs(plugin/codex): dedicated agent-integrations page (zh+en) + fix MCP startup (#2019)

t0saki8034abc158d3
diff --git a/docs/en/agent-integrations/01-overview.md b/docs/en/agent-integrations/01-overview.md
index da21806f1..63d0ada41 100644
--- a/docs/en/agent-integrations/01-overview.md
+++ b/docs/en/agent-integrations/01-overview.md
@@ -8,9 +8,9 @@ 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** | [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 |
+| **Codex** | [Codex Memory Plugin](./04-codex.md) — lifecycle hooks for auto-recall, incremental capture, and pre-compact commit |
+| **LangChain / LangGraph** | [LangChain and LangGraph](./06-langchain-langgraph.md) — session context backend, chat history, retriever, `viking_*` tools, LangGraph store, and middleware for agent workflows |
+| **OpenCode** | [Other community plugins](./05-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 |
diff --git a/docs/en/agent-integrations/04-codex.md b/docs/en/agent-integrations/04-codex.md
new file mode 100644
index 000000000..094cc180f
--- /dev/null
+++ b/docs/en/agent-integrations/04-codex.md
@@ -0,0 +1,191 @@
+# Codex Memory Plugin
+
+Long-term semantic memory for [Codex](https://developers.openai.com/codex). Auto-recalls relevant memories on every prompt, incrementally captures each turn, and commits to OpenViking's memory extractor before compaction — the model doesn't need to call any MCP tool explicitly.
+
+Source: [examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin)
+
+## Quick Start
+
+### One-line installer (recommended)
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)
+```
+
+The installer checks `codex`, `git`, and Node.js 22+, refreshes (or clones on first run) `~/.openviking/openviking-repo`, registers a local `openviking-plugins-local` marketplace, enables `openviking-memory@openviking-plugins-local`, sets `features.plugin_hooks = true`, and pre-populates Codex's plugin cache so the plugin resolves immediately. Rerunning the installer is idempotent — it always pulls latest before installing.
+
+It uses `~/.openviking/ovcli.conf` when present; otherwise the plugin falls back to `http://127.0.0.1:1933` unless `OPENVIKING_URL` / `OPENVIKING_API_KEY` are set in the env.
+
+After install, start Codex:
+
+```bash
+codex
+```
+
+Codex will prompt `/hooks` to review the four new lifecycle hooks the first time — approve them once. From then on, recall runs on every prompt and capture runs on every `Stop`.
+
+### Manual setup
+
+Prerequisites:
+
+```bash
+node --version # >= 22
+codex --version # >= 0.130.0
+codex features list | grep codex_hooks
+```
+
+Enable plugin lifecycle hooks in `~/.codex/config.toml`:
+
+```toml
+[features]
+plugin_hooks = true
+```
+
+From an OpenViking checkout, register a local marketplace:
+
+```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
+```
+
+Pre-populate Codex's cache so the plugin resolves on first launch:
+
+```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.1"
+```
+
+Configure the OpenViking client, sharing the same file as the `ov` CLI:
+
+```jsonc
+// ~/.openviking/ovcli.conf
+{
+ "url": "https://ov.example.com",
+ "api_key": "<your-key>",
+ "account": "default",
+ "user": "<your-user>"
+}
+```
+
+For local-server mode (`http://127.0.0.1:1933`) you can skip this file.
+
+`npm install && npm run build` is only needed when editing `src/memory-server.ts` — the checked-in plugin already includes `servers/memory-server.js`.
+
+## Configuration
+
+Resolution priority for every connection / identity field — env vars always win:
+
+1. **Environment variables** (`OPENVIKING_*`)
+2. **`ovcli.conf`** — `~/.openviking/ovcli.conf` or `OPENVIKING_CLI_CONFIG_FILE`
+3. **`ov.conf`** — `~/.openviking/ov.conf` or `OPENVIKING_CONFIG_FILE` (top-level `server.*` + optional `codex.*` tuning block)
+4. **Built-in defaults** (`http://127.0.0.1:1933`, unauthenticated)
+
+Setting `OPENVIKING_URL` alone is enough to run in env-var-only mode (no config files needed) — useful for daemon-spawned agents.
+
+Auth is sent as `Authorization: Bearer <api_key>` plus the legacy `X-API-Key` header during the transition window.
+
+### Key environment variables
+
+| Variable | Default | Notes |
+|----------|---------|-------|
+| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | Full server URL |
+| `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN` | — | API key (sent as `Authorization: Bearer` either way) |
+| `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` / `OPENVIKING_AGENT_ID` | — | Multi-tenant identity headers |
+| `OPENVIKING_CLI_CONFIG_FILE` | `~/.openviking/ovcli.conf` | Alternate `ovcli.conf` path |
+| `OPENVIKING_CONFIG_FILE` | `~/.openviking/ov.conf` | Alternate `ov.conf` path |
+| `OPENVIKING_CODEX_ACTIVE_WINDOW_MS` | `120000` | SessionStart active-window threshold |
+| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | SessionStart idle-TTL sweep threshold |
+| `OPENVIKING_DEBUG` | `false` | Write JSONL events to `~/.openviking/logs/codex-hooks.log` |
+
+Optional Codex-specific tuning lives under `codex` in `ovcli.conf`:
+
+```jsonc
+{
+ "url": "https://ov.example.com",
+ "api_key": "...",
+ "codex": {
+ "agentId": "codex",
+ "recallLimit": 6,
+ "autoCommitOnCompact": true,
+ "debug": false
+ }
+}
+```
+
+The full field list is in the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#configuration).
+
+## Hook behavior
+
+| Hook | When | Behavior |
+|------|------|----------|
+| `SessionStart` (matcher `clear\|startup`) | Fresh process, `/new`, or `/clear` | Active-window heuristic: if exactly one other state file was touched in the last 2 min, commit it (the just-ended session). Idle-TTL sweep at the tail picks up SIGTERM/`/exit` orphans older than 30 min. `source=resume` is a hard no-op. |
+| `UserPromptSubmit` | Every prompt | Search OpenViking, rank, inject top results into `hookSpecificOutput.additionalContext`. |
+| `Stop` | Every turn end | Append new user/assistant turns to the long-lived OpenViking session keyed by Codex `session_id`. No commit per turn. |
+| `PreCompact` | Before Codex summarizes | Catch-up append + commit so OpenViking's extractor runs against the full pre-compact transcript, then null `ovSessionId` so the next `Stop` opens a fresh OV session. |
+
+`Stop` deliberately does not commit per turn — committing extracts memories, and per-turn extraction would over-fragment the memory tree. The decision tree behind which hook seals which OV session is in [`DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md).
+
+The MCP server (`servers/memory-server.js`) is launched lazily by `scripts/start-memory-server.mjs` on first MCP invocation — `npm ci` runs into `${CODEX_PLUGIN_DATA}/runtime` once and is reused after that.
+
+### Known gap: SIGTERM / Ctrl+C / `/exit` are silent
+
+Codex fires no hook on process exit. If you `/exit` without `/compact`, the OV session for that codex session_id stays open server-side. Two fallbacks recover the orphan:
+
+1. The next `SessionStart` (source=startup|clear) idle-TTL sweep commits any state file older than 30 min.
+2. The active-window heuristic catches the orphan if you `/new` or `/clear` shortly after.
+
+If you need to preserve memory from a specific session, run `/compact` first or call `openviking_store` with the conclusions you want kept.
+
+## MCP tools
+
+For explicit memory operations, the plugin also exposes four MCP tools:
+
+- `openviking_recall` — search memories
+- `openviking_store` — store a memory by creating a short OV session and committing
+- `openviking_forget` — delete an exact memory URI
+- `openviking_health` — server reachability check
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `MCP startup failed: connection closed: initialize response` | MCP launcher couldn't find the script (e.g., stale plugin cache) | Re-run the [one-line installer](#one-line-installer-recommended) — it now refreshes `~/.openviking/openviking-repo` |
+| `4 hooks need review before they can run` | First-launch security review | Open `/hooks` in Codex and approve |
+| Hook runs but recall returns nothing | OpenViking server unreachable or wrong URL | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
+| Remote auth 401/403 | API key wrong or multi-tenant headers missing | Check `OPENVIKING_API_KEY`; multi-tenant also needs `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` |
+| `Stop` hook timeout | Server slow + sync write path | Raise the `Stop` timeout in `hooks/hooks.json` |
+
+Verbose debug logging: set `OPENVIKING_DEBUG=1` or `codex.debug=true` in `ovcli.conf` to write JSON-Lines events to `~/.openviking/logs/codex-hooks.log`.
+
+## Differences from the Claude Code plugin
+
+| Aspect | Claude Code Plugin | Codex Plugin |
+|--------|--------------------|--------------|
+| Plugin root env | `CLAUDE_PLUGIN_ROOT` | `CODEX_PLUGIN_ROOT` |
+| `UserPromptSubmit` output | `decision: "approve"` + `additionalContext` | `additionalContext` only — `approve` is not a Codex output |
+| Compaction hook | n/a | `PreCompact` — full-transcript commit before context loss |
+| Config section | `claude_code` | `codex` |
+| Default config file | `~/.openviking/ov.conf` | `~/.openviking/ovcli.conf`, falls back to `ov.conf` |
+
+## See also
+
+- [Plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) — full env-var list, validation SOP, architecture diagram
+- [`DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) — commit decision tree
+- [MCP Integration Guide](../guides/06-mcp-integration.md) — for clients without lifecycle hooks
+- [Deployment Guide → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` setup
diff --git a/docs/en/agent-integrations/04-other-plugins.md b/docs/en/agent-integrations/04-other-plugins.md
deleted file mode 100644
index 585c7300a..000000000
--- a/docs/en/agent-integrations/04-other-plugins.md
+++ /dev/null
@@ -1,120 +0,0 @@
-# Other Plugins
-
-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 Plugin
-
-Source: [examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin)
-
-[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.
-
-### Install
-
-Recommended one-line installer:
-
-```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
-
-Two OpenCode plugin variants exist with different design choices. Pick whichever matches your usage — we don't make the decision for you.
-
-### `opencode-memory-plugin` — explicit-tool variant
-
-Source: [examples/opencode-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-memory-plugin)
-
-Exposes OpenViking memories as explicit OpenCode tools and syncs the conversation session into OpenViking.
-
-- the agent sees concrete tools and decides when to call them
-- OpenViking data is fetched on demand via tool execution, not pre-injected into every prompt
-- the plugin keeps an OpenViking session in sync with the OpenCode conversation and triggers background extraction with `memcommit`
-
-### `opencode/plugin` — context-injection variant
-
-Source: [examples/opencode/plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode/plugin)
-
-Injects indexed code repos into OpenCode's context and auto-starts the OpenViking server when needed.
-
-- prompt context is augmented with relevant code from indexed repos
-- bundles a small launcher that brings up the OpenViking server on demand
-
-## Generic MCP clients
-
-For Cursor, Trae, Manus, Claude Desktop, ChatGPT/Codex, and any other MCP-compatible runtime, you don't need a dedicated plugin — just point the client at the built-in `/mcp` endpoint.
-
-→ See the [MCP Integration Guide](../guides/06-mcp-integration.md).
diff --git a/docs/en/agent-integrations/05-other-plugins.md b/docs/en/agent-integrations/05-other-plugins.md
new file mode 100644
index 000000000..942e785bd
--- /dev/null
+++ b/docs/en/agent-integrations/05-other-plugins.md
@@ -0,0 +1,32 @@
+# Other Plugins
+
+The repo also ships several community/experimental plugins beyond the headline Claude Code, Codex, and OpenClaw integrations. They differ in target runtime, integration depth, and maintenance status — read each one's README before adopting.
+
+## OpenCode plugins
+
+Two OpenCode plugin variants exist with different design choices. Pick whichever matches your usage — we don't make the decision for you.
+
+### `opencode-memory-plugin` — explicit-tool variant
+
+Source: [examples/opencode-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-memory-plugin)
+
+Exposes OpenViking memories as explicit OpenCode tools and syncs the conversation session into OpenViking.
+
+- the agent sees concrete tools and decides when to call them
+- OpenViking data is fetched on demand via tool execution, not pre-injected into every prompt
+- the plugin keeps an OpenViking session in sync with the OpenCode conversation and triggers background extraction with `memcommit`
+
+### `opencode/plugin` — context-injection variant
+
+Source: [examples/opencode/plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode/plugin)
+
+Injects indexed code repos into OpenCode's context and auto-starts the OpenViking server when needed.
+
+- prompt context is augmented with relevant code from indexed repos
+- bundles a small launcher that brings up the OpenViking server on demand
+
+## Generic MCP clients
+
+For Cursor, Trae, Manus, Claude Desktop, ChatGPT/Codex, and any other MCP-compatible runtime, you don't need a dedicated plugin — just point the client at the built-in `/mcp` endpoint.
+
+→ See the [MCP Integration Guide](../guides/06-mcp-integration.md).
diff --git a/docs/en/agent-integrations/05-langchain-langgraph.md b/docs/en/agent-integrations/06-langchain-langgraph.md
similarity index 100%
rename from docs/en/agent-integrations/05-langchain-langgraph.md
rename to docs/en/agent-integrations/06-langchain-langgraph.md
diff --git a/docs/zh/agent-integrations/01-overview.md b/docs/zh/agent-integrations/01-overview.md
index f08b378d3..0f579501f 100644
--- a/docs/zh/agent-integrations/01-overview.md
+++ b/docs/zh/agent-integrations/01-overview.md
@@ -8,8 +8,9 @@ OpenViking 可以作为多种 Agent 运行时的长期记忆与上下文后端
|---------|---------|
| **Claude Code** | [Claude Code 记忆插件](./02-claude-code.md) — 通过 hooks 实现自动召回与自动捕获,模型侧无需主动调用 MCP 工具 |
| **OpenClaw** | [OpenClaw 插件](./03-openclaw.md) — context-engine + hooks + tools + 运行时管理一体化集成,覆盖完整生命周期 |
-| **LangChain / LangGraph** | [LangChain 和 LangGraph](./05-langchain-langgraph.md) — session context backend、chat history、retriever、`viking_*` tools、LangGraph store 和 workflow middleware |
-| **Codex / OpenCode** | [其他社区插件](./04-other-plugins.md) — 包括 MCP-only 版本和 tool 机制版本 |
+| **Codex** | [Codex 记忆插件](./04-codex.md) — 生命周期 hooks 自动召回、增量捕获、compaction 前 commit |
+| **LangChain / LangGraph** | [LangChain 和 LangGraph](./06-langchain-langgraph.md) — session context backend、chat history、retriever、`viking_*` tools、LangGraph store 和 workflow middleware |
+| **OpenCode** | [其他社区插件](./05-other-plugins.md) — 显式工具版本与上下文注入版本 |
| **Cursor / Trae / Manus / Claude Desktop / ChatGPT / …** | [MCP 集成指南](../guides/06-mcp-integration.md) — 任何兼容 MCP 的客户端都可直接对接内置 `/mcp` 端点 |
| **Hermes Agent (Nous Research)** | [Hermes — OpenViking 记忆提供方](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking) — 一等公民支持,无需额外安装插件 |
@@ -18,7 +19,7 @@ OpenViking 可以作为多种 Agent 运行时的长期记忆与上下文后端
部分集成能力超过通用 MCP 客户端:
- **通用 MCP 客户端**:模型主动调用工具时按需访问 OpenViking。配置只需一份连接片段。
-- **基于 hooks 的插件**(Claude Code、OpenClaw):在运行时生命周期事件(每次 prompt、每轮结束、session 起止、compact、subagent 派生等)中驱动召回与捕获。模型不需要"记得调用"。
+- **基于 hooks 的插件**(Claude Code、Codex、OpenClaw):在运行时生命周期事件(每次 prompt、每轮结束、session 起止、compact、subagent 派生等)中驱动召回与捕获。模型不需要"记得调用"。
- **SDK 集成**(LangChain/LangGraph):把 OpenViking 接入框架原生抽象,例如 retriever、tools、chat history、store 和 middleware。
如果你的 Agent runtime 暴露 hooks、middleware 或 context-engine 槽位,原生集成通常是更好的默认选择。
diff --git a/docs/zh/agent-integrations/04-codex.md b/docs/zh/agent-integrations/04-codex.md
new file mode 100644
index 000000000..f992d9c49
--- /dev/null
+++ b/docs/zh/agent-integrations/04-codex.md
@@ -0,0 +1,191 @@
+# Codex 记忆插件
+
+为 [Codex](https://developers.openai.com/codex) 提供长期语义记忆。每次用户输入前自动召回相关记忆,每轮对话结束后增量捕获,并在 compaction 之前提交给 OpenViking 的记忆抽取器——模型不需要主动调用任何 MCP 工具。
+
+源码:[examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin)
+
+## 快速开始
+
+### 一行安装(推荐)
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)
+```
+
+脚本会检查 `codex`、`git`、Node.js 22+;首次运行时把 OpenViking 仓库 clone 到 `~/.openviking/openviking-repo`,已存在则自动 `git fetch` + `reset --hard` 到 main;注册本地 `openviking-plugins-local` marketplace、启用 `openviking-memory@openviking-plugins-local`、把 `features.plugin_hooks = true` 写入 `~/.codex/config.toml`,并预填 Codex 的 plugin 缓存让插件立即解析到。每一步幂等,反复执行安全。
+
+存在 `~/.openviking/ovcli.conf` 时直接读它;否则插件回落到 `http://127.0.0.1:1933`,或读取 env 中的 `OPENVIKING_URL` / `OPENVIKING_API_KEY`。
+
+安装完成后启动 Codex:
+
+```bash
+codex
+```
+
+首次启动时 Codex 会提示 `4 hooks need review before they can run`——进入 `/hooks` 审批一次后续都不会再问。之后每次用户输入会自动召回,每轮 `Stop` 会自动捕获。
+
+### 手动安装
+
+前置:
+
+```bash
+node --version # >= 22
+codex --version # >= 0.130.0
+codex features list | grep codex_hooks
+```
+
+在 `~/.codex/config.toml` 启用插件生命周期 hooks:
+
+```toml
+[features]
+plugin_hooks = true
+```
+
+在 OpenViking 检出目录注册一个本地 marketplace:
+
+```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
+```
+
+预填 Codex 的 plugin 缓存,首次启动直接命中:
+
+```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.1"
+```
+
+配置 OpenViking 客户端(与 `ov` CLI 共用同一份文件):
+
+```jsonc
+// ~/.openviking/ovcli.conf
+{
+ "url": "https://ov.example.com",
+ "api_key": "<你的 API key>",
+ "account": "default",
+ "user": "<你的 user>"
+}
+```
+
+只用本地服务器(`http://127.0.0.1:1933`)可以跳过这一步。
+
+只有修改 `src/memory-server.ts` 才需要 `npm install && npm run build`——仓库里已经带了 `servers/memory-server.js`。
+
+## 配置
+
+每个连接 / 身份字段的优先级从高到低(环境变量永远最高):
+
+1. **环境变量**(`OPENVIKING_*`)
+2. **`ovcli.conf`** — `~/.openviking/ovcli.conf` 或 `OPENVIKING_CLI_CONFIG_FILE`
+3. **`ov.conf`** — `~/.openviking/ov.conf` 或 `OPENVIKING_CONFIG_FILE`(顶层 `server.*` + 可选的 `codex.*` 调参块)
+4. **内置默认值**(`http://127.0.0.1:1933`,无鉴权)
+
+只设 `OPENVIKING_URL` 一个变量就足以跑 env-only 模式(不需要任何配置文件),适合 daemon 派生 agent 的场景。
+
+鉴权头同时发送 `Authorization: Bearer <api_key>`(主)和 `X-API-Key`(兼容旧版自托管服务)。
+
+### 关键环境变量
+
+| 环境变量 | 默认值 | 说明 |
+|---------|--------|------|
+| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | 完整服务器 URL |
+| `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN` | — | API key(两个变量都通过 `Authorization: Bearer` 发送) |
+| `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` / `OPENVIKING_AGENT_ID` | — | 多租户身份头 |
+| `OPENVIKING_CLI_CONFIG_FILE` | `~/.openviking/ovcli.conf` | 备用 `ovcli.conf` 路径 |
+| `OPENVIKING_CONFIG_FILE` | `~/.openviking/ov.conf` | 备用 `ov.conf` 路径 |
+| `OPENVIKING_CODEX_ACTIVE_WINDOW_MS` | `120000` | SessionStart 活动窗口阈值 |
+| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | SessionStart 闲置 TTL 清理阈值 |
+| `OPENVIKING_DEBUG` | `false` | 把 hook 日志写到 `~/.openviking/logs/codex-hooks.log` |
+
+可选的 Codex 专属调参放在 `ovcli.conf` 的 `codex` 块下:
+
+```jsonc
+{
+ "url": "https://ov.example.com",
+ "api_key": "...",
+ "codex": {
+ "agentId": "codex",
+ "recallLimit": 6,
+ "autoCommitOnCompact": true,
+ "debug": false
+ }
+}
+```
+
+完整字段列表见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#configuration)。
+
+## Hook 行为
+
+| Hook | 触发时机 | 行为 |
+|------|---------|------|
+| `SessionStart`(matcher `clear\|startup`) | 全新进程 / `/new` / `/clear` | 活动窗口启发式:如果最近 2 分钟内恰好只有一个其他 state 文件被更新,就把它 commit 掉(视为刚刚结束的 session)。尾部的闲置 TTL 清理会捕获 30 分钟以上的孤儿 state(SIGTERM / `/exit` 等)。`source=resume` 是硬 no-op。 |
+| `UserPromptSubmit` | 每次用户输入 | 搜索 OpenViking → 排序 → 把 top 结果通过 `hookSpecificOutput.additionalContext` 注入到模型上下文。 |
+| `Stop` | 每轮结束 | 把新的 user/assistant turn 追加到由 Codex `session_id` 索引的长生命周期 OV session。**不**每轮 commit。 |
+| `PreCompact` | Codex 即将做摘要前 | 补齐追加 + commit,让 OV 抽取器跑在完整的 pre-compact transcript 上;commit 后清空 `ovSessionId`,下一次 `Stop` 会打开一个全新的 OV session。 |
+
+`Stop` 故意不每轮 commit——commit 会触发记忆抽取,每轮抽取会过度碎片化记忆树。完整的「哪个 hook 负责封住哪个 OV session」决策树见 [`DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md)。
+
+MCP 服务器(`servers/memory-server.js`)由 `scripts/start-memory-server.mjs` 懒加载启动 —— 首次 MCP 调用时跑一次 `npm ci` 到 `${CODEX_PLUGIN_DATA}/runtime`,后续复用。
+
+### 已知盲区:SIGTERM / Ctrl+C / `/exit` 不触发任何 hook
+
+Codex 在进程退出时不发任何 hook。如果你 `/exit` 之前没跑 `/compact`,那个 codex session 对应的 OV session 会在服务端保持打开状态。两条兜底路径会回收孤儿:
+
+1. 下一次 `SessionStart`(source=startup|clear)的闲置 TTL 清理会 commit 30 分钟以上的孤儿 state。
+2. 如果你在孤儿之后立即 `/new` 或 `/clear`,活动窗口启发式会精准命中并 commit。
+
+如果你想保住某个 session 的记忆,退出前先 `/compact`,或者用 `openviking_store` 显式记下结论。
+
+## MCP 工具
+
+除了自动 hook,插件还暴露四个 MCP 工具供显式调用:
+
+- `openviking_recall` — 搜索记忆
+- `openviking_store` — 创建一个短 OV session、写入内容、commit
+- `openviking_forget` — 删除指定 URI 的记忆
+- `openviking_health` — 服务可达性探测
+
+## 故障排查
+
+| 现象 | 原因 | 修复 |
+|------|------|------|
+| `MCP startup failed: connection closed: initialize response` | MCP 启动脚本找不到(典型成因:plugin 缓存陈旧) | 重新跑[一行安装脚本](#一行安装推荐)——它会自动刷新 `~/.openviking/openviking-repo` |
+| `4 hooks need review before they can run` | 首次启动的安全审批 | 进入 Codex 输入 `/hooks` 批准一次 |
+| Hook 触发但召回为空 | OpenViking 服务器不可达或 URL 不对 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
+| 远程鉴权 401 / 403 | API key 错或多租户头缺失 | 检查 `OPENVIKING_API_KEY`;多租户场景还要核对 `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` |
+| `Stop` hook 超时 | 服务器慢 + 同步写路径 | 调高 `hooks/hooks.json` 里 `Stop` 的 timeout |
+
+调试日志:设 `OPENVIKING_DEBUG=1` 或 `ovcli.conf` 里 `codex.debug=true`,会把 JSON-Lines 事件写到 `~/.openviking/logs/codex-hooks.log`。
+
+## 与 Claude Code 插件的差异
+
+| 维度 | Claude Code 插件 | Codex 插件 |
+|------|------------------|-----------|
+| Plugin root env | `CLAUDE_PLUGIN_ROOT` | `CODEX_PLUGIN_ROOT` |
+| `UserPromptSubmit` 输出 | `decision: "approve"` + `additionalContext` | 只有 `additionalContext` —— Codex 没有 `approve` 这个 decision |
+| Compaction hook | 无 | `PreCompact` —— 在上下文丢失前 commit 完整 transcript |
+| 配置区块 | `claude_code` | `codex` |
+| 默认配置文件 | `~/.openviking/ov.conf` | `~/.openviking/ovcli.conf`,回落到 `ov.conf` |
+
+## 参见
+
+- [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) — 完整环境变量、Validation SOP、架构图
+- [`DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) — commit 决策树
+- [MCP 集成指南](../guides/06-mcp-integration.md) — 用于不支持生命周期 hook 的客户端
+- [部署指南 → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` 配置
diff --git a/docs/zh/agent-integrations/04-other-plugins.md b/docs/zh/agent-integrations/05-other-plugins.md
similarity index 64%
rename from docs/zh/agent-integrations/04-other-plugins.md
rename to docs/zh/agent-integrations/05-other-plugins.md
index 5b67a42b6..130d96c34 100644
--- a/docs/zh/agent-integrations/04-other-plugins.md
+++ b/docs/zh/agent-integrations/05-other-plugins.md
@@ -1,21 +1,6 @@
# 其他插件
-仓库里还附带了几个未在 Claude Code 和 OpenClaw 主集成中介绍的社区/实验性插件。它们在目标 runtime、集成深度和维护状态上各有差异,使用前请先阅读各自的 README。
-
-## Codex 记忆 MCP Server
-
-源码:[examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin)
-
-面向 [Codex](https://github.com/openai/codex) 的最小化 MCP-only 服务,刻意保持窄边界:
-
-- 不挂生命周期 hook
-- 不跑后台捕获 worker
-- 不写 `~/.codex`
-- 不留 build 产物
-
-Codex 拿到的只是几个显式记忆工具:`find`、`remember`,外加几个辅助。
-
-如果你只需要 Codex 显式调用记忆(不需要自动召回/捕获),这是最简方案。
+仓库里还附带了几个未在 Claude Code、Codex 和 OpenClaw 主集成中介绍的社区/实验性插件。它们在目标 runtime、集成深度和维护状态上各有差异,使用前请先阅读各自的 README。
## OpenCode 插件
diff --git a/docs/zh/agent-integrations/05-langchain-langgraph.md b/docs/zh/agent-integrations/06-langchain-langgraph.md
similarity index 97%
rename from docs/zh/agent-integrations/05-langchain-langgraph.md
rename to docs/zh/agent-integrations/06-langchain-langgraph.md
index 769f2046b..e30bf367c 100644
--- a/docs/zh/agent-integrations/05-langchain-langgraph.md
+++ b/docs/zh/agent-integrations/06-langchain-langgraph.md
@@ -47,4 +47,4 @@ tools = create_openviking_tools(
- `examples/langchain-langgraph/langgraph/agent/live_app.py`
- `examples/langchain-langgraph/langgraph/middleware/quick_app.py`
-更完整的英文说明见 [LangChain and LangGraph](../../en/agent-integrations/05-langchain-langgraph.md)。
+更完整的英文说明见 [LangChain and LangGraph](../../en/agent-integrations/06-langchain-langgraph.md)。
diff --git a/examples/codex-memory-plugin/.codex-plugin/plugin.json b/examples/codex-memory-plugin/.codex-plugin/plugin.json
index 4a1453bfb..0674085d1 100644
--- a/examples/codex-memory-plugin/.codex-plugin/plugin.json
+++ b/examples/codex-memory-plugin/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "openviking-memory",
- "version": "0.4.0",
+ "version": "0.4.1",
"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",
diff --git a/examples/codex-memory-plugin/.mcp.json b/examples/codex-memory-plugin/.mcp.json
index 46f9ef5a6..d968463f7 100644
--- a/examples/codex-memory-plugin/.mcp.json
+++ b/examples/codex-memory-plugin/.mcp.json
@@ -3,11 +3,9 @@
"openviking-memory": {
"command": "node",
"args": [
- "${CODEX_PLUGIN_ROOT}/scripts/start-memory-server.mjs"
+ "scripts/start-memory-server.mjs"
],
- "env": {
- "OPENVIKING_CONFIG_FILE": "${OPENVIKING_CONFIG_FILE}"
- }
+ "cwd": "."
}
}
}
diff --git a/examples/codex-memory-plugin/README.md b/examples/codex-memory-plugin/README.md
index 232bd7eb4..ddd80719f 100644
--- a/examples/codex-memory-plugin/README.md
+++ b/examples/codex-memory-plugin/README.md
@@ -77,7 +77,7 @@ For local development, pre-populate Codex's plugin cache so it resolves immediat
```bash
INSTALL_DIR=~/.codex/plugins/cache/openviking-plugins-local/openviking-memory
mkdir -p "$INSTALL_DIR"
-cp -R /abs/path/to/OpenViking/examples/codex-memory-plugin "$INSTALL_DIR/0.4.0"
+cp -R /abs/path/to/OpenViking/examples/codex-memory-plugin "$INSTALL_DIR/0.4.1"
```
#### 3. Configure OpenViking
diff --git a/examples/codex-memory-plugin/VERIFICATION.md b/examples/codex-memory-plugin/VERIFICATION.md
index 6ec3a4ff5..1ca663d1d 100644
--- a/examples/codex-memory-plugin/VERIFICATION.md
+++ b/examples/codex-memory-plugin/VERIFICATION.md
@@ -1,4 +1,4 @@
-# Verification SOP — codex plugin (v0.4.0)
+# Verification SOP — codex plugin (v0.4.1)
End-to-end smoke test against a live OpenViking server. Run this whenever the
hook scripts change. Takes ~3 minutes; the only async wait is OV's memory
diff --git a/examples/codex-memory-plugin/hooks/hooks.json b/examples/codex-memory-plugin/hooks/hooks.json
index 2765abe63..65284645d 100644
--- a/examples/codex-memory-plugin/hooks/hooks.json
+++ b/examples/codex-memory-plugin/hooks/hooks.json
@@ -6,7 +6,7 @@
"hooks": [
{
"type": "command",
- "command": "node \"${CODEX_PLUGIN_ROOT}/scripts/session-start-commit.mjs\"",
+ "command": "node __OPENVIKING_PLUGIN_ROOT__/scripts/session-start-commit.mjs",
"timeout": 30
}
]
@@ -18,8 +18,8 @@
"hooks": [
{
"type": "command",
- "command": "node \"${CODEX_PLUGIN_ROOT}/scripts/auto-recall.mjs\"",
- "timeout": 8
+ "command": "node __OPENVIKING_PLUGIN_ROOT__/scripts/auto-recall.mjs",
+ "timeout": 15
}
]
}
@@ -30,7 +30,7 @@
"hooks": [
{
"type": "command",
- "command": "node \"${CODEX_PLUGIN_ROOT}/scripts/auto-capture.mjs\"",
+ "command": "node __OPENVIKING_PLUGIN_ROOT__/scripts/auto-capture.mjs",
"timeout": 30
}
]
@@ -42,7 +42,7 @@
"hooks": [
{
"type": "command",
- "command": "node \"${CODEX_PLUGIN_ROOT}/scripts/pre-compact-capture.mjs\"",
+ "command": "node __OPENVIKING_PLUGIN_ROOT__/scripts/pre-compact-capture.mjs",
"timeout": 60
}
]
diff --git a/examples/codex-memory-plugin/package-lock.json b/examples/codex-memory-plugin/package-lock.json
index 409c4d2f3..84e9148f2 100644
--- a/examples/codex-memory-plugin/package-lock.json
+++ b/examples/codex-memory-plugin/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "codex-openviking-memory",
- "version": "0.4.0",
+ "version": "0.4.1",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "codex-openviking-memory",
- "version": "0.4.0",
+ "version": "0.4.1",
"dependencies": {
"@modelcontextprotocol/sdk": "^1.12.1",
"zod": "^4.3.6"
diff --git a/examples/codex-memory-plugin/package.json b/examples/codex-memory-plugin/package.json
index 0798bda63..e70643290 100644
--- a/examples/codex-memory-plugin/package.json
+++ b/examples/codex-memory-plugin/package.json
@@ -1,6 +1,6 @@
{
"name": "codex-openviking-memory",
- "version": "0.4.0",
+ "version": "0.4.1",
"description": "OpenViking memory plugin for Codex — hooks (recall/capture/pre-compact) + MCP server for explicit memory operations.",
"type": "module",
"scripts": {
diff --git a/examples/codex-memory-plugin/scripts/runtime-common.mjs b/examples/codex-memory-plugin/scripts/runtime-common.mjs
index 5636c31b9..b7f7952b0 100644
--- a/examples/codex-memory-plugin/scripts/runtime-common.mjs
+++ b/examples/codex-memory-plugin/scripts/runtime-common.mjs
@@ -3,20 +3,24 @@ import { createHash } from "node:crypto";
import { constants as fsConstants } from "node:fs";
import { access, copyFile, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
export const INSTALL_TIMEOUT_MS = 120000;
const LOCK_STALE_MS = 10 * 60 * 1000;
const FALLBACK_PLUGIN_DATA_ROOT = join(homedir(), ".openviking", "codex-memory-plugin");
const RUNTIME_ENV_META_PATH = ".runtime-env.json";
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT_FROM_SCRIPT = resolve(SCRIPT_DIR, "..");
export function getRuntimePaths() {
- const pluginRoot = process.env.CODEX_PLUGIN_ROOT;
+ // Codex 0.130 does not expand ${CODEX_PLUGIN_ROOT} in .mcp.json args and does
+ // not always inject CODEX_PLUGIN_ROOT into MCP child env, so fall back to the
+ // script's own location (scripts/ lives directly under the plugin root).
+ const pluginRoot = process.env.CODEX_PLUGIN_ROOT || PLUGIN_ROOT_FROM_SCRIPT;
const pluginDataRoot = process.env.CODEX_PLUGIN_DATA || FALLBACK_PLUGIN_DATA_ROOT;
- if (!pluginRoot) throw new Error("CODEX_PLUGIN_ROOT is not set");
-
const runtimeRoot = join(pluginDataRoot, "runtime");
return {
diff --git a/examples/codex-memory-plugin/setup-helper/install.sh b/examples/codex-memory-plugin/setup-helper/install.sh
index 69d31bf3b..bc03f92d5 100755
--- a/examples/codex-memory-plugin/setup-helper/install.sh
+++ b/examples/codex-memory-plugin/setup-helper/install.sh
@@ -3,6 +3,9 @@ set -euo pipefail
REPO_URL="${OPENVIKING_REPO_URL:-https://github.com/volcengine/OpenViking.git}"
REPO_DIR="${OPENVIKING_REPO_DIR:-$HOME/.openviking/openviking-repo}"
+# Accept both OPENVIKING_REPO_REF and OPENVIKING_REPO_BRANCH so users can
+# reuse the same env var across the claude-code and codex installers.
+REPO_REF="${OPENVIKING_REPO_REF:-${OPENVIKING_REPO_BRANCH:-main}}"
MARKETPLACE_NAME="${OPENVIKING_CODEX_MARKETPLACE_NAME:-openviking-plugins-local}"
MARKETPLACE_ROOT="${OPENVIKING_CODEX_MARKETPLACE_ROOT:-$HOME/.codex/${MARKETPLACE_NAME}-marketplace}"
PLUGIN_NAME="openviking-memory"
@@ -33,7 +36,11 @@ if [ ! -e "$REPO_DIR/.git" ]; then
echo "$REPO_DIR exists but is not a git checkout." >&2
exit 1
fi
- git clone --depth 1 "$REPO_URL" "$REPO_DIR"
+ git clone --depth 1 --branch "$REPO_REF" "$REPO_URL" "$REPO_DIR"
+else
+ echo "Refreshing existing OpenViking checkout at $REPO_DIR ($REPO_REF)..."
+ git -C "$REPO_DIR" fetch --depth 1 origin "$REPO_REF"
+ git -C "$REPO_DIR" reset --hard FETCH_HEAD
fi
PLUGIN_DIR="$REPO_DIR/examples/codex-memory-plugin"
@@ -139,6 +146,19 @@ mkdir -p "$(dirname "$CACHE_DIR")"
rm -rf "$CACHE_DIR"
cp -R "$PLUGIN_DIR" "$CACHE_DIR"
+# Codex 0.130 does not inject CODEX_PLUGIN_ROOT into hook subprocess env and
+# does not let hooks.json declare a cwd, so relative paths in hooks.json
+# resolve against the user's cwd (typically ~). Render the placeholder
+# __OPENVIKING_PLUGIN_ROOT__ into the cache copy's absolute path. The repo's
+# checked-in hooks.json keeps the placeholder; only the cached copy is
+# rewritten at install time.
+HOOKS_JSON="$CACHE_DIR/hooks/hooks.json"
+if [ -f "$HOOKS_JSON" ]; then
+ CACHE_ESC="$(printf '%s' "$CACHE_DIR" | sed -e 's/[\\/&]/\\&/g')"
+ sed -i.bak -e "s/__OPENVIKING_PLUGIN_ROOT__/$CACHE_ESC/g" "$HOOKS_JSON"
+ rm -f "${HOOKS_JSON}.bak"
+fi
+
if [ ! -f "$HOME/.openviking/ovcli.conf" ]; then
cat >&2 <<'EOF'