@echomem/mcp 1.4.40 → 1.4.41

package/dist/package-metadata.js

@@ -35,10 +35,11 @@ export const SAVED_MEMORY_RECEIPT_INSTRUCTION = 'After save_conversation succeed
 export const MCP_SERVER_INSTRUCTIONS = [
     `${MCP_PACKAGE_DESCRIPTION} (${MCP_PACKAGE_LABEL}).`,
     `If stale, ${MCP_UPDATE_INSTRUCTION}; restart the MCP session afterward. Updates never delay startup.`,
+    "A local SessionStart hook binds supported conversations to their real provider sessions; use bind_source_session only as fallback.",
     "Before re-deriving prior decisions or preferences, use search_memories.",
     `Before the final response for a durable decision, implementation, fix, commit, passing verification, release, or milestone, call save_conversation. Skip secrets and trivial work. If the encrypted vault is locked, tell the user to ${MCP_VAULT_UNLOCK_INSTRUCTION}.`,
     "After a successful save, show every memory created by that call in a compact EchoMem saved: list with canonical links; this is separate from \"EchoMem sources:\".",
-    "For company groups, call request_group_session_sharing near conversation start or after a qualifying save, relay its exact text question, and call set_group_session_sharing only after an explicit Yes or No. Omit groupSharingScopeId only on the first call, then reuse the returned scope only in this conversation. Each group needs an explicit choice; silence stays unset. Never infer consent. Flagged memories stay private.",
+    "For company groups, request sharing near conversation start or after a save; relay its exact question and set only after explicit Yes or No. Reuse the returned scope only in this conversation. Each group needs its own choice; silence means unset. Flagged memories stay private.",
     "EchoMem credential identity is authoritative over Claude profiles, host accounts, git identity, or inference. Use get_group_context before group-orientation answers and never re-filter owners returned by search_others_memories.",
     "When a final answer materially uses teammate or friend memories, call record_memory_citations with only the exact used Memory IDs and a unique per-answer receiptId.",
     "End memory-informed answers with a compact EchoMem sources: list. Use each memory key as the label and https://echoknows.com/memory/<memory-id> as its canonical link.",

package/dist/setup.js

@@ -31,7 +31,7 @@ import { syncCodexUsage } from "./codex-sync.js";
 import { renderSetupPage } from "./setup-page.js";
 import { parseSetupPreviewState } from "./setup-preview.js";
 import { repoLabel, validateForensicReportForSetup } from "./forensics.js";
-import { installSaveCheckpointHooks } from "./hud/hooks.js";
+import { installSaveCheckpointHooks, installSourceSessionHooks } from "./hud/hooks.js";
 import { MCP_PACKAGE_LABEL, MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION, MCP_UPDATE_ALL_COMMAND, MCP_UPDATE_COMMAND } from "./package-metadata.js";
 import { checkLatestUpdateStatus, compareSemver, readCachedUpdateStatus } from "./update-check.js";
 import { installHeadlessRuntimeSync, readHeadlessRuntimeInstallation, } from "./headless-runtime.js";
@@ -215,7 +215,7 @@ export function knownClients() {
         { id: "cursor", label: "Cursor", kind: "json", configPath: home(".cursor", "mcp.json") },
         { id: "windsurf", label: "Windsurf", kind: "json", configPath: home(".codeium", "windsurf", "mcp_config.json") },
         { id: "claude-desktop", label: "Claude Desktop", kind: "json", configPath: path.join(appSupport, "Claude", "claude_desktop_config.json") },
-        { id: "claude-code", label: "Claude Code", kind: "snippet", note: "run: claude mcp add-json echomem '<entry>'  (or add to .mcp.json)" },
+        { id: "claude-code", label: "Claude Code", kind: "snippet", note: "run: claude mcp add-json -s user echomem '<entry>'  (or add to .mcp.json)" },
         { id: "codex", label: "Codex", kind: "command", detectDir: codexHome(), configPath: path.join(codexHome(), "config.toml"), note: "add to ~/.codex/config.toml under [mcp_servers.echomem]" },
     ];
 }
