@echomem/mcp 1.4.40 → 1.4.42

package/README.md

@@ -74,6 +74,27 @@ installation, and `npx -y @echomem/mcp@latest update --all` remains the bootstra
 Agents can still call `echo_context_health` for an on-demand local context-health report. It reads
 the local Codex/Claude logs and does not require a separate process or desktop overlay.
 
+## Local conversation lifecycle hooks
+
+For hook-capable Codex and Claude Code clients, MCP setup installs two local lifecycle hooks:
+
+- **`SessionStart` — source-session binding.** The hook receives the host-owned `session_id` and
+  `transcript_path`, verifies that they identify the same local JSONL, and idempotently binds the
+  canonical `codex:<id>` or `claude-code:<id>` context through
+  `POST /api/extension/source-sessions/bind`. On each MCP call, the bridge independently confirms
+  the exact host-owned session metadata and attaches the returned context before saving, recalling,
+  citing, sharing, or recording activity. No "latest session" lookup is used. `bind_source_session`
+  remains available only for clients without startup hooks.
+- **`Stop` — private-save checkpoint.** Before a completed turn exits, the hook reads only that
+  turn's local transcript slice. If the turn appears durable and did not already call
+  `save_conversation`, it blocks completion once and asks the Agent to create a concise private
+  checkpoint. It never authors or uploads a checkpoint itself. Re-entry is guarded by
+  `stop_hook_active`, so the second Stop is allowed after the Agent has checked or saved.
+
+Both hook entries are merged idempotently into `~/.codex/hooks.json` and
+`~/.claude/settings.json`; unrelated user hooks and settings are preserved. Hooks fail open when
+their local input is missing so they cannot prevent a conversation from starting or finishing.
+
 ## Agent Doctor — local workspace forensics (new in 1.4.9)
 
 `echomem-mcp init` / `setup` now ends with an **Agent Doctor report**: a local scan of your

package/dist/hud/cli.js

@@ -5,12 +5,13 @@ import { fileURLToPath } from "node:url";
 import { adapterList } from "./adapters.js";
 import { autostartPlistPath, autostartSupported, disableAutostart, enableAutostart, isAutostartEnabled } from "./autostart.js";
 import { statSignature } from "./fs.js";
-import { installHooks, installSaveCheckpointHooks } from "./hooks.js";
+import { installHooks, installSaveCheckpointHooks, installSourceSessionHooks } from "./hooks.js";
 import { HudMonitor } from "./monitor.js";
 import { renderStateText } from "./render.js";
 import { renderReportText, runReport } from "./report.js";
 import { createHudServer } from "./server.js";
 import { runSaveCheckpointHook } from "../save-checkpoint-hook.js";
+import { runSourceSessionStartHook } from "../source-session-hook.js";
 const argv = process.argv.slice(2);
 const command = argv[0] || "summary";
 const flags = parseFlags(argv.slice(1));
