memoryrouter-codex 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MemoryRouter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,225 @@
+# MemoryRouter for OpenAI Codex
+
+Native Codex integration for durable MemoryRouter memory. It uses Codex's current MCP, lifecycle hooks, and `AGENTS.md` surfaces rather than pretending that model-selected MCP calls alone are automatic memory.
+
+## What this integration does
+
+| Layer | Behavior |
+| --- | --- |
+| `UserPromptSubmit` hook | Searches MemoryRouter before every prompt and injects bounded, project-scoped context as developer context. |
+| `PostToolUse` + `Stop` hooks | Captures the user request, stable hook-provided tool inputs/results, and final answer after each completed turn. |
+| `SubagentStop` hook | Captures the stable final outcome of completed subagents without parsing their unstable transcript files. |
+| `PreCompact` / compact `SessionStart` | Checkpoints work before compaction and recalls context before Codex continues after compaction. |
+| `SessionEnd` | Best-effort 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 with strict project filtering, handles, local suppression, status, and full-vault clear confirmation. |
+| `AGENTS.md` | Tells Codex when to recall/store and how MemoryRouter coexists with native Memories. |
+
+MemoryRouter is the **cross-machine, cross-tool, team-shareable, and auditable** layer. Codex's native Memories remain useful as an automated local personal recall layer.
+
+## Requirements and supported surfaces
+
+- 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.
+- 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.
+
+There is no dependency on the obsolete `experimental_use_rmcp_client` setting in current Codex. That flag was required by old Codex releases; it is absent from the current 0.146 configuration reference and is not written by this installer.
+
+## Install
+
+### Recommended: remote OAuth MCP plus automatic hooks
+
+Obtain a MemoryRouter memory key from your account. Pass it on stdin so it does not appear in shell history:
+
+```bash
+printf '%s' "$MEMORYROUTER_API_KEY" | \
+  npx -y memoryrouter-codex@1.0.0 init --scope user --auth oauth --api-key-stdin
+
+codex mcp login memoryrouter
+memoryrouter-codex doctor --scope user
+```
+
+Then start Codex and inspect:
+
+```text
+/mcp verbose
+/hooks
+```
+
+The API key is written to `~/.memoryrouter/codex/config.json` with mode `0600`; the directory is `0700`. It is never written to `config.toml`, `hooks.json`, `AGENTS.md`, or a repository.
+
+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.
+
+### Project scope
+
+```bash
+cd /path/to/repository
+printf '%s' "$MEMORYROUTER_API_KEY" | \
+  npx -y memoryrouter-codex@1.0.0 init --scope project --auth oauth --api-key-stdin
+codex mcp login memoryrouter
+```
+
+This writes managed blocks/files under the repository's `AGENTS.md` and `.codex/`. The runtime contains no secret. Review which files your team wants to commit. Every machine or cloud environment must supply its own authentication.
+
+### Secure API-key fallback when OAuth is blocked
+
+```bash
+printf '%s' "$MEMORYROUTER_API_KEY" | \
+  npx -y memoryrouter-codex@1.0.0 init --scope user --auth api-key --api-key-stdin
+```
+
+This uses a local stdio MCP server and the MemoryRouter API. It does not put the memory key in Codex config. The fallback tools are:
+
+- `memory_search`
+- `memory_store`
+- `memory_status`
+- `memory_forget`
+
+For project scope, the stdio command is package-version-pinned through `npx`; secrets still come from the environment or private home config.
+
+## Exact configuration written
+
+The remote mode adds a versioned managed block equivalent to:
+
+```toml
+[mcp_servers.memoryrouter]
+url = "https://mcp.memoryrouter.ai/mcp"
+auth = "oauth"
+enabled = true
+required = false
+startup_timeout_sec = 20
+tool_timeout_sec = 45
+default_tools_approval_mode = "writes"
+scopes = ["memories:read", "memories:write"]
+
+[mcp_servers.memoryrouter.tools.store_memory]
+approval_mode = "prompt"
+```
+
+`oauth_resource` is intentionally omitted: MemoryRouter's RFC 9728 metadata already supplies the exact resource. Codex 0.146 was observed duplicating the `resource` authorization parameter when the same value was also pinned in config.
+
+The installer preserves unrelated TOML byte-for-byte outside its managed block. If an unmanaged `[mcp_servers.memoryrouter]` table already exists, it refuses to create invalid duplicate TOML. `--force` creates a timestamped backup, removes only that table and its nested MemoryRouter tool tables, and installs the managed block.
+
+Hooks are merged into `hooks.json`; foreign hooks remain. Re-running `init` upgrades/replaces only MemoryRouter-owned handlers. `uninstall` removes only owned handlers and managed blocks.
+
+## Project identity and scoping
+
+The runtime computes:
+
+```text
+proj_<first 20 hex chars of SHA-256(canonical project identity)>
+```
+
+Identity preference:
+
+1. Canonical `origin` git URL, with credentials removed and `.git` normalized.
+2. Git common directory (so local worktrees share a project).
+3. Absolute path fallback.
+
+Only the opaque handle is stored remotely. Local paths are not sent as identity metadata. A canonical remote makes identity stable across worktrees and machines.
+
+Automatic memories use an envelope containing project handle, stable memory handle, kind, and capture time. Retrieval requests extra semantic candidates and then **strictly filters** to the current project handle before context injection. Legacy/unscoped vault records remain available through explicit remote MCP search but are not automatically injected in project mode.
+
+Set `retrievalScope` to `"vault"` in the private config only if you intentionally want unscoped automatic recall.
+
+## Handles, deduplication, retries, and forgetting
+
+- Handles (`mrh_...`) are content-derived from project, kind, and normalized content.
+- Explicit local `memory_store` searches for the exact handle before writing, so exact repeats deduplicate across machines when the earlier record is searchable.
+- Automatic turn capture keeps local captured-turn/handle state and does not retry writes. This avoids most duplicates. Because the current ingest API has no server-side idempotency key, a network timeout after server acceptance can still create a duplicate on a later attempt. The integration does not claim otherwise.
+- Read/search/status requests retry transient errors with short exponential backoff. Writes and destructive operations are never blindly retried.
+- `memory_forget(handle=...)` suppresses that handle from this machine's Codex integration; it explicitly does **not** claim server deletion because the current API has no per-memory delete endpoint.
+- Whole-vault deletion is available only when `memory_forget` receives the exact phrase `CLEAR MY ENTIRE MEMORYROUTER VAULT`. It is irreversible and should require Codex approval.
+- Use the MemoryRouter dashboard for server-side audit/management where available.
+
+## Context budget and failure behavior
+
+- Default injected context cap: 12,000 characters, assembled at memory boundaries.
+- Hook `additionalContextLimit`: approximately 3,500 tokens, so Codex can spill unexpectedly large context safely instead of consuming the whole model window.
+- Candidate search default: 12 before strict project filtering.
+- All hook entrypoints exit zero on missing credentials, malformed input, API errors, and timeouts. Memory never blocks Codex work.
+- Hook status is recorded without secrets in `~/.memoryrouter/codex/health.json`. Search/store/forget outcomes (metadata only, never memory content or keys) append to a rotating 5 MiB local `~/.memoryrouter/codex/audit.jsonl`. `memory_status` exposes both locations. This is a host-local integration audit, not a server-wide team access log. Session/trace state older than 30 days is pruned at session start.
+- Set `MEMORYROUTER_DEBUG=1` for hook errors on stderr. Debug is off by default.
+
+## Codex native Memories coexistence
+
+This installer does not overwrite native-memory settings. Native Memories are off by default and can be enabled independently:
+
+```toml
+[features]
+memories = true
+
+[memories]
+disable_on_external_context = true
+```
+
+`disable_on_external_context = true` keeps chats that used MCP/web/tool-search context out of Codex's background memory generation, avoiding a second divergent extraction of MemoryRouter-assisted work. This also means those chats will not contribute to native Memories. Leave it `false` if you intentionally want both systems to learn from the same chat.
+
+Use `/memories` for per-chat native-memory controls. Keep required team rules in `AGENTS.md`, not in either memory system.
+
+## OAuth findings (tested 2026-07-31)
+
+Live verification with official `@openai/codex` **0.146.0** established:
+
+1. `codex mcp add --url https://mcp.memoryrouter.ai/mcp memoryrouter` writes the expected streamable HTTP entry.
+2. Codex discovers RFC 9728 protected-resource metadata.
+3. Codex discovers `https://auth.memoryrouter.ai` authorization metadata.
+4. Dynamic client registration succeeds and issues a `dcr_...` client ID.
+5. Codex generates an authorization URL with PKCE S256, `memories:read memories:write`, the exact RFC 8707 resource, and a loopback callback.
+6. The browser consent/token step was deliberately not completed by the package test because it is account-specific. Therefore `doctor` verifies discovery compatibility but never reports an OAuth session as logged in without user consent. Use `codex mcp login memoryrouter` and `/mcp verbose` to complete/verify it.
+
+The remote server currently negotiates legacy MCP `2025-11-25`. Codex 0.146 remains dual-era and initializes it successfully today. MemoryRouter's MCP server still needs its separate `2026-07-28` protocol modernization; this client integration does not hide that server limitation.
+
+## Doctor
+
+```bash
+memoryrouter-codex doctor --scope user
+memoryrouter-codex doctor --scope project --project-dir /repo
+memoryrouter-codex doctor --offline
+```
+
+Doctor checks Codex version, managed config, runtime version, hook count, `AGENTS.md`, private-key availability/validity, OAuth discovery, native-memory coexistence, project identity portability, and local/cloud surface limitations.
+
+## Upgrade and uninstall
+
+Upgrade idempotently by re-running the pinned/new package:
+
+```bash
+npx -y memoryrouter-codex@1.0.0 init --scope user
+```
+
+Uninstall:
+
+```bash
+npx -y memoryrouter-codex@1.0.0 uninstall --scope user
+# or
+npx -y memoryrouter-codex@1.0.0 uninstall --scope project --project-dir /repo
+```
+
+Uninstall deliberately retains `~/.memoryrouter/codex/` because another project installation may use the credentials and local suppression state. Delete that private directory manually only when no integration uses it.
+
+## Honest limitations
+
+- Hooks are the deterministic automatic path. Remote MCP alone remains model-invoked, not guaranteed every turn.
+- The transcript file path supplied to hooks is documented as unstable, so this integration does **not** parse Codex transcript JSONL. It captures only stable hook fields: prompt, tool input/result, and final assistant message.
+- Hosted tools such as web search do not currently emit `PostToolUse`; their detailed output is not automatically captured unless reflected in the final response.
+- Some specialized tool paths can opt out of hooks. Codex documents hooks as a useful extension surface, not a complete enforcement boundary.
+- SessionEnd can happen after a 30-minute idle period and has a three-second maximum. It is a best-effort checkpoint; normal `Stop` capture is the primary write path.
+- Project scoping is strict for this package's automatic retrieval/local MCP. The existing hosted remote MCP server has no first-class project argument, so use local tools/hooks when cross-project isolation is required.
+- Per-memory server deletion is not available through the current API. Local suppression and explicit full-vault clear are accurately labeled.
+- API-level idempotency is not yet available; timeout-after-acceptance duplicates remain possible.
+
+## Development
+
+```bash
+cd integrations/codex
+npm test
+npm run typecheck
+npm run pack:dry
+```
+
+No package, config, fixture, or runtime file contains a production secret.

