mnemos-capture 1.0.6 → 1.2.0

package/dist/cli/hooks.js

@@ -0,0 +1,303 @@
+import { homedir, tmpdir } from "os";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+const HOSTED_URL = "https://mnemos-capture.vercel.app/api/mcp";
+const CLAUDE_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+// Matches both legacy ("mnemos-capture inbox-check") and modern
+// ("mnemos-capture@latest inbox-check") hook command forms.
+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 {};
+    try {
+        return JSON.parse(readFileSync(CLAUDE_SETTINGS_PATH, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeSettings(settings) {
+    const dir = join(homedir(), ".claude");
+    if (!existsSync(dir))
+        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 ?? {};
+    const sessionStart = hooks.SessionStart ?? [];
+    // Inspect any existing mnemos hook so we can either skip, migrate, or replace
+    let existingCmd = null;
+    for (const group of sessionStart) {
+        for (const h of group.hooks ?? []) {
+            if (typeof h.command === "string" && isMnemosHook(h.command)) {
+                existingCmd = h.command;
+                break;
+            }
+        }
+        if (existingCmd)
+            break;
+    }
+    // skipIfExists (serve-mcp auto-install): preserve user-configured hooks but
+    // silently migrate legacy hooks that don't use @latest so they always stay fresh.
+    if (existingCmd && opts.skipIfExists) {
+        const alreadyLatest = existingCmd.includes("mnemos-capture@latest");
+        if (alreadyLatest)
+            return;
+        // Migration: preserve the existing --briefing flag when upgrading to @latest
+        opts = { ...opts, briefing: existingCmd.includes("--briefing") };
+    }
+    const command = opts.briefing
+        ? `npx -y mnemos-capture@latest inbox-check --key ${apiKey} --briefing`
+        : `npx -y mnemos-capture@latest inbox-check --key ${apiKey}`;
+    // Remove any existing mnemos inbox-check hook (handles key rotation too)
+    const filtered = sessionStart
+        .map((group) => ({
+        ...group,
+        hooks: (group.hooks ?? []).filter((h) => !(typeof h.command === "string" && isMnemosHook(h.command))),
+    }))
+        .filter((group) => (group.hooks ?? []).length > 0);
+    filtered.push({ hooks: [{ type: "command", command }] });
+    settings.hooks = { ...hooks, SessionStart: filtered };
+    writeSettings(settings);
+    if (!opts.silent) {
+        console.log("Mnemos inbox hook installed.");
+        console.log(`Location: ${CLAUDE_SETTINGS_PATH}`);
+        if (opts.briefing) {
+            console.log("At the start of each Claude Code session you'll see a full project briefing.");
+        }
+        else {
+            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();
+}
+function detectProjectContext() {
+    const parts = [];
+    // Repo name
+    try {
+        const remote = run("git remote get-url origin");
+        const match = remote.match(/\/([^/]+?)(?:\.git)?$/);
+        const repo = match?.[1] ?? run("git rev-parse --show-toplevel").split("/").pop();
+        if (repo)
+            parts.push(`Project: ${repo}`);
+    }
+    catch {
+        const dir = process.cwd().split("/").pop();
+        if (dir)
+            parts.push(`Project: ${dir}`);
+    }
+    // Current branch
+    try {
+        const branch = run("git branch --show-current");
+        if (branch)
+            parts.push(`Branch: ${branch}`);
+    }
+    catch { }
+    // Recent commits (last 5)
+    try {
+        const log = run("git log --oneline -5");
+        if (log)
+            parts.push(`Recent commits:\n${log}`);
+    }
+    catch { }
+    // CLAUDE.md — first 800 chars gives the model real project intent
+    try {
+        const root = run("git rev-parse --show-toplevel");
+        const claudeMd = readFileSync(join(root, "CLAUDE.md"), "utf-8").slice(0, 800).trim();
+        if (claudeMd)
+            parts.push(`Project instructions (CLAUDE.md excerpt):\n${claudeMd}`);
+    }
+    catch { }
+    return parts.length > 0 ? parts.join("\n\n") : "current project";
+}
+export async function callMcp(apiKey, toolName, toolArgs, timeoutMs = 15000) {
+    const res = await fetch(HOSTED_URL, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            method: "tools/call",
+            params: { name: toolName, arguments: toolArgs },
+            id: 1,
+        }),
+        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())
+                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)
+        const text = await callMcp(apiKey, "list_inbox", {});
+        if (!text)
+            return;
+        // list_inbox returns "N capture(s) in inbox:" or "Inbox is empty."
+        const match = text.match(/^(\d+)\s+capture/);
+        if (!match)
+            return;
+        const count = parseInt(match[1], 10);
+        if (count > 0) {
+            process.stdout.write(`Mnemos: ${count} capture${count === 1 ? "" : "s"} in inbox — run list_inbox to review\n`);
+        }
+    }
+    catch {
+        // Silent fail — never interrupt a session startup
+    }
+}

package/dist/cli/index.js

@@ -8,11 +8,58 @@ async function main() {
         return;
     }
     if (command === "serve-mcp") {
-        // MCP server mode — proxies to hosted instance
         const { serveMcp } = await import("./mcp-server.js");
         await serveMcp();
         return;
     }
+    if (command === "setup-hooks") {
+        const { setupHooks } = await import("./hooks.js");
+        const keyIdx = args.indexOf("--key");
+        const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : undefined;
+        if (!apiKey) {
+            console.error("Usage: npx mnemos-capture setup-hooks --key YOUR_API_KEY [--briefing] [--vault]");
+            process.exit(1);
+        }
+        setupHooks(apiKey, { briefing: args.includes("--briefing"), vault: args.includes("--vault") });
+        return;
+    }
+    if (command === "inbox-check") {
+        const { inboxCheck } = await import("./hooks.js");
+        const keyIdx = args.indexOf("--key");
+        const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : undefined;
+        if (!apiKey)
+            process.exit(0); // silent fail in hook context
+        await inboxCheck(apiKey, { briefing: args.includes("--briefing") });
+        return;
+    }
+    if (command === "vault-check") {
+        const { vaultCheck } = await import("./hooks.js");
+        const keyIdx = args.indexOf("--key");
+        const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : undefined;
+        if (!apiKey)
+            process.exit(0); // silent fail in hook context
+        await vaultCheck(apiKey);
+        return;
+    }
+    if (command === "config") {
+        const { runConfigCommand } = await import("./config.js");
+        runConfigCommand(args.slice(1));
+        return;
+    }
+    if (command === "kos") {
+        const { kos } = await import("./kos.js");
+        const { readConfig } = await import("./config.js");
+        const keyIdx = args.indexOf("--key");
+        const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : readConfig().key;
+        if (!apiKey) {
+            console.error("No API key. Pass --key YOUR_KEY or store it: mnemos config set key YOUR_KEY");
+            process.exit(1);
+        }
+        const planIdx = args.indexOf("--plan");
+        const plan = planIdx !== -1 ? args[planIdx + 1] : undefined;
+        await kos(apiKey, { plan });
+        return;
+    }
     // Default: open the hosted app
     console.log("");
     console.log("  Mnemos — Knowledge capture for agentic workflows\n");
@@ -21,7 +68,7 @@ async function main() {
     console.log("  First time? Sign in with GitHub — setup takes 30 seconds.");
     console.log("");
     console.log("  Connect to Claude Code:");
-    console.log("  claude mcp add mnemos -- npx mnemos-capture serve-mcp --key YOUR_API_KEY");
+    console.log("  claude mcp add mnemos -- npx -y mnemos-capture@latest serve-mcp --key YOUR_API_KEY");
     console.log("");
     // Try to open the URL in the default browser
     const { exec } = await import("child_process");
@@ -33,9 +80,30 @@ function printHelp() {
   Mnemos — Knowledge capture for agentic workflows
 
   Usage:
-    npx mnemos-capture              Open Mnemos in your browser
-    npx mnemos-capture serve-mcp    Start the MCP server for Claude Code
-    npx mnemos-capture help         Show this help
+    npx mnemos-capture                                         Open Mnemos in your browser
+    npx mnemos-capture serve-mcp --key KEY                     Start the MCP server for Claude Code
+    npx mnemos-capture setup-hooks --key KEY                   Install inbox count hook (fast)
+    npx mnemos-capture setup-hooks --key KEY --briefing        Install full briefing hook (uses LLM)
+    npx mnemos-capture setup-hooks --key KEY --vault           Install vault hook (PreToolCall)
+    npx mnemos-capture setup-hooks --key KEY --briefing --vault  Install both hooks
+    npx mnemos-capture config set agent "claude -p"            Set which AI assistant kos drives
+    npx mnemos-capture kos --key KEY [--plan FILE]             Implement a plan in an isolated worktree
+    npx mnemos-capture help                                    Show this help
+
+  MCP tools (via your AI assistant):
+    briefing          — Session-start briefing with ranked insights to apply
+    generate_plan     — Turn selected captures into a full implementation plan
+    list_plans        — List or read saved implementation plans
+    vault_scan        — Scan all captures for relevance to current activity
+    curate            — Validate URLs and flag stale captures
+
+  kos — implement plans with your own AI assistant (model-agnostic):
+    1. Tell Mnemos which assistant to drive (once):
+         mnemos config set agent "claude -p"      # or "codex exec", "aider --yes --message"
+    2. Generate a plan via the generate_plan MCP tool.
+    3. Run: mnemos kos --key YOUR_KEY
+       kos creates an isolated git worktree, hands the plan to your assistant,
+       and reports the branch + the plan's Verification Checklist when done.
 
   Get started:
     1. Run: npx mnemos-capture
@@ -44,7 +112,18 @@ function printHelp() {
     4. Start capturing!
 
   Connect to Claude Code:
-    claude mcp add mnemos -- npx mnemos-capture serve-mcp --key YOUR_API_KEY
+    claude mcp add mnemos -- npx -y mnemos-capture@latest serve-mcp --key YOUR_API_KEY
+
+  The @latest tag ensures every Claude Code session uses the most recent
+  published version. serve-mcp also self-upgrades on startup as a safety net
+  for users who registered without @latest.
+
+  The hook is installed automatically when you start the MCP server.
+  To upgrade to a full project briefing at session start:
+    npx mnemos-capture setup-hooks --key YOUR_API_KEY --briefing
+
+  To enable the vault (surfaces captures as you edit files — opt-in):
+    npx mnemos-capture setup-hooks --key YOUR_API_KEY --vault
   `);
 }
 main().catch((err) => {

package/dist/cli/kos.js

@@ -0,0 +1,123 @@
+/**
+ * kos — Mnemos' Knowledge Operations orchestrator.
+ *
+ * Drives whatever AI assistant the user configured (`mnemos config set agent ...`)
+ * to implement a generated plan in an isolated git worktree. Mnemos owns the
+ * harness-independent parts: fetching the plan, the worktree, and reporting the
+ * Verification Checklist. The assistant is a black box — model-agnostic by design.
+ */
+import { tmpdir } from "os";
+import { join } from "path";
+import { writeFileSync, existsSync, appendFileSync, readFileSync } from "fs";
+import { execSync } from "child_process";
+import { callMcp } from "./hooks.js";
+import { readConfig } from "./config.js";
+// ── Pure helpers (exported for testing) ──
+/** Extract `**filename.md**` plan names from a list_plans response. */
+export function parsePlanFilenames(listText) {
+    const matches = listText.match(/\*\*([^*]+\.md)\*\*/g) ?? [];
+    return matches.map((m) => m.replace(/\*\*/g, ""));
+}
+/** Pick the newest plan. Filenames are date-prefixed (YYYY-MM-DD-...), so lexical desc = newest. */
+export function latestPlanFilename(listText) {
+    const names = parsePlanFilenames(listText);
+    if (names.length === 0)
+        return null;
+    return [...names].sort((a, b) => b.localeCompare(a))[0] ?? null;
+}
+/** Pull the Verification Checklist items out of a plan's Markdown. */
+export function parseChecklist(planText) {
+    const section = planText.match(/##\s*Verification Checklist\s*\n([\s\S]*?)(?=\n##\s|$)/i);
+    if (!section?.[1])
+        return [];
+    return section[1]
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => /^- \[[ x]\]/i.test(l))
+        .map((l) => l.replace(/^- \[[ x]\]\s*/i, ""));
+}
+/** Build a unique, sortable branch name for a kos run. */
+export function buildKosBranch(now = new Date()) {
+    const stamp = now.toISOString().replace(/[:.]/g, "-").replace("T", "-").slice(0, 19);
+    return `mnemos/kos-${stamp}`;
+}
+/** The instruction handed to the assistant. The plan file is the real contract. */
+export const KOS_PROMPT = "Implement the plan in MNEMOS_PLAN.md in this repository. " +
+    "Follow the Codebase Mapping table exactly — change only the files it lists. " +
+    "For each step apply the thinking effort named in its Effort column " +
+    "(low = quick/mechanical, medium = careful, high = deep reasoning). " +
+    "When finished, make sure every item in the Verification Checklist is satisfied.";
+// ── Orchestrator ──
+function run(cmd, cwd) {
+    return execSync(cmd, { cwd, stdio: ["pipe", "pipe", "pipe"] }).toString().trim();
+}
+export async function kos(apiKey, opts = {}) {
+    const cfg = readConfig();
+    if (!cfg.agent) {
+        console.error("No agent configured. Tell Mnemos which AI assistant to drive:\n");
+        console.error('  mnemos config set agent "claude -p"               # Claude Code');
+        console.error('  mnemos config set agent "codex exec"              # Codex');
+        console.error('  mnemos config set agent "aider --yes --message"   # Aider');
+        process.exit(1);
+    }
+    // 1. Resolve the plan — explicit filename, or the newest saved plan
+    const planFile = opts.plan ?? latestPlanFilename((await callMcp(apiKey, "list_plans", {}, 15000)) ?? "");
+    if (!planFile) {
+        console.error("No plans found. Generate one first with the generate_plan MCP tool.");
+        process.exit(1);
+    }
+    const planText = await callMcp(apiKey, "list_plans", { filename: planFile }, 15000);
+    if (!planText || !planText.trim()) {
+        console.error(`Could not read plan: ${planFile}`);
+        process.exit(1);
+    }
+    // 2. Must be inside a git repo
+    let repoRoot;
+    try {
+        repoRoot = run("git rev-parse --show-toplevel");
+    }
+    catch {
+        console.error("mnemos kos must be run inside a git repository.");
+        process.exit(1);
+        return;
+    }
+    // 3. Isolated worktree on a fresh branch
+    const branch = buildKosBranch();
+    const worktreePath = join(tmpdir(), branch.replace(/\//g, "-"));
+    console.log(`Creating isolated worktree on branch ${branch}...`);
+    run(`git worktree add -b ${branch} "${worktreePath}"`, repoRoot);
+    // 4. Drop the plan in and keep git from tracking it (local exclude, not committed)
+    writeFileSync(join(worktreePath, "MNEMOS_PLAN.md"), planText);
+    try {
+        const excludePath = join(repoRoot, ".git", "info", "exclude");
+        if (existsSync(excludePath)) {
+            const current = readFileSync(excludePath, "utf-8");
+            if (!current.includes("MNEMOS_PLAN.md"))
+                appendFileSync(excludePath, "\nMNEMOS_PLAN.md\n");
+        }
+    }
+    catch {
+        // best-effort
+    }
+    // 5. Hand off to the user's assistant, running inside the worktree
+    console.log(`Launching: ${cfg.agent}\n`);
+    try {
+        execSync(`${cfg.agent} ${JSON.stringify(KOS_PROMPT)}`, { cwd: worktreePath, stdio: "inherit" });
+    }
+    catch {
+        console.error("\nThe agent exited with an error. The worktree is preserved for inspection.");
+    }
+    // 6. Report — branch + the plan's own checklist as the review gate
+    const checklist = parseChecklist(planText);
+    console.log(`\n${"─".repeat(60)}`);
+    console.log(`kos finished. Plan: ${planFile}`);
+    console.log(`Branch:   ${branch}`);
+    console.log(`Worktree: ${worktreePath}`);
+    if (checklist.length > 0) {
+        console.log(`\nVerify before merging:`);
+        for (const item of checklist)
+            console.log(`  [ ] ${item}`);
+    }
+    console.log(`\nReview the branch, then merge. Clean up the worktree with:`);
+    console.log(`  git worktree remove "${worktreePath}"`);
+}

package/dist/cli/mcp-server.js

@@ -33,10 +33,30 @@ export async function serveMcp() {
     const apiKey = keyIdx !== -1 ? args[keyIdx + 1] : undefined;
     if (!apiKey) {
         process.stderr.write("\nMnemos MCP server requires an API key.\n");
-        process.stderr.write("Usage: npx mnemos-capture serve-mcp --key <your-api-key>\n\n");
+        process.stderr.write("Usage: npx -y mnemos-capture@latest serve-mcp --key <your-api-key>\n\n");
         process.stderr.write("Get your API key at: https://mnemos-capture.vercel.app/onboard\n\n");
         process.exit(1);
     }
+    // Self-upgrade: if a newer version exists on npm, respawn via npx @latest.
+    // Handled before anything else so stdio isn't yet owned by the MCP loop.
+    try {
+        const { maybeSelfUpgrade } = await import("./version-check.js");
+        const upgrading = await maybeSelfUpgrade();
+        if (upgrading)
+            return; // child has taken over; parent will exit when child does
+    }
+    catch {
+        // Version check must never block startup
+    }
+    // Auto-install the inbox hook the first time the MCP server is registered.
+    // Uses silent mode so it never prints to stdout (which is reserved for MCP protocol).
+    try {
+        const { setupHooks } = await import("./hooks.js");
+        setupHooks(apiKey, { silent: true, skipIfExists: true });
+    }
+    catch {
+        // Non-fatal — hook setup should never block the MCP server from starting
+    }
     process.stderr.write("Mnemos MCP server starting (proxying to hosted instance)...\n");
     let buffer = "";
     process.stdin.setEncoding("utf-8");

package/dist/cli/version-check.js

@@ -0,0 +1,79 @@
+// Self-update enforcement: ensures users always run the latest mnemos-capture.
+//
+// Strategy: on serve-mcp startup, query npm for the latest published version.
+// If behind, respawn the process via `npx -y mnemos-capture@latest` and proxy
+// stdio. A MNEMOS_UPGRADED=1 env var prevents infinite recursion.
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { spawn } from "child_process";
+const NPM_REGISTRY = "https://registry.npmjs.org/mnemos-capture/latest";
+const CHECK_TIMEOUT_MS = 2000;
+export function getCurrentVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        // dist/cli/version-check.js → ../../package.json
+        const pkg = JSON.parse(readFileSync(join(here, "../../package.json"), "utf-8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export function isNewer(latest, current) {
+    const l = latest.split(".").map((n) => parseInt(n, 10) || 0);
+    const c = current.split(".").map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        const lv = l[i] ?? 0;
+        const cv = c[i] ?? 0;
+        if (lv > cv)
+            return true;
+        if (lv < cv)
+            return false;
+    }
+    return false;
+}
+async function getLatestVersion() {
+    try {
+        const res = await fetch(NPM_REGISTRY, { signal: AbortSignal.timeout(CHECK_TIMEOUT_MS) });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * If a newer version exists on npm, respawn via `npx -y mnemos-capture@latest`
+ * with the original argv, piping stdio. Returns true if the caller should stop
+ * (because the child is taking over). Returns false otherwise — caller should
+ * continue with normal startup.
+ */
+export async function maybeSelfUpgrade() {
+    // Recursion guard: the child spawned below will inherit this env var.
+    if (process.env.MNEMOS_UPGRADED === "1")
+        return false;
+    const current = getCurrentVersion();
+    const latest = await getLatestVersion();
+    if (!latest || !isNewer(latest, current))
+        return false;
+    process.stderr.write(`Mnemos: upgrading to v${latest} (was v${current})...\n`);
+    const child = spawn("npx", ["-y", `mnemos-capture@${latest}`, ...process.argv.slice(2)], {
+        stdio: "inherit",
+        env: { ...process.env, MNEMOS_UPGRADED: "1" },
+    });
+    // Keep parent alive until the child exits, then exit with its code.
+    await new Promise((resolve) => {
+        child.on("exit", (code) => {
+            process.exit(code ?? 0);
+            resolve();
+        });
+        child.on("error", () => {
+            // If spawn itself fails, fall through and let the parent continue
+            resolve();
+        });
+    });
+    return true;
+}