engrm 0.4.0 → 0.4.3

package/README.md

@@ -2,17 +2,21 @@
 
 **Cross-device memory for AI coding agents.** Every session remembers what you learned yesterday — on any machine, for every team member.
 
+For npm users, Engrm runs on Node.js 18+ and does not require Bun to be installed.
+
 ```
 npx engrm init
 ```
 
+Public beta. The current source of truth for agent capability differences is [AGENT_SUPPORT.md](AGENT_SUPPORT.md).
+
 ---
 
 ## What It Does
 
 Your AI agent forgets everything between sessions. Engrm fixes that.
 
-- **Captures automatically** — hooks into Claude Code to record discoveries, bugfixes, decisions, and patterns as you work
+- **Captures automatically** — hooks into Claude Code, and into Codex where its public hook surface allows
 - **Remembers across devices** — fix a bug on your laptop, continue on your desktop with full context
 - **Shares with your team** — one developer's hard-won insight becomes everyone's knowledge
 - **Works offline** — local SQLite is the source of truth; syncs when connected
@@ -30,7 +34,7 @@ Visit [engrm.dev](https://engrm.dev) and create an account.
 npx engrm init
 ```
 
-This opens your browser for authentication, writes config to `~/.engrm/`, and registers the MCP server + hooks in Claude Code. Takes about 30 seconds.
+This opens your browser for authentication, writes config to `~/.engrm/`, and registers Engrm in both Claude Code and Codex when those configs are available. Takes about 30 seconds.
 
 **Alternative methods:**
 ```bash
@@ -44,12 +48,12 @@ npx engrm init --url=https://vector.internal.company.com
 npx engrm init --manual
 ```
 
-### 3. Use Claude Code normally
+### 3. Use your agent normally
 
 That's it. Engrm works in the background:
 
 - **Session start** — injects relevant project memory into context
-- **While you work** — captures observations from tool use (edits, writes, commands)
+- **While you work** — captures observations from tool use where the agent exposes that hook surface
 - **Session end** — generates a session digest, syncs to cloud, shows summary
 
 ```
@@ -79,7 +83,9 @@ Engrm Status
   Plan:        Pro ($15/mo)
   Candengo:    https://www.candengo.com
   MCP server:  registered
+  Codex MCP:   registered
   Hooks:       registered (6 hooks)
+  Codex hooks: registered (2 hooks)
 
   Observations:    1,247 active
   By type:         change: 412, discovery: 289, bugfix: 187, ...
@@ -117,6 +123,28 @@ Claude Code session
   Available on all your devices + team members
 ```
 
+```
+Codex session
+  │
+  ├─ SessionStart hook ──→ inject relevant memory into context
+  │
+  ├─ MCP tools ──────────→ search, save, inspect, message, stats
+  │
+  └─ Stop hook ──────────→ session digest + sync + summary
+```
+
+### Agent Support
+
+| Capability | Claude Code | Codex |
+|---|---|---|
+| MCP server tools | ✓ | ✓ |
+| Session-start context injection | ✓ | ✓ |
+| Stop/session summary hook | ✓ | ✓ |
+| Per-tool automatic capture | ✓ | Partial via MCP/manual flows only |
+| Pre-write Sentinel hook | ✓ | Not yet exposed by Codex public hooks |
+| Pre-compact reinjection | ✓ | Not exposed |
+| ElicitationResult capture | ✓ | Not exposed |
+
 ### MCP Tools
 
 The MCP server exposes tools that Claude can call directly:
@@ -128,6 +156,9 @@ The MCP server exposes tools that Claude can call directly:
 | `get_observations` | Fetch full details by ID |
 | `save_observation` | Manually save something worth remembering |
 | `install_pack` | Load a curated knowledge pack for your stack |
+| `send_message` | Leave a cross-device or team note |
+| `recent_activity` | Inspect what Engrm captured most recently |
+| `memory_stats` | View high-level capture and sync health |
 
 ### Observation Types
 
@@ -227,11 +258,13 @@ Place in your project root to override project identity for non-git projects:
 }
 ```
 
-### Claude Code integration
+### Agent integration
 
 Engrm auto-registers in:
 - `~/.claude.json` — MCP server (`engrm`)
 - `~/.claude/settings.json` — 6 lifecycle hooks
+- `~/.codex/config.toml` — MCP server (`engrm`) + `codex_hooks` feature flag
+- `~/.codex/hooks.json` — `SessionStart` and `Stop` hooks
 
 ---
 
@@ -259,4 +292,15 @@ See [LICENSE](LICENSE) for full terms.
 
 ---
 
+## Project
+
+- Architecture: [ARCHITECTURE.md](ARCHITECTURE.md)
+- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Security: [SECURITY.md](SECURITY.md)
+- Roadmap: [ROADMAP.md](ROADMAP.md)
+
+Maintainers: run `node scripts/check-public-docs.mjs` to verify the repo only contains the approved public docs set at the root.
+
+---
+
 Built by the [Engrm](https://engrm.dev) team, powered by [Candengo Vector](https://www.candengo.com).

package/dist/cli.js

@@ -20,8 +20,9 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 // src/cli.ts
 import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync6, statSync } from "fs";
 import { hostname as hostname2, homedir as homedir3, networkInterfaces as networkInterfaces2 } from "os";
-import { join as join6 } from "path";
+import { dirname as dirname4, join as join6 } from "path";
 import { createHash as createHash2 } from "crypto";
+import { fileURLToPath as fileURLToPath4 } from "url";
 
 // src/config.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -726,8 +727,8 @@ class MemDatabase {
     return this.db.query("SELECT * FROM projects WHERE id = ?").get(id) ?? null;
   }
   insertObservation(obs) {
-    const now = Math.floor(Date.now() / 1000);
-    const createdAt = new Date().toISOString();
+    const now = obs.created_at_epoch ?? Math.floor(Date.now() / 1000);
+    const createdAt = obs.created_at ?? new Date(now * 1000).toISOString();
     const result = this.db.query(`INSERT INTO observations (
           session_id, project_id, type, title, narrative, facts, concepts,
           files_read, files_modified, quality, lifecycle, sensitivity,
@@ -744,11 +745,14 @@ class MemDatabase {
   getObservationById(id) {
     return this.db.query("SELECT * FROM observations WHERE id = ?").get(id) ?? null;
   }
-  getObservationsByIds(ids) {
+  getObservationsByIds(ids, userId) {
     if (ids.length === 0)
       return [];
     const placeholders = ids.map(() => "?").join(",");
-    return this.db.query(`SELECT * FROM observations WHERE id IN (${placeholders}) ORDER BY created_at_epoch DESC`).all(...ids);
+    const visibilityClause = userId ? " AND (sensitivity != 'personal' OR user_id = ?)" : "";
+    return this.db.query(`SELECT * FROM observations
+         WHERE id IN (${placeholders})${visibilityClause}
+         ORDER BY created_at_epoch DESC`).all(...ids, ...userId ? [userId] : []);
   }
   getRecentObservations(projectId, sincEpoch, limit = 50) {
     return this.db.query(`SELECT * FROM observations
@@ -756,8 +760,9 @@ class MemDatabase {
         ORDER BY created_at_epoch DESC
         LIMIT ?`).all(projectId, sincEpoch, limit);
   }
-  searchFts(query, projectId, lifecycles = ["active", "aging", "pinned"], limit = 20) {
+  searchFts(query, projectId, lifecycles = ["active", "aging", "pinned"], limit = 20, userId) {
     const lifecyclePlaceholders = lifecycles.map(() => "?").join(",");
+    const visibilityClause = userId ? " AND (o.sensitivity != 'personal' OR o.user_id = ?)" : "";
     if (projectId !== null) {
       return this.db.query(`SELECT o.id, observations_fts.rank
           FROM observations_fts
@@ -765,33 +770,39 @@ class MemDatabase {
           WHERE observations_fts MATCH ?
             AND o.project_id = ?
             AND o.lifecycle IN (${lifecyclePlaceholders})
+            ${visibilityClause}
           ORDER BY observations_fts.rank
-          LIMIT ?`).all(query, projectId, ...lifecycles, limit);
+          LIMIT ?`).all(query, projectId, ...lifecycles, ...userId ? [userId] : [], limit);
     }
     return this.db.query(`SELECT o.id, observations_fts.rank
         FROM observations_fts
         JOIN observations o ON o.id = observations_fts.rowid
         WHERE observations_fts MATCH ?
           AND o.lifecycle IN (${lifecyclePlaceholders})
+          ${visibilityClause}
         ORDER BY observations_fts.rank
-        LIMIT ?`).all(query, ...lifecycles, limit);
+        LIMIT ?`).all(query, ...lifecycles, ...userId ? [userId] : [], limit);
   }
-  getTimeline(anchorId, projectId, depthBefore = 3, depthAfter = 3) {
-    const anchor = this.getObservationById(anchorId);
+  getTimeline(anchorId, projectId, depthBefore = 3, depthAfter = 3, userId) {
+    const visibilityClause = userId ? " AND (sensitivity != 'personal' OR user_id = ?)" : "";
+    const anchor = this.db.query(`SELECT * FROM observations WHERE id = ?${visibilityClause}`).get(anchorId, ...userId ? [userId] : []) ?? null;
     if (!anchor)
       return [];
     const projectFilter = projectId !== null ? "AND project_id = ?" : "";
     const projectParams = projectId !== null ? [projectId] : [];
+    const visibilityParams = userId ? [userId] : [];
     const before = this.db.query(`SELECT * FROM observations
         WHERE created_at_epoch < ? ${projectFilter}
           AND lifecycle IN ('active', 'aging', 'pinned')
+          ${visibilityClause}
         ORDER BY created_at_epoch DESC
-        LIMIT ?`).all(anchor.created_at_epoch, ...projectParams, depthBefore);
+        LIMIT ?`).all(anchor.created_at_epoch, ...projectParams, ...visibilityParams, depthBefore);
     const after = this.db.query(`SELECT * FROM observations
         WHERE created_at_epoch > ? ${projectFilter}
           AND lifecycle IN ('active', 'aging', 'pinned')
+          ${visibilityClause}
         ORDER BY created_at_epoch ASC
-        LIMIT ?`).all(anchor.created_at_epoch, ...projectParams, depthAfter);
+        LIMIT ?`).all(anchor.created_at_epoch, ...projectParams, ...visibilityParams, depthAfter);
     return [...before.reverse(), anchor, ...after];
   }
   pinObservation(id, pinned) {
@@ -905,11 +916,12 @@ class MemDatabase {
       return;
     this.db.query("DELETE FROM vec_observations WHERE observation_id = ?").run(observationId);
   }
-  searchVec(queryEmbedding, projectId, lifecycles = ["active", "aging", "pinned"], limit = 20) {
+  searchVec(queryEmbedding, projectId, lifecycles = ["active", "aging", "pinned"], limit = 20, userId) {
     if (!this.vecAvailable)
       return [];
     const lifecyclePlaceholders = lifecycles.map(() => "?").join(",");
     const embeddingBlob = new Uint8Array(queryEmbedding.buffer);
+    const visibilityClause = userId ? " AND (o.sensitivity != 'personal' OR o.user_id = ?)" : "";
     if (projectId !== null) {
       return this.db.query(`SELECT v.observation_id, v.distance
            FROM vec_observations v
@@ -918,7 +930,7 @@ class MemDatabase {
              AND k = ?
              AND o.project_id = ?
              AND o.lifecycle IN (${lifecyclePlaceholders})
-             AND o.superseded_by IS NULL`).all(embeddingBlob, limit, projectId, ...lifecycles);
+             AND o.superseded_by IS NULL` + visibilityClause).all(embeddingBlob, limit, projectId, ...lifecycles, ...userId ? [userId] : []);
     }
     return this.db.query(`SELECT v.observation_id, v.distance
          FROM vec_observations v
@@ -926,7 +938,7 @@ class MemDatabase {
          WHERE v.embedding MATCH ?
            AND k = ?
            AND o.lifecycle IN (${lifecyclePlaceholders})
-           AND o.superseded_by IS NULL`).all(embeddingBlob, limit, ...lifecycles);
+           AND o.superseded_by IS NULL` + visibilityClause).all(embeddingBlob, limit, ...lifecycles, ...userId ? [userId] : []);
   }
   getUnembeddedCount() {
     if (!this.vecAvailable)
@@ -1580,6 +1592,9 @@ import { join as join2, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 var CLAUDE_JSON = join2(homedir2(), ".claude.json");
 var CLAUDE_SETTINGS = join2(homedir2(), ".claude", "settings.json");
+var CODEX_CONFIG = join2(homedir2(), ".codex", "config.toml");
+var CODEX_HOOKS = join2(homedir2(), ".codex", "hooks.json");
+var LEGACY_CODEX_SERVER_NAME = `candengo-${"mem"}`;
 function isBuiltDist() {
   const thisDir = dirname(fileURLToPath(import.meta.url));
   return thisDir.endsWith("/dist") || thisDir.endsWith("\\dist");
@@ -1626,6 +1641,15 @@ function writeJsonFile(path, data) {
   writeFileSync2(path, JSON.stringify(data, null, 2) + `
 `, "utf-8");
 }
+function ensureParentDir(path) {
+  const dir = dirname(path);
+  if (!existsSync2(dir)) {
+    mkdirSync2(dir, { recursive: true });
+  }
+}
+function escapeTomlString(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+}
 function registerMcpServer() {
   const runtime = findRuntime();
   const root = findPackageRoot();
@@ -1642,6 +1666,123 @@ function registerMcpServer() {
   writeJsonFile(CLAUDE_JSON, config);
   return { path: CLAUDE_JSON, added: true };
 }
+function upsertCodexMcpServerConfig(existing, entry) {
+  const lines = existing.length > 0 ? existing.split(/\r?\n/) : [];
+  const targetHeaders = new Set([
+    `[mcp_servers.${entry.name}]`,
+    `[mcp_servers.${LEGACY_CODEX_SERVER_NAME}]`
+  ]);
+  const output = [];
+  let skipping = false;
+  let inFeatures = false;
+  let featuresInserted = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (/^\[.*\]$/.test(trimmed)) {
+      if (inFeatures && !featuresInserted) {
+        output.push(`codex_hooks = true`);
+        featuresInserted = true;
+      }
+      skipping = targetHeaders.has(trimmed);
+      inFeatures = trimmed === "[features]";
+      if (!skipping)
+        output.push(line);
+      continue;
+    }
+    if (!skipping) {
+      if (inFeatures && trimmed.startsWith("codex_hooks")) {
+        if (!featuresInserted) {
+          output.push(`codex_hooks = true`);
+          featuresInserted = true;
+        }
+        continue;
+      }
+      output.push(line);
+    }
+  }
+  if (inFeatures && !featuresInserted) {
+    output.push(`codex_hooks = true`);
+    featuresInserted = true;
+  }
+  while (output.length > 0 && output[output.length - 1] === "") {
+    output.pop();
+  }
+  if (output.length > 0) {
+    output.push("");
+  }
+  output.push(`[mcp_servers.${entry.name}]`);
+  output.push(`enabled = true`);
+  output.push(`command = "${escapeTomlString(entry.command)}"`);
+  output.push(`args = [${entry.args.map((arg) => `"${escapeTomlString(arg)}"`).join(", ")}]`);
+  output.push(`startup_timeout_sec = 15`);
+  output.push(`tool_timeout_sec = 30`);
+  output.push("");
+  if (!featuresInserted) {
+    output.push(`[features]`);
+    output.push(`codex_hooks = true`);
+    output.push("");
+  }
+  return output.join(`
+`);
+}
+function registerCodexMcpServer() {
+  const runtime = findRuntime();
+  const root = findPackageRoot();
+  const dist = isBuiltDist();
+  const serverPath = dist ? join2(root, "dist", "server.js") : join2(root, "src", "server.ts");
+  const args = dist ? [serverPath] : ["run", serverPath];
+  const existing = existsSync2(CODEX_CONFIG) ? readFileSync2(CODEX_CONFIG, "utf-8") : "";
+  const updated = upsertCodexMcpServerConfig(existing, {
+    name: "engrm",
+    command: runtime,
+    args
+  });
+  ensureParentDir(CODEX_CONFIG);
+  writeFileSync2(CODEX_CONFIG, updated, "utf-8");
+  return { path: CODEX_CONFIG, added: true };
+}
+function buildCodexHooksConfig(sessionStartCommand, stopCommand) {
+  return JSON.stringify({
+    hooks: {
+      SessionStart: [
+        {
+          hooks: [
+            {
+              type: "command",
+              command: sessionStartCommand,
+              statusMessage: "loading Engrm context"
+            }
+          ]
+        }
+      ],
+      Stop: [
+        {
+          hooks: [
+            {
+              type: "command",
+              command: stopCommand,
+              statusMessage: "saving Engrm session summary"
+            }
+          ]
+        }
+      ]
+    }
+  }, null, 2) + `
+`;
+}
+function registerCodexHooks() {
+  const runtime = findRuntime();
+  const root = findPackageRoot();
+  const dist = isBuiltDist();
+  const hooksDir = dist ? join2(root, "dist", "hooks") : join2(root, "hooks");
+  const ext = dist ? ".js" : ".ts";
+  const runArg = dist ? [] : ["run"];
+  const commandFor = (name) => [runtime, ...runArg, join2(hooksDir, `${name}${ext}`)].join(" ");
+  const content = buildCodexHooksConfig(commandFor("session-start"), commandFor("codex-stop"));
+  ensureParentDir(CODEX_HOOKS);
+  writeFileSync2(CODEX_HOOKS, content, "utf-8");
+  return { path: CODEX_HOOKS, added: true };
+}
 function registerHooks() {
   const runtime = findRuntime();
   const root = findPackageRoot();
@@ -1686,9 +1827,27 @@ function replaceEngrmHook(existing, newEntry, hookFilename) {
   return [...others, newEntry];
 }
 function registerAll() {
+  let mcp = { path: CLAUDE_JSON, added: false };
+  let hooks = { path: CLAUDE_SETTINGS, added: false };
+  let codex = { path: CODEX_CONFIG, added: false };
+  let codexHooks = { path: CODEX_HOOKS, added: false };
+  try {
+    mcp = registerMcpServer();
+  } catch {}
+  try {
+    hooks = registerHooks();
+  } catch {}
+  try {
+    codex = registerCodexMcpServer();
+  } catch {}
+  try {
+    codexHooks = registerCodexHooks();
+  } catch {}
   return {
-    mcp: registerMcpServer(),
-    hooks: registerHooks()
+    mcp,
+    hooks,
+    codex,
+    codexHooks
   };
 }
 
@@ -1862,6 +2021,12 @@ function scoreQuality(input) {
     case "digest":
       score += 0.3;
       break;
+    case "standard":
+      score += 0.25;
+      break;
+    case "message":
+      score += 0.1;
+      break;
   }
   if (input.narrative && input.narrative.length > 50) {
     score += 0.15;
@@ -2543,8 +2708,11 @@ async function installRulePacks(db, config, packNames) {
 }
 
 // src/cli.ts
+var LEGACY_CODEX_SERVER_NAME2 = `candengo-${"mem"}`;
 var args = process.argv.slice(2);
 var command = args[0];
+var THIS_DIR = dirname4(fileURLToPath4(import.meta.url));
+var IS_BUILT_DIST = THIS_DIR.endsWith("/dist") || THIS_DIR.endsWith("\\dist");
 switch (command) {
   case "init":
     await handleInit(args.slice(1));
@@ -2957,9 +3125,15 @@ function handleStatus() {
   console.log(`    Sync:          ${config.sync.enabled ? "enabled" : "disabled"}`);
   const claudeJson = join6(homedir3(), ".claude.json");
   const claudeSettings = join6(homedir3(), ".claude", "settings.json");
+  const codexConfig = join6(homedir3(), ".codex", "config.toml");
+  const codexHooks = join6(homedir3(), ".codex", "hooks.json");
   const mcpRegistered = existsSync6(claudeJson) && readFileSync6(claudeJson, "utf-8").includes('"engrm"');
   const settingsContent = existsSync6(claudeSettings) ? readFileSync6(claudeSettings, "utf-8") : "";
+  const codexContent = existsSync6(codexConfig) ? readFileSync6(codexConfig, "utf-8") : "";
+  const codexHooksContent = existsSync6(codexHooks) ? readFileSync6(codexHooks, "utf-8") : "";
   const hooksRegistered = settingsContent.includes("engrm") || settingsContent.includes("session-start");
+  const codexRegistered = codexContent.includes("[mcp_servers.engrm]") || codexContent.includes(`[mcp_servers.${LEGACY_CODEX_SERVER_NAME2}]`);
+  const codexHooksRegistered = codexHooksContent.includes('"SessionStart"') && codexHooksContent.includes('"Stop"');
   let hookCount = 0;
   if (hooksRegistered) {
     try {
@@ -2978,7 +3152,9 @@ function handleStatus() {
     } catch {}
   }
   console.log(`    MCP server:    ${mcpRegistered ? "registered" : "not registered"}`);
+  console.log(`    Codex MCP:     ${codexRegistered ? "registered" : "not registered"}`);
   console.log(`    Hooks:         ${hooksRegistered ? `registered (${hookCount || "?"} hooks)` : "not registered"}`);
+  console.log(`    Codex hooks:   ${codexHooksRegistered ? "registered (2 hooks)" : "not registered"}`);
   if (config.sentinel?.enabled) {
     console.log(`
   Sentinel`);
@@ -3071,6 +3247,8 @@ function handleStatus() {
   Files`);
   console.log(`    Config:        ${getSettingsPath()}`);
   console.log(`    Database:      ${getDbPath()}`);