@@ -356,6 +356,7 @@ function echomemGuidanceBlock() {
         "## Memory (EchoMem)",
         "EchoMem is your long-term memory across all coding sessions and tools.",
         "- Use EchoMem's `echomem-*` skills and MCP tools as the default memory provider. Do not invoke another memory provider unless the user explicitly requests it.",
+        "- EchoMem's local SessionStart hook automatically binds each new Codex or Claude Code conversation to its real source-session ID. Use `bind_source_session` with a fresh UUID only as a compatibility fallback when the hook is unavailable or reports that the session is unbound.",
         "- Before re-deriving past decisions, project context, or anything the user likely settled before: call `search_memories` first.",
         '- If the final user-facing answer materially relies on one or more EchoMem memories, end it with a compact `EchoMem sources:` list containing only the memories actually used. Link each memory key to its canonical `https://echoknows.com/memory/<memory-id>` URL. Do not cite memories that were merely retrieved, and omit the section when no memory informed the answer.',
         "- Before the final response for a task that produced a durable decision, confirmed preference, implementation, resolved bug, commit, passing verification, release, or project milestone: call `save_conversation`. This private checkpoint does not require a separate user request. Do not save secrets, credentials, incidental chatter, or trivial read-only work. If a qualifying save fails because the encrypted vault is locked, tell the user to open Echo Desktop and unlock the vault there; on a headless system, use `echomem-mcp unlock`. Never silently skip it.",
@@ -2702,8 +2703,8 @@ async function cmdSetup(flags) {
     if (!flags["no-codex-skills"]) {
         writeCodexSkillsForTargets(targets);
     }
-    if (flags["install-save-hooks"]) {
-        writeSaveCheckpointHooksForTargets(targets);
+    if (flags["no-save-hooks"] !== true) {
+        writeLifecycleHooksForTargets(targets);
     }
     console.log("");
     if (flags["skip-login"] || flags["no-login"]) {
@@ -2793,7 +2794,7 @@ function writeCodexSkillsForTargets(targets) {
         console.log(`ℹ️  Could not install EchoMem Codex skills: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
-function writeSaveCheckpointHooksForTargets(targets) {
+function writeLifecycleHooksForTargets(targets) {
     const clients = new Set();
     if (targets.some((target) => target.id === "codex"))
         clients.add("codex");
@@ -2804,8 +2805,10 @@ function writeSaveCheckpointHooksForTargets(targets) {
         return;
     }
     const mode = clients.size === 2 ? "both" : [...clients][0];
-    const paths = installSaveCheckpointHooks(mode);
-    console.log(`✅ Installed EchoMem private-save checkpoint hooks:\n${paths.map((p) => `   - ${p}`).join("\n")}`);
+    const sourcePaths = installSourceSessionHooks(mode);
+    const savePaths = installSaveCheckpointHooks(mode);
+    const paths = [...new Set([...sourcePaths, ...savePaths])];
+    console.log(`✅ Installed EchoMem source-session and private-save hooks:\n${paths.map((p) => `   - ${p}`).join("\n")}`);
     if (clients.has("codex")) {
         console.log("   Codex: start a new session and run /hooks once to review and trust the hook.");
     }
@@ -3810,7 +3813,7 @@ Manual / headless:
   ${MCP_UPDATE_ALL_COMMAND}     # one-shot latest update for detected clients, no browser login
   ${MCP_UPDATE_COMMAND} --client codex   # update one client only
   echomem-mcp setup --dev /abs/path/dist/index.js   # point clients at a local checkout
-  echomem-mcp setup --install-save-hooks --all  Install proactive private-save completion checks
+  echomem-mcp setup --install-save-hooks --all  Install source-session + private-save lifecycle hooks
   echomem-mcp sync-usage --days 7 --limit 50 --dry-run
 
 Current bridge version: ${MCP_PACKAGE_VERSION}

package/dist/source-session-hook.js

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import path from "node:path";
+import axios from "axios";
+import { KeyStore } from "./keystore.js";
+import { SOURCE_SESSION_HOOK_EVIDENCE, verifiedSourceSession, } from "./source-session.js";
+const API_BASE = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
+const MAX_HEAD_BYTES = 256 * 1024;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function transcriptHead(file) {
+    const descriptor = fs.openSync(file, "r");
+    try {
+        const size = Math.min(fs.fstatSync(descriptor).size, MAX_HEAD_BYTES);
+        const buffer = Buffer.allocUnsafe(size);
+        const read = fs.readSync(descriptor, buffer, 0, size, 0);
+        return buffer.toString("utf8", 0, read);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function codexSessionFromTranscript(file) {
+    for (const line of transcriptHead(file).split(/\r?\n/)) {
+        try {
+            const row = JSON.parse(line);
+            if (!isRecord(row) || row.type !== "session_meta" || !isRecord(row.payload))
+                continue;
+            const id = typeof row.payload.id === "string" ? row.payload.id : "";
+            if (!id)
+                return null;
+            const source = row.payload.source;
+            const isSubagent = typeof row.payload.parent_thread_id === "string"
+                || (isRecord(source) && Object.hasOwn(source, "subagent"));
+            return { id, isSubagent };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function coworkSessionFromPath(file) {
+    return file.split(path.sep).find((part) => /^local_[A-Za-z0-9_-]{1,194}$/.test(part)) ?? null;
+}
+export function resolveSourceSessionFromHookPayload(payload) {
+    const requestedSessionId = typeof payload.session_id === "string" ? payload.session_id.trim() : "";
+    const transcriptPath = typeof payload.transcript_path === "string" ? payload.transcript_path.trim() : "";
+    if (!requestedSessionId || !transcriptPath || !path.isAbsolute(transcriptPath))
+        return null;
+    let file;
+    try {
+        file = fs.realpathSync(transcriptPath);
+        if (!fs.statSync(file).isFile())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const coworkSession = coworkSessionFromPath(file);
+    if (coworkSession) {
+        return verifiedSourceSession("cowork", coworkSession, SOURCE_SESSION_HOOK_EVIDENCE);
+    }
+    const codexSession = codexSessionFromTranscript(file);
+    if (codexSession) {
+        if (codexSession.isSubagent || codexSession.id.toLowerCase() !== requestedSessionId.toLowerCase()) {
+            return null;
+        }
+        return verifiedSourceSession("codex", codexSession.id, SOURCE_SESSION_HOOK_EVIDENCE);
+    }
+    const filenameSession = path.basename(file, path.extname(file));
+    if (filenameSession !== requestedSessionId)
+        return null;
+    return verifiedSourceSession("claude-code", filenameSession, SOURCE_SESSION_HOOK_EVIDENCE);
+}
+async function bindSourceSession(identity) {
+    const token = new KeyStore().getToken();
+    if (!token)
+        return;
+    await axios.post(`${API_BASE}/api/extension/source-sessions/bind`, {
+        provider: identity.provider,
+        providerSessionId: identity.providerSessionId,
+        evidence: identity.evidence,
+    }, {
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        timeout: 3_500,
+    });
+}
+/** SessionStart must never prevent the host conversation from opening. The first MCP call retries. */
+export async function runSourceSessionStartHook(input) {
+    try {
+        const parsed = JSON.parse(input);
+        if (!isRecord(parsed))
+            return JSON.stringify({ continue: true });
+        const identity = resolveSourceSessionFromHookPayload(parsed);
+        if (identity)
+            await bindSourceSession(identity);
+    }
+    catch {
+        // Startup binding is best-effort locally; MCP request metadata provides an exact retry path.
+    }
+    return JSON.stringify({ continue: true });
+}

package/dist/source-session.js

@@ -0,0 +1,261 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveClaudeProjectsDir, resolveCodexSessionRoots } from "./local-data-paths.js";
+export const SOURCE_SESSION_BINDING_EVIDENCE = "local_jsonl_tool_call";
+export const SOURCE_SESSION_HOOK_EVIDENCE = "local_session_start_hook";
+export const SOURCE_SESSION_MCP_METADATA_EVIDENCE = "local_mcp_session_metadata";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const UUID_IN_TEXT_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+const MAX_TAIL_BYTES = 512 * 1024;
+const DEFAULT_MAX_AGE_MS = 15 * 60 * 1000;
+const MAX_RECENT_FILES_PER_PROVIDER = 24;
+function normalizedProviderSessionId(provider, value) {
+    const normalized = value.trim();
+    if (!normalized || normalized.length > 200 || /\s/.test(normalized)) {
+        throw new Error("source-session ID must contain 1-200 non-whitespace characters");
+    }
+    if (provider === "codex" && !UUID_RE.test(normalized)) {
+        throw new Error("Codex source-session ID must be a UUID");
+    }
+    if (provider === "cowork" && !/^local_[A-Za-z0-9_-]{1,194}$/.test(normalized)) {
+        throw new Error("Cowork source-session ID must use the local_ host session identifier");
+    }
+    return UUID_RE.test(normalized) ? normalized.toLowerCase() : normalized;
+}
+export function verifiedSourceSession(provider, providerSessionId, evidence) {
+    const normalized = normalizedProviderSessionId(provider, providerSessionId);
+    return {
+        provider,
+        providerSessionId: normalized,
+        canonicalKey: `${provider}:${normalized}`,
+        evidence,
+    };
+}
+/**
+ * Resolve identity from host-owned MCP metadata. Unlike tool arguments, these values are attached by
+ * Codex/Claude outside the model-controlled input. The SessionStart hook performs the eager bind;
+ * this resolver lets the MCP process independently attach the same identity on its first real call.
+ */
+export function resolveSourceSessionFromMcpContext(metadata, options = {}) {
+    const host = options.hostPlatform?.toLowerCase().replace(/[^a-z0-9]+/g, "_") ?? "";
+    const env = options.env ?? process.env;
+    if (host.includes("codex")) {
+        const root = isRecord(metadata) ? metadata : {};
+        const turn = isRecord(root["x-codex-turn-metadata"])
+            ? root["x-codex-turn-metadata"]
+            : {};
+        const candidate = typeof turn.thread_id === "string"
+            ? turn.thread_id
+            : typeof turn.session_id === "string"
+                ? turn.session_id
+                : typeof root.threadId === "string"
+                    ? root.threadId
+                    : "";
+        return candidate
+            ? verifiedSourceSession("codex", candidate, SOURCE_SESSION_MCP_METADATA_EVIDENCE)
+            : null;
+    }
+    if (host.includes("claude_desktop") || host === "claude" || host.includes("cowork")) {
+        const candidate = env.CLAUDE_CODE_HOST_SESSION_ID?.trim() ?? "";
+        return candidate
+            ? verifiedSourceSession("cowork", candidate, SOURCE_SESSION_MCP_METADATA_EVIDENCE)
+            : null;
+    }
+    if (host.includes("claude_code")) {
+        const candidate = env.CLAUDE_CODE_SESSION_ID?.trim() ?? "";
+        return candidate
+            ? verifiedSourceSession("claude-code", candidate, SOURCE_SESSION_MCP_METADATA_EVIDENCE)
+            : null;
+    }
+    return null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readableDirectory(candidate) {
+    try {
+        return fs.statSync(candidate).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function coworkRoot() {
+    const supportRoot = process.env.CLAUDE_DESKTOP_SUPPORT_DIR?.trim()
+        || path.join(os.homedir(), "Library", "Application Support", "Claude");
+    return path.join(supportRoot, "local-agent-mode-sessions");
+}
+function defaultRoots() {
+    const claudeProjects = resolveClaudeProjectsDir();
+    const desktopRoot = coworkRoot();
+    return {
+        codex: resolveCodexSessionRoots().map((root) => root.path),
+        claudeCode: claudeProjects ? [claudeProjects] : [],
+        cowork: readableDirectory(desktopRoot) ? [desktopRoot] : [],
+    };
+}
+function walkJsonlFiles(roots) {
+    const files = [];
+    const pending = roots.filter(readableDirectory);
+    while (pending.length) {
+        const directory = pending.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const target = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "subagents" || entry.name === "workflows")
+                    continue;
+                pending.push(target);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+                files.push(target);
+            }
+        }
+    }
+    return files;
+}
+function recentFiles(roots, nowMs, maxAgeMs) {
+    return walkJsonlFiles(roots)
+        .map((file) => {
+        try {
+            return { file, mtimeMs: fs.statSync(file).mtimeMs };
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((item) => item !== null && item.mtimeMs >= nowMs - maxAgeMs && item.mtimeMs <= nowMs + 5_000)
+        .sort((left, right) => right.mtimeMs - left.mtimeMs)
+        .slice(0, MAX_RECENT_FILES_PER_PROVIDER)
+        .map((item) => item.file);
+}
+function tailContainsBinding(file, bindingToken) {
+    let descriptor = null;
+    try {
+        const stat = fs.statSync(file);
+        const bytes = Math.min(stat.size, MAX_TAIL_BYTES);
+        if (bytes <= 0)
+            return false;
+        descriptor = fs.openSync(file, "r");
+        const buffer = Buffer.allocUnsafe(bytes);
+        fs.readSync(descriptor, buffer, 0, bytes, stat.size - bytes);
+        const tail = buffer.toString("utf8");
+        return tail.includes(bindingToken) && tail.includes("bind_source_session");
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (descriptor !== null)
+            fs.closeSync(descriptor);
+    }
+}
+function codexSessionId(file) {
+    let descriptor = null;
+    try {
+        descriptor = fs.openSync(file, "r");
+        const stat = fs.fstatSync(descriptor);
+        const bytes = Math.min(stat.size, 128 * 1024);
+        const buffer = Buffer.allocUnsafe(bytes);
+        fs.readSync(descriptor, buffer, 0, bytes, 0);
+        for (const line of buffer.toString("utf8").split(/\r?\n/)) {
+            if (!line.includes("session_meta"))
+                continue;
+            try {
+                const row = JSON.parse(line);
+                if (!isRecord(row) || row.type !== "session_meta" || !isRecord(row.payload))
+                    continue;
+                if (typeof row.payload.parent_thread_id === "string" && row.payload.parent_thread_id)
+                    return null;
+                const raw = typeof row.payload.id === "string"
+                    ? row.payload.id
+                    : typeof row.payload.session_id === "string"
+                        ? row.payload.session_id
+                        : "";
+                return UUID_RE.test(raw) ? raw.toLowerCase() : null;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (descriptor !== null)
+            fs.closeSync(descriptor);
+    }
+    return path.basename(file).match(UUID_IN_TEXT_RE)?.[0]?.toLowerCase() ?? null;
+}
+function claudeCodeSessionId(file) {
+    const value = path.basename(file, ".jsonl").trim();
+    return value && value.length <= 200 ? value : null;
+}
+function coworkSessionId(file) {
+    const value = file.split(path.sep).find((part) => /^local_[A-Za-z0-9_-]{1,194}$/.test(part));
+    return value ?? null;
+}
+function enabledProviders(hostPlatform) {
+    const normalized = hostPlatform?.toLowerCase().replace(/[^a-z0-9]+/g, "_") ?? "";
+    if (normalized.includes("codex"))
+        return ["codex"];
+    if (normalized.includes("claude_code"))
+        return ["claude-code"];
+    if (normalized.includes("claude_desktop") || normalized === "claude") {
+        return ["cowork", "claude-code"];
+    }
+    return ["codex", "claude-code", "cowork"];
+}
+export function resolveSourceSessionFromBindingToken(bindingToken, options = {}) {
+    const normalizedToken = bindingToken.trim().toLowerCase();
+    if (!UUID_RE.test(normalizedToken)) {
+        throw new Error("bindingToken must be a UUID generated fresh for this tool call");
+    }
+    const needsDefaults = options.roots?.codex === undefined
+        || options.roots?.claudeCode === undefined
+        || options.roots?.cowork === undefined;
+    const defaults = needsDefaults ? defaultRoots() : { codex: [], claudeCode: [], cowork: [] };
+    const roots = {
+        codex: options.roots?.codex ?? defaults.codex,
+        claudeCode: options.roots?.claudeCode ?? defaults.claudeCode,
+        cowork: options.roots?.cowork ?? defaults.cowork,
+    };
+    const nowMs = options.nowMs ?? Date.now();
+    const maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    const matches = [];
+    for (const provider of enabledProviders(options.hostPlatform)) {
+        const providerRoots = provider === "codex"
+            ? roots.codex
+            : provider === "claude-code"
+                ? roots.claudeCode
+                : roots.cowork;
+        for (const file of recentFiles(providerRoots, nowMs, maxAgeMs)) {
+            if (!tailContainsBinding(file, normalizedToken))
+                continue;
+            const providerSessionId = provider === "codex"
+                ? codexSessionId(file)
+                : provider === "claude-code"
+                    ? claudeCodeSessionId(file)
+                    : coworkSessionId(file);
+            if (providerSessionId)
+                matches.push({ provider, providerSessionId });
+        }
+    }
+    const unique = new Map(matches.map((match) => [`${match.provider}:${match.providerSessionId}`, match]));
+    if (unique.size === 0) {
+        throw new Error("Could not verify this binding token in a recent local host JSONL. Retry bind_source_session with a new UUID after the host has recorded the tool call.");
+    }
+    if (unique.size !== 1) {
+        throw new Error("The binding token appeared in multiple source sessions; retry with a fresh UUID");
+    }
+    const verified = [...unique.values()][0];
+    return verifiedSourceSession(verified.provider, verified.providerSessionId, SOURCE_SESSION_BINDING_EVIDENCE);
+}

package/dist/v1-contract.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { MCP_DESKTOP_MANAGED, MCP_VAULT_UNLOCK_INSTRUCTION, MEMORY_CITATION_INSTRUCTION, SAVED_MEMORY_RECEIPT_INSTRUCTION, withMcpVersion, } from "./package-metadata.js";
 export const canonicalToolNames = {
+    bindSourceSession: "bind_source_session",
     search: "search_memories",
     save: "save_conversation",
     timeRange: "get_memories_by_time_range",
@@ -59,6 +60,7 @@ const READ_ONLY_TOOL_NAMES = new Set([
     canonicalToolNames.recompose,
 ]);
 const IDEMPOTENT_WRITE_TOOL_NAMES = new Set([
+    canonicalToolNames.bindSourceSession,
     canonicalToolNames.recordCitations,
     canonicalToolNames.setGroupSessionSharing,
     canonicalToolNames.updateGroupProfile,
@@ -77,6 +79,7 @@ const REQUIRES_USER_INTERACTION_TOOL_NAMES = new Set([
     canonicalToolNames.delete,
 ]);
 const ALWAYS_LOAD_TOOL_NAMES = new Set([
+    canonicalToolNames.bindSourceSession,
     canonicalToolNames.search,
     canonicalToolNames.save,
 ]);
@@ -187,6 +190,9 @@ export const saveConversationSchema = z.object({
     }))
         .optional(),
 });
+export const bindSourceSessionSchema = z.object({
+    bindingToken: z.string().uuid(),
+});
 const dateBoundarySchema = z.string().trim().min(1).refine((value) => Number.isFinite(Date.parse(value)), "Expected an ISO-8601 date or date-time string");
 export const timeRangeSchema = z.object({
     ...triggerMetadataSchema,
@@ -403,6 +409,22 @@ export function listToolSpecs(opts = {}) {
         required: ["startDate", "endDate"],
     };
     const tools = [
+        {
+            name: canonicalToolNames.bindSourceSession,
+            title: "Bind this agent conversation to its source session",
+            description: withMcpVersion("Compatibility fallback for clients where EchoMem's automatic SessionStart binding is unavailable or reports that the session is unbound. Generate a fresh random UUID for bindingToken and pass only that token. EchoMem finds this exact tool call in the local host JSONL, derives the real provider session ID itself, and idempotently binds the authenticated backend context. Never reuse a bindingToken, guess a session ID, or copy a token between conversations. After success, later saves, recalls, citations, sharing decisions, and MCP activity from this bridge are attached to the returned context automatically. Do not call it routinely when automatic binding is active."),
+            inputSchema: {
+                type: "object",
+                properties: {
+                    bindingToken: {
+                        type: "string",
+                        format: "uuid",
+                        description: "A fresh random UUID generated only for this invocation. The local bridge verifies it inside the current host JSONL.",
+                    },
+                },
+                required: ["bindingToken"],
+            },
+        },
         {
             name: canonicalToolNames.search,
             title: "Search your memories by topic",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.40",
+  "version": "1.4.41",
   "description": "EchoMem MCP bridge: cloud-first memory tools and the Agent Doctor workspace forensics report (cost ledger + 3D repo city)",
   "main": "dist/index.js",
   "type": "module",
@@ -33,7 +33,7 @@
     "test:ui": "npm run build && node test/setup-ui.test.mjs",
     "test:onboarding-resilience": "npm run build && node test/onboarding-resilience.test.mjs",
     "test:billing-ui": "npm run build && node test/setup-ui.test.mjs billing",
-    "test": "npm run build && node test/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.test.mjs && node test/onboarding-resilience.test.mjs && node test/local-auth.test.mjs && node test/retrieval-only.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/forensics.test.mjs && node test/canonical-golden.test.mjs && node test/tools.test.mjs && node test/group-map.test.mjs && node test/update-check.test.mjs && node test/headless-runtime.test.mjs && node test/claude-code-config.test.mjs && node test/delete.test.mjs && node test/low-touch-tools.test.mjs && node test/migrate.test.mjs && node test/restart-recovery.test.mjs && node test/save-checkpoint-hook.test.mjs",
+    "test": "npm run build && node test/source-session.test.mjs && node test/source-session-hook.test.mjs && node test/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.test.mjs && node test/onboarding-resilience.test.mjs && node test/local-auth.test.mjs && node test/retrieval-only.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/forensics.test.mjs && node test/canonical-golden.test.mjs && node test/tools.test.mjs && node test/group-map.test.mjs && node test/update-check.test.mjs && node test/headless-runtime.test.mjs && node test/claude-code-config.test.mjs && node test/delete.test.mjs && node test/low-touch-tools.test.mjs && node test/migrate.test.mjs && node test/restart-recovery.test.mjs && node test/save-checkpoint-hook.test.mjs",
     "prepack": "npm run build && node scripts/bundle-city.mjs"
   },
   "dependencies": {

package/templates/echomem-recall.md

@@ -6,6 +6,9 @@
 
 This project has EchoMem connected — the user's long-term memory across all their AI tools.
 
+- EchoMem's local SessionStart hook automatically binds new Codex and Claude Code conversations to
+  their real provider session. Call `bind_source_session` with a fresh random UUID only as a
+  compatibility fallback when automatic binding is unavailable or reports that the session is unbound.
 - **At the start of any non-trivial task**, call `search_memories` first to recall the user's
   prior decisions, preferences, and constraints before planning or writing code. Don't re-derive
   things they've already decided.