codemem-codex

Codex plugin for codemem. It gives Codex local project memory through lifecycle hooks, bundled codemem MCP tools, and a small memory-usage skill.

Maintained by iCoreTech, Inc. Published on npm as @icoretech/codemem-codex.

What You Get

• Relevant memory context injected into Codex prompts
• Codex prompts, tool results, and assistant replies captured as codemem raw events
• Automatic codemem viewer/processor startup for raw-event ingestion
• Bundled codemem MCP tools such as memory search, recent, remember, forget, and learn
• A bundled Codex skill that nudges agents to remember durable facts without storing every turn
• Fail-open hooks: if codemem is missing or slow, Codex continues normally

Install

Install the codemem CLI first:

npm install -g codemem@latest
codemem version

Add the iCoreTech marketplace and install the plugin:

codex plugin marketplace add icoretech/openai-marketplace
codex plugin add codemem-codex@icoretech

Enable Codex lifecycle hooks in ~/.codex/config.toml:

[features]
hooks = true

Start Codex. On first run after install, the TUI asks you to review new hooks:

Hooks need review
4 hooks are new or changed.
Hooks can run outside the sandbox after you trust them.

1. Review hooks
2. Trust all and continue
3. Continue without trusting (hooks won't run)

Choose trust if you want codemem-codex to run. Continuing without trust leaves the plugin installed but prevents the hooks from executing.

That is the normal setup. You do not need to hand-edit MCP config for codemem; the plugin bundles it. You also normally do not need to run codemem serve start yourself; the plugin and codemem MCP server start the local processor when needed.

Check It

Verify Codex sees the plugin:

codex plugin list --marketplace icoretech

In a repository, ask Codex:

Remember this codemem smoke phrase for this repository: velvet-river-742.

Then start a new Codex session in the same repository and ask:

What codemem context do you have for this repository? If you see the smoke phrase, quote it.

The UserPromptSubmit hook injects a small relevance pack for the current prompt. It is intentionally not a full memory inventory, and Codex TUI shows it because Codex prints hook additionalContext.

To prove the MCP side can inspect more than the injected pack, ask Codex:

Use the codemem MCP tools, not only injected hook context.
For this project, call memory_recent with limit 20, then memory_search for the project name with limit 10.
Tell me the counts and list the returned memory ids and titles.

If you want to inspect codemem directly:

codemem db raw-events-status
codemem recent --project "$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")"

Raw events mean the hooks are capturing Codex activity. Searchable memories also require codemem's own observer/model configuration to be valid.

Upgrade

Refresh the marketplace snapshot when a new plugin release is available:

codex plugin marketplace upgrade icoretech

Restart Codex after upgrading so the next session loads the refreshed plugin.

How It Works

codemem-codex has four pieces:

• Hooks inject memory and capture session events
• The codemem viewer/processor converts raw events into memories
• MCP tools let Codex actively search, remember, and manage memory
• The bundled skill tells Codex when memory is useful and when not to write it

Privacy and Local Data

codemem-codex is local-first. The plugin records Codex lifecycle events into the local codemem database and starts local codemem processing when needed. It does not send prompts, tool output, diagnostics, or remembered facts to an iCoreTech service.

The underlying codemem installation may use whichever model provider or observer configuration you have configured for codemem itself. Review that codemem configuration separately if your memory processing uses a remote model provider.

The hook command is:

codemem-codex hook

It reads one Codex hook payload from stdin and writes Codex hook JSON to stdout. Hook execution is fail-open: codemem errors never block Codex. Raw-event streaming diagnostics are append-only and sanitized. Diagnostics do not include raw event JSON, prompt text, tool inputs, tool outputs, secrets, headers, or full stdin.

| Codex hook | Behavior | | --- | --- | | SessionStart | Starts codemem processing and records session metadata | | UserPromptSubmit | Records the prompt and injects codemem pack --json context | | PostToolUse | Records tool name, input, response, and tool-use id | | Stop | Records the assistant message when available, runs one boundary raw-event status diagnostic, and closes the session |

Adapter Contract

Every captured hook becomes a codemem raw event whose top-level event_type is codex.hook. The adapter data lives inside payload with this wrapper shape:

{
  "type": "codex.hook",
  "timestamp": "2026-05-24T00:00:00.000Z",
  "_adapter": {}
}

_adapter uses schema version 1.0 and source: "codex". It includes the Codex session id, stable event id, adapter event type, ISO timestamp, ordering confidence, cwd, normalized payload, and metadata. Supported adapter event types are session_start, prompt, tool_result, assistant, session_end, and error. Metadata keeps the original Codex hook name and safe hook fields such as transcript_path, model, permission_mode, turn_id, and stop_hook_active when Codex sends them. Sensitive-looking fields are omitted from adapter metadata.

This contract is designed to be compatible with codemem's upstream adapter ingest path, but Codex hook limits still apply. It should not be read as full upstream OpenCode hook parity.

Codex Hook Support Matrix

Codex supports PostToolUse and Stop, does not support PostToolUseFailure or SessionEnd, and uses Stop as the closest boundary hook. Dedicated failed-tool capture is unavailable in the current Codex hook contract, failed tools may not emit hooks, and no unsupported hook is registered locally. Unsupported hook names are feature-detected/fail-open no-ops that return { "continue": true }, not invented registrations.

