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
fix(plugin/codex): default-on assistant capture, recommend env vars over ov.conf for tuning (#2065)
t0saki42484bf91d0b
diff --git a/docs/en/agent-integrations/04-codex.md b/docs/en/agent-integrations/04-codex.mdindex a5ccbc642..991adca52 100644--- a/docs/en/agent-integrations/04-codex.md+++ b/docs/en/agent-integrations/04-codex.md@@ -84,7 +84,7 @@ Resolution priority for every connection / identity field — env vars always wi1. **Environment variables** (`OPENVIKING_*`)2. **`ovcli.conf`** — `~/.openviking/ovcli.conf` or `OPENVIKING_CLI_CONFIG_FILE`-3. **`ov.conf`** — `~/.openviking/ov.conf` or `OPENVIKING_CONFIG_FILE` (`server.*` + optional `codex.*` tuning block)+3. **`ov.conf`** — `~/.openviking/ov.conf` or `OPENVIKING_CONFIG_FILE` (only `server.url` / `server.root_api_key` as connection fallback; a legacy `codex.*` tuning block is still honored but deprecated — see [Tuning](#tuning))4. **Built-in defaults** (`http://127.0.0.1:1933`, unauthenticated)Hooks resolve this chain on every fire (changes to ovcli.conf take effect on the next hook). The MCP server URL is baked into `.mcp.json` at install time (changing the URL requires a re-install); the API key is read fresh from env on every codex launch via `bearer_token_env_var`, so rotating `OPENVIKING_API_KEY` in ovcli.conf only requires a codex restart, not a re-install.@@ -106,22 +106,21 @@ For **unauthenticated local OV** (`ovcli.conf` without `api_key`, or no ovcli.co| `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- }-}+### Tuning++Plugin tuning is set via `OPENVIKING_*` environment variables in your shell rc — they take effect on every codex launch.++```sh+# ~/.zshrc+export OPENVIKING_RECALL_LIMIT=6+export OPENVIKING_CAPTURE_ASSISTANT_TURNS=1+export OPENVIKING_AUTO_COMMIT_ON_COMPACT=1+export OPENVIKING_DEBUG=1```-The full field list is in the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#configuration).+The full field list is in the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin).++> **Legacy `codex.*` block**: earlier versions read tuning fields from a `codex` block in `~/.openviking/ov.conf`; that still works for backward compat. But codex is a client-side plugin and per-machine tuning doesn't belong in a server-scope `ov.conf` — new deployments should prefer env vars.## Hook behavior@@ -157,7 +156,7 @@ The plugin wires Codex up to OpenViking's built-in `/mcp` endpoint via streamabl| Hook runs but recall returns nothing | OpenViking server unreachable or wrong URL | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` || Remote auth 401/403 from hooks but MCP works (or vice versa) | env vs ovcli.conf mismatch | Hooks re-read ovcli.conf every fire; MCP reads env only at codex start. Restart codex if you changed env. |-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`.+Verbose debug logging: set `OPENVIKING_DEBUG=1` (or legacy `codex.debug=true` in `ov.conf`) to write JSON-Lines events to `~/.openviking/logs/codex-hooks.log`.## Differences from the Claude Code plugindiff --git a/docs/zh/agent-integrations/04-codex.md b/docs/zh/agent-integrations/04-codex.mdindex 9e357d11a..9b5e2658b 100644--- a/docs/zh/agent-integrations/04-codex.md+++ b/docs/zh/agent-integrations/04-codex.md@@ -83,7 +83,7 @@ installer 替你做的三件事,你也可以自己手动做:1. **环境变量**(`OPENVIKING_*`)2. **`ovcli.conf`** — `~/.openviking/ovcli.conf` 或 `OPENVIKING_CLI_CONFIG_FILE`-3. **`ov.conf`** — `~/.openviking/ov.conf` 或 `OPENVIKING_CONFIG_FILE`(顶层 `server.*` + 可选的 `codex.*` 调参块)+3. **`ov.conf`** — `~/.openviking/ov.conf` 或 `OPENVIKING_CONFIG_FILE`(只用 `server.url` / `server.root_api_key` 当连接 fallback;`codex.*` 调参块仍被读取但已废弃,见下面 [调参](#调参))4. **内置默认值**(`http://127.0.0.1:1933`,无鉴权)Hook 每次触发都重新解析这条优先级链——改完 ovcli.conf 下一次 hook 立即生效。MCP server URL 在 install 时固化进 `.mcp.json`(改 URL 要重跑 installer),但 API key 通过 `bearer_token_env_var` 在 codex 启动时从 env 读,所以**轮换 API key 只需重启 codex,不必重装**。@@ -105,22 +105,21 @@ Hook 每次触发都重新解析这条优先级链——改完 ovcli.conf 下一| `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- }-}+### 调参++调参用 `OPENVIKING_*` 环境变量,写进 shell rc 即可。每次 codex 启动都生效。++```sh+# ~/.zshrc+export OPENVIKING_RECALL_LIMIT=6+export OPENVIKING_CAPTURE_ASSISTANT_TURNS=1+export OPENVIKING_AUTO_COMMIT_ON_COMPACT=1+export OPENVIKING_DEBUG=1```-完整字段列表见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#configuration)。+完整字段列表见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin)。++> **遗留 `codex.*` 块**:早期版本支持把调参字段放在 `~/.openviking/ov.conf` 的 `codex` 块下,仍向后兼容。但 codex 是 client 侧插件,per-machine 的调参不该住在 server-scope 的 `ov.conf` 里——新部署请用环境变量。## Hook 行为@@ -156,7 +155,7 @@ Hook 每次触发都重新解析这条优先级链——改完 ovcli.conf 下一| Hook 触发但召回为空 | OpenViking 服务器不可达或 URL 不对 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` || Hook 401/403 但 MCP 工具可用,或反之 | env vs ovcli.conf 不一致 | Hook 每次都重读 ovcli.conf,MCP 只在 codex 启动读 env。改完 env 要重启 codex。 |-调试日志:设 `OPENVIKING_DEBUG=1` 或 `ovcli.conf` 里 `codex.debug=true`,会把 JSON-Lines 事件写到 `~/.openviking/logs/codex-hooks.log`。+调试日志:设 `OPENVIKING_DEBUG=1`(或老配置 `ov.conf` 里 `codex.debug=true`),会把 JSON-Lines 事件写到 `~/.openviking/logs/codex-hooks.log`。## 与 Claude Code 插件的差异diff --git a/examples/codex-memory-plugin/README.md b/examples/codex-memory-plugin/README.mdindex b3585e09c..4054c5eff 100644--- a/examples/codex-memory-plugin/README.md+++ b/examples/codex-memory-plugin/README.md@@ -88,7 +88,7 @@ Connection / identity resolution order (highest to lowest, applies to both hooks1. **Environment variables**: `OPENVIKING_URL` / `OPENVIKING_BASE_URL`, `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN`, `OPENVIKING_ACCOUNT`, `OPENVIKING_USER`, `OPENVIKING_AGENT_ID`2. **`ovcli.conf`**: `~/.openviking/ovcli.conf` or `OPENVIKING_CLI_CONFIG_FILE`-3. **`ov.conf`**: `~/.openviking/ov.conf` or `OPENVIKING_CONFIG_FILE` (`server.*` + optional `codex.*` tuning block)+3. **`ov.conf`**: `~/.openviking/ov.conf` or `OPENVIKING_CONFIG_FILE` (only `server.url` / `server.root_api_key` as connection fallback; tuning fields under a legacy `codex.*` block are honored but deprecated — see [Tuning the plugin](#tuning-the-plugin))4. **Built-in defaults**: `http://127.0.0.1:1933`, unauthenticatedThe shell function wrapper handles step 1 for you by promoting ovcli.conf fields into env vars before exec'ing codex. Hooks then re-resolve the full chain inside Node; the MCP server URL is baked into `.mcp.json` at install time and the API key flows in via `OPENVIKING_API_KEY` (referenced by `bearer_token_env_var` in `.mcp.json`).@@ -99,21 +99,24 @@ For **unauthenticated local OV** (`ovcli.conf` without `api_key`, or no ovcli.coThe `codex()` shell-function wrapper **re-renders this field on every codex launch** based on the currently-active `ovcli.conf` (the one `OPENVIKING_CLI_CONFIG_FILE` points at, falling back to `~/.openviking/ovcli.conf`). That means you can switch between authenticated and unauthenticated OV — e.g. to isolate a benchmark run from production memory — by just changing `OPENVIKING_CLI_CONFIG_FILE` before invoking `codex`, with no re-install needed. The wrapper also omits empty env-var assignments entirely (so `OPENVIKING_API_KEY=` is never passed to codex), keeping `env_http_headers` for identity (`X-OpenViking-Account` / `User` / `Agent`) intact.-Optional Codex-specific tuning lives under `codex` in `ovcli.conf`:--```jsonc-{- "url": "https://ov.example.com",- "api_key": "...",- "codex": {- "agentId": "codex",- "recallLimit": 6,- "captureAssistantTurns": false,- "autoCommitOnCompact": true- }-}+### Tuning the plugin++All plugin behavior is controlled by `OPENVIKING_*` environment variables — set them in your shell rc (`~/.zshrc` / `~/.bashrc`) so every `codex` launch picks them up. The shell-function wrapper installed alongside the plugin already exports identity vars from `ovcli.conf`; tuning vars sit next to it.++```sh+# ~/.zshrc — examples+export OPENVIKING_RECALL_LIMIT=6+export OPENVIKING_CAPTURE_ASSISTANT_TURNS=1+export OPENVIKING_AUTO_COMMIT_ON_COMPACT=1+export OPENVIKING_DEBUG=1```+Full list: see the `Misc env vars` block in `scripts/config.mjs`. Every field has a `OPENVIKING_*` counterpart and env vars always win.++#### Legacy `codex` block in `ov.conf`++Earlier plugin versions configured tuning fields under a `codex` block in `~/.openviking/ov.conf`. That still works for backward compat — every env var above has a camelCase counterpart (`OPENVIKING_RECALL_LIMIT` → `codex.recallLimit`, etc.) — but **new deployments should prefer env vars**: this is the codex CLI's per-machine plugin tuning, and the server-side `ov.conf` is the wrong place for it. (It's read from `ov.conf`, not `ovcli.conf`, by historical accident in `scripts/config.mjs`.)+## Architecture```diff --git a/examples/codex-memory-plugin/scripts/config.mjs b/examples/codex-memory-plugin/scripts/config.mjsindex 45655d510..c86607166 100644--- a/examples/codex-memory-plugin/scripts/config.mjs+++ b/examples/codex-memory-plugin/scripts/config.mjs@@ -227,7 +227,11 @@ export function loadConfig() {num(cx.captureMaxLength, 24000),))),captureTimeoutMs,- captureAssistantTurns: envBool("OPENVIKING_CAPTURE_ASSISTANT_TURNS") ?? (cx.captureAssistantTurns === true),+ // Default true: a "memory plugin" without assistant-side capture only sees half the+ // conversation, which makes extraction noticeably worse. Mirrors the claude-code plugin+ // (examples/claude-code-memory-plugin/scripts/config.mjs). Operators who want the old+ // user-only behavior can set OPENVIKING_CAPTURE_ASSISTANT_TURNS=0 or codex.captureAssistantTurns=false.+ captureAssistantTurns: envBool("OPENVIKING_CAPTURE_ASSISTANT_TURNS") ?? (cx.captureAssistantTurns !== false),captureLastAssistantOnStop: envBool("OPENVIKING_CAPTURE_LAST_ASSISTANT_ON_STOP") ?? (cx.captureLastAssistantOnStop !== false),autoCommitOnCompact: envBool("OPENVIKING_AUTO_COMMIT_ON_COMPACT") ?? (cx.autoCommitOnCompact !== false),