OpenAI Codex Installation Guide

This is the complete beginner path for memoryrouter-codex 1.7.0, which is published on npm. It combines deterministic lifecycle hooks with an explicit MCP connection. Automatic recall and capture do not depend on the model deciding to call a tool.

MemoryRouter is one memory across every session, repo and tool. One account uses one vault: every Codex session, every Claude Code session, every repository, and every OAuth-connected client (Codex MCP, ChatGPT, Claude) read and write the same memory. A decision captured in Claude Code in one repo is recalled by Codex in another, and the other way round. Every new Codex session recalls what earlier sessions captured.

The published package captures only the user request and final assistant response. It does not install PostToolUse and never stores tool names, IDs, inputs, results, commands, or patches.

Fastest: let Codex install it

Codex can run the whole install for you. Paste this prompt into a Codex session in any project. It asks for your Memory Key, installs the hooks, verifies, and tells you the one step only you can do (trusting the hooks in /hooks).

Install MemoryRouter memory for Codex on this machine.

1. Check node --version (18 or newer) and codex --version (0.145 or newer). If either is missing or too old, tell me what to install and stop.
2. Ask me for my MemoryRouter Memory Key (it starts with mk_). If I say I already use MemoryRouter in Claude Code on this machine, skip this step: the installer reuses that key.
3. Run the installer. It needs network access and writes to ~/.codex and ~/.memoryrouter, so ask me to approve running it outside the sandbox.
   With a key (passed on stdin): printf '%s' "<MY_KEY>" | npx -y memoryrouter-codex init --scope user --auth api-key --api-key-stdin
   Reusing the Claude Code key: npx -y memoryrouter-codex init --scope user --auth api-key
4. Run npx -y memoryrouter-codex doctor --scope user and tell me the result in plain words.
5. Tell me to type /hooks, trust the MemoryRouter hooks, and start a new Codex session.

Never print, log, or repeat my Memory Key.

This prompt uses the local API-key MCP fallback, so no browser sign-in is needed. The manual path below adds the hosted OAuth MCP connection instead. Both paths install the same automatic hooks.

Prerequisites

1. Node.js 18 or newer. Run node --version.
2. Codex 0.145.0 or newer for the full hook lifecycle. Use 0.146.0 or newer for the remote OAuth path below. Run codex --version to check. Follow OpenAI's Codex installation guide if the command is missing.
3. Codex signed in through your normal ChatGPT or OpenAI authentication.
4. A MemoryRouter account and API key. In the dashboard, create or select the vault you want and copy its mk_... key.
5. A trusted project folder. Project-scoped .codex config and command hooks are loaded only for projects you trust in Codex.

Estimated time: 5–7 minutes.

The obsolete experimental_use_rmcp_client setting is not required and the installer does not write it.

Install

1. Choose user or project scope

User scope (recommended for one person on one computer) writes managed configuration under ~/.codex/. The local Codex CLI, Codex IDE extension, and ChatGPT desktop app's local Codex host share that configuration.

Project scope writes managed files into the repository's .codex/ folder and a marked block in AGENTS.md. It can travel with the repository, but it never includes the MemoryRouter key. Every machine or cloud environment must still supply its own credential, Node runtime, network access, and project trust.

2. Install securely on macOS or Windows

Copy your MemoryRouter key to the clipboard, then run the command for your operating system.

macOS:

pbpaste | npx -y memoryrouter-codex init --scope user --auth oauth --api-key-stdin

Windows PowerShell:

Get-Clipboard | npx -y memoryrouter-codex init --scope user --auth oauth --api-key-stdin

The key travels over standard input, not a command-line argument. The installer trims the trailing newline and stores the key privately at ~/.memoryrouter/codex/config.json.

Linux or no clipboard command

Run the installer with stdin mode:

npx -y memoryrouter-codex init --scope user --auth oauth --api-key-stdin

Paste only the key, press Enter, then send end-of-file with Ctrl+D on macOS/Linux. In Windows Command Prompt use Ctrl+Z, then Enter. A password manager that can pipe a secret to standard input is preferable on managed machines.

3. Complete browser OAuth

codex mcp login memoryrouter