@@ -27,8 +28,12 @@ try {
         await cmdInstallHooks(flags);
     else if (command === "install-save-hooks")
         await cmdInstallSaveHooks(flags);
+    else if (command === "install-source-session-hooks")
+        await cmdInstallSourceSessionHooks(flags);
     else if (command === "save-checkpoint")
         await cmdSaveCheckpoint();
+    else if (command === "bind-source-session")
+        await cmdBindSourceSession();
     else if (command === "autostart")
         cmdAutostart(argv[1] || "status", flags);
     else if (command === "status")
@@ -120,8 +125,17 @@ async function cmdInstallHooks(flags) {
     console.log("Codex users: run /hooks in a new Codex session to review and trust changed hooks.");
 }
 async function cmdInstallSaveHooks(flags) {
-    const paths = installSaveCheckpointHooks(parseMode(flags.client));
-    console.log(`Installed EchoMem private-save checkpoint hooks:\n${paths.map((p) => `- ${p}`).join("\n")}`);
+    const mode = parseMode(flags.client);
+    const paths = [...new Set([
+            ...installSourceSessionHooks(mode),
+            ...installSaveCheckpointHooks(mode),
+        ])];
+    console.log(`Installed EchoMem source-session and private-save hooks:\n${paths.map((p) => `- ${p}`).join("\n")}`);
+    console.log("Codex users: run /hooks in a new Codex session to review and trust changed hooks.");
+}
+async function cmdInstallSourceSessionHooks(flags) {
+    const paths = installSourceSessionHooks(parseMode(flags.client));
+    console.log(`Installed EchoMem source-session hooks:\n${paths.map((p) => `- ${p}`).join("\n")}`);
     console.log("Codex users: run /hooks in a new Codex session to review and trust changed hooks.");
 }
 async function cmdSaveCheckpoint() {
@@ -130,6 +144,12 @@ async function cmdSaveCheckpoint() {
         input += String(chunk);
     process.stdout.write(runSaveCheckpointHook(input));
 }
+async function cmdBindSourceSession() {
+    let input = "";
+    for await (const chunk of process.stdin)
+        input += String(chunk);
+    process.stdout.write(await runSourceSessionStartHook(input));
+}
 async function cmdReport(flags) {
     const result = runReport(parseMode(flags.client), { limit: readNumber(flags.limit, 40) });
     if (flags.json)
@@ -182,7 +202,8 @@ Usage:
   echomem-hud serve [--client codex|claude-code|claude-desktop|both|auto] [--port 17377]
   echomem-hud app [--client codex|claude-code|claude-desktop|both|auto]
   echomem-hud install-hooks [--client codex|claude-code|both]
-  echomem-hud install-save-hooks [--client codex|claude-code|both]
+  echomem-hud install-save-hooks [--client codex|claude-code|both]  (installs both lifecycle hooks)
+  echomem-hud install-source-session-hooks [--client codex|claude-code|both]
   echomem-hud autostart on|off|status   (show the HUD after restart — macOS)
   echomem-hud status
   echomem-hud report [--client codex|claude-code|claude-desktop|auto] [--limit 40] [--json]

package/dist/hud/hooks.js

@@ -22,6 +22,16 @@ export function installSaveCheckpointHooks(mode) {
     }
     return written;
 }
+export function installSourceSessionHooks(mode) {
+    const written = [];
+    if (mode === "codex" || mode === "both" || mode === "auto") {
+        written.push(installCodexSourceSessionHook());
+    }
+    if (mode === "claude-code" || mode === "both" || mode === "auto") {
+        written.push(installClaudeCodeSourceSessionHook());
+    }
+    return written;
+}
 function installCodexHooks() {
     const dir = path.join(os.homedir(), ".codex");
     const file = path.join(dir, "hooks.json");
@@ -39,6 +49,44 @@ function saveCheckpointCommand() {
     const lifecycleCli = fileURLToPath(new URL("./cli.js", import.meta.url));
     return `${JSON.stringify(process.execPath)} ${JSON.stringify(lifecycleCli)} save-checkpoint`;
 }
+function sourceSessionCommand() {
+    const lifecycleCli = fileURLToPath(new URL("./cli.js", import.meta.url));
+    return `${JSON.stringify(process.execPath)} ${JSON.stringify(lifecycleCli)} bind-source-session`;
+}
+function installCodexSourceSessionHook() {
+    const dir = path.join(os.homedir(), ".codex");
+    const file = path.join(dir, "hooks.json");
+    fs.mkdirSync(dir, { recursive: true });
+    const content = readHooksFile(file);
+    content.hooks = content.hooks || {};
+    content.hooks.SessionStart = mergeSourceSessionGroup(content.hooks.SessionStart, {
+        hooks: [{
+                type: "command",
+                command: sourceSessionCommand(),
+                timeout: 5,
+                statusMessage: "Binding EchoMem to this conversation",
+            }],
+    });
+    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    return file;
+}
+function installClaudeCodeSourceSessionHook() {
+    const dir = path.join(os.homedir(), ".claude");
+    const file = path.join(dir, "settings.json");
+    fs.mkdirSync(dir, { recursive: true });
+    const content = readHooksFile(file);
+    content.hooks = content.hooks || {};
+    content.hooks.SessionStart = mergeSourceSessionGroup(content.hooks.SessionStart, {
+        hooks: [{
+                type: "command",
+                command: sourceSessionCommand(),
+                timeout: 5,
+                statusMessage: "Binding EchoMem to this conversation",
+            }],
+    });
+    fs.writeFileSync(file, JSON.stringify(content, null, 2));
+    return file;
+}
 function installCodexSaveCheckpointHook() {
     const dir = path.join(os.homedir(), ".codex");
     const file = path.join(dir, "hooks.json");
@@ -97,11 +145,21 @@ function mergeSaveCheckpointGroup(existing, group) {
     groups.push(group);
     return groups;
 }
+function mergeSourceSessionGroup(existing, group) {
+    const groups = Array.isArray(existing) ? existing.filter((item) => !isEchoSourceSessionGroup(item)) : [];
+    groups.push(group);
+    return groups;
+}
 function isEchoHudGroup(value) {
     if (typeof value !== "object" || value === null)
         return false;
     return JSON.stringify(value).includes("summary --client codex --json");
 }
+function isEchoSourceSessionGroup(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    return JSON.stringify(value).includes("bind-source-session");
+}
 function isEchoSaveCheckpointGroup(value) {
     if (typeof value !== "object" || value === null)
         return false;