OpenAI Codex Installation Guide

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

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@1.0.0 init --scope user --auth oauth --api-key-stdin

Windows PowerShell:

Get-Clipboard | npx -y memoryrouter-codex@1.0.0 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@1.0.0 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.

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@1.0.0 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@1.0.0 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_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@1.0.0 doctor --scope user

Project scope:

npx -y memoryrouter-codex@1.0.0 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 the same project.
5. Ask: “What is this project's MemoryRouter installation test phrase?”

Success means the new session answers amber glacier 62 from automatically injected project memory. Use your own unique phrase if this example could already be in your 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 project identity

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.

The runtime derives proj_... from the canonical Git remote, then Git common directory, then the absolute project path. Worktrees with one Git common directory share identity. Clones on different machines share identity when the normalized origin remote matches. Only the opaque handle is used for remote project filtering.

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.

Wrong project's memories appear—or expected memories are absent

Run project-scope doctor from the repository root and inspect the proj_... source. Add a canonical origin remote for portable identity, or pass --project-dir to doctor/installer when you are not standing in the repository. For a strict security boundary, use a separate vault; the hosted remote MCP tools do not accept a project argument.

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

Version 1.0.0 is current. Re-run init with the same scope and auth mode:

npx -y memoryrouter-codex@1.0.0 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@1.0.0 uninstall --scope user

Project scope:

npx -y memoryrouter-codex@1.0.0 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

• Automatic behavior requires trusted command hooks plus an API key; remote OAuth alone remains model-invoked.
• Codex's transcript JSONL is unstable, so capture uses only documented stable prompt, tool, result, and final-message hook fields.
• Hosted tools such as web search may not emit PostToolUse; details not reflected in the final response may not be captured.
• 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.
• The hosted MCP server has no project argument. Package hooks/local fallback filter project handles, but strict isolation requires a separate vault.
• Server-side per-memory deletion is unavailable through MCP. Use the dashboard. 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.

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.