memoryrouter-codex 1.7.0 → 1.8.0

package/README.md

@@ -6,17 +6,27 @@ Native Codex integration for durable MemoryRouter memory. It uses Codex's curren
 
 ## What this integration does
 
+Every turn, automatically: **recall before the prompt, save after the turn.** What is saved is exactly two things per turn, the user's message and the assistant's final response. Tool calls, tool output, reasoning, plans, intermediate assistant messages and subagent output are never saved.
+
 | Layer | Behavior |
 | --- | --- |
-| `UserPromptSubmit` hook | Searches your whole MemoryRouter vault before every prompt and injects bounded context as developer context. The vault is shared with Claude Code and every other MemoryRouter surface. |
-| `Stop` hook | Captures only the user request and final assistant response after each completed turn. Tool names, inputs, and results are excluded. |
-| `SubagentStop` hook | Captures the stable final outcome of completed subagents without parsing their unstable transcript files. |
-| `PreCompact` / compact `SessionStart` | Checkpoints only the current user request and final assistant response when present, then recalls context before Codex continues after compaction. |
-| `SessionEnd` | Best-effort message-only final checkpoint within Codex's three-second SessionEnd budget. |
-| Remote MCP | OAuth-based explicit search/store through `https://mcp.memoryrouter.ai/mcp`. |
-| Local MCP fallback | API-key-authenticated stdio tools over the same whole vault, with handles, local suppression, status, and full-vault clear confirmation. |
+| `UserPromptSubmit` hook | Searches your whole MemoryRouter vault with the prompt and injects what it finds as developer context for that turn. The vault is shared with Claude Code and every other MemoryRouter surface. Records the prompt for this turn. |
+| `Stop` hook | Saves the user's message and the final assistant response for the turn. Nothing else. |
+| `SessionStart` hook | Restores context after Codex compacts a long chat (key mode also on new/resumed chats). |
+| `SessionEnd` (key mode) | Only if the last turn never finished (interrupted), saves that turn's user message. A completed turn is never saved twice. |
+| Remote MCP | OAuth-based explicit search/store through `https://mcp.memoryrouter.ai/mcp` (`search_memories`, `store_memory`, ...). |
+| Local MCP fallback | API-key-authenticated stdio tools over the same whole vault. |
 | `AGENTS.md` | Tells Codex when to recall/store and how MemoryRouter coexists with native Memories. |
 
