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(codex-doctor): accept [features] hooks = true in modern Codex (#4634) (#4635)
Xinmin Zeng9c31b110766a
diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.ymlindex fa4a80025..e43589824 100644--- a/.github/workflows/pr.yml+++ b/.github/workflows/pr.yml@@ -38,6 +38,7 @@ jobs:examples/codex-memory-plugin/scripts/capture-utils.test.mjs \examples/codex-memory-plugin/scripts/marketplace.test.mjs \examples/codex-memory-plugin/scripts/ov-credentials.test.mjs \+ examples/codex-memory-plugin/scripts/ov-memory-doctor.test.mjs \examples/codex-memory-plugin/scripts/recall-compressor-profile.test.mjs \examples/codex-memory-plugin/scripts/auto-recall.test.mjs \examples/codex-memory-plugin/scripts/session-start-commit.test.mjs \diff --git a/examples/codex-memory-plugin/README.md b/examples/codex-memory-plugin/README.mdindex 4e02cdd32..c024a13f6 100644--- a/examples/codex-memory-plugin/README.md+++ b/examples/codex-memory-plugin/README.md@@ -69,7 +69,8 @@ Then enable plugin hooks (if your Codex build doesn't already) by adding to `~/.```toml[features]-plugin_hooks = true+hooks = true+# plugin_hooks = true # for older Codex releases```Finally start Codex and trust the plugin hooks once:diff --git a/examples/codex-memory-plugin/scripts/ov-memory-doctor.mjs b/examples/codex-memory-plugin/scripts/ov-memory-doctor.mjsindex 08c4011f8..c44ff35f7 100644--- a/examples/codex-memory-plugin/scripts/ov-memory-doctor.mjs+++ b/examples/codex-memory-plugin/scripts/ov-memory-doctor.mjs@@ -17,7 +17,7 @@* Exit code 1 when any check fails, 0 otherwise. Never prints a full api key.*/-import { readFileSync, readdirSync, statSync } from "node:fs";+import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";import { homedir } from "node:os";import { dirname, join, resolve as resolvePath } from "node:path";import { fileURLToPath } from "node:url";@@ -142,6 +142,81 @@ function checkEnvironment(report) {return { codexOnPath: codex.ok };}+export function parseFeaturesList(stdout) {+ const map = new Map();+ if (typeof stdout !== "string") return map;+ for (const line of stdout.split(/\r?\n/)) {+ const trimmed = line.trim();+ if (!trimmed) continue;+ const parts = trimmed.split(/\s+/);+ if (parts.length >= 3) {+ const key = parts[0];+ const stateStr = parts[parts.length - 1].toLowerCase();+ const stage = parts.slice(1, -1).join(" ");+ map.set(key, {+ stage,+ enabled: stateStr === "true",+ });+ }+ }+ return map;+}++export function assessHooksFeature(features, cliFeatures = null) {+ const hooks = features?.hooks;+ const pluginHooks = features?.plugin_hooks;++ if (hooks === true) {+ return { status: "ok", message: "[features] hooks = true" };+ }+ if (hooks === false) {+ return {+ status: "fail",+ message: `hooks disabled in [features] (hooks=${hooks ?? "unset"}, plugin_hooks=${pluginHooks ?? "unset"})`,+ detail: "no plugin hook fires when hooks feature is disabled",+ fix: "set hooks = true under [features] in ~/.codex/config.toml",+ };+ }++ if (cliFeatures instanceof Map) {+ const liveHooks = cliFeatures.get("hooks");+ if (liveHooks?.enabled === true) {+ return {+ status: "ok",+ message: `[features] hooks enabled by default (Codex stage: ${liveHooks.stage || "stable"})`,+ };+ }+ if (liveHooks?.enabled === false) {+ return {+ status: "fail",+ message: "hooks feature is disabled in Codex",+ detail: "Codex reports hooks feature effective state is false",+ fix: "set hooks = true under [features] in ~/.codex/config.toml",+ };+ }+ }++ // Legacy config only applies when the modern feature cannot be determined.+ if (pluginHooks === true) {+ return { status: "ok", message: "[features] plugin_hooks = true (legacy; modern Codex uses hooks = true)" };+ }+ if (pluginHooks === false) {+ return {+ status: "fail",+ message: "hooks disabled in [features] (plugin_hooks=false)",+ detail: "legacy plugin hooks are explicitly disabled",+ fix: "set plugin_hooks = true for older Codex, or hooks = true for modern Codex under [features] in ~/.codex/config.toml",+ };+ }++ return {+ status: "info",+ message: "[features] hooks is not set (modern Codex enables hooks by default; older Codex needs plugin_hooks = true)",+ detail: "if hooks do not fire, verify with `codex features list` or add hooks = true",+ fix: "add hooks = true under [features] in ~/.codex/config.toml (or plugin_hooks = true for older Codex)",+ };+}+function checkInstall(report, { codexOnPath }) {report.section("Plugin install");const manifest = tryJson(join(PLUGIN_ROOT, ".codex-plugin", "plugin.json"));@@ -210,9 +285,26 @@ function checkInstall(report, { codexOnPath }) {if (!toml) {report.warn(`${homeShort(CODEX_CONFIG)} not found`, "Codex has never been configured on this machine");} else {- const hooksOn = toml.features?.plugin_hooks;- if (hooksOn === true) report.ok("[features] plugin_hooks = true");- else report.fail(`[features] plugin_hooks is ${hooksOn === undefined ? "not set" : hooksOn}`, "no plugin hook fires at all", `add plugin_hooks = true under [features] in ${homeShort(CODEX_CONFIG)}`);+ let cliFeatures = null;+ if (codexOnPath) {+ const featRes = runCommand("codex", ["features", "list"], { timeoutMs: 5000 });+ if (featRes.ok) cliFeatures = parseFeaturesList(featRes.stdout);+ }++ const hooksAssessment = assessHooksFeature(toml.features, cliFeatures);+ if (hooksAssessment.status === "ok") {+ report.ok(hooksAssessment.message);+ } else if (hooksAssessment.status === "warn") {+ report.warn(hooksAssessment.message, hooksAssessment.detail, hooksAssessment.fix?.replace("~/.codex/config.toml", homeShort(CODEX_CONFIG)));+ } else if (hooksAssessment.status === "info") {+ report.info(hooksAssessment.message);+ } else {+ report.fail(+ hooksAssessment.message,+ hooksAssessment.detail,+ hooksAssessment.fix?.replace("~/.codex/config.toml", homeShort(CODEX_CONFIG)),+ );+ }const pluginSection = toml[`plugins."${PLUGIN_ID}"`];if (!pluginSection) report.warn(`no [plugins."${PLUGIN_ID}"] section`, "the installer normally writes enabled = true here");else if (pluginSection.enabled === false) report.fail(`[plugins."${PLUGIN_ID}"] enabled = false`, "", "set enabled = true");@@ -432,7 +524,7 @@ function checkActivity(report, cfg, connection) {const log = scanDebugLog(cfg.debugLogPath);if (!log.exists) {- report.info(`no hook log at ${homeShort(cfg.debugLogPath)}${cfg.debug ? " — debug is on but no hook has run since; if a Codex turn ran, hooks are not being spawned (plugin_hooks, trust, node)" : ""}`);+ report.info(`no hook log at ${homeShort(cfg.debugLogPath)}${cfg.debug ? " — debug is on but no hook has run since; if a Codex turn ran, hooks are not being spawned (hooks, trust, node)" : ""}`);} else {report.info(`hook log ${homeShort(log.path)} — ${fmtBytes(log.size)}, last write ${fmtAge(log.mtimeMs)}, hooks seen: ${log.hooks.join(", ") || "(none)"}`);if (log.proxyStart?.data?.mcpUrl) {@@ -487,7 +579,18 @@ async function main() {process.exitCode = report.exitCode();}-main().catch((err) => {- console.error("ov-memory-doctor failed:", err?.stack || err?.message || err);- process.exit(2);-});+function isDirectRun() {+ if (!process.argv[1]) return false;+ try {+ return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));+ } catch {+ return resolvePath(process.argv[1]) === fileURLToPath(import.meta.url);+ }+}++if (isDirectRun()) {+ main().catch((err) => {+ console.error("ov-memory-doctor failed:", err?.stack || err?.message || err);+ process.exit(2);+ });+}diff --git a/examples/codex-memory-plugin/scripts/ov-memory-doctor.test.mjs b/examples/codex-memory-plugin/scripts/ov-memory-doctor.test.mjsnew file mode 100644index 000000000..524f752dd--- /dev/null+++ b/examples/codex-memory-plugin/scripts/ov-memory-doctor.test.mjs@@ -0,0 +1,102 @@+import test from "node:test";+import assert from "node:assert/strict";++import { assessHooksFeature, parseFeaturesList } from "./ov-memory-doctor.mjs";++test("parseFeaturesList: parses standard codex features list output", () => {+ const sample = `+hooks stable true+plugin_hooks removed false+plugins stable true+apply_patch_preserve_line_endings under development false+`;+ const map = parseFeaturesList(sample);+ assert.equal(map.size, 4);+ assert.deepEqual(map.get("hooks"), { stage: "stable", enabled: true });+ assert.deepEqual(map.get("plugin_hooks"), { stage: "removed", enabled: false });+ assert.deepEqual(map.get("plugins"), { stage: "stable", enabled: true });+ assert.deepEqual(map.get("apply_patch_preserve_line_endings"), { stage: "under development", enabled: false });+});++test("assessHooksFeature: modern Codex with explicit hooks = true in toml", () => {+ const res = assessHooksFeature({ hooks: true });+ assert.equal(res.status, "ok");+ assert.equal(res.message, "[features] hooks = true");+});++test("assessHooksFeature: legacy Codex with explicit plugin_hooks = true in toml", () => {+ const res = assessHooksFeature({ plugin_hooks: true });+ assert.equal(res.status, "ok");+ assert.match(res.message, /\[features\] plugin_hooks = true \(legacy/);+});++test("assessHooksFeature: both hooks = true and plugin_hooks = true in toml", () => {+ const res = assessHooksFeature({ hooks: true, plugin_hooks: true });+ assert.equal(res.status, "ok");+ assert.equal(res.message, "[features] hooks = true");+});++test("assessHooksFeature: hooks explicitly false in toml", () => {+ const res = assessHooksFeature({ hooks: false });+ assert.equal(res.status, "fail");+ assert.match(res.message, /hooks disabled in \[features\]/);+ assert.match(res.fix, /set hooks = true/);+});++test("assessHooksFeature: explicit hooks overrides legacy config and live state", () => {+ for (const hooks of [true, false]) {+ const cliFeatures = new Map([["hooks", { stage: "stable", enabled: !hooks }]]);+ const res = assessHooksFeature({ hooks, plugin_hooks: !hooks }, cliFeatures);+ assert.equal(res.status, hooks ? "ok" : "fail");+ assert.match(res.message, hooks ? /\[features\] hooks = true/ : /hooks disabled in \[features\]/);+ }+});++test("assessHooksFeature: live hooks overrides conflicting legacy config", () => {+ for (const enabled of [true, false]) {+ const cliFeatures = new Map([["hooks", { stage: "stable", enabled }]]);+ const res = assessHooksFeature({ plugin_hooks: !enabled }, cliFeatures);+ assert.equal(res.status, enabled ? "ok" : "fail");+ assert.match(res.message, enabled ? /hooks enabled by default/ : /hooks feature is disabled in Codex/);+ }+});++test("assessHooksFeature: legacy config applies when CLI has no modern hooks entry", () => {+ for (const enabled of [true, false]) {+ const cliFeatures = new Map([["plugin_hooks", { stage: "experimental", enabled }]]);+ const res = assessHooksFeature({ plugin_hooks: enabled }, cliFeatures);+ assert.equal(res.status, enabled ? "ok" : "fail");+ assert.match(res.message, /plugin_hooks/);+ }+});++test("assessHooksFeature: plugin_hooks explicitly false in toml", () => {+ const res = assessHooksFeature({ plugin_hooks: false });+ assert.equal(res.status, "fail");+ assert.match(res.message, /hooks disabled in \[features\]/);+});++test("assessHooksFeature: unset in toml, but CLI probe reports hooks enabled (stable default)", () => {+ const cliFeatures = new Map([["hooks", { stage: "stable", enabled: true }]]);+ const res = assessHooksFeature({}, cliFeatures);+ assert.equal(res.status, "ok");+ assert.match(res.message, /hooks enabled by default \(Codex stage: stable\)/);+});++test("assessHooksFeature: unset in toml, but CLI probe reports hooks disabled", () => {+ const cliFeatures = new Map([["hooks", { stage: "under development", enabled: false }]]);+ const res = assessHooksFeature({}, cliFeatures);+ assert.equal(res.status, "fail");+ assert.match(res.message, /hooks feature is disabled in Codex/);+});++test("assessHooksFeature: unset in toml and CLI probe unavailable (fallback to info)", () => {+ const resEmpty = assessHooksFeature({}, null);+ assert.equal(resEmpty.status, "info");+ assert.match(resEmpty.message, /\[features\] hooks is not set/);+ assert.match(resEmpty.fix, /hooks = true/);++ const resUndef = assessHooksFeature(undefined, null);+ assert.equal(resUndef.status, "info");+ assert.match(resUndef.message, /\[features\] hooks is not set/);+});diff --git a/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md b/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.mdindex 156a5cd95..a6ebb537a 100644--- a/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md+++ b/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md@@ -19,7 +19,7 @@ Troubleshooting for the OpenViking memory plugin. Three things gowrong on a user's machine, each silently:- **Install** — marketplace registration, `[plugins."openviking-memory@openviking"]`- and `[features] plugin_hooks` in `~/.codex/config.toml`, per-hook trust+ and `[features] hooks` (or legacy `plugin_hooks`) in `~/.codex/config.toml`, per-hook trustrecords, the stdio MCP proxy. When these are wrong, hooks never run andnothing is logged anywhere.- **Configuration** — `~/.openviking/ovcli.conf`, `~/.openviking/ov.conf` and@@ -75,7 +75,9 @@ Work top-down; fix the first ✗ and rerun before chasing the next.|---|---|---|| `ovcli.conf cannot be parsed` / `no usable config` | Trailing comma/comment; the plugin treats the file as absent and uses the localhost default | Fix the JSON. Fresh machine: create `~/.openviking/ovcli.conf` with `url` + `api_key`, `chmod 600`. || `codex plugin list does not show …` | Plugin never installed, or installed under an old id | Re-run the one-line installer (`bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) --harness codex`; add `--dist tos` where GitHub is blocked). |-| `[features] plugin_hooks is not set/false` | Codex never runs plugin hooks | Add `plugin_hooks = true` under `[features]` in `~/.codex/config.toml`, restart Codex. |+| `hooks disabled in [features]` / `hooks feature is disabled in Codex` | The applicable hooks feature is disabled | Set `hooks = true` under `[features]` in `~/.codex/config.toml` (or `plugin_hooks = true` for older Codex), restart Codex. |+| `[features] hooks enabled by default` | The live CLI reports hooks enabled; legacy `plugin_hooks` has no effect | Continue with the remaining checks. |+| `[features] hooks is not set` (info) | The CLI probe could not determine the modern feature state and no legacy flag decides it | Verify with `codex features list`; an unset key alone does not prove hooks are disabled. || `[plugins."…"] enabled = false` / `installed but disabled` | Plugin switched off in config.toml | Set `enabled = true`, restart Codex. || `hooks disabled in [hooks.state]` | A hook was declined at the trust prompt | Remove `enabled = false` from that `[hooks.state."openviking-memory@openviking:hooks/hooks.json:<event>:0:0"]` section; approve the hook again. || `hooks without a trust record yet` | Codex has not yet approved those hooks (fresh install or `hooks.json` changed on update) | Start a Codex session and accept the hook prompt; nothing is wrong. |@@ -110,7 +112,7 @@ More symptoms, exact error strings and log stage names: [reference.md](referenceProve hooks run at all: put `OPENVIKING_DEBUG=1` in the environment thatlaunches Codex, run one turn, then read `~/.openviking/logs/codex-hooks.log`(JSONL; grep `"error"`). An absent or unchanged log after a full turn means the-hooks were not spawned — a `plugin_hooks` / trust / node problem, not a server+hooks were not spawned — a hooks / trust / node problem, not a serverproblem. `~/.openviking/logs/cc-hooks.log` belongs to the Claude Code plugin.Prove the key and identity by hand (`Bearer` is case-sensitive with exactly onediff --git a/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.md b/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.mdindex 2fa9288a4..d972be84d 100644--- a/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.md+++ b/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.md@@ -14,7 +14,7 @@ and `CODEX_CONFIG_FILE` relocate individual pieces.| `~/.openviking/ovcli.conf.<name>` | Saved CLI profiles (`ov config switch` copies one over `ovcli.conf`). `ovcli.conf.bak.<epoch>` are installer backups. || `<repo root>/.openviking/config.json` / `config.local.json` | Workspace config layers, `version: 1` required: `peer.source`, `peer.id`, `recall.*`, `capture.*`, `bypass.session_patterns`, `labels`. `config.json` is committed and shared; `config.local.json` is private and gitignored. Trusted without a prompt, but connection and credential keys (`url`, `api_key`, `account`, `user`, `extra_headers`, …) are stripped with a warning and `${VAR}` is never expanded. A blanket `.openviking/` rule in `.gitignore` stops `config.json` from ever being committed — narrow it to `.openviking/media/` and `.openviking/downloads/`. || `~/.openviking/workspaces/<slot>.json` | Per-machine workspace registry, one file per workspace (`<dir name>-<hash>.json`, mode 0600). Outranks both workspace files, and nothing writes it — a user creates the file by hand. An entry recorded for a different repository is ignored, not inherited. |-| `~/.codex/config.toml` | `[features] plugin_hooks`, `[plugins."openviking-memory@openviking"] enabled`, `[marketplaces.openviking]` (source, ref), `[hooks.state."openviking-memory@openviking:hooks/hooks.json:<event>:0:0"] trusted_hash` for `session_start`, `user_prompt_submit`, `stop`, `session_end`, `pre_compact`. |+| `~/.codex/config.toml` | `[features] hooks` (or legacy `plugin_hooks`), `[plugins."openviking-memory@openviking"] enabled`, `[marketplaces.openviking]` (source, ref), `[hooks.state."openviking-memory@openviking:hooks/hooks.json:<event>:0:0"] trusted_hash` for `session_start`, `user_prompt_submit`, `stop`, `session_end`, `pre_compact`. || `~/.codex/plugins/cache/openviking/openviking-memory/<version>/` | The copy Codex runs hooks from. Keyed by `plugin.json` version. || `~/.codex/.tmp/marketplaces/openviking/` | Git clone of the marketplace (GitHub/TOS dist); `examples/codex-memory-plugin` inside it is what `codex plugin list` reports as the source path. || `~/.openviking/codex-plugin-state/<session_id>.json` | Per-session state: `ovSessionId` (`cx-<session_id>`, null once committed), `transcriptPath` (last rollout seen, used by the SessionStart sweep to catch up unsent turns), `capturedTurnCount`, `lastUpdatedAt`. |@@ -59,6 +59,11 @@ mode only), `X-OpenViking-Actor-Peer`, `User-Agent: openviking-memory-codex/<verThe open-source server also accepts `X-API-Key` (and prefers it when both aresent); the Volcengine-hosted OpenViking Service (`https://api.vikingdb.cn-beijing.volces.com/openviking`) accepts Bearer only.+The doctor checks explicit `features.hooks` first, then the live `hooks` entry+from `codex features list`. Legacy `plugin_hooks` only decides the result when+neither supplies a modern feature state. An unavailable probe with no configured+flag is informational; a live enabled result needs no configuration change.+## Peer: giving a directory its own memory```json@@ -178,7 +183,7 @@ reports `unknown command`.| Symptom | Likely cause | Detect | Fix ||---|---|---|---|-| Plugin listed and enabled, but no `<openviking-context>` ever, no log | `plugin_hooks` off, hooks never trusted, or no parseable config | doctor Plugin install + Configuration sections | Enable hooks / approve the prompt / fix config |+| Plugin listed and enabled, but no `<openviking-context>` ever, no log | `hooks` / `plugin_hooks` off, hooks never trusted, or no parseable config | doctor Plugin install + Configuration sections | Enable hooks / approve the prompt / fix config || Worked until an edit to `ovcli.conf` | JSON broken by the edit | doctor "cannot be parsed" | Fix JSON || Edits to `ovcli.conf` or `ov config switch` have no effect | Env var or rc-file export wins (`credential source: env`) | doctor "← env"; `env \| grep OPENVIKING_` | Remove the export || Recall empty on a healthy server | Wrong key (401 reads as no results), wrong user space, peer scope, threshold | `/health` with key; `/api/v1/system/status` → `result.user` | Fix key; `OPENVIKING_PEER_ID`; lower `OPENVIKING_SCORE_THRESHOLD` |