Codex opens a browser. Sign in to MemoryRouter, choose the same vault represented by the API key used for hooks, and approve read/write scopes. A vault is the private memory collection bound to one Memory Key or OAuth connection. One user, one vault: init asks the MemoryRouter auth server whether the hook key is the vault your OAuth connections selected. If they differ it stops before writing anything and names the selected vault, and doctor reports the same one-vault check. When no OAuth connection exists yet, init tells you which vault to pick at login.

4. Trust the command hooks

Start Codex in the configured folder and enter:

/hooks

Review the MemoryRouter hook definitions and trust them. Codex hashes non-managed hook definitions; new or changed hooks are skipped until you approve the current version. Project hooks also require the project itself to be trusted.

Then enter:

/mcp verbose

MemoryRouter should appear enabled and authenticated.

Project-scope install

From the repository root, use --scope project:

pbpaste | npx -y memoryrouter-codex init --scope project --auth oauth --api-key-stdin
codex mcp login memoryrouter

Review generated .codex/ files and the marked AGENTS.md block before committing them. The key remains in the user's private home config and is not copied into the project.

Authentication and permissions

Remote MCP: OAuth

OAuth authenticates explicit tools at https://mcp.memoryrouter.ai/mcp using PKCE S256 and dynamic client registration. Codex discovers the OAuth resource from protected-resource metadata, so the installer deliberately does not set oauth_resource; pinning the same value can duplicate the OAuth resource parameter in affected Codex versions.

The managed MCP configuration asks for independent memories:read and memories:write scopes. Write does not imply read or whole-vault delete. store_memory remains a write action that can prompt for approval.

Automatic hooks: API key

The lifecycle hooks use the private API key because command hooks do not run inside the MCP OAuth session. The key is read from MEMORYROUTER_API_KEY or private config. It is never written to the repository.

Secure API-key stdio fallback

Choose this when browser OAuth cannot complete, for example, a headless or restricted host:

pbpaste | npx -y memoryrouter-codex init --scope user --auth api-key --api-key-stdin

This installs a local stdio MCP server plus the same automatic hooks. The fallback exposes memory_search, memory_date_search, memory_inspect, memory_store, memory_status, and memory_forget. It does not expose the key in Codex config; the managed process reads it from private home config or environment.

Verify

1. Run doctor

User scope:

npx -y memoryrouter-codex doctor --scope user

Project scope:

npx -y memoryrouter-codex doctor --scope project --project-dir /path/to/repository

Doctor checks Codex version, managed MCP config, runtime version, hooks, AGENTS.md, automatic-hook credentials, OAuth discovery, native Memories coexistence, project identity, and local/cloud boundaries. Use --offline only when you intentionally want to skip API and OAuth network checks.

Success means managed config/runtime/hooks pass, the API key is valid for automatic memory, and no required check says FAIL. OAuth token issuance is user-specific; doctor verifies discovery but /mcp verbose is the authoritative interactive login check.

2. Run a first store-and-recall exercise

1. Start Codex in the configured project and confirm /hooks shows trusted MemoryRouter hooks.
2. Say: “For the MemoryRouter installation test, the project code phrase is amber glacier 62. Please acknowledge it.”
3. Let the turn finish and wait a few seconds.
4. Open a new Codex session, in this project or any other.
5. Ask: “What is this project's MemoryRouter installation test phrase?”

Success means the new session answers amber glacier 62 from automatically injected memory. Use your own unique phrase if this example could already be in your vault.

Using Claude Code too? With memoryrouter-claude installed on the same vault, open Claude Code in any repository and ask the same question. It answers from the same vault. It works the other way round as well: tell Claude Code a decision, then ask a new Codex session. If no Codex key is configured, the Codex hooks reuse the Claude Code key from ~/.memoryrouter/config.json, so both agents use the same vault.

3. Verify explicit MCP separately

Ask Codex: “Use MemoryRouter memory_status and report the connected vault status and scopes.” This should call the remote tool. Automatic hook success and explicit MCP success are separate checks because they have separate authentication.

Expected files and repository tag

User scope can create or update:

• ~/.codex/config.toml, managed remote or stdio MCP block; no key.
• ~/.codex/hooks.json, managed command-hook definitions.
• ~/.codex/AGENTS.md, marked MemoryRouter guidance.
• ~/.codex/memoryrouter/runtime/, versioned hook/runtime files.
• ~/.memoryrouter/codex/config.json, private API key.
• ~/.memoryrouter/codex/health.json and audit.jsonl, local diagnostics and metadata-only audit.

Project scope uses .codex/config.toml, .codex/hooks.json, .codex/memoryrouter/runtime/, and a marked block in repository AGENTS.md; private credential and health state remain under the user's home directory.

Every hook and local MCP call reads and writes your whole vault. There is no per-session or per-repository partition, so new sessions, resumed sessions, compaction, other repositories, Claude Code, and the hosted MCP (ChatGPT, Claude) all share one memory. Recall accepts every record whatever wrote it: Codex and Claude Code captures, MCP saves, reflections, and the recent buffer.

The runtime still derives a ccp_... repository tag, identical to the one Claude Code's memoryrouter-claude uses: an explicit id (MEMORYROUTER_PROJECT_ID, or projectId in the repository's .memoryrouter.json), the normalized git remote, the git common directory, then the directory path. It is metadata only. Codex stamps it on the turns it saves and labels recalled entries from the current repository as this repo; it never limits what is recalled. Only the opaque tag is sent to MemoryRouter.

Upgrading from 1.6.x or earlier: those releases kept memory per Codex session, so a new session started empty. Re-run init to upgrade. Memories captured by the old releases were moved into each vault's main memory on the server when 1.7.0 shipped, so they are recalled again, with nothing lost or duplicated.

Native Codex Memories coexistence

Codex's native Memories and MemoryRouter can both stay enabled. Native Memories are local to Codex; MemoryRouter is cross-machine and cross-tool. The installer does not overwrite native-memory settings.

If you intentionally enable native Memories, this optional Codex configuration avoids generating a second native extraction from conversations that already used MCP or other external context:

[features]
memories = true

[memories]
disable_on_external_context = true

The tradeoff is that those externally assisted chats will not contribute to native Memories. Use /memories for Codex's own per-chat controls. Keep mandatory team rules in AGENTS.md, not only in either memory system.

Supported surfaces

• Codex CLI, IDE extension, and ChatGPT desktop app's local Codex host: share local Codex config on the same host; user scope applies here.
• Project scope: can travel with a trusted repository, but every machine supplies its own authentication.
• Codex cloud: does not automatically inherit your laptop's user config or secrets. Use project scope and provision Node, project trust, package/network access, and MEMORYROUTER_API_KEY in the cloud environment.
• ChatGPT web: does not read local ~/.codex files or command hooks. Use MemoryRouter's separate ChatGPT connector path there.

Troubleshooting

Start with the doctor command for the scope you installed.

codex --version is below 0.145

Upgrade Codex before continuing. Below 0.145, the full hook lifecycle is unavailable. Use 0.146+ for the documented OAuth behavior.

MCP works, but automatic memory does not

The hook runtime cannot see a MemoryRouter API key. Re-run init with --api-key-stdin, or provide MEMORYROUTER_API_KEY to the environment that launches the Codex host. OAuth alone is not hook authentication.

Hooks are listed but skipped

Open /hooks, review, and trust the current MemoryRouter hook hash. For project scope, confirm the project's .codex layer is trusted. Upgrades change runtime definitions and may require review again.

Browser OAuth does not open or complete

Confirm Codex 0.146+, then reset only this MCP OAuth session:

codex mcp logout memoryrouter
codex mcp login memoryrouter

Choose the intended vault. If a loopback callback is blocked by remote development networking, use Codex's documented mcp_oauth_callback_url/port configuration or choose the API-key stdio fallback.

Doctor says the managed MCP block is missing

Run init again with the same scope. If an unmanaged [mcp_servers.memoryrouter] table already exists, the installer refuses to create duplicate TOML. Review it first; --force creates a timestamped backup and replaces only the conflicting MemoryRouter table.

Memories from another repository appear, or expected memories are absent

That is by design: one vault holds every repository's memory, and recall ranks by relevance to your prompt. Entries saved from the current repository are labelled this repo. If expected memories are absent, run doctor and check the one-vault line: the hook key and the OAuth-selected vault must be the same vault. For a strict boundary between two bodies of work (for example a client project), use a separate account and vault.