| Hook or field | Support | Notes | | --- | --- | --- | | SessionStart | supported | registered locally | | UserPromptSubmit | supported | injects the relevance pack; not a full inventory | | PostToolUse | supported | PostToolUse is success-path only with no dedicated error field; error-like tool responses are mapped conservatively but are not dedicated failed-tool capture | | Stop | supported | Use Stop as the closest boundary hook; last_assistant_message is stop-only | | PostToolUseFailure | unsupported | feature-detected fail-open no-op; not registered locally | | SessionEnd | unsupported | feature-detected fail-open no-op; use Stop instead | | transcript_path | conditional | transcript_path is supported and can be null | | tool_response | conditional | present on PostToolUse only when the tool reached the success path | | usage | unsupported | hook stdin does not include usage |

Injection, State, and Working Set

UserPromptSubmit injects a small relevance pack through Codex additionalContext. The query sent to codemem pack --json is a heuristic, not a memory inventory. It combines the persisted first prompt, the current prompt (which is also the latest prompt for this hook), the resolved project, and the last five modified file basenames from session state. The query is capped at 500 characters. The visible additionalContext output is separately capped by CODEMEM_CODEX_INJECT_MAX_CHARS, default 1500, and ends with a truncation marker when it is shortened.

Session state is stored per Codex session under ~/.codemem/codex-hooks by default. Set CODEMEM_CODEX_STATE_DIR to use another directory. The state file stores only first_prompt, last_prompt, files_modified, and updated_at; it is best-effort and is cleared on Stop, the closest Codex boundary hook.

For retrieval, codemem-codex passes up to the last eight modified paths to codemem pack as repeated --working-set-file arguments. Modified paths come from successful PostToolUse hook payloads, including common file-path fields and apply-patch file headers.

Stream Reliability and Boundary Status

Raw events are sent to the local codemem viewer API first so codemem can nudge processing immediately. The plugin first checks GET /api/raw-events/status?limit=1, then posts to POST /api/raw-events only when the status path is healthy. If the status preflight or POST fails, the plugin sets a bounded in-memory stream backoff for the current hook process/runtime and falls back exactly once to codemem enqueue-raw-event. While that process-local backoff is active, repeated events handled by the same runtime skip the status check and POST, then use the same CLI fallback. Normal Codex command-hook executions are separate processes, so the next invocation can try status/POST again before falling back.

Codex currently has no supported SessionEnd hook, so Stop is the only registered boundary. After Stop raw events are streamed or fallback-queued, the hook runs one bounded codemem db raw-events-status --limit 1 --json diagnostic and logs boundary flush unavailable; relying on sweeper. The installed codemem CLI exposes db raw-events-status, db raw-events-retry, and db raw-events-gate, but no direct raw-event flush command; the codemem viewer/processor sweeper performs the actual flush. Boundary diagnostics are fail-open, sanitized, and never include raw hook stdin or raw event JSON.

Configuration

Most users do not need these. They are useful for local debugging or custom codemem installs.

Project resolution uses this precedence: CODEMEM_PROJECT, then git root basename, then cwd basename, then unknown-project. Path-like project labels are normalized to their basename.

| Variable | Default | Description | | --- | --- | --- | | CODEMEM_CODEMEM_COMMAND | codemem | Command prefix used before codemem subcommands | | CODEMEM_CODEX_DISABLED | unset | Set to 1, true, yes, or on to disable all hook work | | CODEMEM_CODEX_INJECT_LIMIT | 8 | codemem pack --limit value | | CODEMEM_CODEX_TOKEN_BUDGET | 800 | codemem pack --token-budget value | | CODEMEM_CODEX_INJECT_MAX_CHARS | 1500 | hard cap for visible hook additionalContext | | CODEMEM_CODEX_TIMEOUT_MS | hook-specific | CLI fallback timeout | | CODEMEM_CODEX_RAW_EVENTS_TIMEOUT_MS | 1500 | combined viewer status/POST timeout before CLI fallback | | CODEMEM_RAW_EVENTS_BACKOFF_MS | 10000 | process-local stream failure backoff; skips status/POST until expiry only inside the same hook process/runtime and uses CLI fallback | | CODEMEM_CODEX_RAW_EVENTS_BACKOFF_MS | CODEMEM_RAW_EVENTS_BACKOFF_MS | Codex-specific stream backoff override | | CODEMEM_PLUGIN_LOG | ~/.codemem/plugin.log | sanitized raw-event stream/fallback diagnostics path; 1, true, yes, or on use the default path | | CODEMEM_CODEX_LOG | CODEMEM_PLUGIN_LOG | Codex-specific diagnostics path used when CODEMEM_PLUGIN_LOG is unset | | CODEMEM_PROJECT | git root basename | canonical explicit codemem project name | | CODEMEM_CODEX_STATE_DIR | ~/.codemem/codex-hooks | per-session hook state directory for first prompt, last prompt, modified paths, and updated timestamp | | CODEMEM_CODEX_VIEWER | enabled | set to 0, false, no, or off to skip viewer use | | CODEMEM_CODEX_VIEWER_AUTO | enabled | set to 0, false, no, or off to skip viewer autostart | | CODEMEM_CODEX_VIEWER_HOST | 127.0.0.1 | viewer host override | | CODEMEM_CODEX_VIEWER_PORT | 38888 | viewer port override | | CODEMEM_DB | codemem default | codemem database path | | CODEMEM_CONFIG | codemem default | codemem config path |

Example using npx explicitly:

CODEMEM_CODEMEM_COMMAND="npx --yes codemem@latest"

Development

From the marketplace repository root:

npm ci
npm run build -w @icoretech/codemem-codex
npm test -w @icoretech/codemem-codex
npm run check -w @icoretech/codemem-codex

For local plugin development from this checkout:

npm run build -w @icoretech/codemem-codex
codex plugin marketplace add ../..
codex plugin add codemem-codex@icoretech

License

MIT