package/RESEARCH.md

@@ -0,0 +1,57 @@
+# Codex integration research and acceptance evidence
+
+Verified 2026-07-31. This is engineering evidence, not public marketing copy.
+
+## Official sources
+
+- MCP configuration and supported local hosts: <https://developers.openai.com/codex/mcp>
+- Current configuration reference: <https://developers.openai.com/codex/config-reference>
+- Lifecycle hooks contract and schemas: <https://developers.openai.com/codex/hooks>
+- `AGENTS.md` discovery and 32 KiB default budget: <https://developers.openai.com/codex/guides/agents-md>
+- Native two-phase local Memories: <https://developers.openai.com/codex/memories>
+- CLI/MCP command reference: <https://developers.openai.com/codex/cli/reference>
+- Codex 0.146.0 release (2026-07-29): <https://github.com/openai/codex/releases/tag/rust-v0.146.0>
+- Current RMCP client source: <https://github.com/openai/codex/blob/main/codex-rs/rmcp-client/src/rmcp_client.rs>
+- Current hook schemas: <https://github.com/openai/codex/tree/main/codex-rs/hooks/schema/generated>
+
+## Platform findings used in the architecture
+
+- Current Codex supports command hooks for `SessionStart`, `SessionEnd`, `PreToolUse`, `PostToolUse`, `PreCompact`, `PostCompact`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, and `Stop`.
+- Hook transcript paths are explicitly documented as unstable. The integration therefore uses stable event fields and an append-only local tool trace rather than parsing transcript JSONL.
+- Hooks are enabled by default and project hooks require trust. `features.codex_hooks` is only a deprecated alias; the current canonical key is `features.hooks`.
+- Remote MCP OAuth no longer needs `experimental_use_rmcp_client` in current Codex. That key is absent from the current configuration reference.
+- The local CLI, desktop Codex host, and IDE extension share Codex config. ChatGPT web uses hosted plugin tools and does not inherit local config.
+- Project `.codex` layers load only in trusted projects.
+- Native Memories are local, off by default, background-extracted/consolidated, and independently controlled by `generate_memories`, `use_memories`, and `disable_on_external_context`.
+
+## Live OAuth acceptance item C1
+
+Using the official npm package `@openai/codex@0.146.0` with a temporary empty `CODEX_HOME`:
+
+1. `codex mcp add --url https://mcp.memoryrouter.ai/mcp memoryrouter` wrote a valid streamable HTTP server entry and immediately detected OAuth.
+2. `codex mcp list` reported the server enabled and not logged in before consent.
+3. `codex mcp get memoryrouter` reported the correct URL and transport.
+4. `codex mcp login memoryrouter` discovered MemoryRouter's RFC 9728 metadata and OAuth authorization metadata.
+5. Dynamic client registration succeeded and returned a `dcr_...` client ID.
+6. Codex produced a loopback authorization URL containing PKCE S256, `memories:read memories:write`, and `resource=https://mcp.memoryrouter.ai/mcp`.
+7. Browser consent was deliberately not completed because token issuance is account-specific. No code claims that user login succeeded.
+8. When `oauth_resource` was explicitly configured to the same value already advertised by RFC 9728, Codex 0.146 emitted the `resource` query parameter twice. The installer intentionally omits that redundant field; a second probe then emitted exactly one resource parameter.
+
+## Live protocol finding
+
+An unauthenticated safe `initialize` probe to `https://mcp.memoryrouter.ai/mcp` returned `protocolVersion: 2025-11-25`. Codex 0.146 is dual-era and currently accepts it. The hosted server is not yet MCP `2026-07-28` compliant; this package reports rather than conceals that limitation.
+
+## Local fallback acceptance
+
+The generated API-key stdio configuration was parsed by Codex 0.146. `codex mcp list/get` reported the expected `node .../mcp-stdio.cjs` transport. Direct stdio initialization and `tools/list` returned all four annotated tools.
+
+## Validation commands
+
+```bash
+cd integrations/codex
+npm test
+npm run typecheck
+npm pack --dry-run
+```
+
+The integration suite covers config migration/backup, foreign-config preservation, corrupt config fail-closed behavior, idempotent upgrades, uninstall, project/worktree identity, project-vs-vault filtering, native-memory config coexistence, OAuth/local fallback configuration, read retries, write deduplication, hook fail-open behavior, full stable-field turn capture, context budgets, local suppression, and MCP tool annotations.

