myagentmemory 0.4.17 → 0.5.2

package/dist/mcp-server.js

@@ -0,0 +1,106 @@
+import * as readline from "node:readline";
+// ---------------------------------------------------------------------------
+// Bare stdio MCP server — no external dependencies
+//
+// MCP uses newline-delimited JSON-RPC 2.0 over stdin/stdout (NOT Content-Length
+// framing). Each message is one JSON object followed by \n.
+// ---------------------------------------------------------------------------
+export class StdioMcpServer {
+    version;
+    tools = new Map();
+    startupHooks = [];
+    constructor(version = "0.0.0") {
+        this.version = version;
+    }
+    addTool(definition, handler) {
+        this.tools.set(definition.name, { definition, handler });
+    }
+    addStartupHook(fn) {
+        this.startupHooks.push(fn);
+    }
+    async start() {
+        // Run all startup hooks before entering the message loop.
+        for (const hook of this.startupHooks)
+            await hook();
+        const rl = readline.createInterface({ input: process.stdin, terminal: false });
+        rl.on("line", (line) => {
+            const trimmed = line.trim();
+            if (!trimmed)
+                return;
+            let message;
+            try {
+                message = JSON.parse(trimmed);
+            }
+            catch {
+                return;
+            }
+            this.handleMessage(message);
+        });
+        await new Promise((resolve) => {
+            rl.on("close", resolve);
+            process.stdin.on("end", resolve);
+        });
+    }
+    handleMessage(msg) {
+        const id = msg.id;
+        const method = typeof msg.method === "string" ? msg.method : "";
+        // Notifications (no id) — no response needed.
+        if (id === undefined || id === null) {
+            // notifications/initialized is the only one we care about; ignore the rest.
+            return;
+        }
+        if (method === "initialize") {
+            this.respond(id, {
+                protocolVersion: "2024-11-05",
+                capabilities: { tools: {} },
+                serverInfo: { name: "agent-memory", version: this.version },
+            });
+            return;
+        }
+        if (method === "ping") {
+            this.respond(id, {});
+            return;
+        }
+        if (method === "tools/list") {
+            this.respond(id, {
+                tools: [...this.tools.values()].map(({ definition }) => definition),
+            });
+            return;
+        }
+        if (method === "tools/call") {
+            const params = (msg.params ?? {});
+            const toolName = typeof params.name === "string" ? params.name : "";
+            const toolInput = (params.arguments ?? {});
+            const entry = this.tools.get(toolName);
+            if (!entry) {
+                this.respondError(id, -32601, `Unknown tool: ${toolName}`);
+                return;
+            }
+            // Execute handler — handle both sync and async.
+            Promise.resolve()
+                .then(() => entry.handler(toolInput))
+                .then((result) => {
+                this.respond(id, {
+                    content: [
+                        { type: "text", text: typeof result === "string" ? result : JSON.stringify(result, null, 2) },
+                    ],
+                });
+            })
+                .catch((error) => {
+                this.respond(id, {
+                    content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
+                    isError: true,
+                });
+            });
+            return;
+        }
+        // Unknown method — JSON-RPC method not found.
+        this.respondError(id, -32601, `Method not found: ${method}`);
+    }
+    respond(id, result) {
+        process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, result })}\n`);
+    }
+    respondError(id, code, message) {
+        process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } })}\n`);
+    }
+}

package/dist/plugin-bootstrap.js

