Document Codex + claude-mem v13.8.0 connection workaround

[pitimon]

Summary

Connecting claude-mem v13.8.0 into Codex worked only after several undocumented compatibility/workaround steps. The final state is healthy, but the path was not discoverable from the upstream docs/issues, so this should be captured as a runbook or fixed in the plugin packaging.

Environment

• Host: macOS workstation
• Codex workspace: /Users/itarun/mgmt-pve
• Plugin source/marketplace: claude-mem@claude-mem-local
• Installed plugin version: 13.8.0
• Related prior fixes: issue Document claude-mem suppressOutput cache hotfix procedure #5/Codex hook config fails to parse when top-level description is present #6-style Codex hook compatibility fixes

What was missing

A normal install/enable was not enough to produce a clean Codex runtime. We had to patch multiple live roots and packaging details manually before a fresh Codex session could load the memory tools cleanly.

The undocumented/manual pieces were:

• pin/install claude-mem@claude-mem-local at v13.8.0 for Codex
• add/enable the mcp-search integration
• add .install-version
• add scripts/codex-hook-output-filter.js
• remove the top-level description field from hooks/codex-hooks.json
• make plugin-owned version-check.js return Codex hook JSON
• pipe worker start output through the hook output filter
• make PreToolUse fail open as a no-op
• apply the same compatibility fixes across all active roots, not only one cache:
  • Codex marketplace snapshot
  • Codex versioned cache
  • Claude cache
  • Claude marketplace

Observed final working state

After the workaround, validation passed:

codex plugin list
claude-mem@claude-mem-local  installed, enabled  13.8.0

curl http://127.0.0.1:37701/health
{"status":"ok", ...}

Additional validation from a fresh Codex session:

• mcp-search was enabled/running
• worker health was ok on 127.0.0.1:37701
• helper verify --json returned ok=true
• direct hook smoke tests returned continue without suppressOutput
• context probe injected recent mgmt-pve context
• lifecycle smokes returned Ready. / Done. with no Failed lines
• current interactive Codex session exposes mcp__mcp_search.search, timeline, and get_observations

Expected upstream outcome

Please add one of these upstream artifacts:

1. a documented Codex install/upgrade runbook for claude-mem v13.8.0, including all compatibility steps and validation commands, or
2. a packaging fix so those steps are applied automatically during install/upgrade, with a smoke-test command that confirms Codex can load the MCP tools.

The most important requirement is that future agents should not have to rediscover the multi-root patching and hook-output behavior by trial and error.

[pitimon]

Upstream implementation hints for future claude-mem version updates

For future claude-mem upgrades, Codex should not require agents to rediscover and hand-patch the connection path. A good upstream fix would make the Codex integration self-healing and testable.

Suggested direction:

1. Ship a Codex-specific compatibility installer/migration

   • Add an idempotent command such as claude-mem codex repair or claude-mem codex doctor --fix.
   • It should detect every active root that Codex may load from: marketplace snapshot, versioned cache, installed plugin path, and any Claude-side cache that still participates in hooks/MCP.
   • It should apply required migrations once and record the applied plugin version, e.g. via .install-version or a structured state file.

2. Make hook output schema a contract test

   • Add fixtures for Codex hook events and assert stdout is valid Codex hook JSON only.
   • Specifically test that legacy fields like suppressOutput never leak into Codex hook responses.
   • Test SessionStart, worker startup, PreToolUse, and lifecycle hooks independently.
   • Prefer fail-open behavior for memory hooks so a memory plugin cannot block normal Codex tool use.

3. Move compatibility shims into packaged source, not local patches

   • codex-hook-output-filter.js, version-check.js Codex JSON behavior, and worker-start output filtering should live in the released plugin package.
   • The package should not require users to manually remove invalid fields such as top-level description in hooks/codex-hooks.json after install.

4. Add a single validation command that proves Codex can see memory tools

   • Example expected checks:
     • plugin is installed, enabled at the expected version
     • local worker health is ok
     • mcp-search is enabled/running
     • hook smoke returns {"continue":true} or the current Codex-compatible equivalent
     • a fresh Codex process can expose mcp__mcp_search.search, timeline, and get_observations
     • a context probe can inject recent project context

5. Document a compatibility matrix

   • Track claude-mem version, Codex plugin schema assumptions, hook JSON schema expectations, and required MCP names.
   • Include upgrade notes when any of those contracts change.

6. Avoid relying on one active path

   • The most fragile part was assuming there is one plugin root. In practice the workstation had multiple roots/caches that could affect runtime behavior.
   • Upstream tooling should enumerate and print the roots it inspected, patched, skipped, and verified.

