myagentmemory 0.4.12 → 0.4.14

package/dist/cli.js

@@ -12,14 +12,32 @@
  *   search     — Search via qmd
  *   init       — Create dirs, detect qmd, setup collection
  *   status     — Show config, qmd status, file counts
+ *   completion — Install or print shell completion
+ *   install-hooks — Install managed session-start hooks
+ *   uninstall-hooks — Remove managed session-start hooks
+ *   plugin     — Discover and bootstrap optional official plugins
  *
  * Global flags:
  *   --dir <path>   Override memory directory
  *   --json         Machine-readable JSON output
  */
+import { spawn } from "node:child_process";
 import * as fs from "node:fs";
-import { _setBaseDir, buildMemoryContext, checkCollection, dailyPath, detectQmd, distilMemories, ensureDirs, ensureQmdAvailableForSync, ensureQmdAvailableForUpdate, getCollectionName, getDailyDir, getMemoryDir, getMemoryFile, getQmdEmbedMode, getQmdHealth, getQmdResultPath, getQmdResultText, getScratchpadFile, getTopicsDir, installSkills, nowTimestamp, parseScratchpad, readFileSafe, runQmdEmbedDetached, runQmdSearch, runQmdSync, runQmdUpdateNow, scheduleQmdUpdate, searchRelevantMemories, serializeScratchpad, setupQmdCollection, slugifyTopic, todayStr, topicPath, uninstallSkills, } from "./core.js";
-const VERSION = typeof __VERSION__ !== "undefined" ? __VERSION__ : "dev";
+import { detectCompletionShell, generateCompletion, installCompletion } from "./completions.js";
+import { _setBaseDir, buildMemoryContext, checkCollection, dailyPath, detectQmd, distilMemories, ensureDirs, ensureQmdAvailableForSync, ensureQmdAvailableForUpdate, getCollectionName, getDailyDir, getMemoryDir, getMemoryFile, getQmdEmbedMode, getQmdHealth, getQmdResultPath, getQmdResultText, getScratchpadFile, getTopicsDir, installSkills, memoryWrite, nowTimestamp, parseScratchpad, probeEmbeddings, readFileSafe, redactSecrets, runQmdEmbedDetached, runQmdSearch, runQmdSync, runQmdUpdateNow, scheduleQmdUpdate, searchRelevantMemories, serializeScratchpad, setupQmdCollection, slugifyTopic, todayStr, topicPath, uninstallSkills, } from "./core.js";
+import { detectHookAgents, installHooks, uninstallHooks } from "./hooks.js";
+import { createDefaultPluginBootstrap, PluginBootstrapFailure, } from "./plugin-bootstrap.js";
+import { InstalledPluginRuntimeV1 } from "./plugin-runtime.js";
+function readPackageVersion() {
+    try {
+        const packageJson = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+        return typeof packageJson.version === "string" ? packageJson.version : "dev";
+    }
+    catch {
+        return "dev";
+    }
+}
+const VERSION = typeof __VERSION__ !== "undefined" ? __VERSION__ : readPackageVersion();
 function parseArgs(argv) {
     const flags = {};
     const positional = [];
@@ -77,14 +95,125 @@ function exitError(message, json) {
     }
     process.exit(1);
 }
