myagentmemory 0.5.2 → 0.5.3

package/dist/completions.js

@@ -395,6 +395,29 @@ function ensureProfileBlock(filePath, lines) {
     fs.writeFileSync(filePath, updated, { mode: 0o600 });
     return true;
 }
+/** Reverse of {@link ensureProfileBlock}: strips the marker block, if present, from the given file. */
+function removeProfileBlock(filePath) {
+    const start = "# >>> agent-memory completion >>>";
+    const end = "# <<< agent-memory completion <<<";
+    if (!fs.existsSync(filePath))
+        return false;
+    const current = fs.readFileSync(filePath, "utf8");
+    const startIndex = current.indexOf(start);
+    const endIndex = startIndex === -1 ? -1 : current.indexOf(end, startIndex);
+    if (startIndex === -1 || endIndex === -1)
+        return false;
+    const updated = (current.slice(0, startIndex) + current.slice(endIndex + end.length)).replace(/\n{3,}/g, "\n\n");
+    if (updated === current)
+        return false;
+    fs.writeFileSync(filePath, updated, { mode: 0o600 });
+    return true;
+}
+function removeCompletionFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return false;
+    fs.unlinkSync(filePath);
+    return true;
+}
 export function installCompletion(shell, options = {}) {
     const homeDir = options.homeDir ?? os.homedir();
     const platform = options.platform ?? process.platform;
@@ -433,3 +456,31 @@ export function installCompletion(shell, options = {}) {
     ]);
     return { shell, completionPath, profilePath, profileUpdated };
 }
+function uninstallShellCompletion(shell, homeDir, platform) {
+    const completionDir = path.join(homeDir, ".config", "agent-memory", "completions");
+    if (shell === "fish") {
+        const completionPath = path.join(homeDir, ".config", "fish", "completions", "agent-memory.fish");
+        return { shell, completionPath, removed: removeCompletionFile(completionPath), profileUpdated: false };
+    }
+    const extension = shell === "powershell" ? "ps1" : shell;
+    const completionPath = path.join(completionDir, `agent-memory.${extension}`);
+    const removed = removeCompletionFile(completionPath);
+    if (shell === "bash") {
+        const profilePath = path.join(homeDir, ".bashrc");
+        return { shell, completionPath, removed, profilePath, profileUpdated: removeProfileBlock(profilePath) };
+    }
+    if (shell === "zsh") {
+        const profilePath = path.join(homeDir, ".zshrc");
+        return { shell, completionPath, removed, profilePath, profileUpdated: removeProfileBlock(profilePath) };
+    }
+    const profilePath = platform === "win32"
+        ? path.join(homeDir, "Documents", "PowerShell", "Microsoft.PowerShell_profile.ps1")
+        : path.join(homeDir, ".config", "powershell", "Microsoft.PowerShell_profile.ps1");
+    return { shell, completionPath, removed, profilePath, profileUpdated: removeProfileBlock(profilePath) };
+}
+/** Reverse of {@link installCompletion} across every supported shell. */
+export function uninstallCompletion(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const platform = options.platform ?? process.platform;
+    return ["bash", "zsh", "fish", "powershell"].map((shell) => uninstallShellCompletion(shell, homeDir, platform));
+}

package/dist/core.js

@@ -872,6 +872,17 @@ export function installSkills() {
             destDir: path.join(homeDir, ".cursor", "skills", "agent-memory"),
             homeMarker: path.join(homeDir, ".cursor"),
         },
