myagentmemory 0.5.2 → 0.5.4

package/dist/cli.js

@@ -26,13 +26,13 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { COMMAND_DESCRIPTIONS, COMMAND_OPTIONS, COMMANDS, GLOBAL_OPTIONS, optionTakesValue, PLUGIN_COMMAND_OPTIONS, renderCommandHelp, SCRATCHPAD_ACTION_OPTIONS, } from "./cli-spec.js";
-import { detectCompletionShell, generateCompletion, installCompletion } from "./completions.js";
+import { detectCompletionShell, generateCompletion, installCompletion, uninstallCompletion, } from "./completions.js";
 import { _setBaseDir, buildDynamicContext, buildMemoryContext, buildStableContext, checkCollection, dailyPath, detectQmd, distilMemories, ensureDirs, ensureQmdAvailableForSync, ensureQmdAvailableForUpdate, getCollectionName, getDailyDir, getMemoryDir, getMemoryFile, getQmdEmbedMode, getQmdHealth, getQmdResultPath, getQmdResultText, getScratchpadFile, getTopicsDir, installSkills, memoryWrite, nowTimestamp, parseScratchpad, probeEmbeddings, readFileSafe, readHookMode, redactSecrets, runQmdEmbedDetached, runQmdSearch, runQmdSync, runQmdUpdateNow, scheduleQmdUpdate, scratchpadAction, searchRelevantMemories, serializeScratchpad, setupQmdCollection, slugifyTopic, todayStr, topicPath, uninstallSkills, } from "./core.js";
-import { detectHookAgents, installHooks, isHookInstalled, isStopHookInstalled, isUserPromptSubmitInstalled, uninstallHooks, } from "./hooks.js";
+import { detectHookAgents, getPiMemoryState, installHooks, isHookInstalled, isStopHookInstalled, isUserPromptSubmitInstalled, uninstallHooks, } from "./hooks.js";
 import { StdioMcpServer } from "./mcp-server.js";
-import { createDefaultPluginBootstrap, PluginBootstrapFailure, } from "./plugin-bootstrap.js";
+import { createDefaultPluginBootstrap, getDefaultPluginInstallRoot, PluginBootstrapFailure, } from "./plugin-bootstrap.js";
 import { InstalledPluginRuntimeV1 } from "./plugin-runtime.js";