The target experience should be: after a claude-mem version bump, run one repair/doctor command, restart Codex, and get deterministic proof that memory tools are available without manual cache surgery.

[pitimon]

2026-06-22 follow-up: Codex runtime upgraded to follow Claude claude-mem v13.8.0

This records the completed live fix/QA path after the mismatch was found: Claude already had claude-mem 13.8.0 available, but Codex was still actively loading claude-mem@claude-mem-local 13.6.2.

Root cause confirmed

• codex plugin list was the live truth source for Codex and reported the active plugin as 13.6.2.
• Claude-side cache/marketplace already contained 13.8.0.
• The 13.8.0 upstream hooks/codex-hooks.json still needed Codex compatibility fixes: remove top-level description, pipe worker hook output through codex-hook-output-filter.js, strip duplicate SessionStart systemMessage when hookSpecificOutput.additionalContext exists, make startup/version-check output Codex-JSON-safe, and patch every live root rather than one cache only.

Fix inventory

1. Backed up previous Codex marketplace snapshot:
   • /Users/itarun/.codex/local-marketplaces/backups/claude-mem-local-before-13.8.0-20260622T105213+0700
2. Synced Claude cache 13.8.0 into Codex active/cache roots:
   • /Users/itarun/.codex/local-marketplaces/claude-mem-local/plugin
   • /Users/itarun/.codex/plugins/cache/claude-mem-local/claude-mem/13.8.0
3. Updated metadata and .install-version so these roots all report 13.8.0:
   • Codex active plugin
   • Codex versioned cache
   • Claude versioned cache
   • Claude marketplace plugin
4. Created reusable repo overlay:
   • overlays/claude-mem/13.8.0/.install-version
   • overlays/claude-mem/13.8.0/hooks/codex-hooks.json
   • overlays/claude-mem/13.8.0/scripts/codex-hook-output-filter.js
   • overlays/claude-mem/13.8.0/README.md
5. Hardened scripts/claude-mem-codex-compat.cjs so future verification fails on unfiltered Codex worker hook commands and smoke-tests the SessionStart context output shape.
6. Added local CHANGES.log handoff entry for multi-agent continuity.

Current live state

codex plugin list
claude-mem@claude-mem-local  installed, enabled  13.8.0  /Users/itarun/.codex/local-marketplaces/claude-mem-local/plugin

All checked .install-version files now report:

{"version":"13.8.0"}

Validation evidence

claude-mem-codex-compat.cjs verify --json:

{
  "ok": true,
  "errors": [],
  "warnings": [],
  "hookSmokes": [
    { "event": "filter", "ok": true, "keys": ["continue"] },
    { "event": "context", "ok": true, "keys": ["hookSpecificOutput"] },
    { "event": "file-context", "ok": true, "keys": ["continue"] },
    { "event": "observation", "ok": true, "keys": ["continue"] }
  ]
}

Direct active SessionStart context probe:

• exit code: 0
• stdout: one JSON line
• keys: hookSpecificOutput
• hasSystemMessage=false
• hasAdditionalContext=true
• hasSuppressOutput=false
• stderr empty

Direct hook smokes:

PreToolUse  {"keys":["continue"],"continue":true,"hasSuppressOutput":false}
PostToolUse {"keys":["continue"],"continue":true,"hasSuppressOutput":false}
Stop        {"keys":["continue"],"continue":true,"hasSuppressOutput":false}

Worker health:

{"status":"ok","activeSessions":1}

Fresh Codex lifecycle smoke:

codex exec --skip-git-repo-check --cd /Volumes/ipv9-OneT/vsCode/generals 'Reply exactly: Ready.'
hook: SessionStart
hook: SessionStart Completed
codex
Ready.
hook: Stop
hook: Stop Completed

Tool-path lifecycle smoke:

codex exec --skip-git-repo-check --cd /Volumes/ipv9-OneT/vsCode/generals 'Use the shell to run: printf Ready. Then reply exactly with the command output.'
hook: SessionStart Completed
hook: PreToolUse Completed
exec ... succeeded ... Ready.
hook: Stop Completed

No duplicate startup warning block was emitted in either lifecycle smoke.

Repo state after fix

Working tree items to commit/review:

 M overlays/claude-mem/13.6.2/hooks/codex-hooks.json
 M scripts/claude-mem-codex-compat.cjs
?? overlays/claude-mem/13.8.0/

Suggested close criteria:

• commit the 13.8.0 overlay and verifier hardening
• add/keep a documented command sequence for inspect, verify, direct context probe, worker health, and fresh codex exec lifecycle smoke
• decide whether this issue should remain open for upstream packaging automation or close once the repo-local runbook/overlay is merged