+        {
+            label: "Qoder skill",
+            srcDir: path.join(skillsDir, "qoder"),
+            destDir: path.join(homeDir, ".qoder", "skills", "agent-memory"),
+            homeMarker: path.join(homeDir, ".qoder"),
+            detectFiles: [
+                path.join(homeDir, ".qoder", "settings.json"),
+                path.join(homeDir, ".qoder", "settings.local.json"),
+            ],
+            detectCommand: "qoder",
+        },
         {
             label: "Agent CLI skill",
             srcDir: path.join(skillsDir, "agent"),

package/dist/hooks.d.ts

@@ -1,7 +1,13 @@
+import { execFileSync } from "node:child_process";
 import { type HookMode } from "./core.js";
+type ExecFileSyncFn = typeof execFileSync;
+/** Override the execFileSync implementation used by hook installers (for testing). */
+export declare function _setHookExecForTest(fn: ExecFileSyncFn): void;
+/** Reset the execFileSync implementation to the real one. */
+export declare function _resetHookExecForTest(): void;
 /** Override the detected home directory in deterministic tests. */
 export declare function _setHookHomeDirForTest(directory: string | null): void;
-export type HookAgentKey = "claude" | "codex" | "cursor" | "opencode" | "pi";
+export type HookAgentKey = "claude" | "codex" | "cursor" | "opencode" | "pi" | "qoder";
 export interface HookTargetInfo {
     key: HookAgentKey;
     label: string;
@@ -52,6 +58,13 @@ export interface InstallHooksReport {
     results: HookInstallResult[];
     error?: string;
 }
+export interface PiMemoryState {
+    lastAttemptAt: string;
+    ok: boolean;
+    detail: string;
+}
+/** Read the last recorded `pi install npm:pi-memory` attempt, if any. Never throws. */
+export declare function getPiMemoryState(): PiMemoryState | null;
 export declare function installHooks(agents: Set<HookAgentKey>, mode?: HookMode): InstallHooksReport;
 export interface UninstallHooksReport {
     ok: boolean;
@@ -60,3 +73,4 @@ export interface UninstallHooksReport {
     error?: string;
 }
 export declare function uninstallHooks(agents?: Set<HookAgentKey>): UninstallHooksReport;
+export {};

package/dist/hooks.js

@@ -1,7 +1,17 @@
+import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { writeHookMode } from "./core.js";
+import { getMemoryDir, writeHookMode } from "./core.js";
+let execFileSyncFn = execFileSync;
+/** Override the execFileSync implementation used by hook installers (for testing). */
+export function _setHookExecForTest(fn) {
+    execFileSyncFn = fn;
+}
+/** Reset the execFileSync implementation to the real one. */
+export function _resetHookExecForTest() {
+    execFileSyncFn = execFileSync;
+}
 let homeDirOverride = null;
 /** Override the detected home directory in deterministic tests. */
 export function _setHookHomeDirForTest(directory) {
@@ -80,12 +90,22 @@ function hookTargets(homeDir) {
         },
         {
             key: "pi",
-            label: "pi",
+            label: "pi (via pi-memory)",
             homeMarker: path.join(homeDir, ".pi"),
             detectFiles: [],
             detectCommand: "pi",
-            supported: false,
-            unsupportedReason: "no documented SessionStart hook mechanism",
+            supported: true,
+        },
+        {
+            key: "qoder",
+            label: "Qoder",
+            homeMarker: path.join(homeDir, ".qoder"),
+            detectFiles: [
+                path.join(homeDir, ".qoder", "settings.json"),
+                path.join(homeDir, ".qoder", "settings.local.json"),
+            ],
+            detectCommand: "qoder",
+            supported: true,
         },
     ];
 }
@@ -143,6 +163,14 @@ export function isHookInstalled(homeDir, key) {
             const instructionsPath = path.join(homeDir, ".agent-memory", "hooks", "opencode.md");
             return list.includes(instructionsPath);
         }
+        if (key === "pi") {
+            // Live filesystem state is authoritative — pi-memory can be installed or
+            // removed outside agent-memory (manually, or via `pi uninstall`) at any
+            // time, so a recorded delegate attempt must never override what's
+            // actually on disk. The state file is diagnostic-only (surfaced
+            // separately in `doctor`'s detail text), not a substitute for this check.
+            return fs.existsSync(path.join(homeDir, ".pi", "agent", "memory"));
+        }
     }
     catch {
         return false;
@@ -232,6 +260,68 @@ function writeJson(filePath, data) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
 }
+function piMemoryStatePath() {
+    return path.join(getMemoryDir(), "pi-memory-state.json");
+}
+function writePiMemoryState(ok, detail) {
+    try {
+        writeJson(piMemoryStatePath(), { lastAttemptAt: new Date().toISOString(), ok, detail });
+    }
+    catch {
+        // best-effort bookkeeping only — never block the actual install/uninstall result on this.
+    }
+}
+/** Read the last recorded `pi install npm:pi-memory` attempt, if any. Never throws. */
+export function getPiMemoryState() {
+    try {
+        const filePath = piMemoryStatePath();
+        if (!fs.existsSync(filePath))
+            return null;
+        const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        if (typeof parsed?.lastAttemptAt !== "string" || typeof parsed?.ok !== "boolean")
+            return null;
+        return { lastAttemptAt: parsed.lastAttemptAt, ok: parsed.ok, detail: String(parsed.detail ?? "") };
+    }
+    catch {
+        return null;
+    }
+}
+function installPiMemoryDelegate(homeDir) {
+    const memoryPath = path.join(homeDir, ".pi", "agent", "memory");
+    try {
+        const stdout = execFileSyncFn("pi", ["install", "npm:pi-memory"], {
+            encoding: "utf-8",
+            timeout: 30_000,
+        });
+        const detail = typeof stdout === "string" ? stdout.trim() : "";
+        writePiMemoryState(true, detail);
+        return { key: "pi", label: "pi (via pi-memory)", installed: true, path: memoryPath, reason: detail || undefined };
+    }
+    catch (err) {
+        const detail = err && typeof err === "object" && "stderr" in err && err.stderr
+            ? String(err.stderr).trim()
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        writePiMemoryState(false, detail);
+        return { key: "pi", label: "pi (via pi-memory)", installed: false, reason: detail };
+    }
+}
+function uninstallPiMemoryDelegate(homeDir) {
+    // agent-memory never owns this install, so it never runs `pi uninstall pi-memory` — but
+    // silently doing nothing would let an `agent-memory uninstall` report read as "fully cleaned
+    // up" while pi-memory keeps running. Phrase the reason distinctly when it's actually still
+    // active so callers (and cmdUninstall's step detail) can surface that honestly.
+    const stillActive = fs.existsSync(path.join(homeDir, ".pi", "agent", "memory"));
+    return {
+        key: "pi",
+        label: "pi (via pi-memory)",
+        installed: false,
+        reason: stillActive
+            ? "pi-memory left installed (not managed by agent-memory) — run `pi uninstall pi-memory` to remove it"
+            : "not installed",
+    };
+}
 /**
  * Idempotently upsert the agent-memory-managed hook group for `eventKey`
  * (SessionStart or UserPromptSubmit) with `command`. Returns `{ changed,
@@ -524,6 +614,93 @@ function installOpencodeInstructions(homeDir) {
     writeJson(configPath, config);
     return { key: "opencode", label: "opencode", installed: true, path: configPath, backup };
 }
+function installQoderHook(homeDir) {
+    const settingsPath = path.join(homeDir, ".qoder", "settings.json");
+    const backup = backupOnce(settingsPath);
+    const settings = readJsonConfig(settingsPath);
+    const hooks = settings.hooks ?? {};
+    const sessionStart = Array.isArray(hooks.SessionStart) ? [...hooks.SessionStart] : [];
+    const command = "agent-memory context";
+    let managed = 0;
+    let updated = 0;
+    for (const group of sessionStart) {
+        if (!group || typeof group !== "object")
+            continue;
+        const g = group;
+        const list = Array.isArray(g.hooks) ? g.hooks : [];
+        for (const hook of list) {
+            if (!hook || typeof hook !== "object")
+                continue;
+            const managedHook = hook;
+            if (managedHook[HOOK_MARKER_JSON] !== true)
+                continue;
+            managed++;
+            if (managedHook.command !== command) {
+                managedHook.command = command;
+                updated++;
+            }
+        }
+    }
+    if (managed && !updated) {
+        return { key: "qoder", label: "Qoder", installed: false, path: settingsPath, reason: "already installed" };
+    }
+    if (updated) {
+        hooks.SessionStart = sessionStart;
+        settings.hooks = hooks;
+        writeJson(settingsPath, settings);
+        return { key: "qoder", label: "Qoder", installed: true, path: settingsPath, backup, reason: "updated" };
+    }
+    sessionStart.push({
+        hooks: [{ type: "command", command, [HOOK_MARKER_JSON]: true }],
+    });
+    hooks.SessionStart = sessionStart;
+    settings.hooks = hooks;
+    writeJson(settingsPath, settings);
+    return { key: "qoder", label: "Qoder", installed: true, path: settingsPath, backup };
+}
+function uninstallQoderHook(homeDir) {
+    const settingsPath = path.join(homeDir, ".qoder", "settings.json");
+    if (!fs.existsSync(settingsPath)) {
+        return { key: "qoder", label: "Qoder", installed: false, reason: "not installed" };
+    }
+    const settings = readJsonConfig(settingsPath);
+    const hooks = settings.hooks ?? {};
+    const sessionStart = Array.isArray(hooks.SessionStart) ? hooks.SessionStart : [];
+    let removed = 0;
+    const filtered = sessionStart
+        .map((group) => {
+        if (!group || typeof group !== "object")
+            return group;
+        const g = { ...group };
+        const list = Array.isArray(g.hooks) ? g.hooks : [];
+        const kept = list.filter((h) => {
+            const isOurs = h && typeof h === "object" && h[HOOK_MARKER_JSON] === true;
+            if (isOurs)
+                removed++;
+            return !isOurs;
+        });
+        g.hooks = kept;
+        return g;
+    })
+        .filter((group) => {
+        if (!group || typeof group !== "object")
+            return true;
+        const g = group;
+        return Array.isArray(g.hooks) && g.hooks.length > 0;
+    });
+    if (removed === 0) {
+        return { key: "qoder", label: "Qoder", installed: false, reason: "not installed" };
+    }
+    hooks.SessionStart = filtered;
+    if (filtered.length === 0)
+        delete hooks.SessionStart;
+    if (Object.keys(hooks).length === 0)
+        delete settings.hooks;
+    else
+        settings.hooks = hooks;
+    writeJson(settingsPath, settings);
+    return { key: "qoder", label: "Qoder", installed: true, path: settingsPath };
+}
 export function installHooks(agents, mode = "per-turn") {
     const { homeDir, targets } = detectHookAgents();
     if (!homeDir) {
@@ -566,6 +743,10 @@ export function installHooks(agents, mode = "per-turn") {
                 result = installCursorHook(homeDir);
             else if (target.key === "opencode")
                 result = installOpencodeInstructions(homeDir);
+            else if (target.key === "pi")
+                result = installPiMemoryDelegate(homeDir);
+            else if (target.key === "qoder")
+                result = installQoderHook(homeDir);
             else
                 continue;
             results.push(result);
@@ -711,7 +892,7 @@ export function uninstallHooks(agents) {
             error: "Home directory not found. Set HOME (or USERPROFILE on Windows) and retry.",
         };
     }
-    const keys = ["claude", "codex", "cursor", "opencode"];
+    const keys = ["claude", "codex", "cursor", "opencode", "pi", "qoder"];
     const results = [];
     for (const key of keys) {
         if (agents && !agents.has(key))
@@ -725,6 +906,10 @@ export function uninstallHooks(agents) {
                 results.push(uninstallCursorHook(homeDir));
             else if (key === "opencode")
                 results.push(uninstallOpencodeInstructions(homeDir));
+            else if (key === "pi")
+                results.push(uninstallPiMemoryDelegate(homeDir));
+            else if (key === "qoder")
+                results.push(uninstallQoderHook(homeDir));
         }
         catch (err) {
             results.push({

package/dist/plugin-service.js

@@ -402,14 +402,8 @@ export class AgentMemoryServiceBackend {
             value.entitlement.state !== "active" ||
             value.entitlement.capabilities.recall?.enabled !== true ||
             !recallQuota ||
-            recallQuota.limit !== 20 ||
-            recallQuota.scope !== "device" ||
-            recallQuota.window !== "day" ||
             value.entitlement.capabilities.learning?.enabled !== true ||
             !learningQuota ||
-            learningQuota.limit !== 5 ||
-            learningQuota.scope !== "device" ||
-            learningQuota.window !== "day" ||
             value.entitlement.capabilities["session-index"]?.enabled !== true ||
             value.entitlement.capabilities["session-worker"]?.enabled !== false ||
             value.entitlement.capabilities["web-console"]?.enabled !== true)

package/dist/upgrade.d.ts

@@ -1,12 +1,18 @@
 /**
  * Upgrade orchestration for the `agent-memory` CLI and its official Pro plugin bundle.
  *
- * Two consumers:
+ * Three consumers:
  *   1. `agent-memory upgrade` — explicit user command; checks and (optionally) installs.
- *   2. `agent-memory hook session-start` — passive notice from a 24h-cached record.
+ *   2. `agent-memory upgrade --background` — detached, non-interactive; checks, then
+ *      installs any target whose `readUpgradePolicy()` value is `"auto"` (the default).
+ *      Spawned by `refreshUpgradeCacheBackground()` from `hook session-start`.
+ *   3. `agent-memory hook session-start` — passive notice from a 24h-cached record,
+ *      including the outcome of the last `--background` auto-install attempt.
  *
  * Network calls always have a hard timeout and always fail closed (upgrade is a
- * quality-of-life feature; a flaky registry must never break the CLI).
+ * quality-of-life feature; a flaky registry must never break the CLI). Same fail-closed
+ * contract applies to auto-install: a failed background install is recorded, never
+ * retried before the next cache refresh, and never thrown.
  */
 import { type SpawnOptions } from "node:child_process";
 export type InstallManager = "bun" | "npm" | "pnpm" | "yarn" | "unknown";
@@ -24,6 +30,17 @@ export interface UpgradeCache {
     cliLatest: string | null;
     pluginCurrent: string | null;
     pluginLatest: string | null;
+    /** Outcome of the most recent `--background` auto-upgrade attempt, if any. */
+    cliAuto?: AutoUpgradeOutcome;
+    pluginAuto?: AutoUpgradeOutcome;
+}
+export interface AutoUpgradeOutcome {
+    at: string;
+    ok: boolean;
+    /** Version installed (ok) or the previous/current version (failure). */
+    version: string | null;
+    /** Failure reason; absent when ok. */
+    error?: string;
 }
 export interface UpgradeStatus {
     cli: {
@@ -42,6 +59,24 @@ export interface UpgradeStatus {
 export declare function readUpgradeCache(): UpgradeCache | null;
 export declare function writeUpgradeCache(record: UpgradeCache): void;
 export declare function isCacheFresh(record: UpgradeCache | null, now?: number): boolean;
+export type UpgradePolicyValue = "off" | "notify" | "auto";
+export interface UpgradePolicy {
+    cli: UpgradePolicyValue;
+    plugin: UpgradePolicyValue;
+}
+/**
+ * Resolve the persisted auto-upgrade policy.
+ * Precedence per target: `AGENT_MEMORY_AUTO_UPGRADE_{CLI,PLUGIN}` env var →
+ * `<memoryDir>/state/upgrade-policy.json` → default `"auto"`.
+ *
+ * `existed` tells callers whether the policy file was already on disk —
+ * used to fire a one-time "auto-upgrade is on" notice on first read.
+ */
+export declare function readUpgradePolicy(): UpgradePolicy & {
+    existed: boolean;
+};
+/** Atomically persist the auto-upgrade policy. Merges with whatever is already on disk. */
+export declare function writeUpgradePolicy(patch: Partial<UpgradePolicy>): UpgradePolicy;
 /**
  * Best-effort detection of how `myagentmemory` was installed. Path signatures
  * are heuristic but cover the common managers. On no match we fall back to
@@ -58,8 +93,10 @@ export interface InstallResult {
 export declare function runInstaller(method: InstallMethod, opts?: SpawnOptions): InstallResult;
 /**
  * Fire-and-forget: spawn a detached child that runs `agent-memory upgrade
- * --check --refresh --quiet` so the next session-start has a fresh cache.
- * Never awaits, never throws.
+ * --background --refresh --quiet` so the next session-start has a fresh
+ * cache. Unlike a plain check, `--background` also installs any target whose
+ * policy is `"auto"` (see `readUpgradePolicy`) — this is the one place
+ * auto-upgrade actually happens. Never awaits, never throws.
  */
 export declare function refreshUpgradeCacheBackground(): void;
 export interface CheckOptions {
@@ -77,4 +114,12 @@ export interface CheckOptions {
     pluginUpgradeAvailable?: boolean;
 }
 export declare function checkForUpgrades(opts: CheckOptions): Promise<UpgradeStatus>;
-export declare function formatUpgradeNotice(status: UpgradeStatus): string | null;
+/**
+ * `cache` (when passed) lets this distinguish a plain "notify" signal from the
+ * outcome of the last `--background` auto-install attempt for that target:
+ *   - succeeded, but this process is running older code than what's on disk
+ *     (e.g. a long-running `serve --mcp`) → "auto-upgraded, restart to use it"
+ *   - failed → surface the error and point at the manual command
+ *   - succeeded and already caught up (this process's own version matches) → silent
+ */
+export declare function formatUpgradeNotice(status: UpgradeStatus, cache?: UpgradeCache | null): string | null;

package/dist/upgrade.js

@@ -1,12 +1,18 @@
 /**
  * Upgrade orchestration for the `agent-memory` CLI and its official Pro plugin bundle.
  *
- * Two consumers:
+ * Three consumers:
  *   1. `agent-memory upgrade` — explicit user command; checks and (optionally) installs.
- *   2. `agent-memory hook session-start` — passive notice from a 24h-cached record.
+ *   2. `agent-memory upgrade --background` — detached, non-interactive; checks, then
+ *      installs any target whose `readUpgradePolicy()` value is `"auto"` (the default).
+ *      Spawned by `refreshUpgradeCacheBackground()` from `hook session-start`.
+ *   3. `agent-memory hook session-start` — passive notice from a 24h-cached record,
+ *      including the outcome of the last `--background` auto-install attempt.
  *
  * Network calls always have a hard timeout and always fail closed (upgrade is a
- * quality-of-life feature; a flaky registry must never break the CLI).
+ * quality-of-life feature; a flaky registry must never break the CLI). Same fail-closed
+ * contract applies to auto-install: a failed background install is recorded, never
+ * retried before the next cache refresh, and never thrown.
  */
 import { spawn, spawnSync } from "node:child_process";
 import * as fs from "node:fs";
@@ -50,6 +56,15 @@ async function fetchLatestFromNpm(fetchImpl = globalThis.fetch) {
 function upgradeCachePath() {
     return path.join(getMemoryDir(), "state", "upgrade-check.json");
 }
+function isValidAutoOutcome(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.at === "string" &&
+        typeof candidate.ok === "boolean" &&
+        (candidate.version === null || typeof candidate.version === "string") &&
+        (candidate.error === undefined || typeof candidate.error === "string"));
+}
 export function readUpgradeCache() {
     try {
         const raw = fs.readFileSync(upgradeCachePath(), "utf-8");
@@ -69,6 +84,8 @@ export function readUpgradeCache() {
             cliLatest: parsed.cliLatest ?? null,
             pluginCurrent: parsed.pluginCurrent ?? null,
             pluginLatest: parsed.pluginLatest ?? null,
+            cliAuto: isValidAutoOutcome(parsed.cliAuto) ? parsed.cliAuto : undefined,
+            pluginAuto: isValidAutoOutcome(parsed.pluginAuto) ? parsed.pluginAuto : undefined,
         };
     }
     catch {
@@ -93,6 +110,60 @@ export function isCacheFresh(record, now = Date.now()) {
         return false;
     return now - checked < CACHE_TTL_MS;
 }
+const UPGRADE_POLICY_FILENAME = "upgrade-policy.json";
+const UPGRADE_POLICY_DEFAULT = { cli: "auto", plugin: "auto" };
+function upgradePolicyPath() {
+    return path.join(getMemoryDir(), "state", UPGRADE_POLICY_FILENAME);
+}
+function isPolicyValue(value) {
+    return value === "off" || value === "notify" || value === "auto";
+}
+/**
+ * Resolve the persisted auto-upgrade policy.
+ * Precedence per target: `AGENT_MEMORY_AUTO_UPGRADE_{CLI,PLUGIN}` env var →
+ * `<memoryDir>/state/upgrade-policy.json` → default `"auto"`.
+ *
+ * `existed` tells callers whether the policy file was already on disk —
+ * used to fire a one-time "auto-upgrade is on" notice on first read.
+ */
+export function readUpgradePolicy() {
+    let stored = {};
+    let existed = false;
+    try {
+        const raw = fs.readFileSync(upgradePolicyPath(), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (isPolicyValue(parsed.cli) || isPolicyValue(parsed.plugin)) {
+            stored = parsed;
+            existed = true;
+        }
+    }
+    catch { }
+    const envCli = process.env.AGENT_MEMORY_AUTO_UPGRADE_CLI;
+    const envPlugin = process.env.AGENT_MEMORY_AUTO_UPGRADE_PLUGIN;
+    return {
+        cli: isPolicyValue(envCli) ? envCli : isPolicyValue(stored.cli) ? stored.cli : UPGRADE_POLICY_DEFAULT.cli,
+        plugin: isPolicyValue(envPlugin)
+            ? envPlugin
+            : isPolicyValue(stored.plugin)
+                ? stored.plugin
+                : UPGRADE_POLICY_DEFAULT.plugin,
+        existed,
+    };
+}
+/** Atomically persist the auto-upgrade policy. Merges with whatever is already on disk. */
+export function writeUpgradePolicy(patch) {
+    const current = readUpgradePolicy();
+    const next = {
+        cli: patch.cli ?? current.cli,
+        plugin: patch.plugin ?? current.plugin,
+    };
+    const target = upgradePolicyPath();
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const temporary = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, target);
+    return next;
+}
 // ---------------------------------------------------------------------------
 // Install-method detection
 // ---------------------------------------------------------------------------
@@ -163,8 +234,10 @@ export function runInstaller(method, opts = {}) {
 // ---------------------------------------------------------------------------
 /**
  * Fire-and-forget: spawn a detached child that runs `agent-memory upgrade
- * --check --refresh --quiet` so the next session-start has a fresh cache.
- * Never awaits, never throws.
+ * --background --refresh --quiet` so the next session-start has a fresh
+ * cache. Unlike a plain check, `--background` also installs any target whose
+ * policy is `"auto"` (see `readUpgradePolicy`) — this is the one place
+ * auto-upgrade actually happens. Never awaits, never throws.
  */
 export function refreshUpgradeCacheBackground() {
     try {
@@ -172,7 +245,7 @@ export function refreshUpgradeCacheBackground() {
         const script = process.argv[1];
         if (!binary || !script)
             return;
-        const child = spawn(binary, [script, "upgrade", "--check", "--refresh", "--quiet", "--json"], {
+        const child = spawn(binary, [script, "upgrade", "--background", "--refresh", "--quiet", "--json"], {
             detached: true,
             stdio: "ignore",
             env: { ...process.env, AGENT_MEMORY_UPGRADE_BACKGROUND: "1" },
@@ -231,13 +304,40 @@ export async function checkForUpgrades(opts) {
         fromCache,
     };
 }
-export function formatUpgradeNotice(status) {
+/**
+ * `cache` (when passed) lets this distinguish a plain "notify" signal from the
+ * outcome of the last `--background` auto-install attempt for that target:
+ *   - succeeded, but this process is running older code than what's on disk
+ *     (e.g. a long-running `serve --mcp`) → "auto-upgraded, restart to use it"
+ *   - failed → surface the error and point at the manual command
+ *   - succeeded and already caught up (this process's own version matches) → silent
+ */
+export function formatUpgradeNotice(status, cache) {
     const parts = [];
-    if (status.cli.upgradeAvailable)
+    let needsManualRun = false;
+    if (cache?.cliAuto && !cache.cliAuto.ok) {
+        parts.push(`CLI auto-upgrade failed (${cache.cliAuto.error ?? "unknown error"})`);
+        needsManualRun = true;
+    }
+    else if (cache?.cliAuto?.ok && cache.cliAuto.version && cache.cliAuto.version !== status.cli.current) {
+        parts.push(`CLI auto-upgraded → ${cache.cliAuto.version} (restart any long-running agent-memory process to use it)`);
+    }
+    else if (status.cli.upgradeAvailable) {
         parts.push(`CLI ${status.cli.current} → ${status.cli.latest ?? "new"}`);
-    if (status.plugin.upgradeAvailable)
+        needsManualRun = true;
+    }
+    if (cache?.pluginAuto && !cache.pluginAuto.ok) {
+        parts.push(`Pro auto-upgrade failed (${cache.pluginAuto.error ?? "unknown error"})`);
+        needsManualRun = true;
+    }
+    else if (cache?.pluginAuto?.ok && cache.pluginAuto.version && cache.pluginAuto.version !== status.plugin.current) {
+        parts.push(`Pro auto-upgraded → ${cache.pluginAuto.version}`);
+    }
+    else if (status.plugin.upgradeAvailable) {
         parts.push(`Pro ${status.plugin.current ?? "?"} → ${status.plugin.latest ?? "new"}`);
+        needsManualRun = true;
+    }
     if (!parts.length)
         return null;
-    return `agent-memory: upgrade available (${parts.join(", ")}). Run: agent-memory upgrade`;
+    return `agent-memory: ${parts.join("; ")}${needsManualRun ? ". Run: agent-memory upgrade" : ""}`;
 }

package/docs/official-plugin-bootstrap.md

@@ -267,7 +267,7 @@ An install or upgrade must:
 
 Failure before activation leaves the previous version active. Failure immediately after activation restores the previous receipt. Concurrent installers do not interleave. The core never invokes package-manager lifecycle scripts or elevates privileges.
 
-Uninstall removes executable versions, the active receipt, contributed skills, and managed hooks. It does not remove `MEMORY.md`, daily logs, topics, scratchpad items, source session logs, plugin-created review data, or billing state. A separate future purge command would require explicit scope and confirmation.
+Uninstall removes executable versions, the active receipt, contributed skills, and managed hooks. It does not remove `MEMORY.md`, daily logs, topics, scratchpad items, source session logs, plugin-created review data, or billing state. The top-level `agent-memory uninstall` command composes this with hook/skill/MCP/completion removal in one step; its explicit `--data` flag additionally deletes the memory directory and the entire plugin install root (bundles, receipts, and the activation credential) once the user opts in and confirms.
 
 ## Plugin host API v1
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "myagentmemory",
-	"version": "0.5.2",
+	"version": "0.5.3",
 	"description": "agentmemory (agent-memory) is persistent memory for coding agents (Claude Code, OpenAI Codex, Cursor, Agent) with qmd-powered semantic search across daily logs, long-term memory, and scratchpad",
 	"main": "./dist/core.js",
 	"types": "./dist/core.d.ts",