Document claude-mem suppressOutput cache hotfix procedure

[pitimon]

Context

On 2026-06-10, Codex startup/tool hooks failed on a workstation because the active claude-mem plugin cache still emitted the legacy suppressOutput field from bundled worker-service.cjs hook output. Codex rejects that field, so the symptom appeared as hook JSON/output failures, for example:

• PreToolUse hook returned unsupported suppressOutput
• PostToolUse hook returned unsupported suppressOutput
• Related startup symptoms such as invalid SessionStart hook JSON may indicate the same class of machine-wide hook/runtime problem and should be triaged from the active plugin runtime first.

This should be treated as a machine-wide active plugin-cache issue, not as an application repo bug.

What was learned

• Verify the active installed plugin path/version first with codex plugin list.
• Also inspect ~/.codex/config.toml for the pinned claude-mem-local ref.
• A pinned tag does not preserve local hotfixes across plugin version changes or cache refreshes.
• Patching only marketplace snapshots is insufficient; patch the active installed cache and marketplace/temp copies together.

Hotfix procedure for another workstation

1. Confirm the active version/path:

codex plugin list
rg -n "claude-mem|claude-mem-local" ~/.codex/config.toml

2. Locate the active worker-service.cjs files for the installed version. On the original workstation, the four paths were:

~/.codex/plugins/cache/claude-mem-local/claude-mem/<version>/scripts/worker-service.cjs
~/.codex/.tmp/marketplaces/claude-mem-local/plugin/scripts/worker-service.cjs
~/.claude/plugins/cache/thedotmack/claude-mem/<version>/scripts/worker-service.cjs
~/.claude/plugins/marketplaces/thedotmack/plugin/scripts/worker-service.cjs

Adjust owner/name/version segments to match codex plugin list output on the target machine.

3. Back up each file before editing.

4. Remove legacy suppressOutput output fields from each bundled/minified runtime. Patterns observed in the broken bundle included:

,suppressOutput:!0
suppressOutput:!0,
"suppressOutput":true

5. Smoke-test both hook paths through the matching version runner, using the target machine's actual paths:

# PreToolUse-style path
/path/to/bun-runner.js /path/to/worker-service.cjs hook codex file-context

# PostToolUse-style path
/path/to/bun-runner.js /path/to/worker-service.cjs hook codex observation

Both should print exactly:

{"continue":true}

If stdout still includes suppressOutput, Codex will continue rejecting the hook.

Durable fix recommendation

This cache edit is only a workstation hotfix. The durable fix should be one of:

• upstream claude-mem release that no longer emits suppressOutput for Codex hooks, or
• maintained fork/tag with this patch applied and all machines pinned to that patched ref.

After any plugin cache refresh or version bump, repeat the verification because local cache edits can be overwritten.

Acceptance criteria

• Add this process to the shared Codex/claude-mem operations notes or runbook.
• Convert the hotfix into a small reusable script if this recurs on more than one workstation.
• Track the upstream/fork fix so cache edits are no longer needed.

[pitimon]

Validated on the affected workstation.

Additional finding: codex plugin list reported the active plugin path as:

~/.codex/.tmp/marketplaces/claude-mem-local/plugin

while the installed cache also existed at:

~/.codex/plugins/cache/claude-mem-local/claude-mem/13.4.2

Patching only the installed cache fixed direct cache tests, but the procedure was not complete until the temp marketplace plugin path and Claude marketplace copy were patched too.

Patched paths:

• ~/.codex/plugins/cache/claude-mem-local/claude-mem/13.4.2
• ~/.codex/.tmp/marketplaces/claude-mem-local/plugin
• ~/.claude/plugins/marketplaces/thedotmack/plugin

Backups were created before edits with suffix .bak.20260609231323.

Validation:

• active runtime files no longer contain suppressOutput
• hook codex observation returns {"continue":true}
• hook codex file-context returns {"continue":true}
• npx claude-mem@latest doctor passes
• worker healthy on 127.0.0.1:37701

Recommendation: the reusable script should patch both the installed cache and the codex plugin list path, because they may differ.

