Give Codex durable project memory in about 7 minutes
Lifecycle hooks retrieve and capture automatically. OAuth adds explicit memory tools. Codex’s own local Memories can stay enabled alongside MemoryRouter.
Before you start
Check these prerequisites
Estimated time: 5–7 minutes
- Node.js 18+
Check withnode --version. - Codex 0.145+
Use 0.146+ for the OAuth path below. Checkcodex --version. - MemoryRouter account
Copy the key for the vault you want hooks to use.
Get running
Five steps, including both auth paths
Copy your MemoryRouter Memory Key
The OAuth connector and the automatic hooks use different credential paths. Hooks need this key even when MCP uses browser OAuth.
Open a terminal in your project
A terminal is the text window where commands run. Use Terminal on macOS or PowerShell on Windows, then change into the repository you use with Codex.
Install hooks and the MCP entry securely
Copy your key, then use the command below. It reads the key from your clipboard through standard input, so the key is not written into shell history or the repository.
Complete browser sign-in
Run codex mcp login memoryrouter, sign in, and choose the same vault as the Memory Key used by hooks. Then open Codex and review/trust the MemoryRouter definitions in /hooks.
Run doctor and a two-session test
Run npx -y [email protected] doctor --scope user. Save a unique fact in one Codex session, open a new session in the same project, and ask for it.
macOS · copy your Memory Key first
pbpaste | npx -y [email protected] init --scope user --auth oauth --api-key-stdinWindows PowerShell · copy your Memory Key first
Get-Clipboard | npx -y [email protected] init --scope user --auth oauth --api-key-stdinThen start OAuth in your browser
codex mcp login memoryrouterChoose your scope
User or project?
Recommended for one computer
User scope
Writes managed blocks under ~/.codex/ and works in the local CLI, Codex IDE extension, and ChatGPT desktop app’s local Codex host on this machine.
Project scope
Writes .codex/ and a managed AGENTS.md block in the repository. Teammates and cloud environments still need their own key, Node, network access, and project trust.
Success looks like this
- ✓ Doctor passes managed config, runtime, and hooks.
- ✓
/hooksshows trusted MemoryRouter hooks. - ✓
/mcp verboseshows MemoryRouter authenticated. - ✓ A new same-project session recalls your unique test fact.
Important auth distinction
Browser OAuth authenticates remote MCP tools. The deterministic command hooks run outside that OAuth session, so they also need the MemoryRouter API key supplied during install. Without it, MCP may work while automatic recall/capture quietly fails open.
Need Linux, cloud, fallback, or removal steps?
The full guide covers every OS, user/project scope, OAuth and API-key stdio fallback, expected files, hook trust, native Memories coexistence, troubleshooting, re-auth, upgrades, uninstall, credential cleanup, limitations, and support.