A new session does not recall the previous one

Releases before 1.7.0 kept memory per Codex session. Re-run init to upgrade, run doctor, and confirm the runtime check reports 1.7.0 or newer. Then trust the updated hooks in /hooks and repeat the store-and-recall exercise.

Cloud or IDE setup behaves differently from CLI

Confirm which host owns the config. The local CLI, IDE extension, and desktop local host share one Codex home on the same machine. Cloud does not inherit it. Check Node, key provisioning, network, project trust, /hooks, and /mcp verbose in the actual failing host.

Native Memories appear to duplicate context

Consider disable_on_external_context = true, or turn off either native generation or native use for that chat with /memories. MemoryRouter does not change those settings automatically.

MemoryRouter API is unavailable

Hooks exit successfully and Codex continues without memory. Reads may retry briefly; writes and destructive operations are not blindly retried. Run doctor after network service returns.

Upgrade

The init command always installs the latest published release. Re-run init with the same scope and auth mode to upgrade:

npx -y memoryrouter-codex init --scope user --auth oauth

The installer replaces only MemoryRouter-managed TOML, hook handlers, runtime files, and marked AGENTS.md guidance. Foreign config and hooks are preserved. The saved private key remains in place. After upgrading:

1. Run doctor.
2. Open /hooks and trust changed definitions if Codex asks.
3. Open /mcp verbose.
4. Re-run codex mcp login memoryrouter only if OAuth is missing or stale.

For project scope, replace --scope user with --scope project and run from the repository root.

Uninstall

1. Log out of MCP OAuth, if used

Do this while the MemoryRouter MCP entry still exists:

codex mcp logout memoryrouter

2. Remove managed integration files

User scope:

npx -y memoryrouter-codex uninstall --scope user

Project scope:

npx -y memoryrouter-codex uninstall --scope project --project-dir /path/to/repository

Uninstall removes only MemoryRouter-managed blocks, hook handlers, instructions, and runtime files. It preserves unrelated Codex config, hooks, and AGENTS.md content.

3. Decide whether to remove private local data

The installer deliberately retains ~/.memoryrouter/codex/ because another project installation may use its credential and suppression state. After uninstalling every user/project instance, you may delete that folder using Finder/File Explorer or your organization's secure device tool. Do not remove it while another installation depends on it.

Uninstalling does not delete stored vault memories. Remove individual memories in the dashboard. Whole-vault deletion is a separate irreversible operation with independent permission and confirmation safeguards.

Enterprise and admin

For managed rollout:

1. Prefer project scope for repository-controlled definitions or Codex managed hooks for enforced device policy.
2. Review and approve hook commands before distribution; Codex treats ordinary command hooks as untrusted until their hash is reviewed.
3. Provision MEMORYROUTER_API_KEY through a secret manager, never through committed project files.
4. Decide whether remote OAuth is permitted. Use API-key stdio when interactive browser consent is impossible.
5. Pilot each actual surface (CLI, IDE/desktop local host, and cloud separately).
6. Use dedicated vaults when projects or groups require strict isolation.

Managed environments can force hooks off or allow managed hooks only. If organization policy blocks command hooks, automatic behavior is unavailable and the integration degrades to explicit MCP tools.

Limitations

• Installation captures future Codex work. It does not import old ChatGPT/Codex conversations. Guided curation from an extracted export is experimental, not a deterministic checkpointed/resumable importer, and MCP connection alone never imports history.
• Automatic behavior requires trusted command hooks plus an API key; remote OAuth alone remains model-invoked.
• Codex's transcript JSONL is unstable, so the package uses only the documented prompt and last_assistant_message fields.
• The package intentionally excludes every tool-call record, including tool names, IDs, inputs, results, commands, and patches.
• Some specialized tools can bypass ordinary hook paths. Hooks are a deterministic lifecycle extension for supported events, not a complete security enforcement boundary.
• SessionEnd is best effort within Codex's short timeout; normal Stop capture is primary.
• Everything shares one vault per account. Strict isolation requires a separate account and vault.
• Codex and Claude Code share memory only when both integrations use the same vault (init and doctor check the hook key against your OAuth-selected vault).
• Server-side per-memory deletion over MCP uses the delete_memories tool with ids from search or inspect results; the dashboard works too. Whole-vault deletion is separate and irreversible.
• The ingest API has no server idempotency key, so a timeout after server acceptance can still create a duplicate on a later write.