[pitimon]

Follow-up from the 2026-06-10 recurrence: the repo documentation/overlay was correct, but the active Codex runtime roots on the workstation were stale.

Live finding:

• codex plugin list reported the active path as ~/.codex/.tmp/marketplaces/claude-mem-local/plugin.
• The active Codex temp plugin path and installed Codex cache did not have scripts/codex-hook-output-filter.js or .install-version.
• Their hooks/codex-hooks.json still called worker-service.cjs hook codex file-context / observation directly, without piping through the filter.
• Direct repro against the active Codex plugin path returned {"continue":true,"suppressOutput":true} for both PreToolUse-style file-context and PostToolUse-style observation, which explains the repeated unsupported suppressOutput hook failures.

Action taken:

• Reapplied overlays/claude-mem/13.4.2/ from commit 7634ba0 to all four live-resolvable roots:
  • ~/.codex/.tmp/marketplaces/claude-mem-local/plugin
  • ~/.codex/plugins/cache/claude-mem-local/claude-mem/13.4.2
  • ~/.claude/plugins/cache/thedotmack/claude-mem/13.4.2
  • ~/.claude/plugins/marketplaces/thedotmack/plugin
• Backups were created under .backup-overlay-20260610132643 in each patched root.

Validation after reapply:

• all four roots now contain scripts/codex-hook-output-filter.js and .install-version
• active Codex hooks/codex-hooks.json now pipes Codex hook output through codex-hook-output-filter.js
• PreToolUse-style direct smoke now returns exactly {"continue":true}
• PostToolUse-style direct smoke now returns exactly {"continue":true}

Conclusion: issue #5 still describes the right failure class. The missing piece was not repo documentation; it was that a live Codex temp/cache root had either been refreshed or never received the overlay. This reinforces the acceptance criterion for a reusable script: it should discover and patch the active codex plugin list path plus all fallback roots, then verify exact hook stdout.

[pitimon]

Updated in commit cc4b8f0 (pushed to main).

What changed:

• scripts/claude-mem-codex-compat.cjs now resolves the active runtime plugin from codex plugin list first, then falls back to the versioned Codex cache.
• Overlay application/verification now covers the active Codex path, versioned Codex cache, Codex marketplace staging roots, Claude cache, and Claude marketplace roots, with duplicate paths deduped.
• verify now checks that scripts/codex-hook-output-filter.js exists in every target root and runs exact stdout smoke checks for the filter, file-context, and observation hooks.
• The 13.4.2 filter now removes duplicate systemMessage when Codex context is already supplied via hookSpecificOutput.additionalContext.
• README/runbook/scenario-test docs now point operators at the active codex plugin list path instead of treating the cache path as the runtime source of truth.

Validation run before commit:

• node --check scripts/claude-mem-codex-compat.cjs
• node --check overlays/claude-mem/13.4.2/scripts/codex-hook-output-filter.js
• node scripts/claude-mem-codex-compat.cjs verify --json | jq '{ok, errors, activePlugin, hookSmokes}'

Result: ok=true, errors=[], active plugin resolved to ~/.codex/.tmp/marketplaces/claude-mem-local/plugin, and hook smoke events filter, file-context, and observation all returned only continue without suppressOutput.

[pitimon]

Follow-up validation from a fresh Codex session on 2026-06-13.

I tested the current main helper from commit cc4b8f0 against the workstation runtime while working from another repo (kubeSIT). The issue class is still valid, and the reusable helper is doing the right thing: it found the codex plugin list path first, included the versioned Codex cache as a target root, applied the exact 13.4.2 overlay, and verify --json passed after apply.

Observed before apply:

• Codex plugin was claude-mem@claude-mem-local version 13.4.2.
• codex plugin list reported ~/.codex/.tmp/marketplaces/claude-mem-local/plugin.
• The versioned cache also existed at ~/.codex/plugins/cache/claude-mem-local/claude-mem/13.4.2.
• Both Codex roots had matching hook hashes, but both were missing scripts/codex-hook-output-filter.js.
• node scripts/claude-mem-codex-compat.cjs verify --json correctly failed with missing filter errors for the Codex active path, Codex cache, and Claude marketplace root.

