mnemos-capture 1.1.0 → 1.2.0

package/dist/cli/__tests__/hooks.test.js

@@ -0,0 +1,276 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, readFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/** Capture stdout writes during a callback. */
+async function captureStdout(fn) {
+    const chunks = [];
+    const orig = process.stdout.write.bind(process.stdout);
+    process.stdout.write = (chunk) => {
+        chunks.push(String(chunk));
+        return true;
+    };
+    try {
+        await fn();
+    }
+    finally {
+        process.stdout.write = orig;
+    }
+    return chunks.join("");
+}
+// ── setupHooks / setupPreToolHook ────────────────────────────────────────────
+describe("setupHooks", () => {
+    let tmpDir;
+    let settingsPath;
+    let origHome;
+    beforeEach(() => {
+        tmpDir = mkdtempSync(join(tmpdir(), "mnemos-test-"));
+        settingsPath = join(tmpDir, ".claude", "settings.json");
+        origHome = process.env["HOME"];
+        process.env["HOME"] = tmpDir;
+        // Clear module cache so CLAUDE_SETTINGS_PATH is recomputed with the new HOME
+        vi.resetModules();
+    });
+    afterEach(() => {
+        rmSync(tmpDir, { recursive: true, force: true });
+        process.env["HOME"] = origHome;
+    });
+    it("installs a SessionStart hook with the provided API key", async () => {
+        const { setupHooks } = await import("../hooks.js");
+        setupHooks("my-api-key", { silent: true });
+        const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+        const cmd = settings.hooks.SessionStart[0]?.hooks[0]?.command ?? "";
+        expect(cmd).toContain("inbox-check");
+        expect(cmd).toContain("my-api-key");
+    });
+    it("includes --briefing flag when briefing option is true", async () => {
+        const { setupHooks } = await import("../hooks.js");
+        setupHooks("key123", { silent: true, briefing: true });
+        const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+        const cmd = settings.hooks.SessionStart[0]?.hooks[0]?.command ?? "";
+        expect(cmd).toContain("--briefing");
+    });
+    it("omits --briefing flag when briefing option is false", async () => {
+        const { setupHooks } = await import("../hooks.js");
+        setupHooks("key123", { silent: true, briefing: false });
+        const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+        const cmd = settings.hooks.SessionStart[0]?.hooks[0]?.command ?? "";
+        expect(cmd).not.toContain("--briefing");
+    });
+    it("also installs PreToolCall hook when vault option is true", async () => {
+        const { setupHooks } = await import("../hooks.js");
+        setupHooks("vault-key", { silent: true, vault: true });
+        const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+        expect(settings.hooks.PreToolCall).toBeDefined();
+        const cmd = settings.hooks.PreToolCall[0]?.hooks[0]?.command ?? "";
+        expect(cmd).toContain("vault-check");
+        expect(cmd).toContain("vault-key");
+    });
+    it("does NOT install PreToolCall hook when vault option is false", async () => {
+        const { setupHooks } = await import("../hooks.js");
+        setupHooks("no-vault-key", { silent: true, vault: false });
+        const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+        expect(settings.hooks["PreToolCall"]).toBeUndefined();
+    });
+    it("replaces an existing mnemos hook rather than duplicating it", async () => {
+        const { setupHooks } = await import("../hooks.js");
+        setupHooks("old-key", { silent: true });
+        setupHooks("new-key", { silent: true });
+        const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+        const cmds = settings.hooks.SessionStart.flatMap((g) => g.hooks.map((h) => h.command));
+        const mnemosHooks = cmds.filter((c) => c.includes("inbox-check"));
+        expect(mnemosHooks).toHaveLength(1);
+        expect(mnemosHooks[0]).toContain("new-key");
+    });
+    it("skipIfExists: keeps exactly one mnemos hook when called twice", async () => {
+        const { setupHooks } = await import("../hooks.js");
+        setupHooks("original-key", { silent: true });
+        setupHooks("different-key", { silent: true, skipIfExists: true });
+        const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+        const cmds = settings.hooks.SessionStart.flatMap((g) => g.hooks.map((h) => h.command));
+        expect(cmds.filter((c) => c.includes("inbox-check"))).toHaveLength(1);
+    });
+});
+// ── inboxCheck — briefing mode parsing ───────────────────────────────────────
+describe("inboxCheck — briefing mode", () => {
+    let fetchSpy;
+    beforeEach(() => {
+        fetchSpy = vi.spyOn(globalThis, "fetch");
+    });
+    afterEach(() => {
+        fetchSpy.mockRestore();
+    });
+    function makeMcpResponse(text) {
+        return Promise.resolve(new Response(JSON.stringify({ result: { content: [{ text }] } }), { status: 200, headers: { "Content-Type": "application/json" } }));
+    }
+    it("strips the JSON block from display output", async () => {
+        fetchSpy.mockReturnValue(makeMcpResponse(`\`\`\`json
+[{"filename":"inbox/a.md","why":"x","benefit":"y","where":"z.ts","applyNow":true}]
+\`\`\`
+
+## Relevant Rules
+None applicable.`));
+        const { inboxCheck } = await import("../hooks.js");
+        const output = await captureStdout(() => inboxCheck("key", { briefing: true }));
+        expect(output).not.toContain("```json");
+        expect(output).toContain("## Relevant Rules");
+    });
+    it("appends generate_plan prompt when there are applyNow suggestions", async () => {
+        fetchSpy.mockReturnValue(makeMcpResponse(`\`\`\`json
+[{"filename":"inbox/a.md","why":"x","benefit":"y","where":"z.ts","applyNow":true}]
+\`\`\`
+
+## Apply Now
+One insight.`));
+        const { inboxCheck } = await import("../hooks.js");
+        const output = await captureStdout(() => inboxCheck("key", { briefing: true }));
+        expect(output).toContain("generate_plan");
+        expect(output).toContain("inbox/a.md");
+    });
+    it("does NOT append generate_plan prompt when all suggestions have applyNow=false", async () => {
+        fetchSpy.mockReturnValue(makeMcpResponse(`\`\`\`json
+[{"filename":"inbox/b.md","why":"x","benefit":"y","where":"z.ts","applyNow":false}]
+\`\`\`
+
+## Knowledge Vault
+One vault item.`));
+        const { inboxCheck } = await import("../hooks.js");
+        const output = await captureStdout(() => inboxCheck("key", { briefing: true }));
+        expect(output).not.toContain("generate_plan");
+    });
+    it("does NOT append generate_plan prompt when JSON block is missing", async () => {
+        fetchSpy.mockReturnValue(makeMcpResponse(`## Relevant Rules
+None applicable.`));
+        const { inboxCheck } = await import("../hooks.js");
+        const output = await captureStdout(() => inboxCheck("key", { briefing: true }));
+        expect(output).not.toContain("generate_plan");
+    });
+    it("shows inbox count in non-briefing mode when count > 0", async () => {
+        fetchSpy.mockReturnValue(makeMcpResponse("3 capture(s) in inbox:\n\n1. file.md"));
+        const { inboxCheck } = await import("../hooks.js");
+        const output = await captureStdout(() => inboxCheck("key"));
+        expect(output).toContain("3");
+        expect(output).toContain("inbox");
+    });
+    it("shows nothing in non-briefing mode when inbox is empty", async () => {
+        fetchSpy.mockReturnValue(makeMcpResponse("Inbox is empty."));
+        const { inboxCheck } = await import("../hooks.js");
+        const output = await captureStdout(() => inboxCheck("key"));
+        expect(output).toBe("");
+    });
+    it("silently fails when fetch throws", async () => {
+        fetchSpy.mockRejectedValue(new Error("Network error"));
+        const { inboxCheck } = await import("../hooks.js");
+        // Should not throw
+        await expect(inboxCheck("key", { briefing: true })).resolves.toBeUndefined();
+    });
+});
+// ── vaultCheck — stdin parsing ────────────────────────────────────────────────
+describe("vaultCheck", () => {
+    let fetchSpy;
+    let origSessionId;
+    beforeEach(() => {
+        fetchSpy = vi.spyOn(globalThis, "fetch");
+        origSessionId = process.env["CLAUDE_SESSION_ID"];
+        // Use a unique session ID per test to avoid state pollution
+        process.env["CLAUDE_SESSION_ID"] = `test-${Date.now()}-${Math.random()}`;
+    });
+    afterEach(() => {
+        fetchSpy.mockRestore();
+        process.env["CLAUDE_SESSION_ID"] = origSessionId;
+    });
+    function makeMcpResponse(text) {
+        return Promise.resolve(new Response(JSON.stringify({ result: { content: [{ text }] } }), { status: 200, headers: { "Content-Type": "application/json" } }));
+    }
+    it("outputs vault match when fetch returns a high-score match", async () => {
+        fetchSpy.mockReturnValue(makeMcpResponse("Mnemos vault match (score: 87%):\n\n**2026-05-01-error-ctx**\nCore idea here.\n- Key takeaway\n\nApply it? Run: `apply_capture` with filename: `inbox/2026-05-01-error-ctx.md`"));
+        const { vaultCheck } = await import("../hooks.js");
+        // Simulate piped stdin with an Edit tool call
+        const hookData = JSON.stringify({
+            tool_name: "Edit",
+            tool_input: { file_path: "src/api/capture/route.ts" },
+        });
+        // Temporarily replace stdin
+        const mockStdin = {
+            isTTY: false,
+            setEncoding: vi.fn(),
+            on: vi.fn((event, cb) => {
+                if (event === "data")
+                    cb(hookData);
+                if (event === "end")
+                    cb();
+            }),
+        };
+        const origStdin = process.stdin;
+        Object.defineProperty(process, "stdin", { value: mockStdin, writable: true, configurable: true });
+        const output = await captureStdout(() => vaultCheck("key"));
+        Object.defineProperty(process, "stdin", { value: origStdin, writable: true, configurable: true });
+        expect(output).toContain("vault match");
+    });
+    it("outputs nothing when vault_scan returns empty", async () => {
+        fetchSpy.mockReturnValue(makeMcpResponse(""));
+        const { vaultCheck } = await import("../hooks.js");
+        const mockStdin = {
+            isTTY: false,
+            setEncoding: vi.fn(),
+            on: vi.fn((event, cb) => {
+                if (event === "data")
+                    cb(JSON.stringify({ tool_name: "Edit", tool_input: { file_path: "src/foo.ts" } }));
+                if (event === "end")
+                    cb();
+            }),
+        };
+        const origStdin = process.stdin;
+        Object.defineProperty(process, "stdin", { value: mockStdin, writable: true, configurable: true });
+        const output = await captureStdout(() => vaultCheck("key"));
+        Object.defineProperty(process, "stdin", { value: origStdin, writable: true, configurable: true });
+        expect(output).toBe("");
+    });
+    it("outputs nothing and does not call fetch when tool is not an editing tool", async () => {
+        const { vaultCheck } = await import("../hooks.js");
+        const mockStdin = {
+            isTTY: false,
+            setEncoding: vi.fn(),
+            on: vi.fn((event, cb) => {
+                if (event === "data")
+                    cb(JSON.stringify({ tool_name: "Bash", tool_input: { command: "ls" } }));
+                if (event === "end")
+                    cb();
+            }),
+        };
+        const origStdin = process.stdin;
+        Object.defineProperty(process, "stdin", { value: mockStdin, writable: true, configurable: true });
+        await vaultCheck("key");
+        Object.defineProperty(process, "stdin", { value: origStdin, writable: true, configurable: true });
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+    it("outputs nothing when stdin is a TTY (not piped)", async () => {
+        const { vaultCheck } = await import("../hooks.js");
+        const mockStdin = { isTTY: true };
+        const origStdin = process.stdin;
+        Object.defineProperty(process, "stdin", { value: mockStdin, writable: true, configurable: true });
+        const output = await captureStdout(() => vaultCheck("key"));
+        Object.defineProperty(process, "stdin", { value: origStdin, writable: true, configurable: true });
+        expect(output).toBe("");
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+    it("silently fails when fetch throws", async () => {
+        fetchSpy.mockRejectedValue(new Error("Network error"));
+        const { vaultCheck } = await import("../hooks.js");
+        const mockStdin = {
+            isTTY: false,
+            setEncoding: vi.fn(),
+            on: vi.fn((event, cb) => {
+                if (event === "data")
+                    cb(JSON.stringify({ tool_name: "Edit", tool_input: { file_path: "src/foo.ts" } }));
+                if (event === "end")
+                    cb();
+            }),
+        };
+        const origStdin = process.stdin;
+        Object.defineProperty(process, "stdin", { value: mockStdin, writable: true, configurable: true });
+        await expect(vaultCheck("key")).resolves.toBeUndefined();
+        Object.defineProperty(process, "stdin", { value: origStdin, writable: true, configurable: true });
+    });
+});

package/dist/cli/__tests__/kos.test.js

@@ -0,0 +1,65 @@
+import { describe, it, expect } from "vitest";
+import { parsePlanFilenames, latestPlanFilename, parseChecklist, buildKosBranch, } from "../kos.js";
+const LIST_PLANS = `3 plan(s):
+
+- **2026-06-03-plan-error-handling.md**: Implementation Plan: Error Handling
+- **2026-06-05-plan-provider-abstraction.md**: Implementation Plan: Provider Abstraction
+- **2026-06-04-plan-vault.md**: Implementation Plan: Vault`;
+describe("parsePlanFilenames", () => {
+    it("extracts all bolded plan filenames", () => {
+        expect(parsePlanFilenames(LIST_PLANS)).toEqual([
+            "2026-06-03-plan-error-handling.md",
+            "2026-06-05-plan-provider-abstraction.md",
+            "2026-06-04-plan-vault.md",
+        ]);
+    });
+    it("returns empty array when there are no plans", () => {
+        expect(parsePlanFilenames("No plans saved yet.")).toEqual([]);
+    });
+});
+describe("latestPlanFilename", () => {
+    it("returns the newest plan by date prefix", () => {
+        expect(latestPlanFilename(LIST_PLANS)).toBe("2026-06-05-plan-provider-abstraction.md");
+    });
+    it("returns null when there are no plans", () => {
+        expect(latestPlanFilename("No plans saved yet.")).toBeNull();
+    });
+});
+describe("parseChecklist", () => {
+    const PLAN = `# Implementation Plan: Foo
+
+## Codebase Mapping
+| File | Capture | Change | Complexity | Effort |
+|------|---------|--------|------------|--------|
+| a.ts | x | edit | simple | low |
+
+## Verification Checklist
+- [ ] Error messages include a handler prefix
+- [ ] No regressions in the happy path
+- [x] Already-done item still counts
+
+## Notes
+Not part of the checklist.`;
+    it("extracts checklist items without the checkbox prefix", () => {
+        expect(parseChecklist(PLAN)).toEqual([
+            "Error messages include a handler prefix",
+            "No regressions in the happy path",
+            "Already-done item still counts",
+        ]);
+    });
+    it("stops at the next section heading", () => {
+        expect(parseChecklist(PLAN)).not.toContain("Not part of the checklist.");
+    });
+    it("returns empty array when there is no checklist section", () => {
+        expect(parseChecklist("# Plan\n\n## Context\nNothing here.")).toEqual([]);
+    });
+});
+describe("buildKosBranch", () => {
+    it("produces a deterministic, sortable branch name from a date", () => {
+        const branch = buildKosBranch(new Date("2026-06-05T10:30:45.000Z"));
+        expect(branch).toBe("mnemos/kos-2026-06-05-10-30-45");
+    });
+    it("always starts with the mnemos/kos- prefix", () => {
+        expect(buildKosBranch()).toMatch(/^mnemos\/kos-/);
+    });
+});

package/dist/cli/config.js

@@ -0,0 +1,70 @@
+/**
+ * Mnemos CLI config — stores which AI assistant kos should drive, and an
+ * optional API key, in ~/.mnemos/config.json. Provider/agent-agnostic: the
+ * user tells Mnemos the exact command to launch their assistant.
+ */
+import { homedir } from "os";
+import { join } from "path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+const CONFIG_DIR = join(homedir(), ".mnemos");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+const ALLOWED_FIELDS = ["agent", "key"];
+export function readConfig() {
+    if (!existsSync(CONFIG_PATH))
+        return {};
+    try {
+        return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeConfig(cfg) {
+    if (!existsSync(CONFIG_DIR))
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n");
+}
+export function setConfigField(field, value) {
+    if (!ALLOWED_FIELDS.includes(field)) {
+        throw new Error(`Unknown config field: ${field}. Allowed: ${ALLOWED_FIELDS.join(", ")}`);
+    }
+    const cfg = readConfig();
+    cfg[field] = value;
+    writeConfig(cfg);
+}
+/** Route `mnemos config <set|get> ...`. */
+export function runConfigCommand(args) {
+    const action = args[0];
+    if (action === "set") {
+        const field = args[1];
+        const value = args.slice(2).join(" ");
+        if (!field || !value) {
+            console.error('Usage: mnemos config set <field> <value>');
+            console.error('  e.g. mnemos config set agent "claude -p"');
+            process.exit(1);
+        }
+        try {
+            setConfigField(field, value);
+            console.log(`Set ${field} = ${value}`);
+            console.log(`Saved to ${CONFIG_PATH}`);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+        return;
+    }
+    if (action === "get") {
+        const cfg = readConfig();
+        const field = args[1];
+        if (field) {
+            console.log(cfg[field] ?? "(not set)");
+        }
+        else {
+            console.log(JSON.stringify(cfg, null, 2));
+        }
+        return;
+    }
+    console.error("Usage: mnemos config set|get <field> [value]");
+    process.exit(1);
+}

package/dist/cli/hooks.js

@@ -1,4 +1,4 @@
-import { homedir } from "os";
+import { homedir, tmpdir } from "os";
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
 import { join } from "path";
 import { execSync } from "child_process";
@@ -9,6 +9,9 @@ const CLAUDE_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
 function isMnemosHook(cmd) {
     return cmd.includes("mnemos-capture") && cmd.includes("inbox-check");
 }
+function isMnemosPreToolHook(cmd) {
+    return cmd.includes("mnemos-capture") && cmd.includes("vault-check");
+}
 function readSettings() {
     if (!existsSync(CLAUDE_SETTINGS_PATH))
         return {};
@@ -25,6 +28,47 @@ function writeSettings(settings) {
         mkdirSync(dir, { recursive: true });
     writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2) + "\n");
 }
+// ── Session state for vault deduplication ──
+function sessionStateFile() {
+    const sessionId = process.env["CLAUDE_SESSION_ID"] ?? new Date().toISOString().split("T")[0] ?? "default";
+    return join(tmpdir(), `mnemos-vault-${sessionId}.json`);
+}
+function readSessionSurfaced() {
+    try {
+        const file = sessionStateFile();
+        if (!existsSync(file))
+            return [];
+        return JSON.parse(readFileSync(file, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+function appendSessionSurfaced(filenames) {
+    try {
+        const file = sessionStateFile();
+        const existing = readSessionSurfaced();
+        const updated = [...new Set([...existing, ...filenames])];
+        writeFileSync(file, JSON.stringify(updated));
+    }
+    catch {
+        // best-effort
+    }
+}
+// ── Stdin reader for hook context ──
+async function readStdin() {
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY) {
+            resolve("");
+            return;
+        }
+        let data = "";
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => { data += chunk; });
+        process.stdin.on("end", () => resolve(data));
+        setTimeout(() => resolve(data), 2000);
+    });
+}
 export function setupHooks(apiKey, opts = {}) {
     const settings = readSettings();
     const hooks = settings.hooks ?? {};
@@ -73,6 +117,43 @@ export function setupHooks(apiKey, opts = {}) {
             console.log("At the start of each Claude Code session you'll see your inbox count.");
         }
     }
+    if (opts.vault) {
+        setupPreToolHook(apiKey, { silent: opts.silent, skipIfExists: opts.skipIfExists });
+    }
+}
+export function setupPreToolHook(apiKey, opts = {}) {
+    const settings = readSettings();
+    const hooks = settings.hooks ?? {};
+    const preToolCall = hooks.PreToolCall ?? [];
+    let existingCmd = null;
+    for (const group of preToolCall) {
+        for (const h of group.hooks ?? []) {
+            if (typeof h.command === "string" && isMnemosPreToolHook(h.command)) {
+                existingCmd = h.command;
+                break;
+            }
+        }
+        if (existingCmd)
+            break;
+    }
+    if (existingCmd && opts.skipIfExists) {
+        if (existingCmd.includes("mnemos-capture@latest"))
+            return;
+    }
+    const command = `npx -y mnemos-capture@latest vault-check --key ${apiKey}`;
+    const filtered = preToolCall
+        .map((group) => ({
+        ...group,
+        hooks: (group.hooks ?? []).filter((h) => !(typeof h.command === "string" && isMnemosPreToolHook(h.command))),
+    }))
+        .filter((group) => (group.hooks ?? []).length > 0);
+    filtered.push({ hooks: [{ type: "command", command }] });
+    settings.hooks = { ...hooks, PreToolCall: filtered };
+    writeSettings(settings);
+    if (!opts.silent) {
+        console.log("Mnemos vault hook installed (PreToolCall).");
+        console.log("Your knowledge vault will surface relevant captures as you edit files.");
+    }
 }
 function run(cmd) {
     return execSync(cmd, { timeout: 2000, stdio: ["pipe", "pipe", "pipe"] }).toString().trim();
@@ -116,7 +197,7 @@ function detectProjectContext() {
     catch { }
     return parts.length > 0 ? parts.join("\n\n") : "current project";
 }
-async function callMcp(apiKey, toolName, toolArgs) {
+export async function callMcp(apiKey, toolName, toolArgs, timeoutMs = 15000) {
     const res = await fetch(HOSTED_URL, {
         method: "POST",
         headers: {
@@ -129,20 +210,78 @@ async function callMcp(apiKey, toolName, toolArgs) {
             params: { name: toolName, arguments: toolArgs },
             id: 1,
         }),
-        signal: AbortSignal.timeout(15000),
+        signal: AbortSignal.timeout(timeoutMs),
     });
     if (!res.ok)
         return null;
     const data = (await res.json());
     return data.result?.content?.[0]?.text ?? null;
 }
+export async function vaultCheck(apiKey) {
+    try {
+        const inputJson = await readStdin();
+        if (!inputJson.trim())
+            return;
+        let hookData;
+        try {
+            hookData = JSON.parse(inputJson);
+        }
+        catch {
+            return;
+        }
+        // Only act on file-editing tool calls
+        const editingTools = ["Edit", "Write", "MultiEdit"];
+        if (!hookData.tool_name || !editingTools.includes(hookData.tool_name))
+            return;
+        const filePath = hookData.tool_input?.["file_path"] ??
+            hookData.tool_input?.["path"];
+        if (!filePath)
+            return;
+        const projectCtx = detectProjectContext();
+        const activityContext = `Editing file: ${filePath}\nProject context:\n${projectCtx}`;
+        const sessionSurfaced = readSessionSurfaced();
+        const text = await callMcp(apiKey, "vault_scan", {
+            activity_context: activityContext,
+            session_surfaced: sessionSurfaced,
+        }, 8000);
+        if (!text?.trim())
+            return;
+        // Track surfaced filenames to avoid repetition within the session
+        const filenameMatches = text.match(/(?:inbox|applied|archived)\/[\w-]+\.md/g) ?? [];
+        if (filenameMatches.length > 0)
+            appendSessionSurfaced(filenameMatches);
+        process.stdout.write(text.trim() + "\n");
+    }
+    catch {
+        // Silent fail — never interrupt a tool call
+    }
+}
 export async function inboxCheck(apiKey, opts = {}) {
     try {
         if (opts.briefing) {
             const projectContext = detectProjectContext();
             const text = await callMcp(apiKey, "briefing", { project_context: projectContext });
-            if (text?.trim())
-                process.stdout.write(text.trim() + "\n");
+            if (!text?.trim())
+                return;
+            const jsonMatch = text.match(/```json\n([\s\S]*?)\n```/);
+            let applyNow = [];
+            if (jsonMatch?.[1]) {
+                try {
+                    const all = JSON.parse(jsonMatch[1]);
+                    applyNow = all.filter((s) => s.applyNow);
+                }
+                catch {
+                    applyNow = [];
+                }
+            }
+            // Strip the JSON block — display only the Markdown narrative
+            const displayText = text.replace(/```json[\s\S]*?```\n?/, "").trim();
+            process.stdout.write(displayText + "\n");
+            if (applyNow.length > 0) {
+                const filenames = applyNow.map((s) => `'${s.filename}'`).join(", ");
+                process.stdout.write(`\n---\nMnemos: ${applyNow.length} insight${applyNow.length === 1 ? "" : "s"} ready to apply now.\n` +
+                    `Run generate_plan with selected_captures: [${filenames}] to get a full implementation plan.\n`);
+            }
             return;
         }
         // Default: fast count via list_inbox (no LLM call)