All commands

# Install or upgrade (user scope, key on stdin, hosted OAuth MCP)
pbpaste | npx -y memoryrouter-codex init --scope user --auth oauth --api-key-stdin
codex mcp login memoryrouter

# Install without browser sign-in (local API-key MCP fallback)
pbpaste | npx -y memoryrouter-codex init --scope user --auth api-key --api-key-stdin

# Add only the hosted MCP connection, without hooks
codex mcp add memoryrouter --url https://mcp.memoryrouter.ai/mcp

# Health check
npx -y memoryrouter-codex doctor --scope user

# Import past Codex conversations
npx -y memoryrouter-codex import --instructions

# Consolidate memories into reflections on demand
npx -y memoryrouter-codex reflect

# Remove hooks and managed config
npx -y memoryrouter-codex uninstall --scope user

Reflections

The Reflection Hierarchy is fully wired into this package. Your vault tracks reflection debt server-side, and the package consolidates it three ways:

• Automatic consolidation (default on). When a hook's memory retrieval reports debt above the server's threshold, the hooks spawn the reflect loop as a detached background process. Your session is never blocked: the run checks out a batch, drives your local Codex (codex exec) with the server's instructions, commits the reflections, and repeats up to 3 batches per trigger, re-checking debt between batches. A machine-wide lockfile (~/.memoryrouter/consolidate.lock, stale after 20 minutes) prevents concurrent sessions from double-firing, and a 30 minute cooldown after each completed run prevents churn. Failures never surface in your session; everything is logged to ~/.memoryrouter/consolidate.log.
• Manual runs. memoryrouter-codex reflect runs the same loop on demand, with --tier, --batches, --max-tokens, and --dry-run controls.
• Stdio tools and the hint. The stdio MCP lane exposes memory_consolidate and memory_commit_reflections, and injected context carries a one-line consolidation suggestion whenever debt is above threshold.
• Time-window retrieval. The stdio MCP lane also exposes memory_date_search (from required ISO 8601, optional to, query, tiers, importance, max_tokens) for questions like "what happened last week" or "most important things this month or lately". The tool descriptions teach the tier guide: tier 3 holds the highest-level consolidated reflections (identity, principles, what matters most); tier 2 holds reflections of specific meaningful events; tier 1 holds raw verbatim memories. The model is taught to match filters to the question: broad "most important" questions use tiers [3] with importance 8 or higher and a large limit such as 250; big-picture overviews use tiers [3] with no importance filter; specific lookups omit tiers and importance entirely, since a high importance filter hides the specific detail being sought; specific events without raw noise use tiers [2] or [2, 3]; exact verbatim detail not already in context is reached by searching tiers [3] and drilling down by lineage with memory_inspect through the tier 2 reflections to the raw memories underneath (direct tiers [1] works when the exact wording is known). Only reflections carry importance ratings. Omit query for a chronological review. The stdio lane also exposes memory_inspect (lineage by memory id: tier, sources consolidated, and what a row was consolidated into), usable repeatedly for the drill-down.

Opting out: set "autoConsolidate": false in ~/.memoryrouter/codex/config.json. The suggestion hint, stdio tools, and the manual reflect verb keep working; only the automatic background trigger is disabled.

Cost: the reflecting model is your own Codex (you pay your own inference, exactly like any other codex exec run). MemoryRouter bills the consolidation checkout and commit tokens at the normal 1x raw rate, as documented on the Reflections page.

Support

Email hello@memoryrouter.ai. Include:

• memoryrouter-codex version and codex --version;
• operating system, host surface, and user/project scope;
• doctor output plus whether /hooks and /mcp verbose pass;
• the exact symptom and whether it affects hooks, MCP, or both.

Never send your MemoryRouter API key, OAuth token, full private config, or memory contents.

Next steps

View the integration · Create an account · All integrations