Action/validation:

• Ran node scripts/claude-mem-codex-compat.cjs apply --json from a fresh /tmp/exp-myCodex-verify clone.
• Ran node scripts/claude-mem-codex-compat.cjs verify --json immediately after.
• Result: ok=true, errors=[], and hook smokes for filter, file-context, and observation all passed.
• Post-apply hashes matched between the Codex marketplace snapshot and versioned Codex cache for hooks/codex-hooks.json, hooks/hooks.json, scripts/codex-hook-output-filter.js, and skills/standup/SKILL.md.
• npx claude-mem@latest status still reported the worker running on port 37701.

Remaining useful improvement for the runbook/helper:

• Clarify wording around activePlugin: the helper currently reports the codex plugin list path as active, while an already-running Codex session may have loaded skills/runtime context from the versioned cache path. Since the helper patches/verifies both roots, this is fine operationally, but the docs should call it codexPluginListPath or explicitly state that it is the CLI-reported active install path, not necessarily the only path a current session has loaded.
• Add a non-fatal worker health/version note to inspect/verify: in this run, the shared worker health endpoint still reported version: 13.4.0 and workerPath: ~/.claude/plugins/marketplaces/thedotmack/plugin/scripts/worker-service.cjs, while the Codex plugin roots were 13.4.2. It did not block hook verification, but it is valuable drift evidence for operators.
• Consider adding a final instruction: after apply succeeds, restart Codex before declaring startup-hook behavior fixed, because a running session may already have loaded hook definitions.

Conclusion: cc4b8f0 closes the main recurring failure path for missing filter/unsupported suppressOutput. The next refinement is mostly observability and wording: distinguish CLI-reported active path, versioned cache path, and shared worker path so future operators do not misread a healthy-but-drifted setup.

[pitimon]

สรุปภาษาไทยจากการทดสอบรอบล่าสุดวันที่ 2026-06-13

รอบนี้เอา helper ล่าสุดจาก commit cc4b8f0 มาลองกับ session Codex ที่ใช้งานจริง พบว่าแนวทางแก้ใน issue นี้ถูกทางแล้ว และ helper ใช้แก้เคสซ้ำได้จริง

สิ่งที่เจอก่อนแก้:

• Codex ใช้ claude-mem version 13.4.2
• codex plugin list ชี้ path ไปที่ ~/.codex/.tmp/marketplaces/claude-mem-local/plugin
• แต่ cache versioned ก็มีอยู่ที่ ~/.codex/plugins/cache/claude-mem-local/claude-mem/13.4.2
• ทั้งสอง root มี hook เหมือนกัน แต่ยังขาดไฟล์ scripts/codex-hook-output-filter.js
• พอรัน verify --json helper จับปัญหาได้ถูกต้องว่า filter หายจากหลาย root

สิ่งที่ทำ:

• clone repo สดไปไว้ที่ /tmp/exp-myCodex-verify
• รัน node scripts/claude-mem-codex-compat.cjs apply --json
• แล้วรัน node scripts/claude-mem-codex-compat.cjs verify --json

ผลลัพธ์:

• verify ผ่านแล้ว: ok=true, errors=[]
• smoke test ผ่านทั้ง filter, file-context, และ observation
• path ฝั่ง marketplace snapshot กับ versioned cache มี hash ตรงกันแล้วในไฟล์สำคัญ เช่น hooks, filter, และ standup skill
• claude-mem worker ยังทำงานอยู่ที่ port 37701

ข้อเสนอเพื่อทำให้งานนี้สมบูรณ์ขึ้น:

1. คำว่า activePlugin ใน helper อาจทำให้สับสน เพราะมันหมายถึง path ที่ codex plugin list รายงาน แต่ session ที่กำลังรันอยู่อาจโหลดบางส่วนจาก versioned cache แล้ว ควรเขียนใน docs ให้ชัดว่า helper จะ patch/verify หลาย root พร้อมกัน
2. ควรให้ inspect หรือ verify แสดง warning เรื่อง worker version/path drift ด้วย เช่นกรณีนี้ Codex plugin เป็น 13.4.2 แต่ worker health ยังรายงาน path/version ฝั่ง Claude marketplace เดิม
3. หลัง apply สำเร็จ ควรบอก operator ให้ restart Codex session ก่อนสรุปว่า startup hook หายขาด เพราะ session เดิมอาจโหลด hook definition ไปแล้ว

สรุป: fix ใน cc4b8f0 แก้ปัญหาหลักของ issue นี้ได้แล้ว เหลือปรับ docs/observability ให้คนอ่านเข้าใจง่ายขึ้นว่า Codex plugin path, versioned cache, marketplace snapshot, และ shared worker เป็นคนละชั้นกัน แต่ต้องตรวจร่วมกันทั้งหมด

[pitimon]

Follow-up from 2026-06-16: same failure class recurred during the 13.6.0 -> 13.6.1 transition, with one extra wrinkle from user-level Codex hooks.

User-visible symptom:

PostToolUse hook (failed)
error: hook exited with code 1

Live findings:

• The workstation had already tested/installed claude-mem 13.6.1 on the Claude side, but Codex was still pinned to ref = "v13.6.0" in ~/.codex/config.toml.
• codex plugin list reported Codex active runtime as 13.6.0 at ~/.codex/.tmp/marketplaces/claude-mem-local/plugin.
• After upgrading Codex to 13.6.1, verify --json still failed because .install-version and scripts/codex-hook-output-filter.js were missing from the live roots.
• Direct 13.6.1 worker hook smokes returned {"continue":true} for file-context, observation, context, session-init, and summarize, so the worker hook implementation itself was OK.
• The remaining failures came from the user-level /Users/itarun/.codex/hooks.json, which still pipes several hooks through scripts/codex-hook-output-filter.js. Since the file was missing from 13.6.1, these commands exited non-zero even though the raw worker hook output was valid.

Action taken:

• Updated ~/.codex/config.toml from ref = "v13.6.0" to ref = "v13.6.1".
• Ran codex plugin marketplace upgrade claude-mem-local.
• Restored .install-version as {"version":"13.6.1"} into the live Codex/Claude roots.
• Restored scripts/codex-hook-output-filter.js into all live-resolvable 13.6.1 roots:
  • ~/.codex/.tmp/marketplaces/claude-mem-local/plugin
  • ~/.codex/plugins/cache/claude-mem-local/claude-mem/13.6.1
  • ~/.claude/plugins/cache/thedotmack/claude-mem/13.6.1
  • ~/.claude/plugins/marketplaces/thedotmack/plugin

Validation:

codex plugin list
# claude-mem@claude-mem-local installed, enabled 13.6.1

node /Users/itarun/src-repo/exp-myCodex/scripts/claude-mem-codex-compat.cjs verify --json
# ok=true, errors=[], hookSmokes filter/file-context/observation all passed

Direct user-level hook command smoke for every entry in /Users/itarun/.codex/hooks.json passed with exit code 0 and {"continue":true} output for:

• SessionStart
• UserPromptSubmit
• PreToolUse
• PostToolUse
• Stop

Final lifecycle validation:

codex exec --cd /Volumes/ipv9-OneT/src-repo/Prepare-PNG_DB 'Reply exactly: Ready.'
# SessionStart Completed, UserPromptSubmit Completed, Stop Completed

codex exec --cd /Volumes/ipv9-OneT/src-repo/Prepare-PNG_DB 'Use the shell to run `printf hook-smoke`, then reply exactly: Done.'
# PreToolUse Completed
# PostToolUse Completed
# Stop Completed

Useful future improvement for this issue/helper:

1. Add a 13.6.1 overlay, or make the helper able to install the small codex-hook-output-filter.js compatibility shim generically when a user-level hook still references it.
2. Extend verify --json to inspect /Users/itarun/.codex/hooks.json, not only plugin-provided hooks/codex-hooks.json, because this recurrence was hidden in the user-level hook layer.
3. Keep the final acceptance criterion as a real lifecycle smoke that forces a tool call. A plain Reply exactly: Ready. proves startup/stop hooks, but it does not prove PostToolUse; a command-running prompt is needed to see PostToolUse Completed.

Conclusion: the recurring issue is still not just “which claude-mem version is installed.” The durable check needs to compare the Codex pin, the codex plugin list active path, all versioned cache/marketplace roots, user-level hook wrappers, and a final Codex lifecycle run that actually triggers PostToolUse.

[pitimon]

Follow-up from 2026-06-16 after the earlier 13.6.1 repair: there was one more Codex hook failure mode that the previous runbook did not capture.

User-visible symptom:

UserPromptSubmit hook (failed)
error: hook exited with code 1

Live findings:

• claude-mem@claude-mem-local was installed/enabled at 13.6.1.
• codex plugin list reported the active Codex plugin path as:
  • ~/.codex/.tmp/marketplaces/claude-mem-local/plugin
• The versioned Codex cache also existed at:
  • ~/.codex/plugins/cache/claude-mem-local/claude-mem/13.6.1
• Both active Codex roots were missing:
  • .install-version
  • scripts/codex-hook-output-filter.js
• /Users/itarun/.codex/hooks.json still piped user-level hooks through scripts/codex-hook-output-filter.js, so UserPromptSubmit could exit non-zero even though raw worker hook output was otherwise valid.
• After restoring the filter and .install-version, UserPromptSubmit passed, but one SessionStart failure remained.
• The remaining SessionStart failure was traced to the plugin-owned hooks/codex-hooks.json version-check.js hook: it exited 0 but produced empty stdout. In the Codex lifecycle this can still be reported as a failed startup hook.
• The global ~/.codex/hooks.json already runs a resilient version-check wrapper that returns {"continue":true}, so the plugin-owned duplicate version-check was redundant.

Action taken:

• Restored scripts/codex-hook-output-filter.js to:
  • ~/.codex/.tmp/marketplaces/claude-mem-local/plugin/scripts/codex-hook-output-filter.js
  • ~/.codex/plugins/cache/claude-mem-local/claude-mem/13.6.1/scripts/codex-hook-output-filter.js
• Restored .install-version with {"version":"13.6.1"} to:
  • ~/.codex/.tmp/marketplaces/claude-mem-local/plugin/.install-version
  • ~/.codex/plugins/cache/claude-mem-local/claude-mem/13.6.1/.install-version
• Also checked the Codex staging root:
  • ~/.codex/.tmp/marketplaces/.staging/marketplace-upgrade-RCVz0m/plugin
• Removed only the duplicate plugin-owned SessionStart version-check.js hook from the active/staging claude-mem-local hooks/codex-hooks.json files. The worker-start and context-loading SessionStart hooks were left in place.

Validation:

# Direct hook command smoke
# All SessionStart commands in the active Codex roots returned exit 0 and JSON stdout.

codex exec --cd /Volumes/ipv9-OneT/src-repo/Prepare-PNG_DB 'Reply exactly: OK'

Final lifecycle smoke result:

SessionStart Completed x4
UserPromptSubmit Completed x2
Stop Completed x3
no Failed entries

Additional live status after the fix:

claude-mem@claude-mem-local installed, enabled 13.6.1

Project count smoke:

{"observations":521,"prompts":89,"project":"Prepare-PNG_DB"}

Future runbook/helper improvements from this recurrence:

1. verify --json should inspect both user-level /Users/itarun/.codex/hooks.json and plugin-owned hooks/codex-hooks.json.
2. Verification should treat “exit 0 but empty stdout” as suspicious for Codex hooks that are expected to return hook JSON.
3. For SessionStart, verify the real lifecycle with codex exec, not only direct command execution, because Codex can still mark a hook failed when direct shell smoke looks clean.
4. The helper should detect duplicate version-check layers: global user hook plus plugin-owned hook. If the global hook is already resilient and returns {"continue":true}, the plugin-owned duplicate should either return JSON too or be omitted.
5. Keep patch targets broad: active codex plugin list path, versioned Codex cache, Codex staging roots, Claude cache/marketplace roots, and user-level hook wrappers.