-import { checkForUpgrades, detectInstallMethod, formatUpgradeNotice, isCacheFresh, readUpgradeCache, refreshUpgradeCacheBackground, runInstaller, } from "./upgrade.js";
+import { checkForUpgrades, detectInstallMethod, formatUpgradeNotice, isCacheFresh, readUpgradeCache, readUpgradePolicy, refreshUpgradeCacheBackground, runInstaller, writeUpgradeCache, writeUpgradePolicy, } from "./upgrade.js";
 function readPackageVersion() {
     try {
         const packageJson = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
@@ -124,10 +124,6 @@ function levenshtein(a, b) {
     }
     return prev[b.length];
 }
-// ---------------------------------------------------------------------------
-// Pro plan / cap-exhausted UX
-// ---------------------------------------------------------------------------
-const UPGRADE_URL = "https://agentmemory.paperpilot.me/upgrade";
 function detectCapExhausted(result) {
     if (result.ok !== false)
         return null;
@@ -194,13 +190,11 @@ function printCapExhaustedBox(command, info) {
         "─────────────────────────────────────────────────────────────",
         usedLine,
         "",
-        "  Upgrade for unlimited recall + automatic capture:",
-        `    ${UPGRADE_URL}`,
+        "  Paid plans are not available yet. Try again after the free-preview allowance resets.",
         "─────────────────────────────────────────────────────────────",
         "",
     ];
     console.error(lines.join("\n"));
-    openExternalUrl(UPGRADE_URL);
 }
 // Persist the last usage decision to disk so `pro status` can show counters.
 function cacheProUsage(decision) {
@@ -394,9 +388,9 @@ function printProOverview(installed) {
     console.log("Core remembers what you save. Pro learns from what you do.");
     console.log("");
     console.log("AgentMemory Pro:");
-    console.log('  Remember past sessions      Ask "what did we decide about auth?" across Claude Code, Codex, and Cursor.');
+    console.log('  Remember past sessions      Ask "what did we decide about auth?" across Claude Code, Codex, and Pi history.');
     console.log("  Learn from your patterns    Turn repeated corrections into memory you can inspect and undo.");
-    console.log("  Private by default          Memory and session content index locally and never leave this machine.");
+    console.log("  Private by default          AgentMemory services never receive memory or session content.");
     console.log("");
     if (installed) {
         printProUsageCounters();
@@ -443,7 +437,7 @@ function printPluginResult(result, json, allowBrowser) {
                 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.");
+                console.log("AgentMemory Pro executable components were removed. Memory and local activation state were preserved.");
                 break;
             case "not_installed":
                 console.log("AgentMemory Pro is not installed.");
@@ -674,10 +668,15 @@ const STOP_NAG_REASON = "Before stopping: if this session produced a durable fac
     "ignore this and stop normally.";
 /**
  * Stop hook handler — fires at the end of every assistant turn (not once per
- * session). Blocks at most once every STOP_NAG_INTERVAL turns per session_id
- * to nudge a memory-write check without being disruptive. Always allows the
- * stop (empty stdout) on missing session_id, `stop_hook_active` (Claude Code's
- * own re-entrancy signal — never block twice in a row), or any internal error.
+ * session). Continues the conversation at most once every STOP_NAG_INTERVAL
+ * turns per session_id to nudge a memory-write check without being
+ * disruptive. Uses `hookSpecificOutput.additionalContext` rather than
+ * `decision: "block"` — functionally identical (both go through the same
+ * `stop_hook_active` re-entry check and Claude Code's loop-protection cap),
+ * but additionalContext renders as "Stop hook feedback" in the transcript
+ * instead of the alarming-looking "Stop hook error". Always allows the stop
+ * (empty stdout) on missing session_id, `stop_hook_active` (Claude Code's own
+ * re-entrancy signal — never nag twice in a row), or any internal error.
  */
 async function cmdStop(_flags) {
     const TIMEOUT_MS = 3_000;
@@ -695,7 +694,9 @@ async function cmdStop(_flags) {
         if (!sessionId || payload?.stop_hook_active === true)
             return;
         if (shouldNagOnStop(sessionId, Date.now())) {
-            process.stdout.write(JSON.stringify({ decision: "block", reason: STOP_NAG_REASON }));
+            process.stdout.write(JSON.stringify({
+                hookSpecificOutput: { hookEventName: "Stop", additionalContext: STOP_NAG_REASON },
+            }));
         }
     })().catch(() => {
         // Any failure in the Stop hook must be swallowed — never trap the user
@@ -1070,6 +1071,11 @@ 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;
+    // Internal-only signal from cmdSetup: pi's action is a real network package
+    // install (`pi install npm:pi-memory`), not a local config-file edit like
+    // every other agent here — so setup's internally-manufactured `yes: true`
+    // must not cover it. Not a public flag; never documented in cli-spec.
+    const deferPi = hasFlag(flags, "_setup-defer-pi");
     const modeFlag = getFlag(flags, "mode");
     if (modeFlag !== undefined && modeFlag !== "stable" && modeFlag !== "per-turn") {
         exitError(`--mode must be 'stable' or 'per-turn' (got ${modeFlag})`, json);
@@ -1078,11 +1084,19 @@ async function cmdInstallHooks(flags) {
     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 eligible = targets.filter((target) => {
+        if (!(target.supported && target.detected))
+            return false;
+        if (requestedKeys && !requestedKeys.has(target.key))
+            return false;
+        if (target.key === "pi" && deferPi)
+            return false;
+        return true;
+    });
     if (!eligible.length) {
-        if (json)
-            return output({ ok: true, homeDir, results: [] }, true);
-        return output("No eligible agents. Nothing to install.", false);
+        const report = { ok: true, homeDir, results: [] };
+        output(json ? report : "No eligible agents. Nothing to install.", json);
+        return report;
     }
     // Consider an agent "already installed" only when the wiring matches the requested mode.
     // per-turn requires BOTH SessionStart and UserPromptSubmit; stable requires SessionStart AND
@@ -1112,43 +1126,50 @@ async function cmdInstallHooks(flags) {
         console.log(`Automatic context already active for: ${labels}.`);
     }
     if (!pending.length) {
-        if (json) {
-            return output({
-                ok: true,
-                homeDir,
-                results: alreadyInstalled.map((target) => ({
-                    key: target.key,
-                    label: target.label,
-                    installed: false,
-                    reason: "already installed",
-                    mode,
-                })),
-            }, true);
-        }
-        return output("Nothing to install.", false);
+        const report = {
+            ok: true,
+            homeDir,
+            results: alreadyInstalled.map((target) => ({
+                key: target.key,
+                label: target.label,
+                installed: false,
+                reason: "already installed",
+                mode,
+            })),
+        };
+        output(json ? report : "Nothing to install.", json);
+        return report;
     }
     const selected = new Set();
     const applyAll = hasFlag(flags, "yes") || hasFlag(flags, "all") || !process.stdin.isTTY;
     const hookLabel = mode === "per-turn" ? "SessionStart + UserPromptSubmit hooks" : "SessionStart hook";
     for (const target of pending) {
-        if (applyAll || (await promptYesNo(`Install ${hookLabel} for ${target.label}?`, true)))
+        // pi gets a real package install (`pi install npm:pi-memory`), not a config-file hook edit —
+        // word the prompt accordingly so the confirmation matches what actually happens.
+        const question = target.key === "pi"
+            ? `Install pi-memory (native pi extension) for ${target.label}?`
+            : `Install ${hookLabel} for ${target.label}?`;
+        if (applyAll || (await promptYesNo(question, true)))
             selected.add(target.key);
     }
     if (!selected.size) {
-        if (json)
-            return output({ ok: true, homeDir, results: [] }, true);
-        return output("Nothing selected. Skipped.", false);
+        const report = { ok: true, homeDir, results: [] };
+        output(json ? report : "Nothing selected. Skipped.", json);
+        return report;
     }
     const report = installHooks(selected, mode);
     if (!report.ok)
         exitError(report.error ?? "install failed", json);
-    if (json)
-        return output(report, true);
+    if (json) {
+        output(report, true);
+        return report;
+    }
     for (const result of report.results) {
         console.log(result.installed
             ? `Installed ${result.label} hook (${result.mode ?? mode}): ${result.path}`
             : `Skipped ${result.label} (${result.reason ?? "unknown"})`);
     }
+    return report;
 }
 function cmdUninstallHooks(flags) {
     const json = hasFlag(flags, "json");
@@ -1434,15 +1455,14 @@ async function cmdSetup(flags) {
     const steps = [];
     const runQuiet = async (fn) => {
         if (!json) {
-            await fn();
-            return;
+            return await fn();
         }
         const originalLog = console.log;
         const originalInfo = console.info;
         console.log = () => { };
         console.info = () => { };
         try {
-            await fn();
+            return await fn();
         }
         finally {
             console.log = originalLog;
@@ -1473,8 +1493,31 @@ async function cmdSetup(flags) {
     // Step 3: hooks (uses the improved preflight — silent when all already installed)
     if (!skipHooks) {
         try {
-            await runQuiet(() => cmdInstallHooks(subFlags));
-            steps.push({ name: "hooks", ok: true });
+            const userSuppliedYes = hasFlag(flags, "yes");
+            // pi's install is a real network package fetch (`pi install npm:pi-memory`),
+            // unlike every other agent here (local config-file edits) — setup's
+            // manufactured `yes: true` above must not silently cover that unless the
+            // user actually asked for --yes themselves.
+            const { homeDir: detectedHomeDir, targets: detectedTargets } = detectHookAgents();
+            const piTarget = detectedTargets.find((target) => target.key === "pi");
+            const piDetected = Boolean(piTarget?.supported && piTarget?.detected);
+            const piAlreadyActive = piDetected && detectedHomeDir ? isHookInstalled(detectedHomeDir, "pi") : false;
+            const hooksFlags = userSuppliedYes ? subFlags : { ...subFlags, "_setup-defer-pi": true };
+            const report = await runQuiet(() => cmdInstallHooks(hooksFlags));
+            const piFailure = report?.results.find((result) => result.key === "pi" && !result.installed && result.reason && result.reason !== "already installed");
+            if (piFailure) {
+                steps.push({ name: "hooks", ok: false, detail: `pi-memory install failed: ${piFailure.reason}` });
+            }
+            else if (piDetected && !piAlreadyActive && !userSuppliedYes) {
+                steps.push({
+                    name: "hooks",
+                    ok: true,
+                    detail: "pi-memory deferred — re-run with --yes, or agent-memory install-hooks --only pi",
+                });
+            }
+            else {
+                steps.push({ name: "hooks", ok: true });
+            }
         }
         catch (error) {
             steps.push({ name: "hooks", ok: false, detail: error.message });
@@ -1656,7 +1699,7 @@ async function cmdSetup(flags) {
         console.log(colorize("The local plugin is live. Feel the magic now:", "green"));
         console.log(`  ${colorize('agent-memory recall "what did we decide about auth?"', "cyan")}   — search past sessions`);
         console.log(`  ${colorize("agent-memory learn", "cyan")}                                    — surface repeated corrections`);
-        console.log(`  ${colorize("agent-memory worker start", "cyan")}                             — capture new sessions in real time`);
+        console.log(`  ${colorize("agent-memory index", "cyan")}                                    — refresh the supported local session index`);
         console.log(`  ${colorize("agent-memory dashboard", "cyan")}                                — private local dashboard`);
     }
     else if (skipPlugin) {
@@ -1665,6 +1708,138 @@ async function cmdSetup(flags) {
     }
     console.log("");
 }
+/**
+ * Reverse of {@link cmdSetup}: removes every install artifact agent-memory
+ * creates outside of this package — hooks, skills, MCP registrations, shell
+ * completions, and the Pro plugin executables. Memory data under
+ * `getMemoryDir()` (MEMORY.md, daily logs, scratchpad, topics, qmd index) is
+ * left untouched unless `--data` is passed, since that's the one step a user
+ * can't undo. Destructive by nature, so it always requires either an
+ * interactive confirmation or `--yes`.
+ */
+async function cmdUninstall(flags) {
+    const json = hasFlag(flags, "json");
+    const yes = hasFlag(flags, "yes");
+    const wipeData = hasFlag(flags, "data");
+    const interactive = !json && Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    if (!yes) {
+        const message = wipeData
+            ? "Re-run with --yes to remove agent-memory's hooks, skills, MCP registrations, completions, and Pro plugin, and permanently delete ~/.agent-memory (MEMORY.md, daily logs, scratchpad, topics, qmd index)."
+            : "Re-run with --yes to remove agent-memory's hooks, skills, MCP registrations, completions, and Pro plugin. Your memory data is left untouched.";
+        if (interactive) {
+            const question = wipeData
+                ? "This will also permanently delete your memory data (MEMORY.md, daily logs, scratchpad). Continue?"
+                : "Remove agent-memory's hooks, skills, MCP registrations, completions, and Pro plugin?";
+            if (!(await promptYesNo(question, false))) {
+                console.log("Aborted. Nothing was removed.");
+                return;
+            }
+        }
+        else {
+            if (json)
+                output({ ok: false, error: { code: "confirmation_required", message } }, true);
+            else
+                console.error(`Error: ${message}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const steps = [];
+    try {
+        const report = uninstallSkills();
+        if (!report.ok)
+            throw new Error(report.error ?? "failed to remove skills");
+        steps.push({
+            name: "skills",
+            ok: true,
+            detail: report.removed.length ? `removed ${report.removed.length}` : "not installed",
+        });
+    }
+    catch (error) {
+        steps.push({ name: "skills", ok: false, detail: error.message });
+    }
+    try {
+        const report = uninstallHooks();
+        if (!report.ok)
+            throw new Error(report.error ?? "failed to remove hooks");
+        const removed = report.results.filter((r) => r.installed).length;
+        // agent-memory never removes pi-memory itself (see uninstallPiMemoryDelegate) — make that
+        // explicit here rather than letting a generic "removed N" detail imply everything is gone.
+        const piResult = report.results.find((r) => r.key === "pi");
+        const piNote = piResult?.reason?.startsWith("pi-memory left installed") ? `; ${piResult.reason}` : "";
+        steps.push({
+            name: "hooks",
+            ok: true,
+            detail: (removed ? `removed ${removed}` : "not installed") + piNote,
+        });
+    }
+    catch (error) {
+        steps.push({ name: "hooks", ok: false, detail: error.message });
+    }
+    try {
+        const results = unregisterMcpFromAgents(null);
+        const removed = results.filter((r) => r.status === "unregistered").length;
+        steps.push({ name: "mcp", ok: true, detail: removed ? `unregistered ${removed}` : "not registered" });
+    }
+    catch (error) {
+        steps.push({ name: "mcp", ok: false, detail: error.message });
+    }
+    try {
+        const results = uninstallCompletion();
+        const removed = results.filter((r) => r.removed || r.profileUpdated).length;
+        steps.push({ name: "completions", ok: true, detail: removed ? `removed ${removed}` : "not installed" });
+    }
+    catch (error) {
+        steps.push({ name: "completions", ok: false, detail: error.message });
+    }
+    try {
+        const manager = createDefaultPluginBootstrap(VERSION);
+        const pluginResult = await manager.uninstall();
+        steps.push({ name: "plugin", ok: pluginResult.ok, detail: pluginResult.result });
+    }
+    catch (error) {
+        steps.push({ name: "plugin", ok: false, detail: error.message });
+    }
+    if (wipeData) {
+        try {
+            const memoryDir = getMemoryDir();
+            if (fs.existsSync(memoryDir))
+                fs.rmSync(memoryDir, { recursive: true, force: true });
+            const pluginRoot = getDefaultPluginInstallRoot();
+            if (fs.existsSync(pluginRoot))
+                fs.rmSync(pluginRoot, { recursive: true, force: true });
+            steps.push({ name: "data", ok: true, detail: memoryDir });
+        }
+        catch (error) {
+            steps.push({ name: "data", ok: false, detail: error.message });
+        }
+    }
+    const allOk = steps.every((step) => step.ok);
+    if (!allOk)
+        process.exitCode = 1;
+    if (json) {
+        output({ ok: allOk, data: wipeData, steps }, true);
+        return;
+    }
+    console.log("");
+    console.log(colorize("agent-memory uninstall", "bold"));
+    for (const step of steps) {
+        const mark = step.ok ? MARK_OK : MARK_FAIL;
+        const detail = step.detail ? colorize(` ${step.detail}`, "dim") : "";
+        console.log(`  ${mark} ${step.name}${detail}`);
+    }
+    console.log("");
+    if (!allOk) {
+        console.log(colorize("Some steps failed — see details above.", "yellow"));
+    }
+    else if (wipeData) {
+        console.log(colorize("agent-memory has been fully removed, including your memory data.", "green"));
+    }
+    else {
+        console.log(colorize("agent-memory's install artifacts have been removed.", "green"));
+        console.log(colorize(`Your notes are untouched at ${getMemoryDir()}. Re-run with --data to remove them too.`, "dim"));
+    }
+}
 /**
  * Explain the optional plugin without making a successful core setup feel
  * incomplete. Keep the quota line here in sync with `freeEntitlement()`.
@@ -1678,10 +1853,10 @@ function printProPitch(mode) {
     else {
         console.log(`${colorize("Optional: AgentMemory Pro", "bold")} — ${colorize("memory that learns from your work", "dim")}`);
     }
-    console.log(`  ${colorize("Recall across sessions", "cyan")}   Ask "what did we decide about auth?" across Claude, Codex, Cursor.`);
+    console.log(`  ${colorize("Recall across sessions", "cyan")}   Ask "what did we decide about auth?" across Claude Code, Codex, and Pi history.`);
     console.log(`  ${colorize("Learn from corrections", "cyan")}   Turn repeated fixes into memory you can inspect and undo.`);
-    console.log(`  ${colorize("Real-time capture", "cyan")}        Local worker indexes new sessions as they happen.`);
-    console.log(`  ${colorize("Private by default", "cyan")}       Memory and session content stay on this device — no account required.`);
+    console.log(`  ${colorize("Local session index", "cyan")}      Scan supported session history without uploading it to AgentMemory.`);
+    console.log(`  ${colorize("Private by default", "cyan")}       AgentMemory services never receive memory or session content.`);
     console.log(`  ${colorize("Included at no cost:", "green")} ${colorize("20 recalls + 5 learning scans per day", "bold")}. Local indexing and dashboard remain free.`);
     console.log("");
 }
@@ -1900,6 +2075,14 @@ async function cmdDoctor(flags) {
             });
         }
     }
+    // Auto-upgrade policy
+    const upgradePolicy = readUpgradePolicy();
+    rows.push({
+        status: "ok",
+        label: "Auto-upgrade",
+        detail: `CLI: ${upgradePolicy.cli}, Pro: ${upgradePolicy.plugin}`,
+        fix: upgradePolicy.cli === "off" && upgradePolicy.plugin === "off" ? "agent-memory upgrade policy auto" : undefined,
+    });
     // Skills + hooks per detected host
     const { homeDir, targets } = detectHookAgents();
     const detected = targets.filter((target) => target.detected);
@@ -1915,7 +2098,7 @@ async function cmdDoctor(flags) {
         rows.push({
             status: "warn",
             label: "Agent hosts",
-            detail: "no supported agents detected (Claude Code, Codex, Cursor, opencode)",
+            detail: "no supported agents detected (Claude Code, Codex, Cursor, opencode, pi)",
             fix: "install one of the agents first, then: agent-memory install-skills",
         });
     }
@@ -1927,7 +2110,35 @@ async function cmdDoctor(flags) {
         });
         for (const target of detected) {
             if (!target.supported) {
-                // Skip skill/hook rows for hosts we don't yet integrate with (e.g. pi has its own extension).
+                // Skip skill/hook rows for hosts we don't yet integrate with.
+                continue;
+            }
+            if (target.key === "pi") {
+                // pi has no SKILL.md — agent-memory delegates entirely to the pi-memory
+                // extension, installed via `pi install npm:pi-memory` rather than a
+                // config-file edit, so it gets its own row instead of the generic
+                // Skill:/Hook: pair below.
+                const installed = homeDir ? isHookInstalled(homeDir, "pi") : false;
+                const state = getPiMemoryState();
+                let detail;
+                if (installed) {
+                    detail = "pi-memory extension active (github.com/jayzeng/pi-memory)";
+                }
+                else if (state && !state.ok) {
+                    detail = `pi-memory not detected — last install attempt (${state.lastAttemptAt}) failed: ${state.detail}`;
+                }
+                else if (state?.ok) {
+                    detail = `pi-memory installed (${state.lastAttemptAt}) but no session has run yet`;
+                }
+                else {
+                    detail = "pi-memory not detected — agent-memory can install it";
+                }
+                rows.push({
+                    status: installed ? "ok" : "warn",
+                    label: "Memory: pi",
+                    detail,
+                    fix: installed ? undefined : "agent-memory install-hooks --only pi",
+                });
                 continue;
             }
             const skillPath = homeDir ? `${target.homeMarker}/skills/agent-memory/SKILL.md` : null;
@@ -2173,9 +2384,10 @@ Usage:
   agent-memory plugin manage [--no-browser]
 
 The public core remains fully usable without AgentMemory Pro. Install uses a random
-installation identifier and requires no account or email. The free tier includes
-20 recalls and 5 learning scans per local day; indexing and the Memory Dashboard
-remain available. Memory and session content stay on this device.`);
+	installation identifier and requires no account or email. The free tier includes
+	20 recalls and 5 learning scans per local day; indexing and the Memory Dashboard
+	remain available. AgentMemory services never receive memory or session content;
+	recall results are subject to the coding agent or model provider you invoke.`);
 }
 function pluginCommandFailure(command, error) {
     return {
@@ -2482,16 +2694,108 @@ async function resolvePluginLatestHint() {
         return { latest: null, updateAvailable: false };
     }
 }
-async function cmdUpgrade(flags) {
+async function cmdUpgradePolicy(flags, positional) {
+    const json = hasFlag(flags, "json");
+    const value = positional[0];
+    if (!value) {
+        const policy = readUpgradePolicy();
+        if (json)
+            output({ cli: policy.cli, plugin: policy.plugin }, true);
+        else
+            console.log(`  cli:    ${policy.cli}\n  plugin: ${policy.plugin}`);
+        return;
+    }
+    if (value !== "off" && value !== "notify" && value !== "auto") {
+        exitError(`Invalid policy '${value}'. Expected one of: off, notify, auto.`, json);
+    }
+    const onlyCli = hasFlag(flags, "cli");
+    const onlyPlugin = hasFlag(flags, "plugin");
+    const patch = {};
+    if (onlyCli || !onlyPlugin)
+        patch.cli = value;
+    if (onlyPlugin || !onlyCli)
+        patch.plugin = value;
+    const next = writeUpgradePolicy(patch);
+    if (json)
+        output(next, true);
+    else
+        console.log(`  cli:    ${next.cli}\n  plugin: ${next.plugin}`);
+}
+/**
+ * `--background`-mode install: only touches a target when its persisted policy
+ * (see `readUpgradePolicy`) is `"auto"`. Always non-interactive — this path is
+ * only ever reached from a detached, non-TTY child spawned by
+ * `refreshUpgradeCacheBackground()`. Failures are recorded, never thrown.
+ */
+async function runAutoUpgrade(status, policy, pluginCurrent, quiet) {
+    const now = new Date().toISOString();
+    let cliAuto;
+    let pluginAuto;
+    if (policy.cli === "auto" && status.cli.upgradeAvailable) {
+        const method = detectInstallMethod();
+        if (!quiet)
+            console.log(`Auto-upgrading CLI via: ${method.command.join(" ")}`);
+        try {
+            const result = runInstaller(method);
+            cliAuto = result.ok
+                ? { at: now, ok: true, version: status.cli.latest }
+                : {
+                    at: now,
+                    ok: false,
+                    version: status.cli.current,
+                    error: (result.stderr || result.stdout || `exit ${result.code}`).trim(),
+                };
+        }
+        catch (error) {
+            cliAuto = {
+                at: now,
+                ok: false,
+                version: status.cli.current,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    if (policy.plugin === "auto" && status.plugin.upgradeAvailable) {
+        if (!quiet)
+            console.log("Auto-upgrading Pro plugin bundle…");
+        try {
+            const pluginResult = await cmdPlugin({ json: true }, ["update"]);
+            const ok = Boolean(pluginResult?.ok);
+            pluginAuto = ok
+                ? { at: now, ok: true, version: status.plugin.latest }
+                : {
+                    at: now,
+                    ok: false,
+                    version: pluginCurrent,
+                    error: pluginResult?.error?.message ?? "plugin update failed",
+                };
+        }
+        catch (error) {
+            pluginAuto = {
+                at: now,
+                ok: false,
+                version: pluginCurrent,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    return { cliAuto, pluginAuto };
+}
+async function cmdUpgrade(flags, positional = []) {
+    if (positional[0] === "policy") {
+        await cmdUpgradePolicy(flags, positional.slice(1));
+        return;
+    }
     const json = hasFlag(flags, "json");
     const quiet = hasFlag(flags, "quiet");
     const checkOnly = hasFlag(flags, "check");
+    const background = hasFlag(flags, "background");
     const refresh = hasFlag(flags, "refresh");
     const onlyCli = hasFlag(flags, "cli");
     const onlyPlugin = hasFlag(flags, "plugin");
     const targetCli = onlyCli || !onlyPlugin;
     const targetPlugin = onlyPlugin || !onlyCli;
-    const applyAll = hasFlag(flags, "yes") || !process.stdin.isTTY || !process.stdout.isTTY;
+    const applyAll = hasFlag(flags, "yes") || background || !process.stdin.isTTY || !process.stdout.isTTY;
     const pluginCurrent = await readPluginCurrentVersion();
     const pluginProbe = targetPlugin ? await resolvePluginLatestHint() : { latest: null, updateAvailable: false };
     const status = await checkForUpgrades({
@@ -2508,6 +2812,30 @@ async function cmdUpgrade(flags) {
             printUpgradeStatus(status, { targetCli, targetPlugin });
         return;
     }
+    if (background) {
+        const policy = readUpgradePolicy();
+        const { cliAuto, pluginAuto } = await runAutoUpgrade(status, policy, pluginCurrent, quiet);
+        writeUpgradeCache({
+            checkedAt: status.checkedAt,
+            cliCurrent: VERSION,
+            cliLatest: status.cli.latest,
+            pluginCurrent,
+            pluginLatest: status.plugin.latest,
+            cliAuto,
+            pluginAuto,
+        });
+        if (json)
+            output({ ...status, cliAuto, pluginAuto }, true);
+        else if (!quiet) {
+            if (cliAuto)
+                console.log(`  ${cliAuto.ok ? MARK_OK : MARK_FAIL} CLI auto-upgrade: ${cliAuto.ok ? `→ ${cliAuto.version}` : cliAuto.error}`);
+            if (pluginAuto)
+                console.log(`  ${pluginAuto.ok ? MARK_OK : MARK_FAIL} Pro auto-upgrade: ${pluginAuto.ok ? `→ ${pluginAuto.version}` : pluginAuto.error}`);
+        }
+        if ((cliAuto && !cliAuto.ok) || (pluginAuto && !pluginAuto.ok))
+            process.exitCode = 1;
+        return;
+    }
     const cliNeedsUpgrade = targetCli && status.cli.upgradeAvailable;
     const pluginNeedsUpgrade = targetPlugin && status.plugin.upgradeAvailable;
     if (!cliNeedsUpgrade && !pluginNeedsUpgrade) {
@@ -2648,6 +2976,64 @@ function registerMcpInAgents(only) {
     }
     return results;
 }
+/**
+ * Reverse of {@link registerMcpInAgents}: removes the `agent-memory` MCP server
+ * entry from every supported local harness. Missing config files are reported
+ * as `not-installed`, files that never had the entry as `not-registered`.
+ */
+function unregisterMcpFromAgents(only) {
+    const home = os.homedir();
+    const want = (key) => !only || only.has(key);
+    const results = [];
+    const unregisterJson = (key, displayName, configFile) => {
+        const p = path.join(home, configFile);
+        if (!fs.existsSync(p)) {
+            results.push({ key, displayName, path: p, status: "not-installed" });
+            return;
+        }
+        let s = {};
+        try {
+            s = JSON.parse(fs.readFileSync(p, "utf8"));
+        }
+        catch { }
+        const servers = (s.mcpServers ?? {});
+        if (!servers["agent-memory"]) {
+            results.push({ key, displayName, path: p, status: "not-registered" });
+            return;
+        }
+        delete servers["agent-memory"];
+        if (Object.keys(servers).length === 0)
+            delete s.mcpServers;
+        else
+            s.mcpServers = servers;
+        fs.writeFileSync(p, `${JSON.stringify(s, null, 2)}\n`);
+        results.push({ key, displayName, path: p, status: "unregistered" });
+    };
+    if (want("claude"))
+        unregisterJson("claude", "Claude Code", ".claude.json");
+    if (want("cursor"))
+        unregisterJson("cursor", "Cursor", ".cursor/mcp.json");
+    if (want("windsurf"))
+        unregisterJson("windsurf", "Windsurf", ".windsurf/mcp_settings.json");
+    if (want("codex")) {
+        const p = path.join(home, ".codex", "config.toml");
+        if (!fs.existsSync(p)) {
+            results.push({ key: "codex", displayName: "Codex", path: p, status: "not-installed" });
+        }
+        else {
+            const existing = fs.readFileSync(p, "utf8");
+            if (!existing.includes("[mcp_servers.agent-memory]")) {
+                results.push({ key: "codex", displayName: "Codex", path: p, status: "not-registered" });
+            }
+            else {
+                const pattern = /\n?\[mcp_servers\.agent-memory\]\n(?:(?!\[)[^\n]*\n?)*/;
+                fs.writeFileSync(p, existing.replace(pattern, ""), "utf8");
+                results.push({ key: "codex", displayName: "Codex", path: p, status: "unregistered" });
+            }
+        }
+    }
+    return results;
+}
 async function cmdServe(flags) {
     const isMcp = hasFlag(flags, "mcp");
     const isRegister = hasFlag(flags, "register");
@@ -2689,7 +3075,7 @@ async function cmdServe(flags) {
     // Core tools: free tier, available without Pro.
     server.addTool({
         name: "memory_read",
-        description: "Read the current long-term memory (MEMORY.md) and scratchpad checklist.",
+        description: "Read ONLY the curated long-term memory (MEMORY.md) and open scratchpad items — a small saved snapshot, not a search. For finding things in daily logs/topics, or recalling past chat sessions, use the `agent-memory` skill (search/recall commands) instead of this tool.",
         inputSchema: { type: "object", properties: {} },
     }, async () => {
         const memFile = getMemoryFile();
@@ -2739,11 +3125,16 @@ async function cmdServe(flags) {
             server.addTool({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema }, (input) => runtime.runMcpTool(tool.name, input));
         }
         server.addStartupHook(() => runtime.runMcpStartup());
+        server.addShutdownHook(() => runtime.runMcpShutdown());
     }
     catch {
         // Pro not installed or failed to load — serve with core tools only.
     }
     await server.start();
+    // Hard backstop: a Pro plugin's fs.watch handles (or any other resource
+    // that keeps the event loop alive) must never prevent this process from
+    // exiting once stdin has closed.
+    process.exit(0);
 }
 // ---------------------------------------------------------------------------
 // Usage
@@ -2753,7 +3144,7 @@ function printUsage() {
         ["Do things", ["save", "note", "recall", "search"]],
         ["See things", ["status", "doctor", "dashboard"]],
         ["Advanced", ["write", "read", "context", "scratchpad", "distil", "sync"]],
-        ["Setup", ["setup", "install-skills", "install-hooks", "completion"]],
+        ["Setup", ["setup", "install-skills", "install-hooks", "completion", "uninstall"]],
         ["Pro", ["pro", "learn"]],
     ];
     const knownGroupCommands = new Set(groups.flatMap(([, list]) => list));
@@ -2854,7 +3245,7 @@ async function main() {
         process.stdout.isTTY &&
         !json &&
         command &&
-        !["init", "help", "version", "doctor", "status", "completion", "hook", "serve"].includes(command) &&
+        !["init", "help", "version", "doctor", "status", "completion", "hook", "serve", "uninstall"].includes(command) &&
         !fs.existsSync(getMemoryDir())) {
         console.log(colorize("It looks like this is your first run — no memory directory yet.", "yellow"));
         if (await promptYesNo("Run agent-memory init to set things up?", true)) {
@@ -2966,6 +3357,9 @@ async function main() {
         case "uninstall-hooks":
             cmdUninstallHooks(flags);
             break;
+        case "uninstall":
+            await cmdUninstall(flags);
+            break;
         case "hook": {
             const sub = positional[0];
             if (sub !== "session-start" && sub !== "user-prompt-submit" && sub !== "stop") {
@@ -2988,6 +3382,13 @@ async function main() {
             const layer = readHookMode() === "per-turn" ? "stable" : undefined;
             await cmdContext(layer ? { "no-search": true, layer } : { "no-search": true });
             try {
+                const policy = readUpgradePolicy();
+                if (!policy.existed) {
+                    // Persist the (possibly env-overridden) defaults now, so this notice
+                    // only ever fires once — the file's mere existence is the "seen" flag.
+                    writeUpgradePolicy({ cli: policy.cli, plugin: policy.plugin });
+                    console.error("agent-memory: auto-upgrade is on by default (CLI + Pro plugin). Disable with: agent-memory upgrade policy off");
+                }
                 const cache = readUpgradeCache();
                 if (cache) {
                     const status = await checkForUpgrades({
@@ -2995,7 +3396,7 @@ async function main() {
                         pluginCurrent: cache.pluginCurrent,
                         cacheOnly: true,
                     });
-                    const notice = formatUpgradeNotice(status);
+                    const notice = formatUpgradeNotice(status, cache);
                     if (notice)
                         console.error(notice);
                 }
@@ -3022,7 +3423,7 @@ async function main() {
                         capability: "session",
                     });
                     if (decision.state === "exhausted") {
-                        console.error(`AgentMemory free session allowance resets in ${formatResetTime(decision.resetAt)}. Upgrade: ${UPGRADE_URL}`);
+                        console.error(`AgentMemory free session allowance resets in ${formatResetTime(decision.resetAt)}. Paid plans are not available yet.`);
                     }
                 }
             }
@@ -3041,7 +3442,7 @@ async function main() {
             await cmdPro(flags, positional);
             break;
         case "upgrade":
-            await cmdUpgrade(flags);
+            await cmdUpgrade(flags, positional);
             break;
         case "serve":
             await cmdServe(flags);