+function openExternalUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== "https:")
+        return false;
+    try {
+        const child = process.platform === "darwin"
+            ? spawn("open", [parsed.toString()], { detached: true, stdio: "ignore" })
+            : process.platform === "win32"
+                ? spawn("explorer.exe", [parsed.toString()], { detached: true, stdio: "ignore" })
+                : spawn("xdg-open", [parsed.toString()], { detached: true, stdio: "ignore" });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function printProOverview(installed) {
+    console.log("");
+    console.log("AgentMemory Pro includes:");
+    console.log("  Session Intelligence  Recall decisions and context across Pi, Codex, and Claude Code sessions.");
+    console.log("  Guided Learning       Turn repeated corrections into reviewable, reversible memory.");
+    console.log("  Local Web Console     Inspect memories, activity, health, and settings in your browser.");
+    console.log("");
+    console.log("Your session content stays on this device.");
+    console.log("");
+    if (installed) {
+        console.log("Try it:");
+        console.log('  agent-memory recall "what did we decide about authentication?"');
+        console.log("  agent-memory learn");
+        console.log("  agent-memory web");
+    }
+    else {
+        console.log("Start your Pro beta:");
+        console.log("  agent-memory plugin install");
+    }
+}
+function printPluginResult(result, json, allowBrowser) {
+    if (json) {
+        output(result, true);
+    }
+    else if (result.command === "plugin.list" && result.plugins) {
+        for (const plugin of result.plugins) {
+            const state = plugin.available ? "available" : plugin.installed ? plugin.entitlement : "not installed";
+            console.log(`${plugin.name}: ${state}`);
+        }
+        printProOverview(Boolean(result.bundle));
+    }
+    else {
+        const version = result.bundle?.version ? ` ${result.bundle.version}` : "";
+        let showOverview = false;
+        switch (result.result) {
+            case "installed":
+                console.log(`AgentMemory Pro${version} installed.`);
+                showOverview = true;
+                break;
+            case "upgraded":
+                console.log(`AgentMemory Pro upgraded to${version}.`);
+                showOverview = true;
+                break;
+            case "current":
+                console.log(result.bundle
+                    ? `AgentMemory Pro${version} is installed and ready.`
+                    : "AgentMemory Pro is not installed.");
+                showOverview = Boolean(result.bundle);
+                break;
+            case "update_available":
+                console.log(`AgentMemory Pro${version} has an update available.`);
+                break;
+            case "uninstalled":
+                console.log("AgentMemory Pro executable components were removed. Memory and billing state were preserved.");
+                break;
+            case "not_installed":
+                console.log("AgentMemory Pro is not installed.");
+                console.log("Run: agent-memory plugin install");
+                break;
+            case "auth_required":
+                console.log("Run this command in an interactive terminal to enter an email and activate temporary access.");
+                break;
+            case "renewal_required":
+                console.log("Renew AgentMemory Pro to continue using paid capabilities.");
+                break;
+            default:
+                console.log(result.error?.message ?? "AgentMemory Pro is currently unavailable.");
+        }
+        if (showOverview)
+            printProOverview(true);
+    }
+    if (result.nextAction) {
+        if (allowBrowser && openExternalUrl(result.nextAction.url)) {
+            if (!json)
+                console.log("Opened the AgentMemory account website.");
+        }
+        else if (!json) {
+            console.log(`Open: ${result.nextAction.url}`);
+        }
+        if (!json && result.nextAction.userCode)
+            console.log(`Code: ${result.nextAction.userCode}`);
+    }
+    if (!result.ok)
+        process.exitCode = 1;
+}
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
 async function cmdContext(flags) {
     const json = hasFlag(flags, "json");
     const noSearch = hasFlag(flags, "no-search");
+    const query = getFlag(flags, "query") ?? "";
     ensureDirs();
-    const searchResults = noSearch ? "" : await searchRelevantMemories("");
+    if (!noSearch && query)
+        await ensureQmdAvailableForSync();
+    const searchResults = noSearch ? "" : await searchRelevantMemories(query);
     const context = buildMemoryContext(searchResults);
     if (json) {
         output({ context, directory: getMemoryDir() }, true);
@@ -102,68 +231,28 @@ async function cmdWrite(flags) {
     const mode = getFlag(flags, "mode") ?? "append";
     const topic = getFlag(flags, "topic");
     const date = getFlag(flags, "date");
+    const sourceUri = getFlag(flags, "source-uri");
     if (!["long_term", "daily", "topic"].includes(target)) {
         exitError("--target must be 'long_term', 'daily', or 'topic' (default: daily)", json);
     }
+    if (!["append", "overwrite"].includes(mode)) {
+        exitError("--mode must be 'append' or 'overwrite'", json);
+    }
     if (!content) {
         exitError("--content is required", json);
     }
-    ensureDirs();
-    const ts = nowTimestamp();
-    const sid = "cli";
-    if (target === "daily") {
-        const filePath = dailyPath(todayStr());
-        const existing = readFileSafe(filePath) ?? "";
-        const separator = existing.trim() ? "\n\n" : "";
-        const stamped = `<!-- ${ts} [${sid}] -->\n${content}`;
-        fs.writeFileSync(filePath, existing + separator + stamped, "utf-8");
-        await ensureQmdAvailableForUpdate();
-        scheduleQmdUpdate();
-        output(json
-            ? { ok: true, path: filePath, target, mode: "append", timestamp: ts }
-            : `Appended to daily log: ${filePath}`, json);
-        return;
-    }
-    if (target === "topic") {
-        if (!topic) {
-            exitError("--topic is required when --target is 'topic'", json);
-        }
-        const slug = slugifyTopic(topic);
-        if (!slug) {
-            exitError("--topic must include at least one letter or number", json);
-        }
-        const filePath = topicPath(slug);
-        const existing = readFileSafe(filePath) ?? "";
-        const linkDate = date?.trim() || todayStr();
-        const header = `# Topic: ${topic}\n\n<!-- created: ${ts} [${sid}] -->\n`;
-        const separator = existing.trim() ? "\n\n" : "";
-        const base = existing.trim() ? existing : header.trimEnd();
-        const stamped = `<!-- ${ts} [${sid}] -->\n${content.trim()}\nDaily: [[${linkDate}]]`;
-        fs.writeFileSync(filePath, `${base}${separator}${stamped}`, "utf-8");
-        await ensureQmdAvailableForUpdate();
-        scheduleQmdUpdate();
-        output(json
-            ? { ok: true, path: filePath, target, mode: "append", timestamp: ts, topic, slug, date: linkDate }
-            : `Appended to topic: ${filePath}`, json);
-        return;
-    }
-    // long_term
-    const memFile = getMemoryFile();
-    const existing = readFileSafe(memFile) ?? "";
-    if (mode === "overwrite") {
-        const stamped = `<!-- last updated: ${ts} [${sid}] -->\n${content}`;
-        fs.writeFileSync(memFile, stamped, "utf-8");
-    }
-    else {
-        const separator = existing.trim() ? "\n\n" : "";
-        const stamped = `<!-- ${ts} [${sid}] -->\n${content}`;
-        fs.writeFileSync(memFile, existing + separator + stamped, "utf-8");
-    }
-    await ensureQmdAvailableForUpdate();
-    scheduleQmdUpdate();
-    output(json
-        ? { ok: true, path: memFile, target, mode, timestamp: ts }
-        : `${mode === "overwrite" ? "Overwrote" : "Appended to"} MEMORY.md`, json);
+    const result = await memoryWrite({
+        target: target,
+        content,
+        mode: mode,
+        sessionId: "cli",
+        topic,
+        date,
+        sourceUri,
+    });
+    if (result.isError)
+        exitError(result.text.replace(/^Error:\s*/, ""), json);
+    output(json ? { ok: true, ...result.details } : result.text.split("\n\n", 1)[0], json);
 }
 async function cmdRead(flags) {
     const json = hasFlag(flags, "json");
@@ -270,7 +359,11 @@ async function cmdScratchpad(flags, positional) {
     ensureDirs();
     const spFile = getScratchpadFile();
     const existing = readFileSafe(spFile) ?? "";
-    let items = parseScratchpad(existing);
+    let items = parseScratchpad(existing).map((item) => ({
+        ...item,
+        text: redactSecrets(item.text).content,
+        meta: redactSecrets(item.meta).content,
+    }));
     if (action === "list") {
         if (items.length === 0) {
             output(json ? { items: [], count: 0, open: 0 } : "Scratchpad is empty.", json);
@@ -292,11 +385,12 @@ async function cmdScratchpad(flags, positional) {
         if (!text)
             exitError("--text is required for add", json);
         const ts = nowTimestamp();
-        items.push({ done: false, text: text, meta: `<!-- ${ts} [cli] -->` });
+        const safeText = redactSecrets(text).content;
+        items.push({ done: false, text: safeText, meta: `<!-- ${ts} [cli] -->` });
         fs.writeFileSync(spFile, serializeScratchpad(items), "utf-8");
         await ensureQmdAvailableForUpdate();
         scheduleQmdUpdate();
-        output(json ? { ok: true, action, text } : `Added: - [ ] ${text}`, json);
+        output(json ? { ok: true, action, text: safeText } : `Added: - [ ] ${safeText}`, json);
         return;
     }
     if (action === "done" || action === "undo") {
@@ -446,6 +540,84 @@ function cmdInstallSkills(flags) {
         }
     }
 }
+async function promptYesNo(question, defaultYes) {
+    const readline = await import("node:readline/promises");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = (await rl.question(`${question} ${defaultYes ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
+        if (!answer)
+            return defaultYes;
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+async function cmdInstallHooks(flags) {
+    const json = hasFlag(flags, "json");
+    const requested = getFlag(flags, "only");
+    const requestedKeys = requested ? new Set(requested.split(",").map((value) => value.trim())) : null;
+    const { homeDir, targets } = detectHookAgents();
+    if (!homeDir)
+        exitError("Home directory not found.", json);
+    const eligible = targets.filter((target) => target.supported && target.detected && (!requestedKeys || requestedKeys.has(target.key)));
+    const selected = new Set();
+    const applyAll = hasFlag(flags, "yes") || hasFlag(flags, "all") || !process.stdin.isTTY;
+    for (const target of eligible) {
+        if (applyAll || (await promptYesNo(`Install SessionStart hook for ${target.label}?`, true)))
+            selected.add(target.key);
+    }
+    const report = installHooks(selected);
+    if (!report.ok)
+        exitError(report.error ?? "install failed", json);
+    if (json)
+        return output(report, true);
+    if (!report.results.length)
+        return output("No eligible agents. Nothing to install.", false);
+    for (const result of report.results) {
+        console.log(result.installed
+            ? `Installed ${result.label} hook: ${result.path}`
+            : `Skipped ${result.label} (${result.reason ?? "unknown"})`);
+    }
+}
+function cmdUninstallHooks(flags) {
+    const json = hasFlag(flags, "json");
+    const only = getFlag(flags, "only");
+    const agents = only ? new Set(only.split(",").map((value) => value.trim())) : undefined;
+    const report = uninstallHooks(agents);
+    if (!report.ok)
+        exitError(report.error ?? "uninstall failed", json);
+    if (json) {
+        output(report, true);
+        return;
+    }
+    for (const result of report.results) {
+        console.log(result.installed
+            ? `Uninstalled ${result.label}: ${result.path}`
+            : `Skipped ${result.label} (${result.reason ?? "unknown"})`);
+    }
+}
+function cmdCompletion(flags, positional) {
+    const requestedShell = positional[0];
+    const shells = ["bash", "zsh", "fish", "powershell"];
+    if (requestedShell && !shells.includes(requestedShell))
+        exitError(`Unsupported shell '${requestedShell}'. Choose bash, zsh, fish, or powershell.`, hasFlag(flags, "json"));
+    const shell = requestedShell ?? detectCompletionShell();
+    if (!shell)
+        exitError("Could not detect your shell. Specify bash, zsh, fish, or powershell.", hasFlag(flags, "json"));
+    if (hasFlag(flags, "stdout")) {
+        process.stdout.write(generateCompletion(shell));
+        return;
+    }
+    const result = installCompletion(shell);
+    if (hasFlag(flags, "json")) {
+        output(result, true);
+        return;
+    }
+    console.log(`Installed ${shell} completion: ${result.completionPath}`);
+    if (result.profilePath)
+        console.log(`${result.profileUpdated ? "Configured" : "Already configured"}: ${result.profilePath}`);
+}
 async function cmdSync(flags) {
     const json = hasFlag(flags, "json");
     ensureDirs();
@@ -532,6 +704,19 @@ async function cmdInit(flags) {
             console.log(`  qmd not found — search features unavailable.`);
             console.log(`  Install: bun install -g https://github.com/tobi/qmd`);
         }
+        if (process.stdout.isTTY) {
+            try {
+                const plugin = await createDefaultPluginBootstrap(VERSION).list();
+                if (plugin.result === "not_installed") {
+                    console.log("");
+                    console.log("Optional: AgentMemory Pro adds session recall and a local Web Console.");
+                    console.log("Run: agent-memory plugin install");
+                }
+            }
+            catch {
+                // Commercial discovery must never make core initialization fail.
+            }
+        }
     }
 }
 async function cmdStatus(flags) {
@@ -561,14 +746,37 @@ async function cmdStatus(flags) {
     const qmdFound = await detectQmd();
     let hasCollection = false;
     let health = null;
+    let embeddings = "n/a";
     if (qmdFound) {
         hasCollection = await checkCollection();
         if (hasCollection) {
             await ensureQmdAvailableForSync();
             health = await getQmdHealth();
+            // A live semantic probe confirms embeddings are actually usable, but
+            // it costs a real qmd query (and a possible model load), so it's
+            // opt-in — the cheap pending-embed count below covers the common case.
+            if (hasFlag(flags, "probe")) {
+                embeddings = await probeEmbeddings();
+            }
         }
     }
     const embedMode = getQmdEmbedMode();
+    let officialPlugin = {
+        installed: false,
+        result: "unavailable",
+        entitlement: "missing",
+    };
+    try {
+        const plugin = await createDefaultPluginBootstrap(VERSION).status();
+        officialPlugin = {
+            installed: Boolean(plugin.bundle),
+            result: plugin.result,
+            entitlement: plugin.entitlement.state,
+        };
+    }
+    catch {
+        // Commercial status must never make core status fail.
+    }
     if (json) {
         output({
             directory: dir,
@@ -588,8 +796,10 @@ async function cmdStatus(flags) {
                 available: qmdFound,
                 collection: hasCollection ? getCollectionName() : null,
                 health,
+                embeddings,
             },
             embedMode,
+            officialPlugin,
         }, true);
     }
     else {
@@ -617,6 +827,14 @@ async function cmdStatus(flags) {
             console.log(`qmd: available`);
             console.log(`Collection '${getCollectionName()}': ${hasCollection ? "configured" : "not configured — run: agent-memory init"}`);
             console.log(`Embed mode: ${embedMode}`);
+            if (hasCollection && embeddings !== "n/a") {
+                const embLabel = embeddings === "ready"
+                    ? "ready"
+                    : embeddings === "missing"
+                        ? "missing — run: agent-memory sync"
+                        : "unknown (could not verify within probe timeout)";
+                console.log(`Embeddings (semantic/deep search): ${embLabel}`);
+            }
             if (health) {
                 if (health.totalFiles !== null)
                     console.log(`Files indexed: ${health.totalFiles}`);
@@ -633,6 +851,11 @@ async function cmdStatus(flags) {
         else {
             console.log("qmd: not installed");
         }
+        if (!officialPlugin.installed) {
+            console.log("");
+            console.log("Optional official plugins: not installed");
+            console.log("  run: agent-memory plugin install");
+        }
     }
 }
 async function cmdDistil(flags) {
@@ -658,6 +881,100 @@ async function cmdDistil(flags) {
         }
     }
 }
+function printPluginUsage() {
+    console.log(`agent-memory plugin — optional official plugins
+
+Usage:
+  agent-memory plugin [list]
+  agent-memory plugin status
+  agent-memory plugin install [--channel stable] [--no-browser]
+  agent-memory plugin update [--channel stable]
+  agent-memory plugin uninstall --yes
+  agent-memory plugin manage [--no-browser]
+
+The public core remains fully usable without AgentMemory Pro. Interactive install
+opens a loopback website for temporary email activation and unlimited local use.
+Authentication and payment will be added later.`);
+}
+function pluginCommandFailure(command, error) {
+    return {
+        schemaVersion: 1,
+        command: `plugin.${command}`,
+        ok: false,
+        result: "unavailable",
+        bundle: null,
+        entitlement: {
+            plan: null,
+            state: "missing",
+            features: [],
+            capabilities: {},
+        },
+        nextAction: null,
+        error: {
+            code: error instanceof PluginBootstrapFailure ? error.code : "plugin_command_failed",
+            message: error instanceof Error ? error.message : String(error),
+            ...(error instanceof PluginBootstrapFailure && error.retryable ? { retryable: true } : {}),
+        },
+    };
+}
+async function cmdPlugin(flags, positional) {
+    const json = hasFlag(flags, "json");
+    const subcommand = positional[0] ?? "list";
+    if (subcommand === "help" || hasFlag(flags, "help")) {
+        printPluginUsage();
+        return;
+    }
+    const channel = getFlag(flags, "channel") ?? "stable";
+    if (channel !== "stable") {
+        printPluginResult(pluginCommandFailure(subcommand, new PluginBootstrapFailure("channel_invalid", "--channel supports only 'stable'")), json, false);
+        return;
+    }
+    const allowBrowser = !json && !hasFlag(flags, "no-browser") && Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const manager = createDefaultPluginBootstrap(VERSION);
+    let result;
+    try {
+        switch (subcommand) {
+            case "list":
+                result = await manager.list();
+                break;
+            case "status":
+                result = await manager.status(channel);
+                break;
+            case "install":
+                result = await manager.install({ channel, allowAuthentication: allowBrowser });
+                break;
+            case "update":
+                result = await manager.update({ channel, allowAuthentication: false });
+                break;
+            case "uninstall":
+                if (!hasFlag(flags, "yes")) {
+                    const status = await manager.status(channel);
+                    result = {
+                        ...status,
+                        command: "plugin.uninstall",
+                        ok: false,
+                        result: "unavailable",
+                        error: {
+                            code: "confirmation_required",
+                            message: "Re-run with --yes to remove AgentMemory Pro executable components",
+                        },
+                    };
+                    break;
+                }
+                result = await manager.uninstall();
+                break;
+            case "manage":
+                result = await manager.manage();
+                break;
+            default:
+                result = pluginCommandFailure(subcommand, new PluginBootstrapFailure("unknown_plugin_command", `Unknown plugin command: ${subcommand}. Available bootstrap commands: list, status, install, update, uninstall, manage.`));
+        }
+    }
+    catch (error) {
+        result = pluginCommandFailure(subcommand, error);
+    }
+    printPluginResult(result, json, allowBrowser && (subcommand === "install" || subcommand === "manage"));
+}
 // ---------------------------------------------------------------------------
 // Usage
 // ---------------------------------------------------------------------------
@@ -671,15 +988,19 @@ Commands:
   version     Show binary version
   install-skills  Install (or --uninstall) bundled skills
   uninstall-skills  Uninstall bundled skills
-  context     Build & print context injection string
-  write       Write to memory files (default: daily)
+  context     Build context; optionally retrieve memories with --query
+  write       Write to memory files (default: daily; optional --source-uri)
   read        Read memory files
   scratchpad  Manage checklist items
   search      Search across memory files (requires qmd)
   distil      Generate compact MEMORY.md index from daily logs + topics
   sync        Re-index and embed all files (requires qmd)
   init        Initialize memory directory and qmd collection
-  status      Show configuration and status
+  status      Show configuration and status (--probe for a live embeddings check)
+  completion  Install or print shell completion
+  install-hooks  Install managed SessionStart hooks
+  uninstall-hooks  Remove only managed SessionStart hooks
+  plugin      Discover, install, update, or remove optional official plugins
 
 Global flags:
   --dir <path>   Override memory directory
@@ -688,7 +1009,7 @@ Global flags:
 Examples:
   agent-memory init
   agent-memory write --content "Fixed auth bug in login flow"
-  agent-memory write --target long_term --content "User prefers dark mode"
+  agent-memory write --target long_term --content "User prefers dark mode" --source-uri "session://agent/turn/12"
   agent-memory write --target topic --topic "auth" --content "Rolled JWT refresh to edge"
   agent-memory read --target long_term
   agent-memory read --target daily --date 2026-02-15
@@ -700,9 +1021,13 @@ Examples:
   agent-memory scratchpad done --text "PR #42"
   agent-memory search --query "database choice" --mode keyword
   agent-memory distil --dry-run
-  agent-memory context --no-search
+  agent-memory context --query "database choice"
   agent-memory sync
-  agent-memory status --json`);
+  agent-memory status --json
+  agent-memory completion zsh
+  agent-memory install-hooks --yes
+  agent-memory plugin status
+  agent-memory plugin install`);
 }
 // ---------------------------------------------------------------------------
 // Main
@@ -719,7 +1044,7 @@ async function main() {
         output(json ? { version: VERSION } : VERSION, json);
         return;
     }
-    if (!command || command === "help" || hasFlag(flags, "help")) {
+    if (!command || command === "help" || (hasFlag(flags, "help") && command !== "plugin")) {
         printUsage();
         return;
     }
@@ -758,8 +1083,47 @@ async function main() {
         case "status":
             await cmdStatus(flags);
             break;
-        default:
-            exitError(`Unknown command: ${command}. Run 'agent-memory help' for usage.`, json);
+        case "completion":
+            cmdCompletion(flags, positional);
+            break;
+        case "install-hooks":
+            await cmdInstallHooks(flags);
+            break;
+        case "uninstall-hooks":
+            cmdUninstallHooks(flags);
+            break;
+        case "hook": {
+            if (positional[0] !== "session-start")
+                exitError("hook requires 'session-start'", json);
+            const agent = getFlag(flags, "agent");
+            if (!agent)
+                exitError("hook session-start requires --agent", json);
+            await cmdContext({ "no-search": true });
+            break;
+        }
+        case "plugin":
+            await cmdPlugin(flags, positional);
+            break;
+        default: {
+            const controller = new AbortController();
+            const abort = () => controller.abort();
+            process.once("SIGINT", abort);
+            try {
+                const result = await new InstalledPluginRuntimeV1({ coreVersion: VERSION }).run(command, {
+                    args: positional,
+                    flags,
+                    signal: controller.signal,
+                });
+                if (!result)
+                    exitError(`Unknown command: ${command}. Run 'agent-memory help' for usage.`, json);
+                if (!result.ok)
+                    exitError(result.error?.message ?? `Plugin command ${command} failed`, json);
+                output(result.data ?? { ok: true }, json);
+            }
+            finally {
+                process.removeListener("SIGINT", abort);
+            }
+        }
     }
 }
 main().catch((err) => {

package/dist/completions.d.ts

@@ -0,0 +1,13 @@
+export type CompletionShell = "bash" | "zsh" | "fish" | "powershell";
+export interface CompletionInstallResult {
+    shell: CompletionShell;
+    completionPath: string;
+    profilePath?: string;
+    profileUpdated: boolean;
+}
+export declare function generateCompletion(shell: CompletionShell): string;
+export declare function detectCompletionShell(environment?: Record<string, string | undefined>, platform?: NodeJS.Platform): CompletionShell | null;
+export declare function installCompletion(shell: CompletionShell, options?: {
+    homeDir?: string;
+    platform?: NodeJS.Platform;
+}): CompletionInstallResult;