Conclusion: the durable acceptance criterion for this issue should be: exact hook stdout checks plus a final codex exec lifecycle smoke showing SessionStart, UserPromptSubmit, tool-triggered PreToolUse/PostToolUse, and Stop all Completed with no Failed entries.

[pitimon]

Operator Checklist: Codex claude-mem Hook Failures

Use this checklist when Codex shows hook failures such as:

SessionStart hook (failed)
UserPromptSubmit hook (failed)
PreToolUse hook (failed)
PostToolUse hook (failed)
Stop hook (failed)
error: hook exited with code 1

1. Establish live runtime truth

• Run codex plugin list and record the active claude-mem-local version/path.
• Confirm the Codex plugin pin in ~/.codex/config.toml if the marketplace is pinned by ref.
• Record the CLI-reported active path, usually ~/.codex/.tmp/marketplaces/claude-mem-local/plugin.
• Record the versioned Codex cache path, usually ~/.codex/plugins/cache/claude-mem-local/claude-mem/<version>.
• Check Codex staging roots under ~/.codex/.tmp/marketplaces/.staging/*/plugin.
• Check Claude cache/marketplace roots if shared worker drift is suspected.

2. Check required files in every live root

• Verify .install-version exists and matches the installed version, for example {"version":"13.6.1"}.
• Verify scripts/codex-hook-output-filter.js exists where any hook command pipes through it.
• Verify file mode is executable for scripts/codex-hook-output-filter.js.
• If a root is missing those files, patch the active codex plugin list path and the versioned Codex cache together.
• Include staging roots if a marketplace upgrade is in progress or recently ran.

3. Inspect both hook layers

• Inspect user-level hooks: ~/.codex/hooks.json.
• Inspect plugin-owned hooks: <plugin-root>/hooks/codex-hooks.json.
• Confirm UserPromptSubmit, PreToolUse, PostToolUse, and Stop commands return valid Codex hook JSON.
• For SessionStart, check for duplicate version-check.js hooks between user-level and plugin-owned configs.
• Treat exit 0 with empty stdout as suspicious for Codex hook commands that are expected to return JSON.
• If plugin-owned version-check.js is duplicate and returns empty stdout, either wrap it to always return {"continue":true} or remove the duplicate while keeping worker-start/context hooks.

4. Direct hook smoke tests

• Run direct command smoke for every command in ~/.codex/hooks.json.
• Run direct command smoke for every command in plugin-owned hooks/codex-hooks.json.
• Require exit code 0.
• Require stdout to be valid JSON where Codex expects JSON, usually {"continue":true}.
• Confirm no unsupported fields such as raw suppressOutput leak into Codex-facing output.

5. Lifecycle acceptance tests

• Run a startup-only lifecycle smoke:

codex exec --cd /path/to/project 'Reply exactly: OK'

Expected result:

SessionStart Completed
UserPromptSubmit Completed
Stop Completed
no Failed entries

• Run a tool-triggering lifecycle smoke so PreToolUse and PostToolUse are exercised:

codex exec --cd /path/to/project 'Use the shell to run `printf hook-smoke`, then reply exactly: Done.'

Expected result:

PreToolUse Completed
PostToolUse Completed
Stop Completed
no Failed entries

6. Final status record

• Record final codex plugin list result.
• Record all patched roots.
• Record whether .install-version and codex-hook-output-filter.js exist in each root.
• Record direct hook smoke result.
• Record final codex exec lifecycle result.
• If claude-mem counts/status are available, record a project count smoke such as {"observations":...,"prompts":...,"project":"..."}.

Durable acceptance criterion

Do not call this fixed from file inspection alone. The fix is accepted only when direct hook smokes pass and a real codex exec lifecycle run shows all relevant hooks completed with no Failed entries.