package/bin/cli.cjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const { init, uninstall, doctor } = require('../lib/installer.cjs');
+const { INTEGRATION_VERSION } = require('../runtime/constants.cjs');
+
+function parseArgs(argv) {
+  const result = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) { result._.push(arg); continue; }
+    const [rawKey, inline] = arg.slice(2).split('=', 2);
+    const key = rawKey.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+    if (rawKey.startsWith('no-')) {
+      const positive = rawKey.slice(3).replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+      result[positive] = false;
+    } else if (inline !== undefined) result[key] = inline;
+    else if (argv[i + 1] && !argv[i + 1].startsWith('--')) result[key] = argv[++i];
+    else result[key] = true;
+  }
+  return result;
+}
+
+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 mcp-server\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 or a key saved with --api-key-stdin.\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) {
+  const options = {
+    scope: args.scope || 'user',
+    auth: args.auth || 'oauth',
+    projectDir: args.projectDir,
+    hooks: args.hooks,
+    agents: args.agents,
+    force: Boolean(args.force),
+    offline: Boolean(args.offline),
+  };
+  if (args.apiKeyStdin) {
+    options.apiKey = fs.readFileSync(0, 'utf8').trim();
+    if (!options.apiKey) throw new Error('--api-key-stdin received an empty value');
+  } else if (args.apiKey) {
+    process.stderr.write('Warning: --api-key can remain in shell history. Prefer --api-key-stdin or MEMORYROUTER_API_KEY.\n');
+    options.apiKey = String(args.apiKey);
+  }
+  return options;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+  if (!command || command === 'help' || args.help) {
+    process.stdout.write(usage());
+    return;
+  }
+  if (command === 'version' || args.version) {
+    process.stdout.write(`${INTEGRATION_VERSION}\n`);
+    return;
+  }
+  if (command === 'hook') {
+    process.argv = [process.argv[0], process.argv[1], args._[1]];
+    await require('../runtime/hook.cjs').main();
+    return;
+  }
+  if (command === 'mcp-server') {
+    await require('../runtime/mcp-stdio.cjs').main();
+    return;
+  }
+  const options = optionsFromArgs(args);
+  if (command === 'init') {
+    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`);
+    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 (result.auth === 'oauth') process.stdout.write('\nNext: codex mcp login memoryrouter\nThen open Codex and run /mcp verbose and /hooks.\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');
+    process.stdout.write('\nRun: memoryrouter-codex doctor\n');
+    return;
+  }
+  if (command === 'doctor') {
+    const result = await doctor(options);
+    for (const check of result.checks) {
+      const icon = check.level === 'pass' ? 'PASS' : check.level === 'error' ? 'FAIL' : check.level.toUpperCase();
+      process.stdout.write(`[${icon}] ${check.name}: ${check.message}\n`);
+    }
+    process.exitCode = result.ok ? 0 : 1;
+    return;
+  }
+  if (command === 'uninstall') {
+    const result = uninstall(options);
+    process.stdout.write(`Removed managed MemoryRouter Codex files from ${result.layout.scope} scope. Foreign config/hooks/instructions were preserved.\n`);
+    process.stdout.write(`Private credentials at ~/.memoryrouter/codex were retained. Delete them manually only if no other installation uses them.\n`);
+    return;
+  }
+  throw new Error(`Unknown command: ${command}\n\n${usage()}`);
+}
+
+main().catch(error => {
+  process.stderr.write(`memoryrouter-codex: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/lib/hooks.cjs

@@ -0,0 +1,103 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWrite, readText } = require('./managed.cjs');
+const { INTEGRATION_VERSION } = require('../runtime/constants.cjs');
+
+function isOwnedHook(handler) {
+  return handler?.type === 'command' && typeof handler.command === 'string' &&
+    (/memoryrouter[\\/]runtime[\\/]hook\.cjs/.test(handler.command) || /memoryrouter-codex(?:@[^ ]+)?\s+hook\b/.test(handler.command));
+}
+
+function cleanOwnedHooks(document) {
+  const clone = JSON.parse(JSON.stringify(document || {}));
+  clone.hooks = clone.hooks && typeof clone.hooks === 'object' ? clone.hooks : {};
+  for (const [event, groups] of Object.entries(clone.hooks)) {
+    if (!Array.isArray(groups)) continue;
+    clone.hooks[event] = groups.map(group => ({
+      ...group,
+      hooks: Array.isArray(group.hooks) ? group.hooks.filter(handler => !isOwnedHook(handler)) : [],
+    })).filter(group => group.hooks.length > 0);
+    if (clone.hooks[event].length === 0) delete clone.hooks[event];
+  }
+  return clone;
+}
+
+function commandFor(runtimeDir, scope) {
+  if (scope === 'project') {
+    return 'node "$(git rev-parse --show-toplevel)/.codex/memoryrouter/runtime/hook.cjs"';
+  }
+  return `node ${JSON.stringify(path.join(runtimeDir, 'hook.cjs'))}`;
+}
+
+function commandWindowsFor(runtimeDir, scope) {
+  if (scope === 'project') {
+    return `npx -y memoryrouter-codex@${INTEGRATION_VERSION} hook`;
+  }
+  return `node ${JSON.stringify(path.join(runtimeDir, 'hook.cjs'))}`;
+}
+
+function managedGroups(runtimeDir, scope) {
+  const base = commandFor(runtimeDir, scope);
+  const windows = commandWindowsFor(runtimeDir, scope);
+  const handler = (kind, timeout, statusMessage, additionalContextLimit) => ({
+    type: 'command',
+    command: `${base} ${kind}`,
+    commandWindows: `${windows} ${kind}`,
+    timeout,
+    ...(statusMessage ? { statusMessage } : {}),
+    ...(additionalContextLimit ? { additionalContextLimit } : {}),
+  });
+  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)] }],
+    PostToolUse: [{ hooks: [handler('trace', 3)] }],
+    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')] }],
+    SessionEnd: [{ hooks: [handler('flush', 3)] }],
+  };
+}
+
+function parseHooks(file) {
+  const raw = readText(file);
+  if (!raw.trim()) return { description: 'Lifecycle hooks for this Codex configuration.', hooks: {} };
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('root must be an object');
+    return parsed;
+  } catch (error) {
+    throw new Error(`Cannot update invalid hooks JSON at ${file}: ${error.message}`);
+  }
+}
+
+function installHooks(file, runtimeDir, scope) {
+  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))) {
+    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)) };
+}
+
+function uninstallHooks(file) {
+  if (!fs.existsSync(file)) return { changed: false, file };
+  const current = parseHooks(file);
+  const clean = cleanOwnedHooks(current);
+  const changed = JSON.stringify(clean) !== JSON.stringify(current);
+  if (!changed) return { changed: false, file };
+  if (Object.keys(clean.hooks || {}).length === 0 && (!clean.description || clean.description === 'Lifecycle hooks for this Codex configuration.')) {
+    fs.rmSync(file, { force: true });
+  } else {
+    atomicWrite(file, `${JSON.stringify(clean, null, 2)}\n`);
+  }
+  return { changed: true, file };
+}
+
+module.exports = { isOwnedHook, cleanOwnedHooks, commandFor, managedGroups, parseHooks, installHooks, uninstallHooks };