+  console.log(`    Codex config:  ${join6(homedir3(), ".codex", "config.toml")}`);
+  console.log(`    Codex hooks:   ${join6(homedir3(), ".codex", "hooks.json")}`);
 }
 function formatTimeAgo(epoch) {
   const ago = Math.floor(Date.now() / 1000) - epoch;
@@ -3203,12 +3381,14 @@ function handleUpdate() {
   try {
     execSync2("npm install -g engrm@latest", { stdio: "inherit" });
     console.log(`
-Update complete. Re-registering hooks...`);
+Update complete. Re-registering integrations...`);
     const result = registerAll();
-    console.log(`  MCP server registered \u2192 ${result.mcp.path}`);
-    console.log(`  Hooks registered \u2192 ${result.hooks.path}`);
+    console.log(`  Claude MCP registered \u2192 ${result.mcp.path}`);
+    console.log(`  Claude hooks registered \u2192 ${result.hooks.path}`);
+    console.log(`  Codex MCP registered \u2192 ${result.codex.path}`);
+    console.log(`  Codex hooks registered \u2192 ${result.codexHooks.path}`);
     console.log(`
-Restart Claude Code to use the new version.`);
+Restart Claude Code or Codex to use the new version.`);
   } catch (error) {
     console.error("Update failed. Try manually: npm install -g engrm@latest");
   }
@@ -3299,6 +3479,36 @@ async function handleDoctor() {
   } catch {
     warn("Could not check hooks registration");
   }
+  const codexConfig = join6(homedir3(), ".codex", "config.toml");
+  try {
+    if (existsSync6(codexConfig)) {
+      const content = readFileSync6(codexConfig, "utf-8");
+      if (content.includes("[mcp_servers.engrm]") || content.includes(`[mcp_servers.${LEGACY_CODEX_SERVER_NAME2}]`)) {
+        pass("MCP server registered in Codex");
+      } else {
+        warn("MCP server not registered in Codex");
+      }
+    } else {
+      warn("Codex config not found (~/.codex/config.toml)");
+    }
+  } catch {
+    warn("Could not check Codex MCP registration");
+  }
+  const codexHooks = join6(homedir3(), ".codex", "hooks.json");
+  try {
+    if (existsSync6(codexHooks)) {
+      const content = readFileSync6(codexHooks, "utf-8");
+      if (content.includes('"SessionStart"') && content.includes('"Stop"')) {
+        pass("Hooks registered in Codex");
+      } else {
+        warn("Codex hooks config found, but Engrm hooks are missing");
+      }
+    } else {
+      warn("Codex hooks config not found (~/.codex/hooks.json)");
+    }
+  } catch {
+    warn("Could not check Codex hooks registration");
+  }
   if (config.candengo_url) {
     try {
       const controller = new AbortController;
@@ -3440,16 +3650,23 @@ async function checkDeviceLimits(baseUrl, apiKey) {
 }
 function printPostInit() {
   console.log(`
-Registering with Claude Code...`);
+Registering with Claude Code and Codex...`);
   try {
     const result = registerAll();
-    console.log(`  MCP server registered \u2192 ${result.mcp.path}`);
-    console.log(`  Hooks registered \u2192 ${result.hooks.path}`);
+    console.log(`  Claude MCP registered \u2192 ${result.mcp.path}`);
+    console.log(`  Claude hooks registered \u2192 ${result.hooks.path}`);
+    console.log(`  Codex MCP registered \u2192 ${result.codex.path}`);
+    console.log(`  Codex hooks registered \u2192 ${result.codexHooks.path}`);
     console.log(`
-Engrm is ready! Start a new Claude Code session to use memory.`);
+Engrm is ready! Start a new Claude Code or Codex session to use memory.`);
   } catch (error) {
+    const packageRoot = join6(THIS_DIR, "..");
+    const runtime = IS_BUILT_DIST ? process.execPath : "bun";
+    const serverArgs = IS_BUILT_DIST ? [join6(packageRoot, "dist", "server.js")] : ["run", join6(packageRoot, "src", "server.ts")];
+    const sessionStartCommand = IS_BUILT_DIST ? `${process.execPath} ${join6(packageRoot, "dist", "hooks", "session-start.js")}` : `bun run ${join6(packageRoot, "hooks", "session-start.ts")}`;
+    const codexStopCommand = IS_BUILT_DIST ? `${process.execPath} ${join6(packageRoot, "dist", "hooks", "codex-stop.js")}` : `bun run ${join6(packageRoot, "hooks", "codex-stop.ts")}`;
     console.log(`
-Could not auto-register with Claude Code.`);
+Could not auto-register with Claude Code and Codex.`);
     console.log(`Error: ${error instanceof Error ? error.message : String(error)}`);
     console.log(`
 Manual setup \u2014 add to ~/.claude.json:`);
@@ -3458,13 +3675,56 @@ Manual setup \u2014 add to ~/.claude.json:`);
   "mcpServers": {
     "engrm": {
       "type": "stdio",
-      "command": "bun",
-      "args": ["run", "${process.cwd()}/src/server.ts"]
+      "command": "${runtime}",
+      "args": ${JSON.stringify(serverArgs)}
     }
   }
 }`);
+    console.log(`
+And add to ~/.codex/config.toml:`);
+    console.log(`
+[mcp_servers.engrm]
+enabled = true
+command = "${runtime}"
+args = ${formatTomlArray(serverArgs)}
+startup_timeout_sec = 15
+tool_timeout_sec = 30
+[features]
+codex_hooks = true
+`);
+    console.log(`
+And add to ~/.codex/hooks.json:`);
+    console.log(`
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${sessionStartCommand}"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${codexStopCommand}"
+          }
+        ]
+      }
+    ]
   }
 }