@@ -3,7 +3,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { AGENT_MEMORY_PLUGIN_API_VERSION, isSafeBundlePath, validateBundleManifestV1, } from "./plugin-host.js";
-import { TemporaryPluginBackend } from "./plugin-service.js";
+import { AgentMemoryServiceBackend } from "./plugin-service.js";
 export const OFFICIAL_BUNDLE_ID = "agentmemory.pro";
 export const OFFICIAL_PLUGIN_IDS = ["agentmemory.session-intelligence", "agentmemory.web-console"];
 const MISSING_ENTITLEMENT = {
@@ -20,7 +20,7 @@ const OFFICIAL_PLUGINS = [
 const PACKAGE_MAX_BYTES = 64 * 1024 * 1024;
 const PACKAGE_MAX_EXPANDED_BYTES = 128 * 1024 * 1024;
 const PACKAGE_MAX_FILES = 10_000;
-const TEMPORARY_RELEASE_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
+const RELEASE_SIGNING_KEY_2026_08 = `-----BEGIN PUBLIC KEY-----
 MCowBQYDK2VwAyEASefZFUVFy1EmvGbd0ckHZThmPgqQ3u9HCwZRReAZQW8=
 -----END PUBLIC KEY-----`;
 export class PluginBootstrapFailure extends Error {
@@ -423,11 +423,11 @@ export class PluginBootstrapV1 {
 }
 export function createDefaultPluginBootstrap(coreVersion) {
     const store = new FilePluginInstallStore();
-    const backend = new TemporaryPluginBackend({ root: store.root, coreVersion });
+    const backend = new AgentMemoryServiceBackend({ root: store.root, coreVersion });
     return new PluginBootstrapV1({
         coreVersion,
         backend,
-        verifier: new Ed25519ReleaseVerifier({ "agentmemory-temporary-2026-08": TEMPORARY_RELEASE_PUBLIC_KEY }),
+        verifier: new Ed25519ReleaseVerifier({ "agentmemory-temporary-2026-08": RELEASE_SIGNING_KEY_2026_08 }),
         store,
         healthCheck: async (directory, release) => {
             const { createInstalledBundleHealthCheck } = await import("./plugin-runtime.js");

package/dist/plugin-host.d.ts

@@ -73,6 +73,21 @@ export interface PluginSessionStartHookV1 {
     requiredCapability: string;
     run(context: PluginSessionStartContextV1): Promise<void>;
 }
+export interface PluginBackgroundRefreshContextV1 {
+    host: string;
+    cwd?: string;
+    signal: AbortSignal;
+}
+/**
+ * Un-metered per-turn refresh callback. Fired on every UserPromptSubmit so
+ * plugins can keep background workers alive across `/clear` and long idle.
+ * MUST be idempotent and cheap — no quota is charged.
+ */
+export interface PluginBackgroundRefreshHookV1 {
+    name: string;
+    requiredCapability: string;
+    run(context: PluginBackgroundRefreshContextV1): Promise<void>;
+}
 export interface PluginMemoryWriteV1 {
     target: "long_term" | "daily" | "topic";
     content: string;
@@ -120,12 +135,31 @@ export interface PluginContextProviderV1 {
         signal: AbortSignal;
     }): Promise<PluginContextSectionV1[]>;
 }
+export interface PluginMcpToolInputSchema {
+    type: "object";
+    properties: Record<string, {
+        type: string;
+        description?: string;
+        enum?: string[];
+    }>;
+    required?: string[];
+}
+export interface PluginMcpToolV1 {
+    name: string;
+    description: string;
+    requiredCapability: string;
+    inputSchema: PluginMcpToolInputSchema;
+    run(input: Record<string, unknown>): unknown | Promise<unknown>;
+}
 export interface AgentMemoryPluginHostV1 {
     apiVersion: 1;
     coreVersion: string;
     registerCommand(command: PluginCommandV1): void;
     registerSessionStartHook(hook: PluginSessionStartHookV1): void;
+    registerBackgroundRefresh?(hook: PluginBackgroundRefreshHookV1): void;
     registerContextProvider?(provider: PluginContextProviderV1): void;
+    registerMcpTool?(tool: PluginMcpToolV1): void;
+    registerMcpStartup?(fn: () => void | Promise<void>): void;
     getStateDirectory(): string;
     getMemoryDirectory(): string;
     getEntitlement(): Promise<PluginEntitlementStatusV1>;

package/dist/plugin-runtime.d.ts

@@ -1,5 +1,5 @@
 import { type PluginBootstrapBackendV1, type PluginInstallStoreV1, type PluginSessionUsageDecisionV1, type SignedPluginReleaseV1 } from "./plugin-bootstrap.js";
-import { type PluginCommandContextV1, type PluginCommandResultV1, type PluginContextSectionV1, type PluginSessionStartHookV1 } from "./plugin-host.js";
+import { type PluginBackgroundRefreshContextV1, type PluginCommandContextV1, type PluginCommandResultV1, type PluginContextSectionV1, type PluginMcpToolV1, type PluginSessionStartHookV1 } from "./plugin-host.js";
 export interface PluginRuntimeOptionsV1 {
     coreVersion: string;
     store?: PluginInstallStoreV1;
@@ -11,18 +11,39 @@ export declare class InstalledPluginRuntimeV1 {
     private readonly backend;
     private readonly commands;
     private readonly hooks;
+    private readonly backgroundRefreshHooks;
     private readonly contextProviders;
+    private readonly mcpTools;
+    private readonly mcpStartupHooks;
     private loaded;
     constructor(options: PluginRuntimeOptionsV1);
     load(): Promise<boolean>;
     run(name: string, context: PluginCommandContextV1): Promise<PluginCommandResultV1 | null>;
     runSessionStart(context: Parameters<PluginSessionStartHookV1["run"]>[0]): Promise<PluginSessionUsageDecisionV1 | null>;
+    /**
+     * Fire all registered background-refresh hooks. Un-metered — intended for
+     * per-turn UserPromptSubmit invocation, keeping workers alive across
+     * `/clear` and idle without charging session quota. Failures propagate to
+     * the caller (which is expected to swallow them silently).
+     */
+    refreshBackgroundWorkers(context: PluginBackgroundRefreshContextV1): Promise<void>;
     provideContext(context: {
         host: string;
         cwd?: string;
         query?: string;
         signal: AbortSignal;
     }): Promise<PluginContextSectionV1[]>;
+    getMcpTools(): PluginMcpToolV1[];
+    /**
+     * Invoke a registered MCP tool by name, re-checking entitlement on every
+     * call — matching `run()`'s behavior for commands. MCP tools are
+     * registered once at `serve --mcp` startup and the server process can
+     * live for a long session, so a tool's entitlement must be re-verified
+     * per-call rather than trusted from registration time (e.g. a trial
+     * expiring mid-session must actually stop the tool from working).
+     */
+    runMcpTool(name: string, input: Record<string, unknown>): Promise<unknown>;
+    runMcpStartup(): Promise<void>;
     private createHost;
     private refreshEntitlement;
 }

package/dist/plugin-runtime.js

@@ -5,7 +5,7 @@ import { pathToFileURL } from "node:url";
 import { getMemoryDir, memoryWrite, redactSecrets, scheduleQmdUpdate } from "./core.js";
 import { FilePluginInstallStore, OFFICIAL_BUNDLE_ID, PluginBootstrapFailure, } from "./plugin-bootstrap.js";
 import { AGENT_MEMORY_PLUGIN_API_VERSION, isPluginCapabilityEnabled, validateBundleManifestV1, validatePluginEntitlementStatusV1, validatePluginManifestV1, } from "./plugin-host.js";
-import { TemporaryPluginBackend } from "./plugin-service.js";
+import { AgentMemoryServiceBackend } from "./plugin-service.js";
 function assertPermission(manifest, permission) {
     if (!manifest.permissions.includes(permission))
         throw new PluginBootstrapFailure("plugin_permission_denied", `Plugin ${manifest.id} did not declare permission ${permission}`);
@@ -61,12 +61,15 @@ export class InstalledPluginRuntimeV1 {
     backend;
     commands = new Map();
     hooks = [];
+    backgroundRefreshHooks = [];
     contextProviders = [];
+    mcpTools = [];
+    mcpStartupHooks = [];
     loaded = false;
     constructor(options) {
         this.options = options;
         this.store = options.store ?? new FilePluginInstallStore();
-        this.backend = options.backend ?? new TemporaryPluginBackend({ root: this.store.root });
+        this.backend = options.backend ?? new AgentMemoryServiceBackend({ root: this.store.root });
     }
     async load() {
         if (this.loaded)
@@ -133,6 +136,22 @@ export class InstalledPluginRuntimeV1 {
             throw error;
         }
     }
+    /**
+     * Fire all registered background-refresh hooks. Un-metered — intended for
+     * per-turn UserPromptSubmit invocation, keeping workers alive across
+     * `/clear` and idle without charging session quota. Failures propagate to
+     * the caller (which is expected to swallow them silently).
+     */
+    async refreshBackgroundWorkers(context) {
+        if (!(await this.load()) || this.backgroundRefreshHooks.length === 0)
+            return;
+        const entitlement = await this.refreshEntitlement();
+        for (const hook of this.backgroundRefreshHooks) {
+            if (!isPluginCapabilityEnabled(entitlement, hook.requiredCapability))
+                continue;
+            await hook.run(context);
+        }
+    }
     async provideContext(context) {
         if (!(await this.load()) || this.contextProviders.length === 0)
             return [];
@@ -164,6 +183,32 @@ export class InstalledPluginRuntimeV1 {
         }
         return sections;
     }
+    getMcpTools() {
+        return [...this.mcpTools];
+    }
+    /**
+     * Invoke a registered MCP tool by name, re-checking entitlement on every
+     * call — matching `run()`'s behavior for commands. MCP tools are
+     * registered once at `serve --mcp` startup and the server process can
+     * live for a long session, so a tool's entitlement must be re-verified
+     * per-call rather than trusted from registration time (e.g. a trial
+     * expiring mid-session must actually stop the tool from working).
+     */
+    async runMcpTool(name, input) {
+        if (!(await this.load()))
+            return { error: `Unknown MCP tool: ${name}` };
+        const tool = this.mcpTools.find((candidate) => candidate.name === name);
+        if (!tool)
+            return { error: `Unknown MCP tool: ${name}` };
+        const entitlement = await this.refreshEntitlement();
+        if (!isPluginCapabilityEnabled(entitlement, tool.requiredCapability))
+            return { error: `Capability ${tool.requiredCapability} is not enabled for the ${name} tool` };
+        return tool.run(input);
+    }
+    async runMcpStartup() {
+        for (const hook of this.mcpStartupHooks)
+            await hook();
+    }
     createHost(manifest) {
         const descriptors = new Map(manifest.commands.map((command) => [command.name, command]));
         const stateRoot = path.join(this.store.root, "state");
@@ -197,6 +242,13 @@ export class InstalledPluginRuntimeV1 {
                     throw new PluginBootstrapFailure("plugin_hook_invalid", `Plugin ${manifest.id} registered a hook with an undeclared capability`);
                 this.hooks.push(hook);
             },
+            registerBackgroundRefresh: (hook) => {
+                if (!(manifest.capabilities ?? []).includes(hook.requiredCapability))
+                    throw new PluginBootstrapFailure("plugin_hook_invalid", `Plugin ${manifest.id} registered a background refresh hook with an undeclared capability`);
+                if (!hook.name || this.backgroundRefreshHooks.some((existing) => existing.name === hook.name))
+                    throw new PluginBootstrapFailure("plugin_hook_invalid", `Plugin background refresh hook ${hook.name || "(unnamed)"} is invalid or already registered`);
+                this.backgroundRefreshHooks.push(hook);
+            },
             registerContextProvider: (provider) => {
                 if (!(manifest.capabilities ?? []).includes(provider.requiredCapability))
                     throw new PluginBootstrapFailure("plugin_context_invalid", `Plugin ${manifest.id} registered a context provider with an undeclared capability`);
@@ -204,6 +256,16 @@ export class InstalledPluginRuntimeV1 {
                     throw new PluginBootstrapFailure("plugin_context_invalid", `Plugin context provider ${provider.name || "(unnamed)"} is invalid or already registered`);
                 this.contextProviders.push({ provider, pluginId: manifest.id });
             },
+            registerMcpTool: (tool) => {
+                if (!(manifest.capabilities ?? []).includes(tool.requiredCapability))
+                    throw new PluginBootstrapFailure("plugin_mcp_tool_invalid", `Plugin ${manifest.id} registered an MCP tool with an undeclared capability`);
+                if (!tool.name || this.mcpTools.some((existing) => existing.name === tool.name))
+                    throw new PluginBootstrapFailure("plugin_mcp_tool_invalid", `Plugin MCP tool ${tool.name || "(unnamed)"} is invalid or already registered`);
+                this.mcpTools.push(tool);
+            },
+            registerMcpStartup: (fn) => {
+                this.mcpStartupHooks.push(fn);
+            },
             getStateDirectory: () => stateDirectory,
             getMemoryDirectory: () => {
                 assertPermission(manifest, "memory:read");
@@ -254,6 +316,7 @@ export function createInstalledBundleHealthCheck(coreVersion, backend, storeRoot
                 coreVersion,
                 registerCommand() { },
                 registerSessionStartHook() { },
+                registerBackgroundRefresh() { },
                 getStateDirectory: () => stateDirectory,
                 getMemoryDirectory: () => {
                     assertPermission(plugin.manifest, "memory:read");

package/dist/plugin-service.d.ts

@@ -1,6 +1,6 @@
 import { type PluginAccessDecisionV1, type PluginBootstrapBackendV1, type PluginNextActionV1, type PluginSessionUsageDecisionV1, type SignedPluginReleaseV1 } from "./plugin-bootstrap.js";
 import { type PluginEntitlementStatusV1 } from "./plugin-host.js";
-interface TemporaryPluginBackendOptions {
+interface AgentMemoryServiceBackendOptions {
     root?: string;
     coreVersion?: string;
     apiOrigin?: string;
@@ -10,8 +10,8 @@ interface TemporaryPluginBackendOptions {
     activate?: () => Promise<string>;
 }
 export declare function openLoopbackUrl(url: string): boolean;
-export declare function collectTemporaryActivation(openUrl?: (url: string) => boolean): Promise<string>;
-export declare class TemporaryPluginBackend implements PluginBootstrapBackendV1 {
+export declare function collectActivation(openUrl?: (url: string) => boolean): Promise<string>;
+export declare class AgentMemoryServiceBackend implements PluginBootstrapBackendV1 {
     private readonly root;
     private readonly coreVersion;
     private readonly apiOrigin;
@@ -19,7 +19,7 @@ export declare class TemporaryPluginBackend implements PluginBootstrapBackendV1
     private readonly fetchImplementation;
     private readonly openUrl;
     private readonly activate;
-    constructor(options?: TemporaryPluginBackendOptions);
+    constructor(options?: AgentMemoryServiceBackendOptions);
     getLocalEntitlement(): Promise<PluginEntitlementStatusV1>;
     resolveAccess(request: {
         bundleId: string;
@@ -46,4 +46,10 @@ export declare class TemporaryPluginBackend implements PluginBootstrapBackendV1
     private sessionUsage;
     private request;
 }
+export declare class TemporaryPluginBackend extends AgentMemoryServiceBackend {
+    constructor(options: {
+        root: string;
+        coreVersion: string;
+    });
+}
 export {};

package/dist/plugin-service.js

@@ -7,7 +7,8 @@ import { getDefaultPluginInstallRoot, PluginBootstrapFailure, } from "./plugin-b
 import { validatePluginEntitlementStatusV1 } from "./plugin-host.js";
 const API_ORIGIN = "https://api.agentmemory.paperpilot.me";
 const ARTIFACT_ORIGIN = "https://plugins.agentmemory.paperpilot.me";
-const ACTIVATION_FILE = "credentials/temporary-access.json";
+const ACTIVATION_FILE = "credentials/activation.json";
+const ACTIVATION_FILE_LEGACY = "credentials/temporary-access.json";
 const REQUEST_TIMEOUT_MS = 30_000;
 const EMAIL_MAX_BYTES = 254;
 const FORM_MAX_BYTES = 2_048;
@@ -30,15 +31,33 @@ function freeEntitlement() {
         features: ["session-intelligence", "web-console"],
         capabilities: {
             "session-index": { enabled: true },
-            recall: { enabled: true, quota: { limit: 10, window: "day", scope: "device" } },
+            recall: { enabled: true, quota: { limit: 20, window: "day", scope: "device" } },
             "session-worker": { enabled: false },
-            learning: { enabled: true, quota: { limit: 1, window: "day", scope: "device" } },
+            learning: { enabled: true, quota: { limit: 5, window: "day", scope: "device" } },
             "retrieval-evaluation": { enabled: true },
             "operational-metrics": { enabled: true },
             "web-console": { enabled: true },
             "memory-explorer": { enabled: true },
         },
-        reason: "Free preview: 10 recalls and 1 learning scan per local day; indexing and dashboard access remain available",
+        reason: "Included at no cost: 20 recalls and 5 learning scans per local day; local indexing and dashboard access remain available",
+    };
+}
+function devEntitlement() {
+    return {
+        plan: "pro",
+        state: "active",
+        features: ["session-intelligence", "web-console"],
+        capabilities: {
+            "session-index": { enabled: true },
+            recall: { enabled: true },
+            "session-worker": { enabled: true },
+            learning: { enabled: true },
+            "retrieval-evaluation": { enabled: true },
+            "operational-metrics": { enabled: true },
+            "web-console": { enabled: true },
+            "memory-explorer": { enabled: true },
+        },
+        reason: "Dev entitlement: all capabilities enabled, no quotas (AGENT_MEMORY_DEV_ENTITLEMENT=1)",
     };
 }
 function isEmail(value) {
@@ -253,7 +272,7 @@ export function openLoopbackUrl(url) {
         return false;
     }
 }
-export async function collectTemporaryActivation(openUrl = openLoopbackUrl) {
+export async function collectActivation(openUrl = openLoopbackUrl) {
     const nonce = randomBytes(24).toString("hex");
     const activationPath = `/activate/${nonce}`;
     let expectedHost = "";
@@ -317,7 +336,7 @@ export async function collectTemporaryActivation(openUrl = openLoopbackUrl) {
         throw new PluginBootstrapFailure("browser_unavailable", `Open this URL in a browser: ${url}`);
     }
     const timer = setTimeout(() => {
-        fail?.(new PluginBootstrapFailure("activation_timeout", "Temporary activation timed out", true));
+        fail?.(new PluginBootstrapFailure("activation_timeout", "Browser activation timed out", true));
         server.close();
     }, 5 * 60_000);
     timer.unref();
@@ -329,7 +348,7 @@ export async function collectTemporaryActivation(openUrl = openLoopbackUrl) {
         server.close();
     }
 }
-export class TemporaryPluginBackend {
+export class AgentMemoryServiceBackend {
     root;
     coreVersion;
     apiOrigin;
@@ -348,7 +367,11 @@ export class TemporaryPluginBackend {
     }
     async getLocalEntitlement() {
         const activation = this.readActivation();
-        return activation ? freeEntitlement() : cloneEntitlement(MISSING_ENTITLEMENT);
+        if (!activation)
+            return cloneEntitlement(MISSING_ENTITLEMENT);
+        if (process.env.AGENT_MEMORY_DEV_ENTITLEMENT === "1")
+            return devEntitlement();
+        return freeEntitlement();
     }
     async resolveAccess(request) {
         const activation = this.readActivation();
@@ -377,13 +400,18 @@ export class TemporaryPluginBackend {
         const learningQuota = value.entitlement.capabilities.learning?.quota;
         if (value.entitlement.plan !== "free" ||
             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)
             throw new PluginBootstrapFailure("service_response_invalid", "The free preview policy is invalid");
         this.writeActivation(installationId, value.usageCredential, 1);
@@ -427,6 +455,17 @@ export class TemporaryPluginBackend {
     }
     readActivation() {
         const activationPath = this.activationPath();
+        if (!fs.existsSync(activationPath)) {
+            const legacyPath = path.join(this.root, ...ACTIVATION_FILE_LEGACY.split("/"));
+            if (fs.existsSync(legacyPath)) {
+                try {
+                    fs.renameSync(legacyPath, activationPath);
+                }
+                catch {
+                    /* best-effort migration */
+                }
+            }
+        }
         if (!fs.existsSync(activationPath))
             return null;
         try {
@@ -542,3 +581,8 @@ export class TemporaryPluginBackend {
         return response;
     }
 }
+export class TemporaryPluginBackend extends AgentMemoryServiceBackend {
+    constructor(options) {
+        super({ ...options, openUrl: () => false });
+    }
+}

package/dist/upgrade.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Upgrade orchestration for the `agent-memory` CLI and its official Pro plugin bundle.
+ *
+ * Two 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.
+ *
+ * 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).
+ */
+import { type SpawnOptions } from "node:child_process";
+export type InstallManager = "bun" | "npm" | "pnpm" | "yarn" | "unknown";
+export interface InstallMethod {
+    manager: InstallManager;
+    global: boolean;
+    /** Absolute path we think holds the current install (for diagnostics). */
+    origin: string;
+    /** Argv used to invoke the package manager (e.g. ["npm","i","-g","myagentmemory@latest"]). */
+    command: string[];
+}
+export interface UpgradeCache {
+    checkedAt: string;
+    cliCurrent: string;
+    cliLatest: string | null;
+    pluginCurrent: string | null;
+    pluginLatest: string | null;
+}
+export interface UpgradeStatus {
+    cli: {
+        current: string;
+        latest: string | null;
+        upgradeAvailable: boolean;
+    };
+    plugin: {
+        current: string | null;
+        latest: string | null;
+        upgradeAvailable: boolean;
+    };
+    checkedAt: string;
+    fromCache: boolean;
+}
+export declare function readUpgradeCache(): UpgradeCache | null;
+export declare function writeUpgradeCache(record: UpgradeCache): void;
+export declare function isCacheFresh(record: UpgradeCache | null, now?: number): boolean;
+/**
+ * Best-effort detection of how `myagentmemory` was installed. Path signatures
+ * are heuristic but cover the common managers. On no match we fall back to
+ * `npm -g` per the user's choice ("best-effort try anyway").
+ */
+export declare function detectInstallMethod(location?: string): InstallMethod;
+export interface InstallResult {
+    ok: boolean;
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    command: string[];
+}
+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.
+ */
+export declare function refreshUpgradeCacheBackground(): void;
+export interface CheckOptions {
+    cliCurrent: string;
+    pluginCurrent: string | null;
+    /** When true, do NOT hit the network — read cache only. Returns fromCache=true even on miss. */
+    cacheOnly?: boolean;
+    /** When true, force a network refresh and rewrite the cache regardless of freshness. */
+    refresh?: boolean;
+    /** Optional injected npm fetcher (used by tests). */
+    fetchCliLatest?: () => Promise<string | null>;
+    /** Optional injected plugin-latest resolver. When omitted, plugin latest is taken from pluginLatestHint. */
+    pluginLatestHint?: string | null;
+    /** Explicit signal from the bootstrap that a newer release exists even when the version number is unknown. */
+    pluginUpgradeAvailable?: boolean;
+}
+export declare function checkForUpgrades(opts: CheckOptions): Promise<UpgradeStatus>;
+export declare function formatUpgradeNotice(status: UpgradeStatus): string | null;