OpenAI Codex Installation Guide

This is the complete beginner path for memoryrouter-codex 1.1.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.

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.

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.

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 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

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 published version 1.1 uses only the documented prompt and last_assistant_message fields.
• Published version 1.1 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.
• 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 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.

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