Codex Memory Hooks

Portable ESM hooks for Agent Memory Platform. Run directly from npm in Codex's shared system configuration, without installing source files in each user's home. The optional legacy installer remains available and never modifies config.toml.

Shared configuration (recommended)

With Node/npm available in Codex's shell, place the following in the shared system config.toml. Replace the example gateway with your private gateway. Use the same immutable npm tarball for all three events. The tarball spec keeps npx from selecting a same-named local checkout instead of the published hook.

[[hooks.SessionStart]]
matcher = "startup|resume|clear|compact"
[[hooks.SessionStart.hooks]]
type = "command"
command = "npx --yes --prefer-offline --package=https://registry.npmjs.org/@staticeng/codex-agent-memory/-/codex-agent-memory-0.1.1.tgz amp-codex-memory-hook SessionStart --gateway-url https://memory.example.test"
timeout = 120
statusMessage = "Loading memory context"
additionalContextLimit = 12000

[[hooks.UserPromptSubmit]]
[[hooks.UserPromptSubmit.hooks]]
type = "command"
command = "npx --yes --prefer-offline --package=https://registry.npmjs.org/@staticeng/codex-agent-memory/-/codex-agent-memory-0.1.1.tgz amp-codex-memory-hook UserPromptSubmit --gateway-url https://memory.example.test"
timeout = 120
statusMessage = "Recalling memory"
additionalContextLimit = 12000

[[hooks.Stop]]
[[hooks.Stop.hooks]]
type = "command"
command = "npx --yes --prefer-offline --package=https://registry.npmjs.org/@staticeng/codex-agent-memory/-/codex-agent-memory-0.1.1.tgz amp-codex-memory-hook Stop --gateway-url https://memory.example.test"
timeout = 120
statusMessage = "Reviewing memory candidate"

The first invocation downloads the complete package to npm's per-user cache; subsequent invocations prefer that cached version. Initial download requires registry connectivity. No global npm install or fixed Node path is required. The gateway flag supplies a default: an existing local gatewayUrl or explicit AMP_MEMORY_GATEWAY_URL preserves host-specific memory routing. New installations need no local configuration file. The package writes only bounded runtime state to the selected Codex home; it does not install hooks or skills when run directly.

System hooks are managed by Codex and do not require user trusted_hash entries. Remove legacy memory declarations and their matching trust entries only after verifying system-hook discovery; otherwise both registrations may execute. Do not duplicate declarations in system hooks.json and system config.toml.

Install

npx --package=https://registry.npmjs.org/@staticeng/codex-agent-memory/-/codex-agent-memory-0.1.1.tgz amp-codex-memory install --codex-home ~/.codex --dry-run
npx --package=https://registry.npmjs.org/@staticeng/codex-agent-memory/-/codex-agent-memory-0.1.1.tgz amp-codex-memory install --codex-home ~/.codex
npx --package=https://registry.npmjs.org/@staticeng/codex-agent-memory/-/codex-agent-memory-0.1.1.tgz amp-codex-memory doctor --codex-home ~/.codex

The installer atomically merges its SessionStart, UserPromptSubmit, and Stop command hooks with existing hooks, creates timestamped hooks.json backups, installs agent-memory and memory-review skills, and records managed asset hashes. SessionStart covers startup, resume, clear, and compact. Reinstallation replaces only this package's entries, refuses modified or unowned skill directories, and detects best-effort concurrent hooks.json changes before replacement. Codex trust remains an explicit user action; status reports it as unknown rather than guessing.

Set authorization in AMP_MEMORY_AUTH_HEADER; the value is never written to config, state, logs, or stdout. Non-secret settings live in ~/.codex/agent-memory-platform/config.json. AMP_MEMORY_HOST_ID overrides the normalized hostname when hostId is not configured.

The memory gateway has no package-level authentication enforcement. Keep it bound to loopback, or place it behind an authenticated reverse proxy; do not expose it directly to an untrusted network.

Behavior and privacy

• SessionStart calls /v1/context and injects only bounded safe_prompt_block content.
• Substantive UserPromptSubmit calls /v1/recall; trivial prompts are skipped and transmitted prompts are redacted and bounded first. Only bounded/redacted summary, topic, and scope fields from compact-v2 results are injected with the search_id and an untrusted-context reminder.
• Stop is enabled by default and calls /v1/review/propose only when last_assistant_message contains a strict English or Spanish completed-work signal. Any negation, uncertainty, conditional, future intent, pending/proposed state, short response, or secret-bearing conclusion suppresses a proposal for the entire response. This is a deliberately conservative heuristic, not a language model: mixed replies can be skipped. It never reads a transcript fallback and never calls /v1/save-memory.
• Codex invokes Stop per turn, not only once per session. Strict filtering, one-candidate bounds, hashed session/turn provenance, local fingerprints, and deterministic amp:v1:<sha256> per-turn idempotency keys limit duplicate review writes while gateway semantic IDs converge equivalent facts across turns.
• Hook failures return the exact fail-open { "continue": true } response and exit successfully, with a content-free diagnostic on stderr. State contains only hashed session identity, project/scope IDs, search ID, timestamps, version, and dedupe fingerprint.

Uninstall

npx --package=https://registry.npmjs.org/@staticeng/codex-agent-memory/-/codex-agent-memory-0.1.1.tgz amp-codex-memory uninstall --codex-home ~/.codex --dry-run
npx --package=https://registry.npmjs.org/@staticeng/codex-agent-memory/-/codex-agent-memory-0.1.1.tgz amp-codex-memory uninstall --codex-home ~/.codex

Uninstall removes this package's hook entries and only assets whose hashes still match the manifest. User-modified assets and all unrelated hooks, settings, MCPs, and sessions are preserved.