+**Two ways the hooks reach MemoryRouter (1.8.0):**
+
+- **Over your MemoryRouter sign-in (no API key).** Default when you signed in with OAuth (Codex app Settings > Plugins > Authenticate, or `codex mcp login memoryrouter`) and no key is configured. The hooks are Codex `mcp_tool` hooks that call hidden lifecycle tools on the already-connected `memoryrouter` server (`codex_turn_start`, `codex_turn_end`, `codex_session_start`) with your OAuth token and the vault you picked when you signed in. Nothing secret is written to disk.
+- **Local runtime with a Memory Key.** Used when a key is configured (`MEMORYROUTER_API_KEY`, `--api-key-stdin`, or `memoryrouter-claude`'s `~/.memoryrouter/config.json`). Same per-turn behavior.
+
+Force either with `--hooks-via mcp` or `--hooks-via command`.
+
+1.8.0 removed the `SubagentStop` and `PreCompact` capture hooks: subagent output is intermediate work, and the PreCompact checkpoint re-saved a prompt the `Stop` hook already captured.
+
 MemoryRouter is the **cross-machine, cross-tool, team-shareable, and auditable** layer: one memory across every session, repo and tool, shared by Codex, Claude Code, ChatGPT, and Claude. Codex's native Memories remain useful as an automated local personal recall layer.
 
 ## Requirements and supported surfaces
@@ -24,7 +34,7 @@ MemoryRouter is the **cross-machine, cross-tool, team-shareable, and auditable**
 - Node.js 18 or newer.
 - **Codex 0.145.0 or newer** for the complete lifecycle-hook integration. Version 0.146.0 was tested directly.
 - Local Codex CLI, ChatGPT desktop app's local Codex host, and Codex IDE extension share `config.toml` MCP configuration.
-- User/project hooks require the Codex host to support and trust command hooks. Use `/hooks` to review them.
+- Hooks must be trusted once: Codex app **Settings > Hooks**, or `/hooks` in the CLI. OAuth (`mcp_tool`) hooks need a Codex build with MCP tool hooks (the current app and CLI 0.166 have them).
 - Project `.codex` config is loaded only for trusted projects.
 - ChatGPT web does **not** read a laptop's `~/.codex/config.toml` or local hooks. Use MemoryRouter's hosted plugin/connector surface there.
 - Codex cloud environments do not automatically inherit host-local user config or secrets. A project-scope install can travel with a repository, but the environment still needs Node, project trust, package/network availability for the stdio fallback, and `MEMORYROUTER_API_KEY` for hooks.
@@ -33,9 +43,30 @@ There is no dependency on the obsolete `experimental_use_rmcp_client` setting in
 
 ## Install
 
-### Recommended: remote OAuth MCP plus automatic hooks
+### Codex app (Mac): two steps, no key
+
+1. Add the server in the app: **Settings > Plugins > Add > Add MCP server**, Type **Streamable HTTP**, Name `memoryrouter`, URL `https://mcp.memoryrouter.ai/mcp`, **Save**, then **Authenticate** and sign in (or create an account) in the browser tab that opens.
+2. In a Codex chat, paste:
+
+   > Run `npx -y memoryrouter-codex@latest init` with network access, then tell me to trust the MemoryRouter hooks in Settings > Hooks.
+
+   Then trust the three MemoryRouter hooks in **Settings > Hooks** and open a **New chat**.
+
+`init` keeps the server the app added (and its sign-in), adds the three `mcp_tool` hooks to `~/.codex/hooks.json` and the MemoryRouter guidance to `~/.codex/AGENTS.md`. The Codex CLI and IDE extension on the same Mac share all of it.
+
+### Codex CLI, OAuth (no key)
+
+```bash
+npx -y memoryrouter-codex init --scope user
+codex mcp login memoryrouter
+npx -y memoryrouter-codex doctor --scope user
+```
+
+Then start Codex, trust the MemoryRouter hooks in `/hooks`, and check `/mcp verbose`.
+
+### With a Memory Key (local hook runtime)
 
-Obtain a MemoryRouter memory key from your account. Pass it on stdin so it does not appear in shell history:
+Pass the key on stdin so it does not appear in shell history:
 
 ```bash
 printf '%s' "$MEMORYROUTER_API_KEY" | \
@@ -56,7 +87,7 @@ The API key is written to `~/.memoryrouter/codex/config.json` with mode `0600`;
 
 Already using MemoryRouter in Claude Code? When no Codex key is configured, the hooks reuse the `memoryrouter-claude` key in `~/.memoryrouter/config.json`, so both agents use the same vault (one memory for every session, repo and tool) with no second paste. Key precedence: `MEMORYROUTER_API_KEY`, then the Codex private config, then the Claude Code config.
 
-If you prefer not to persist the key, omit `--api-key-stdin` and ensure `MEMORYROUTER_API_KEY` is in the environment of the Codex host. Without either source, remote OAuth MCP tools can work after login, but automatic hooks intentionally become no-op/fail-open.
+If you prefer not to persist the key, omit `--api-key-stdin` and ensure `MEMORYROUTER_API_KEY` is in the environment of the Codex host. Without any key, `init` installs the OAuth (`mcp_tool`) hooks instead, which work as soon as you are signed in.
 
 ### Project scope
 

package/bin/cli.cjs

@@ -23,7 +23,7 @@ function parseArgs(argv) {
 }
 
 function usage() {
-  return `memoryrouter-codex ${INTEGRATION_VERSION}\n\nUsage:\n  memoryrouter-codex init [--scope user|project] [--auth oauth|api-key]\n                          [--project-dir PATH] [--api-key-stdin]\n                          [--no-hooks] [--no-agents]\n  memoryrouter-codex doctor [--scope user|project] [--project-dir PATH] [--offline]\n  memoryrouter-codex uninstall [--scope user|project] [--project-dir PATH]\n  memoryrouter-codex reflect [--tier 1|2] [--batches N|all] [--max-tokens N] [--dry-run]\n  memoryrouter-codex import [--instructions [--run]] [--file PATH] [--dismiss] [--yes]\n  memoryrouter-codex mcp-server\n\nImport:\n  Import historical Codex conversations into your vault. --instructions\n  fetches the server's extraction prompt for the host agent to execute\n  (--run spawns it via codex exec); --file uploads a JSONL extract with a\n  preview, price quote, explicit approval (--yes for non-interactive),\n  idempotent batches, and resume; --dismiss silences the import nudge\n  permanently. Re-running --file is always safe: committed batches replay\n  for free and duplicates are never re-billed.\n\nReflect:\n  Consolidates unconsolidated memories into reflections using Codex itself as\n  the model (codex exec, you pay your own inference). Server-authored\n  instructions; resumable; no local state. --dry-run prints the checkout and\n  lets the lease expire without committing.\n  Automatic mode: when the server reports consolidation debt above its\n  threshold, the hooks spawn this same loop in the background (max 3 batches\n  per trigger, 30 minute cooldown, machine-wide lockfile at\n  ~/.memoryrouter/consolidate.lock). Opt out with "autoConsolidate": false in\n  ~/.memoryrouter/codex/config.json. Logs: ~/.memoryrouter/consolidate.log\n\nAuth modes:\n  oauth    Current remote MCP at ${'https://mcp.memoryrouter.ai/mcp'} (default).\n           Run \`codex mcp login memoryrouter\` after init. Hooks additionally\n           require MEMORYROUTER_API_KEY, a key saved with --api-key-stdin, or\n           an existing memoryrouter-claude key in ~/.memoryrouter/config.json.\n  api-key  Local stdio MCP fallback plus automatic hooks. The key is read only\n           from the environment/private config, never from project files.\n\nSecure key setup:\n  printf '%s' "$MEMORYROUTER_API_KEY" | memoryrouter-codex init --api-key-stdin\n`;
+  return `memoryrouter-codex ${INTEGRATION_VERSION}\n\nUsage:\n  memoryrouter-codex init [--scope user|project] [--auth oauth|api-key]\n                          [--project-dir PATH] [--api-key-stdin]\n                          [--hooks-via mcp|command] [--no-hooks] [--no-agents]\n  memoryrouter-codex doctor [--scope user|project] [--project-dir PATH] [--offline]\n  memoryrouter-codex uninstall [--scope user|project] [--project-dir PATH]\n  memoryrouter-codex reflect [--tier 1|2] [--batches N|all] [--max-tokens N] [--dry-run]\n  memoryrouter-codex import [--instructions [--run]] [--file PATH] [--dismiss] [--yes]\n  memoryrouter-codex mcp-server\n\nImport:\n  Import historical Codex conversations into your vault. --instructions\n  fetches the server's extraction prompt for the host agent to execute\n  (--run spawns it via codex exec); --file uploads a JSONL extract with a\n  preview, price quote, explicit approval (--yes for non-interactive),\n  idempotent batches, and resume; --dismiss silences the import nudge\n  permanently. Re-running --file is always safe: committed batches replay\n  for free and duplicates are never re-billed.\n\nReflect:\n  Consolidates unconsolidated memories into reflections using Codex itself as\n  the model (codex exec, you pay your own inference). Server-authored\n  instructions; resumable; no local state. --dry-run prints the checkout and\n  lets the lease expire without committing.\n  Automatic mode: when the server reports consolidation debt above its\n  threshold, the hooks spawn this same loop in the background (max 3 batches\n  per trigger, 30 minute cooldown, machine-wide lockfile at\n  ~/.memoryrouter/consolidate.lock). Opt out with "autoConsolidate": false in\n  ~/.memoryrouter/codex/config.json. Logs: ~/.memoryrouter/consolidate.log\n\nAuth modes:\n  oauth    Current remote MCP at ${'https://mcp.memoryrouter.ai/mcp'} (default).\n           Sign in once (Codex app: Settings > Plugins > Authenticate; CLI:\n           \`codex mcp login memoryrouter\`). With no API key, the automatic\n           hooks call MemoryRouter over that same sign-in (Codex mcp_tool\n           hooks): recall before every prompt, save the prompt and the final\n           response after every turn. No key on disk. If a key is configured\n           (MEMORYROUTER_API_KEY, --api-key-stdin, or memoryrouter-claude's\n           ~/.memoryrouter/config.json) the local hook runtime is used\n           instead; force either with --hooks-via mcp|command.\n           A server you already added in the Codex app is kept as is.\n  api-key  Local stdio MCP fallback plus automatic hooks. The key is read only\n           from the environment/private config, never from project files.\n\nSecure key setup:\n  printf '%s' "$MEMORYROUTER_API_KEY" | memoryrouter-codex init --api-key-stdin\n`;
 }
 
 function optionsFromArgs(args) {
@@ -35,6 +35,7 @@ function optionsFromArgs(args) {
     agents: args.agents,
     force: Boolean(args.force),
     offline: Boolean(args.offline),
+    ...(args.hooksVia ? { hookMode: String(args.hooksVia) } : {}),
   };
   if (args.apiKeyStdin) {
     options.apiKey = fs.readFileSync(0, 'utf8').trim();
@@ -122,20 +123,26 @@ async function main() {
       if (binding.status === 'mismatch') throw new VaultMismatchError(binding);
     }
     const result = init(options);
-    process.stdout.write(`MemoryRouter Codex ${INTEGRATION_VERSION} installed (${result.layout.scope}, ${result.auth}).\n`);
-    process.stdout.write(`  config: ${result.layout.configFile}\n`);
+    process.stdout.write(`MemoryRouter Codex ${INTEGRATION_VERSION} installed (${result.layout.scope}, ${result.auth}${result.hookMode === 'mcp' ? ', hooks over your MemoryRouter sign-in' : ''}).\n`);
+    process.stdout.write(`  config: ${result.layout.configFile}${result.adoptedServer ? ` (kept your existing "${result.adoptedServer}" server)` : ''}\n`);
     if (options.hooks !== false) process.stdout.write(`  hooks:  ${result.layout.hooksFile}\n`);
     if (options.agents !== false) process.stdout.write(`  guide:  ${result.layout.agentsFile}\n`);
     if (binding && binding.status === 'match') process.stdout.write(`\nVault check: the hooks use the same vault you selected in OAuth, ${vaultLabel(binding)}.\n`);
     else if (binding && binding.status === 'mixed') process.stdout.write(`\nVault check: ${binding.message}\n`);
     else if (binding && binding.status === 'unknown') process.stdout.write(`\nVault check skipped (${binding.message}). Run doctor later to confirm one vault.\n`);
-    if (result.auth === 'oauth') {
+    if (result.hookMode === 'mcp') {
+      process.stdout.write('\nAutomatic memory: before every prompt Codex searches your vault and adds what it finds as context; after every turn it saves your message and its final response (never tool calls, tool output or intermediate steps). No API key needed.\n');
+      process.stdout.write('\nNext:\n');
+      if (!result.adoptedServer) process.stdout.write('  1. Sign in: Codex app Settings > Plugins > memoryrouter > Authenticate (or run: codex mcp login memoryrouter)\n');
+      process.stdout.write(`  ${result.adoptedServer ? '1' : '2'}. Trust the MemoryRouter hooks once: Codex app Settings > Hooks (or /hooks in the CLI)\n`);
+      process.stdout.write(`  ${result.adoptedServer ? '2' : '3'}. Start a New chat\n`);
+    } else if (result.auth === 'oauth') {
       const pick = binding && binding.vault ? ` and select the vault ${vaultLabel(binding)} (the one your hooks use)` : '';
       process.stdout.write(`\nNext: codex mcp login memoryrouter${pick}\nThen open Codex, run /hooks and trust the MemoryRouter hooks, and check /mcp verbose.\n`);
     }
     else process.stdout.write('\nNext: open Codex, run /hooks, and trust the MemoryRouter hooks.\n');
     if (result.keySource === 'claude-code-config') process.stdout.write('\nAutomatic hooks reuse your Claude Code Memory Key (~/.memoryrouter/config.json), so both agents share the same vault.\n');
-    if (!result.automaticMemory) process.stdout.write('\nRemote MCP tools are configured, but automatic hooks are fail-open/no-op until MEMORYROUTER_API_KEY is available or init is re-run with --api-key-stdin.\n');
+    if (!result.automaticMemory && options.hooks !== false) process.stdout.write('\nRemote MCP tools are configured, but automatic hooks are fail-open/no-op until MEMORYROUTER_API_KEY is available or init is re-run with --api-key-stdin.\n');
     const scopeArgs = result.layout.scope === 'project' ? `--scope project --project-dir ${JSON.stringify(result.layout.root)}` : '--scope user';
     process.stdout.write(`\nVerify: npx -y memoryrouter-codex@${INTEGRATION_VERSION} doctor ${scopeArgs}\n`);
     process.stdout.write('One memory across every session, repo and tool: Codex, Claude Code (memoryrouter-claude) and the MemoryRouter MCP all use the same vault.\n');

package/lib/hooks.cjs

@@ -5,7 +5,14 @@ const path = require('path');
 const { atomicWrite, readText } = require('./managed.cjs');
 const { INTEGRATION_VERSION } = require('../runtime/constants.cjs');
 
+// The hidden Codex lifecycle tools on the MemoryRouter MCP server
+// (mcp-server/src/tools/codex-hooks.ts).
+const MCP_HOOK_TOOLS = new Set(['codex_turn_start', 'codex_turn_end', 'codex_session_start']);
+
 function isOwnedHook(handler) {
+  if (handler?.type === 'mcp_tool') {
+    return handler.server === 'memoryrouter' && MCP_HOOK_TOOLS.has(handler.tool);
+  }
   return handler?.type === 'command' && typeof handler.command === 'string' &&
     (/memoryrouter[\\/]runtime[\\/]hook\.cjs/.test(handler.command) || /memoryrouter-codex(?:@[^ ]+)?\s+hook\b/.test(handler.command));
 }
@@ -49,16 +56,47 @@ function managedGroups(runtimeDir, scope) {
     ...(statusMessage ? { statusMessage } : {}),
     ...(additionalContextLimit ? { additionalContextLimit } : {}),
   });
+  // Per turn: recall before the prompt, save the user's prompt and the final
+  // assistant response after the turn. Nothing in between (no tool calls, tool
+  // output, reasoning, subagent output). SessionEnd only saves the prompt of a
+  // last turn that never finished (interrupted), see runtime/hook.cjs flush.
   return {
     SessionStart: [{ matcher: 'startup|resume|clear|compact', hooks: [handler('session-start', 8, 'Recalling MemoryRouter context', 3500)] }],
-    UserPromptSubmit: [{ hooks: [handler('inject', 8, 'Searching project memory', 3500)] }],
-    Stop: [{ hooks: [handler('capture', 18, 'Saving durable project memory')] }],
-    SubagentStop: [{ hooks: [handler('capture-subagent', 15, 'Saving durable subagent outcome')] }],
-    PreCompact: [{ matcher: 'manual|auto', hooks: [handler('flush', 18, 'Saving memory before compaction')] }],
+    UserPromptSubmit: [{ hooks: [handler('inject', 8, 'Searching MemoryRouter', 3500)] }],
+    Stop: [{ hooks: [handler('capture', 18, 'Saving to MemoryRouter')] }],
     SessionEnd: [{ hooks: [handler('flush', 3)] }],
   };
 }
 
+/**
+ * OAuth hooks: no API key and no local runtime. Codex calls hidden tools on the
+ * already-authenticated `memoryrouter` MCP server (`type: "mcp_tool"`), with
+ * the user's OAuth token and the vault picked during sign-in.
+ *   UserPromptSubmit -> codex_turn_start: recall for this prompt (returned as
+ *     developer context), then save the prompt.
+ *   Stop -> codex_turn_end: save the final assistant message.
+ *   SessionStart (compact) -> codex_session_start: restore context right after
+ *     Codex compacts a long chat.
+ * Codex does not support mcp_tool hooks on SessionEnd; none is needed.
+ */
+function mcpManagedGroups(serverName = 'memoryrouter') {
+  const turn = { session_id: '${session_id}', turn_id: '${turn_id}', cwd: '${cwd}' };
+  return {
+    // Only after compaction: on startup/resume/clear the first prompt's
+    // codex_turn_start recall already injects context (no double injection).
+    SessionStart: [{
+      matcher: 'compact',
+      hooks: [{ type: 'mcp_tool', server: serverName, tool: 'codex_session_start', input: { session_id: '${session_id}', cwd: '${cwd}', source: '${source}' }, timeout: 12, statusMessage: 'Recalling MemoryRouter context' }],
+    }],
+    UserPromptSubmit: [{
+      hooks: [{ type: 'mcp_tool', server: serverName, tool: 'codex_turn_start', input: { prompt: '${prompt}', ...turn }, timeout: 12, statusMessage: 'Searching MemoryRouter' }],
+    }],
+    Stop: [{
+      hooks: [{ type: 'mcp_tool', server: serverName, tool: 'codex_turn_end', input: { last_assistant_message: '${last_assistant_message}', ...turn }, timeout: 15, statusMessage: 'Saving to MemoryRouter' }],
+    }],
+  };
+}
+
 function parseHooks(file) {
   const raw = readText(file);
   if (!raw.trim()) return { description: 'Lifecycle hooks for this Codex configuration.', hooks: {} };
@@ -71,18 +109,19 @@ function parseHooks(file) {
   }
 }
 
-function installHooks(file, runtimeDir, scope) {
+function installHooks(file, runtimeDir, scope, options = {}) {
   const current = parseHooks(file);
   const clean = cleanOwnedHooks(current);
   clean.description = clean.description || 'Lifecycle hooks for this Codex configuration.';
   clean.hooks = clean.hooks || {};
-  for (const [event, groups] of Object.entries(managedGroups(runtimeDir, scope))) {
+  const groupsToInstall = options.mode === 'mcp' ? mcpManagedGroups(options.serverName) : managedGroups(runtimeDir, scope);
+  for (const [event, groups] of Object.entries(groupsToInstall)) {
     clean.hooks[event] = [...(clean.hooks[event] || []), ...groups];
   }
   const rendered = `${JSON.stringify(clean, null, 2)}\n`;
   const previous = readText(file);
   atomicWrite(file, rendered);
-  return { changed: rendered !== previous, file, events: Object.keys(managedGroups(runtimeDir, scope)) };
+  return { changed: rendered !== previous, file, mode: options.mode === 'mcp' ? 'mcp' : 'command', events: Object.keys(groupsToInstall) };
 }
 
 function uninstallHooks(file) {
@@ -99,4 +138,4 @@ function uninstallHooks(file) {
   return { changed: true, file };
 }
 
-module.exports = { isOwnedHook, cleanOwnedHooks, commandFor, managedGroups, parseHooks, installHooks, uninstallHooks };
+module.exports = { isOwnedHook, cleanOwnedHooks, commandFor, managedGroups, mcpManagedGroups, MCP_HOOK_TOOLS, parseHooks, installHooks, uninstallHooks };

package/lib/installer.cjs

@@ -9,9 +9,9 @@ const { resolveProject } = require('../runtime/project.cjs');
 const { MCP_ENDPOINT, INTEGRATION_VERSION } = require('../runtime/constants.cjs');
 const {
   installToml, uninstallToml, installAgents, uninstallAgents, readText, replaceBlock,
-  hasUnmanagedMemoryRouterTable, TOML_START, TOML_END, AGENTS_START, AGENTS_END,
+  hasUnmanagedMemoryRouterTable, externalRemoteServerName, TOML_START, TOML_END, AGENTS_START, AGENTS_END,
 } = require('./managed.cjs');
-const { installHooks, uninstallHooks, isOwnedHook, managedGroups, parseHooks } = require('./hooks.cjs');
+const { installHooks, uninstallHooks, isOwnedHook, managedGroups, mcpManagedGroups, parseHooks } = require('./hooks.cjs');
 
 function resolveLayout(options = {}) {
   const env = options.env || process.env;
@@ -54,6 +54,9 @@ function preflight(layout, options = {}) {
   const configText = readText(layout.configFile);
   // Validate marker pairs before any file is changed.
   replaceBlock(configText, TOML_START, TOML_END, '');
+  // A remote MemoryRouter server the user added themselves (Codex app:
+  // Settings > Plugins > Add MCP server) is adopted as is, never an error.
+  if (options.auth !== 'api-key' && externalRemoteServerName(configText, MCP_ENDPOINT)) return;
   if (hasUnmanagedMemoryRouterTable(configText) && !options.force) {
     throw new Error(`An unmanaged [mcp_servers.memoryrouter] table already exists in ${layout.configFile}. Re-run with --force after reviewing the migration backup.`);
   }
@@ -61,16 +64,41 @@ function preflight(layout, options = {}) {
   if (options.agents !== false) replaceBlock(readText(layout.agentsFile), AGENTS_START, AGENTS_END, '');
 }
 
+/**
+ * How the automatic hooks reach MemoryRouter.
+ * - 'mcp': Codex `mcp_tool` hooks call MemoryRouter's hidden lifecycle tools
+ *   over the signed-in OAuth MCP connection. No API key on disk.
+ * - 'command': the local Node runtime with a Memory Key (api-key mode, or
+ *   OAuth users who also configured a key, e.g. shared with Claude Code).
+ */
+function resolveHookMode(options, auth, env) {
+  if (options.hookMode === 'mcp' || options.hookMode === 'command') return options.hookMode;
+  if (auth === 'api-key') return 'command';
+  const key = options.apiKey || getApiKey(env, loadConfig(options.env));
+  return key ? 'command' : 'mcp';
+}
+
 function init(options = {}) {
   const layout = resolveLayout(options);
   const auth = options.auth || 'oauth';
   if (!['oauth', 'api-key'].includes(auth)) throw new Error('--auth must be oauth or api-key');
-  preflight(layout, options);
+  if (options.hookMode && !['mcp', 'command'].includes(options.hookMode)) throw new Error('--hooks-via must be mcp or command');
+  const env = options.env || process.env;
+  preflight(layout, { ...options, auth });
+  const hookMode = resolveHookMode(options, auth, env);
+  if (hookMode === 'mcp' && auth === 'api-key') throw new Error('--hooks-via mcp needs the OAuth MCP server (--auth oauth).');
   copyRuntime(layout.runtimeDir);
   const results = [];
-  results.push(installToml(layout.configFile, { auth, scope: layout.scope, runtimeDir: layout.runtimeDir, force: options.force }));
-  if (options.hooks !== false) results.push(installHooks(layout.hooksFile, layout.runtimeDir, layout.scope));
-  if (options.agents !== false) results.push(installAgents(layout.agentsFile));
+  const adoptedServer = auth === 'oauth' ? externalRemoteServerName(readText(layout.configFile), MCP_ENDPOINT) : null;
+  if (adoptedServer) {
+    // Leave the user's own server table (and its sign-in) untouched.
+    results.push({ changed: false, file: layout.configFile, adopted: adoptedServer });
+  } else {
+    results.push(installToml(layout.configFile, { auth, scope: layout.scope, runtimeDir: layout.runtimeDir, force: options.force }));
+  }
+  const serverName = adoptedServer || 'memoryrouter';
+  if (options.hooks !== false) results.push(installHooks(layout.hooksFile, layout.runtimeDir, layout.scope, { mode: hookMode, serverName }));
+  if (options.agents !== false) results.push(installAgents(layout.agentsFile, { hookMode }));
 
   if (options.apiKey) {
     const current = loadConfig(options.env);
@@ -81,6 +109,9 @@ function init(options = {}) {
     installedAt: new Date().toISOString(),
     scope: layout.scope,
     auth,
+    hookMode,
+    serverName,
+    adoptedServer: Boolean(adoptedServer),
     configFile: layout.configFile,
     hooksFile: options.hooks === false ? null : layout.hooksFile,
     agentsFile: options.agents === false ? null : layout.agentsFile,
@@ -90,12 +121,14 @@ function init(options = {}) {
   fs.mkdirSync(manifestDir, { recursive: true, mode: 0o700 });
   const manifestName = Buffer.from(`${layout.scope}:${layout.root}`).toString('base64url');
   fs.writeFileSync(path.join(manifestDir, `${manifestName}.json`), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
-  const env = options.env || process.env;
   return {
     layout,
     auth,
+    hookMode,
+    serverName,
+    adoptedServer,
     results,
-    automaticMemory: Boolean(options.apiKey || getApiKey(env, loadConfig(options.env))),
+    automaticMemory: options.hooks !== false && (hookMode === 'mcp' || Boolean(options.apiKey || getApiKey(env, loadConfig(options.env)))),
     keySource: options.apiKey ? 'codex-config' : apiKeySource(env, loadConfig(options.env)),
   };
 }
@@ -175,7 +208,9 @@ async function doctor(options = {}) {
   else if (!versionAtLeast(codex.version, [0, 145, 0])) addCheck(checks, 'codex-version', 'error', `${codex.output} is too old for the lifecycle hooks used here. Upgrade to Codex 0.145.0 or newer.`);
   else addCheck(checks, 'codex-version', 'pass', `${codex.output} supports current hooks and remote MCP configuration.`);
 
-  addCheck(checks, 'mcp-config', configText.includes(TOML_START) && configText.includes('[mcp_servers.memoryrouter]') ? 'pass' : 'error',
+  const adopted = externalRemoteServerName(configText, MCP_ENDPOINT);
+  if (adopted) addCheck(checks, 'mcp-config', 'pass', `MemoryRouter MCP server "${adopted}" (added in the Codex app or by hand) is configured.`);
+  else addCheck(checks, 'mcp-config', configText.includes(TOML_START) && configText.includes('[mcp_servers.memoryrouter]') ? 'pass' : 'error',
     configText.includes(TOML_START) ? 'Managed MemoryRouter MCP configuration is present.' : 'Managed MemoryRouter MCP configuration is missing.');
   addCheck(checks, 'runtime', runtimeVersion === INTEGRATION_VERSION ? 'pass' : 'error',
     runtimeVersion ? `Installed runtime version is ${runtimeVersion}; package version is ${INTEGRATION_VERSION}.` : 'Managed runtime is missing.');
@@ -183,15 +218,21 @@ async function doctor(options = {}) {
   let hooks = null;
   try { hooks = hooksText ? JSON.parse(hooksText) : null; } catch { /* handled */ }
   const owned = hooks ? Object.values(hooks.hooks || {}).flat().flatMap(group => group.hooks || []).filter(isOwnedHook) : [];
-  const expectedOwned = Object.values(managedGroups(layout.runtimeDir, layout.scope)).flat().flatMap(group => group.hooks || []).length;
-  addCheck(checks, 'hooks', owned.length === expectedOwned ? 'pass' : 'error', owned.length ? `${owned.length} of ${expectedOwned} managed lifecycle hooks found.` : 'Managed lifecycle hooks are missing or hooks.json is invalid.');
+  const mcpHooks = owned.filter(handler => handler.type === 'mcp_tool');
+  const expectedOwned = mcpHooks.length
+    ? Object.values(mcpManagedGroups()).flat().flatMap(group => group.hooks || []).length
+    : Object.values(managedGroups(layout.runtimeDir, layout.scope)).flat().flatMap(group => group.hooks || []).length;
+  addCheck(checks, 'hooks', owned.length === expectedOwned ? 'pass' : 'error', owned.length
+    ? `${owned.length} of ${expectedOwned} managed lifecycle hooks found${mcpHooks.length ? ' (over the signed-in MCP connection, no API key needed)' : ''}. Trust them once in Codex: app Settings > Hooks, or /hooks in the CLI.`
+    : 'Managed lifecycle hooks are missing or hooks.json is invalid.');
   addCheck(checks, 'agents', agentsText.includes(AGENTS_START) ? 'pass' : 'warn', agentsText.includes(AGENTS_START) ? 'Managed AGENTS.md guidance is present.' : 'Managed AGENTS.md guidance is missing.');
 
   const cfg = loadConfig(options.env);
   const keyEnv = options.env || process.env;
   const key = getApiKey(keyEnv, cfg);
   const keyFrom = apiKeySource(keyEnv, cfg);
-  if (!key) addCheck(checks, 'automatic-auth', 'warn', 'No MemoryRouter API key is available. Remote OAuth tools can work after `codex mcp login memoryrouter`, but automatic hook retrieval/capture is disabled.');
+  if (!key && mcpHooks.length) addCheck(checks, 'automatic-auth', 'pass', 'Automatic recall and saving use your MemoryRouter sign-in (OAuth). No API key needed.');
+  else if (!key) addCheck(checks, 'automatic-auth', 'warn', 'No MemoryRouter API key is available. Remote OAuth tools can work after `codex mcp login memoryrouter`, but automatic hook retrieval/capture is disabled.');
   else {
     try {
       const { stats } = require('../runtime/api.cjs');
@@ -210,7 +251,7 @@ async function doctor(options = {}) {
     }
   }
 
-  if (configText.includes('auth = "oauth"')) {
+  if (configText.includes('auth = "oauth"') || adopted) {
     if (options.offline) {
       addCheck(checks, 'oauth-discovery', 'warn', 'OAuth discovery check skipped in offline mode.');
       addCheck(checks, 'oauth-session', 'info', 'Browser consent/token issuance is user-specific. Run `codex mcp login memoryrouter`; then `/mcp verbose`. Doctor does not claim login completion without interactive consent.');

package/lib/managed.cjs

@@ -53,6 +53,26 @@ function removeUnmanagedMemoryRouterTables(text) {
   return kept.join('\n').replace(/\n{3,}/g, '\n\n');
 }
 
+/**
+ * The MCP server name the user already connected to MemoryRouter's remote
+ * endpoint outside our managed block (for example the Codex app's
+ * Settings > Plugins > Add MCP server), or null. Returns the first
+ * `[mcp_servers.<name>]` whose `url` is the MemoryRouter MCP endpoint.
+ */
+function externalRemoteServerName(text, endpoint) {
+  const stripped = replaceBlock(text, TOML_START, TOML_END, '');
+  const lines = stripped.split('\n');
+  let current = null;
+  for (const line of lines) {
+    const table = line.match(/^\s*\[mcp_servers\.("?)([^\]".]+)\1\]\s*(?:#.*)?$/);
+    if (table) { current = table[2]; continue; }
+    if (/^\s*\[/.test(line)) { current = null; continue; }
+    const url = line.match(/^\s*url\s*=\s*"([^"]+)"/);
+    if (current && url && url[1].replace(/\/+$/, '') === endpoint.replace(/\/+$/, '')) return current;
+  }
+  return null;
+}
+
 function tomlString(value) { return JSON.stringify(String(value)); }
 
 function mcpBlock({ auth = 'oauth', scope = 'user', runtimeDir }) {
@@ -129,13 +149,16 @@ function uninstallToml(file) {
   return { changed: true, file };
 }
 
-function agentsBlock() {
-  return `## MemoryRouter memory\n\n- MemoryRouter is the durable cross-machine, cross-tool, and team/auditable memory layer. Codex native Memories may remain enabled as the local personal recall layer.\n- Automatic hooks search project-scoped memory before each prompt and capture completed turns when a MemoryRouter API key is configured.\n- For explicit recall, search MemoryRouter before answering questions about prior decisions, preferences, incidents, or unfinished work. Depending on auth mode, the tool is named \`search_memories\` or \`memory_search\`.\n- Store only concise, durable decisions, preferences, facts, and incident outcomes. Depending on auth mode, use \`store_memory\` or \`memory_store\`. Do not duplicate a completed turn that hooks already captured.\n- Keep and cite returned \`mrh_...\` handles when a specific memory must be referenced later.\n- Project scope is derived from the canonical git remote when available, so worktrees and machines share identity without uploading local paths. It is the same project memory Claude Code uses through memoryrouter-claude, so decisions made in either agent are available in both.\n- If MemoryRouter is offline, continue the task without memory; never block work on recall or capture.`;
+function agentsBlock(options = {}) {
+  const automatic = options.hookMode === 'mcp'
+    ? '- Automatic hooks (over the signed-in MemoryRouter connection) search the vault before each prompt and add what they find as context, then save each completed turn: the user\'s message and your final response only, never tool calls, tool output or intermediate steps.\n'
+    : '- Automatic hooks search the vault before each prompt and save each completed turn (the user\'s message and your final response only) when a MemoryRouter API key is configured.\n';
+  return `## MemoryRouter memory\n\n- MemoryRouter is the durable cross-machine, cross-tool, and team/auditable memory layer. Codex native Memories may remain enabled as the local personal recall layer.\n${automatic}- For explicit recall, search MemoryRouter before answering questions about prior decisions, preferences, incidents, or unfinished work. Depending on auth mode, the tool is named \`search_memories\` or \`memory_search\`.\n- Store only concise, durable decisions, preferences, facts, and incident outcomes. Depending on auth mode, use \`store_memory\` or \`memory_store\`. Do not duplicate a completed turn that hooks already captured.\n- Keep and cite returned \`mrh_...\` handles when a specific memory must be referenced later.\n- Project scope is derived from the canonical git remote when available, so worktrees and machines share identity without uploading local paths. It is the same project memory Claude Code uses through memoryrouter-claude, so decisions made in either agent are available in both.\n- If MemoryRouter is offline, continue the task without memory; never block work on recall or capture.`;
 }
 
-function installAgents(file) {
+function installAgents(file, options = {}) {
   const current = readText(file);
-  const updated = replaceBlock(current, AGENTS_START, AGENTS_END, agentsBlock());
+  const updated = replaceBlock(current, AGENTS_START, AGENTS_END, agentsBlock(options));
   atomicWrite(file, updated);
   return { changed: updated !== current, file };
 }
@@ -158,6 +181,7 @@ module.exports = {
   atomicWrite,
   replaceBlock,
   hasUnmanagedMemoryRouterTable,
+  externalRemoteServerName,
   removeUnmanagedMemoryRouterTables,
   mcpBlock,
   installToml,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memoryrouter-codex",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Automatic MemoryRouter memory for OpenAI Codex: one vault shared by every session, repo and tool, including Claude Code",
   "license": "MIT",
   "type": "commonjs",

package/runtime/constants.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-const INTEGRATION_VERSION = '1.7.0';
+const INTEGRATION_VERSION = '1.8.0';
 const RUNTIME_SCHEMA_VERSION = 1;
 const API_BASE = 'https://api.memoryrouter.ai';
 const MCP_ENDPOINT = 'https://mcp.memoryrouter.ai/mcp';

package/runtime/hook.cjs

@@ -64,8 +64,16 @@ function maybeAppendNudge(context, reflection, sessionId, hookContext, importSta
   return context;
 }
 
+// The prompt that started THIS turn. Never another turn's prompt: falling back
+// to "the last prompt seen" could pair a response with the wrong question.
+function promptForTurn(state, turnId) {
+  if (state.prompts?.[turnId]) return state.prompts[turnId];
+  if (turnId && state.lastTurnId === turnId) return state.lastPrompt || '';
+  return '';
+}
+
 function turnContent(input, state) {
-  const prompt = state.prompts?.[input.turn_id] || state.lastPrompt || '';
+  const prompt = promptForTurn(state, input.turn_id);
   return [
     prompt ? `User request:
 ${truncate(prompt, 40000)}` : null,
@@ -79,11 +87,15 @@ ${truncate(input.last_assistant_message, 60000)}`
 async function handleInject(input, context) {
   const prompt = typeof input.prompt === 'string' ? input.prompt.trim() : '';
   if (!prompt) return;
-  const state = loadSessionState(input.session_id, context.env);
-  state.prompts = { ...(state.prompts || {}), [input.turn_id]: prompt.slice(0, 100000) };
-  state.lastPrompt = prompt.slice(0, 100000);
-  state.lastTurnId = input.turn_id;
-  saveSessionState(input.session_id, state, context.env);
+  // A thread-spawned subagent's "prompt" is the parent agent's instruction (an
+  // intermediate step). Recall for it, but never record it for capture.
+  if (!input.agent_id) {
+    const state = loadSessionState(input.session_id, context.env);
+    state.prompts = { ...(state.prompts || {}), [input.turn_id]: prompt.slice(0, 100000) };
+    state.lastPrompt = prompt.slice(0, 100000);
+    state.lastTurnId = input.turn_id;
+    saveSessionState(input.session_id, state, context.env);
+  }
 
   const result = await searchScoped(prompt, {
     ...context,
@@ -125,18 +137,27 @@ async function handleSessionStart(input, context) {
   emitContext('SessionStart', maybeAppendNudge(result.context, result.reflection, input.session_id, context, result.importState));
 }
 
+// Stop (partial=false): save the user's prompt + the final assistant response.
+// SessionEnd / PreCompact (partial=true): only if the last turn never reached
+// Stop (interrupted), save that turn's user prompt so it is not lost. A turn
+// that was already saved is never saved again.
 async function captureTurn(input, context, partial = false) {
   const sessionId = input.session_id;
   const turnId = input.turn_id || loadSessionState(sessionId, context.env).lastTurnId;
   if (!sessionId || !turnId) return { ok: false, reason: 'missing-turn' };
   if (!partial && input.stop_hook_active) return { ok: true, skipped: 'stop-hook-active' };
   const state = loadSessionState(sessionId, context.env);
-  if (!partial && state.capturedTurns?.[turnId]) {
+  if (state.capturedTurns?.[turnId]) {
     return { ok: true, skipped: 'deduplicated', handle: state.capturedTurns[turnId] };
   }
-  const prompt = state.prompts?.[turnId] || state.lastPrompt || '';
+  if (partial && state.checkpointedTurns?.[turnId]) {
+    return { ok: true, skipped: 'deduplicated', handle: state.checkpointedTurns[turnId] };
+  }
+  const prompt = promptForTurn(state, turnId);
   if (!partial && !input.last_assistant_message) return { ok: true, skipped: 'empty' };
-  if (partial && !prompt && !input.last_assistant_message) return { ok: true, skipped: 'empty' };
+  if (partial && !prompt) return { ok: true, skipped: 'empty' };
+  // PreCompact/SessionEnd carry no final response; never invent one.
+  if (partial) input = { ...input, last_assistant_message: undefined };
   const content = turnContent({ ...input, turn_id: turnId }, state);
   const kind = partial ? 'checkpoint' : 'turn';
   const handle = memoryHandle(context.project.handle, kind, content);
@@ -151,9 +172,12 @@ async function captureTurn(input, context, partial = false) {
   });
   if (result.ok && result.stored) {
     state.capturedHandles = [...(state.capturedHandles || []), handle].slice(-500);
-    if (!partial) state.capturedTurns = { ...(state.capturedTurns || {}), [turnId]: handle };
-    if (Object.keys(state.capturedTurns || {}).length > 500) {
-      state.capturedTurns = Object.fromEntries(Object.entries(state.capturedTurns).slice(-500));
+    // A checkpoint (prompt of an unfinished turn) never blocks that turn's
+    // full save if it does finish later.
+    const ledger = partial ? 'checkpointedTurns' : 'capturedTurns';
+    state[ledger] = { ...(state[ledger] || {}), [turnId]: handle };
+    if (Object.keys(state[ledger] || {}).length > 500) {
+      state[ledger] = Object.fromEntries(Object.entries(state[ledger]).slice(-500));
     }
     if (!partial && state.prompts) delete state.prompts[turnId];
     state.lastCaptureAt = new Date().toISOString();
@@ -170,36 +194,16 @@ async function captureTurn(input, context, partial = false) {
   return result;
 }
 
+// Subagent output is intermediate work, not the user's conversation. Saving it
+// broke the "user message + final response only" rule, so 1.8.0 no longer
+// installs a SubagentStop hook and this handler is a no-op for installs that
+// still have one until `init` is re-run.
 async function captureSubagent(input, context) {
-  if (!input.last_assistant_message || !input.session_id) return { ok: true, skipped: 'empty' };
-  const state = loadSessionState(input.session_id, context.env);
-  const captureKey = `subagent:${input.agent_id || 'unknown'}:${input.turn_id || 'unknown'}`;
-  if (state.capturedTurns?.[captureKey]) return { ok: true, skipped: 'deduplicated', handle: state.capturedTurns[captureKey] };
-  const content = [
-    'Completed Codex subagent outcome.',
-    `Subagent type: ${input.agent_type || 'unknown'}`,
-    `Subagent id: ${input.agent_id || 'unknown'}`,
-    `Outcome:\n${truncate(input.last_assistant_message, 60000)}`,
-  ].join('\n\n');
-  const handle = memoryHandle(context.project.handle, 'subagent', content);
-  const result = await storeScoped(content, {
-    ...context,
-    kind: 'subagent',
-    handle,
-    skipRemoteDedupe: true,
-    timeoutMs: 12000,
-    tags: ['codex', 'subagent', input.agent_type || 'unknown'],
-  });
-  if (result.ok && result.stored) {
-    state.capturedHandles = [...(state.capturedHandles || []), handle].slice(-500);
-    state.capturedTurns = { ...(state.capturedTurns || {}), [captureKey]: handle };
-    if (Object.keys(state.capturedTurns).length > 500) state.capturedTurns = Object.fromEntries(Object.entries(state.capturedTurns).slice(-500));
-    saveSessionState(input.session_id, state, context.env);
-  }
-  recordHealth('capture-subagent', { ok: result.ok, status: result.status, project: context.project.handle, handle }, context.env);
-  return result;
+  recordHealth('capture-subagent', { ok: true, skipped: 'subagent-not-captured', project: context.project.handle }, context.env);
+  return { ok: true, skipped: 'subagent-not-captured' };
 }
 
+
 async function run(kind, input, options = {}) {
   const env = options.env || process.env;
   const config = options.config || loadConfig(env);