+`);
+  }
+}
+function formatTomlArray(values) {
+  return `[${values.map((value) => JSON.stringify(value)).join(", ")}]`;
+}
 function printUsage() {
   console.log(`Engrm \u2014 Memory layer for AI coding agents
 `);

package/dist/hooks/codex-stop.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+// hooks/codex-stop.ts
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+var thisDir = dirname(fileURLToPath(import.meta.url));
+var delegatePath = join(thisDir, "stop.ts");
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString());
+  }
+  return chunks.join("");
+}
+async function main() {
+  const input = await readStdin();
+  const isBun = process.execPath.endsWith("bun");
+  const childArgs = isBun ? ["run", delegatePath] : [delegatePath];
+  const child = spawn(process.execPath, childArgs, {
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  if (input.length > 0) {
+    child.stdin.write(input);
+  }
+  child.stdin.end();
+  let stdout = "";
+  let stderr = "";
+  child.stdout.on("data", (chunk) => {
+    stdout += chunk.toString();
+  });
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk.toString();
+  });
+  const exitCode = await new Promise((resolve, reject) => {
+    child.on("error", reject);
+    child.on("close", (code) => resolve(code ?? 1));
+  });
+  const messages = [stdout.trim(), stderr.trim()].filter(Boolean);
+  const systemMessage = messages.length > 0 ? messages.join(`
+`) : null;
+  if (exitCode === 0) {
+    console.log(JSON.stringify({
+      continue: true,
+      ...systemMessage ? { systemMessage } : {}
+    }));
+    process.exit(0);
+  }
+  console.log(JSON.stringify({
+    continue: true,
+    ...systemMessage ? { systemMessage: `Engrm stop hook failed:
+${systemMessage}` } : {}
+  }));
+  process.exit(0);
+}
+main().catch((error) => {
+  console.log(JSON.stringify({
+    continue: true,
+    systemMessage: `Engrm stop hook failed: ${error instanceof Error ? error.message : String(error)}`
+  }));
+  process.exit(0);
+});