Skip to main content

​
Setup

1

Start agentmemory

2

Wire MCP

The adapter detects ~/.codex/, backs up config.toml, and appends the server block. On Codex Desktop, add --with-hooks (see below).
3

Install the Codex plugin (recommended)

The plugin ships from the same plugin/ directory as the Claude Code plugin and registers the MCP server, 6 lifecycle hooks, and 17 skills.
4

Restart Codex

Codex picks up MCP servers on next launch.
5

Verify

codex mcp list should show agentmemory as enabled. Run one prompt, then check the Sessions tab at http://localhost:3113 for hook-captured observations — and if none appear, see the hook trust approval below.

​
What connect writes

~/.codex/config.toml
Re-running with --force strips the existing [mcp_servers.agentmemory] block first and appends a fresh one, so the file never accumulates duplicates. The write is verified by re-reading the file.

​
Capture model

The plugin registers 6 lifecycle hooks: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop. Codex’s hook engine injects CLAUDE_PLUGIN_ROOT into hook subprocesses, so the same hook scripts run unmodified across Claude Code and Codex. Subagent, SessionEnd, Notification, TaskCompleted, and PostToolUseFailure events are Claude Code only and are not registered for Codex. The plugin also registers 9 invocable skills (/recall, /remember, /session-history, /forget, /recap, /handoff, /lesson, /commit-context, /commit-history) plus 8 reference skills the agent loads on demand.

​
Codex Desktop: --with-hooks workaround

Codex Desktop builds currently do not dispatch plugin-local hooks.json even though the CodexHooks and PluginHooks feature flags are stable and default-enabled (openai/codex#16430). MCP tools still work; only the lifecycle observations go missing.
Until upstream fixes plugin-scope dispatch, mirror the same hook commands into the global hooks file:
This merges the bundled hooks.codex.json manifest into ~/.codex/hooks.json with ${CLAUDE_PLUGIN_ROOT} resolved to the absolute bundled plugin/ path. The merge is idempotent: re-installs strip only entries whose command points under the bundled scripts/ directory, and your own hook entries survive. It runs even when MCP is already wired.
Codex requires a one-time interactive trust approval before any new hook runs. Launch codex (the TUI) once after --with-hooks; it shows “Hooks need review — N hooks are new or changed” — choose Trust all and continue. Codex records a per-hook trusted_hash in config.toml, and only trusted hooks execute. codex exec never shows this prompt, so hooks stay silently inert on exec-only usage until the TUI approval happens. The approval also re-triggers whenever a hook command changes (including the path refresh after upgrading agentmemory).
The merged entries reference absolute, version-embedding paths. Re-run agentmemory connect codex --with-hooks after upgrading agentmemory to refresh them, then re-approve in the TUI.

​
Troubleshooting

Two causes, in order of likelihood. First: the hooks were never trusted — codex runs only hooks with a recorded trusted_hash, and the “Hooks need review” prompt appears only in the interactive TUI, so launch codex once and choose Trust all (a codex exec-only workflow never sees the prompt and the hooks stay inert, while codex still prints hook: ... Completed for other tools’ trusted hooks, which is easy to misread). Second: you are on Codex Desktop relying on plugin-local hooks, which are currently silent there (openai/codex#16430) — run connect codex --with-hooks to mirror the hooks into ~/.codex/hooks.json, then trust them in the TUI.
The installer resolves the bundled plugin/ directory of the installed @agentmemory/agentmemory package. Reinstall the package (npm install -g @agentmemory/agentmemory) and re-run. The MCP wiring is applied regardless of this skip.
Adapter source: src/cli/connect/codex.ts and src/cli/connect/codex-hooks.ts. Hook manifest: plugin/hooks/hooks.codex.json.
Last modified on August 15, 2026