Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
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.mdindex 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.mdnew file mode 100644index 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` setupdiff --git a/docs/en/agent-integrations/04-other-plugins.md b/docs/en/agent-integrations/04-other-plugins.mddeleted file mode 100644index 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.mdnew file mode 100644index 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.mdsimilarity index 100%rename from docs/en/agent-integrations/05-langchain-langgraph.mdrename to docs/en/agent-integrations/06-langchain-langgraph.mddiff --git a/docs/zh/agent-integrations/01-overview.md b/docs/zh/agent-integrations/01-overview.mdindex 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.mdnew file mode 100644index 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.mdsimilarity index 64%rename from docs/zh/agent-integrations/04-other-plugins.mdrename to docs/zh/agent-integrations/05-other-plugins.mdindex 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.mdsimilarity index 97%rename from docs/zh/agent-integrations/05-langchain-langgraph.mdrename to docs/zh/agent-integrations/06-langchain-langgraph.mdindex 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.jsonindex 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.jsonindex 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.mdindex 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```bashINSTALL_DIR=~/.codex/plugins/cache/openviking-plugins-local/openviking-memorymkdir -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 OpenVikingdiff --git a/examples/codex-memory-plugin/VERIFICATION.md b/examples/codex-memory-plugin/VERIFICATION.mdindex 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 thehook scripts change. Takes ~3 minutes; the only async wait is OV's memorydiff --git a/examples/codex-memory-plugin/hooks/hooks.json b/examples/codex-memory-plugin/hooks/hooks.jsonindex 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.jsonindex 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.jsonindex 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.mjsindex 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.shindex 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 pipefailREPO_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" ]; thenecho "$REPO_DIR exists but is not a git checkout." >&2exit 1fi- 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_HEADfiPLUGIN_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" ]; thencat >&2 <<'EOF'