myagentmemory 0.5.3 → 0.5.4

package/README.md

@@ -24,7 +24,7 @@ Prefer to have an agent drive the whole thing — install, configure, verify, th
 
 - AgentMemory injects your decisions, scratchpad, and daily log at session start — no copy-paste, no re-explaining.
 - Repeated corrections become durable memory you can inspect and undo (Pro).
-- Every memory is a plain Markdown file you own. Memory content, session content, queries, and repository paths stay on this machine.
+- Every memory is a plain Markdown file you own. AgentMemory's services do not receive memory content, session content, queries, or repository paths. Context you ask AgentMemory to return to a coding agent is then subject to that agent or model provider's data handling.
 
 AgentMemory does not provide a Python SDK, does not provide a vector database, and does not provide a knowledge graph. It is a local Markdown store with a CLI, agent skills, and optional full-text and semantic search via [qmd](https://github.com/tobi/qmd). See [product boundary](docs/product-boundary.md) for full scope.
 
@@ -36,9 +36,9 @@ AgentMemory does not provide a Python SDK, does not provide a vector database, a
 
 **Core remembers what you save. Pro learns from what you do.** Core remains free, MIT-licensed, and useful forever. Pro adds three things:
 
-- **Remember past sessions** — ask *"what did we decide about auth?"* across Claude Code, Codex, and Cursor.
+- **Remember past sessions** — ask *"what did we decide about auth?"* across Claude Code, Codex, and Pi session history. Cursor can use AgentMemory's skills and hooks, but Cursor transcript ingestion is not currently supported.
 - **Learn from your patterns** — turn repeated corrections into memory you can inspect and undo.
-- **Private by default** — memory and session content index locally. Pro installation uses a pseudonymous installation identifier and bounded compatibility metadata, never your memory or session content.
+- **Private by default** — memory and session content index locally. AgentMemory's services receive only a pseudonymous installation identifier and bounded compatibility metadata, never your memory or session content. Recall results provided locally to a coding agent are subject to that agent or model provider's data handling.
 
 Preview what Pro would find in your existing sessions *before* installing anything:
 
@@ -50,7 +50,7 @@ agent-memory learn
 agent-memory dashboard
 ```
 
-Pre-install preview: up to 50 local sessions per day. Free installed preview: 20 recalls + 5 learning scans per local day. Memory, session, query, and repository content stay on your machine; installation sends only a pseudonymous identifier and bounded compatibility metadata. Full detail on [privacy, signing, and installation](docs/official-plugin-bootstrap.md).
+Pre-install preview: up to 50 local sessions per day. Free installed preview: 20 recalls + 5 learning scans per local day. AgentMemory's services do not receive memory, session, query, or repository content; installation sends only a pseudonymous identifier and bounded compatibility metadata. Recall results provided locally to a coding agent are subject to that agent or model provider's data handling. Full detail on [privacy, signing, and installation](docs/official-plugin-bootstrap.md).
 
 ## Installation
 
@@ -59,7 +59,7 @@ Pre-install preview: up to 50 local sessions per day. Free installed preview: 20
 brew tap jayzeng/agentmemory https://github.com/jayzeng/agentmemory
 brew install jayzeng/agentmemory/agent-memory
 
-# Install the portable CLI globally (Node.js 20+; macOS, Linux, or Windows)
+# Install the portable Core CLI globally (Node.js 20+; Pro session recall requires Node.js 22.13+)
 npm install -g myagentmemory
 
 # If corporate TLS inspection requires a private CA, use your organization's CA file:

package/dist/cli-spec.js

@@ -67,7 +67,7 @@ export const PLUGIN_COMMAND_DESCRIPTIONS = {
     install: "authenticate if needed, then install or upgrade the official bundle",
     update: "upgrade an existing official bundle when a compatible release exists",
     uninstall: "remove official plugin executables while preserving user data",
-    manage: "open the AgentMemory account and billing website",
+    manage: "open account management when that future service is available",
 };
 export const WORKER_ACTION_DESCRIPTIONS = {};
 export const SCRATCHPAD_ACTION_DESCRIPTIONS = {

package/dist/cli.js

@@ -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
@@ -1698,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) {
@@ -1852,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("");
 }
@@ -2383,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 {
@@ -3123,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
@@ -3416,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.`);
                     }
                 }
             }

package/dist/mcp-server.d.ts

@@ -17,9 +17,11 @@ export declare class StdioMcpServer {
     private readonly version;
     private readonly tools;
     private readonly startupHooks;
+    private readonly shutdownHooks;
     constructor(version?: string);
     addTool(definition: McpToolDefinition, handler: McpToolHandler): void;
     addStartupHook(fn: () => void | Promise<void>): void;
+    addShutdownHook(fn: () => void | Promise<void>): void;
     start(): Promise<void>;
     private handleMessage;
     private respond;

package/dist/mcp-server.js

@@ -9,6 +9,7 @@ export class StdioMcpServer {
     version;
     tools = new Map();
     startupHooks = [];
+    shutdownHooks = [];
     constructor(version = "0.0.0") {
         this.version = version;
     }
@@ -18,6 +19,9 @@ export class StdioMcpServer {
     addStartupHook(fn) {
         this.startupHooks.push(fn);
     }
+    addShutdownHook(fn) {
+        this.shutdownHooks.push(fn);
+    }
     async start() {
         // Run all startup hooks before entering the message loop.
         for (const hook of this.startupHooks)
@@ -40,6 +44,17 @@ export class StdioMcpServer {
             rl.on("close", resolve);
             process.stdin.on("end", resolve);
         });
+        // A hook may hold resources (e.g. fs.watch handles) that keep the event
+        // loop alive past stdin close — run them, but don't let one broken hook
+        // block the others or block process exit.
+        for (const hook of this.shutdownHooks) {
+            try {
+                await hook();
+            }
+            catch {
+                // Non-fatal — the caller still hard-exits after start() returns.
+            }
+        }
     }
     handleMessage(msg) {
         const id = msg.id;

package/dist/plugin-host.d.ts

@@ -147,7 +147,12 @@ export interface PluginMcpToolInputSchema {
 export interface PluginMcpToolV1 {
     name: string;
     description: string;
-    requiredCapability: string;
+    /**
+     * Capability checked on every invocation. Optional only to keep plugin API 1
+     * source-compatible with bundles built before capability-gated MCP tools
+     * were introduced; legacy tools load but are denied until updated.
+     */
+    requiredCapability?: string;
     inputSchema: PluginMcpToolInputSchema;
     run(input: Record<string, unknown>): unknown | Promise<unknown>;
 }
@@ -160,6 +165,7 @@ export interface AgentMemoryPluginHostV1 {
     registerContextProvider?(provider: PluginContextProviderV1): void;
     registerMcpTool?(tool: PluginMcpToolV1): void;
     registerMcpStartup?(fn: () => void | Promise<void>): void;
+    registerMcpShutdown?(fn: () => void | Promise<void>): void;
     getStateDirectory(): string;
     getMemoryDirectory(): string;
     getEntitlement(): Promise<PluginEntitlementStatusV1>;

package/dist/plugin-runtime.d.ts

@@ -15,6 +15,7 @@ export declare class InstalledPluginRuntimeV1 {
     private readonly contextProviders;
     private readonly mcpTools;
     private readonly mcpStartupHooks;
+    private readonly mcpShutdownHooks;
     private loaded;
     constructor(options: PluginRuntimeOptionsV1);
     load(): Promise<boolean>;
@@ -44,6 +45,7 @@ export declare class InstalledPluginRuntimeV1 {
      */
     runMcpTool(name: string, input: Record<string, unknown>): Promise<unknown>;
     runMcpStartup(): Promise<void>;
+    runMcpShutdown(): Promise<void>;
     private createHost;
     private refreshEntitlement;
 }

package/dist/plugin-runtime.js

@@ -65,6 +65,7 @@ export class InstalledPluginRuntimeV1 {
     contextProviders = [];
     mcpTools = [];
     mcpStartupHooks = [];
+    mcpShutdownHooks = [];
     loaded = false;
     constructor(options) {
         this.options = options;
@@ -200,6 +201,10 @@ export class InstalledPluginRuntimeV1 {
         const tool = this.mcpTools.find((candidate) => candidate.name === name);
         if (!tool)
             return { error: `Unknown MCP tool: ${name}` };
+        if (!tool.requiredCapability)
+            return {
+                error: `The ${name} tool was built for an older plugin API and must be updated before it can run`,
+            };
         const entitlement = await this.refreshEntitlement();
         if (!isPluginCapabilityEnabled(entitlement, tool.requiredCapability))
             return { error: `Capability ${tool.requiredCapability} is not enabled for the ${name} tool` };
@@ -209,6 +214,10 @@ export class InstalledPluginRuntimeV1 {
         for (const hook of this.mcpStartupHooks)
             await hook();
     }
+    async runMcpShutdown() {
+        for (const hook of this.mcpShutdownHooks)
+            await hook();
+    }
     createHost(manifest) {
         const descriptors = new Map(manifest.commands.map((command) => [command.name, command]));
         const stateRoot = path.join(this.store.root, "state");
@@ -257,7 +266,7 @@ export class InstalledPluginRuntimeV1 {
                 this.contextProviders.push({ provider, pluginId: manifest.id });
             },
             registerMcpTool: (tool) => {
-                if (!(manifest.capabilities ?? []).includes(tool.requiredCapability))
+                if (tool.requiredCapability && !(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`);
@@ -266,6 +275,9 @@ export class InstalledPluginRuntimeV1 {
             registerMcpStartup: (fn) => {
                 this.mcpStartupHooks.push(fn);
             },
+            registerMcpShutdown: (fn) => {
+                this.mcpShutdownHooks.push(fn);
+            },
             getStateDirectory: () => stateDirectory,
             getMemoryDirectory: () => {
                 assertPermission(manifest, "memory:read");

package/dist/plugin-service.d.ts

@@ -1,4 +1,4 @@
-import { type PluginAccessDecisionV1, type PluginBootstrapBackendV1, type PluginNextActionV1, type PluginSessionUsageDecisionV1, type SignedPluginReleaseV1 } from "./plugin-bootstrap.js";
+import { type PluginAccessDecisionV1, type PluginBootstrapBackendV1, type PluginNextActionV1, type SignedPluginReleaseV1 } from "./plugin-bootstrap.js";
 import { type PluginEntitlementStatusV1 } from "./plugin-host.js";
 interface AgentMemoryServiceBackendOptions {
     root?: string;
@@ -27,9 +27,6 @@ export declare class AgentMemoryServiceBackend implements PluginBootstrapBackend
         channel: string;
         allowAuthentication: boolean;
     }): Promise<PluginAccessDecisionV1>;
-    reserveSession(operationId: string): Promise<PluginSessionUsageDecisionV1>;
-    commitSession(operationId: string): Promise<PluginSessionUsageDecisionV1>;
-    releaseSession(operationId: string): Promise<PluginSessionUsageDecisionV1>;
     listReleases(request: {
         bundleId: string;
         channel: string;
@@ -43,7 +40,6 @@ export declare class AgentMemoryServiceBackend implements PluginBootstrapBackend
     private activationPath;
     private readActivation;
     private writeActivation;
-    private sessionUsage;
     private request;
 }
 export declare class TemporaryPluginBackend extends AgentMemoryServiceBackend {

package/dist/plugin-service.js

@@ -139,8 +139,8 @@ function activationPage(action, error) {
 			<p class="terminal-note" id="terminal-note">Your terminal will finish setup after activation.</p>
 			<details>
 				<summary>What’s shared during activation</summary>
-				<p>Your email identifies your free daily allowance. The CLI also sends core and bundle versions, platform, architecture, and release channel. The service stores a daily count of opaque session-start operations. Activation records expire after 365 days without use.</p>
-				<p class="never-sent"><strong>Never sent:</strong> The request never includes memory, session content, queries, repository paths, raw agent session identifiers, IP addresses, or user-agent strings.</p>
+				<p>Your email identifies your free daily allowance. The CLI also sends core and bundle versions, platform, architecture, and release channel. The service stores bounded activation metadata. Activation records expire after 365 days without use.</p>
+				<p class="never-sent"><strong>Not included in AgentMemory's application payload:</strong> memory, session content, queries, repository paths, raw agent session identifiers, IP addresses, or user-agent strings.</p>
 			</details>
 		</section>
 	</main>
@@ -394,8 +394,6 @@ export class AgentMemoryServiceBackend {
         validatePluginEntitlementStatusV1(value.entitlement);
         if (typeof value.artifactGrant !== "string" || !value.artifactGrant)
             throw new PluginBootstrapFailure("service_response_invalid", "The access response omitted its artifact grant");
-        if (typeof value.usageCredential !== "string" || !ACTIVATION_CREDENTIAL.test(value.usageCredential))
-            throw new PluginBootstrapFailure("service_response_invalid", "The access response omitted its usage credential");
         const recallQuota = value.entitlement.capabilities.recall?.quota;
         const learningQuota = value.entitlement.capabilities.learning?.quota;
         if (value.entitlement.plan !== "free" ||
@@ -408,18 +406,9 @@ export class AgentMemoryServiceBackend {
             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);
+        this.writeActivation(installationId);
         return { kind: "granted", entitlement: value.entitlement, artifactGrant: value.artifactGrant };
     }
-    async reserveSession(operationId) {
-        return this.sessionUsage("reserve", operationId);
-    }
-    async commitSession(operationId) {
-        return this.sessionUsage("commit", operationId);
-    }
-    async releaseSession(operationId) {
-        return this.sessionUsage("release", operationId);
-    }
     async listReleases(request) {
         const response = await this.request(`${this.apiOrigin}/v1/plugin/releases`, {
             headers: { Authorization: `Bearer ${request.artifactGrant}` },
@@ -474,28 +463,28 @@ export class AgentMemoryServiceBackend {
             if (!stat.isFile() || stat.isSymbolicLink() || (process.platform !== "win32" && (stat.mode & 0o077) !== 0))
                 return null;
             const value = JSON.parse(fs.readFileSync(activationPath, "utf-8"));
-            if (value.schemaVersion !== 3 ||
-                typeof value.installationId !== "string" ||
+            if (typeof value.installationId !== "string" ||
                 !/^am_install_[A-Za-z0-9_-]{32}$/.test(value.installationId) ||
                 !Number.isFinite(Date.parse(value.activatedAt)) ||
-                !ACTIVATION_CREDENTIAL.test(value.usageCredential) ||
-                !Number.isSafeInteger(value.dailySessionLimit) ||
-                value.dailySessionLimit <= 0 ||
-                value.dailySessionLimit > 10_000)
+                (value.schemaVersion !== 4 &&
+                    (value.schemaVersion !== 3 ||
+                        typeof value.usageCredential !== "string" ||
+                        !ACTIVATION_CREDENTIAL.test(value.usageCredential) ||
+                        !Number.isSafeInteger(value.dailySessionLimit))))
                 return null;
-            return value;
+            return {
+                schemaVersion: 4,
+                installationId: value.installationId,
+                activatedAt: value.activatedAt,
+            };
         }
         catch {
             return null;
         }
     }
-    writeActivation(installationId, usageCredential, dailySessionLimit) {
+    writeActivation(installationId) {
         if (!/^am_install_[A-Za-z0-9_-]{32}$/.test(installationId))
             throw new PluginBootstrapFailure("activation_failed", "The installation identifier is invalid");
-        if (!ACTIVATION_CREDENTIAL.test(usageCredential))
-            throw new PluginBootstrapFailure("activation_failed", "The activation credential is invalid");
-        if (!Number.isSafeInteger(dailySessionLimit) || dailySessionLimit <= 0 || dailySessionLimit > 10_000)
-            throw new PluginBootstrapFailure("activation_failed", "The free session allowance is invalid");
         const target = this.activationPath();
         fs.mkdirSync(this.root, { recursive: true, mode: 0o700 });
         const rootStat = fs.lstatSync(this.root);
@@ -509,43 +498,12 @@ export class AgentMemoryServiceBackend {
             throw new PluginBootstrapFailure("activation_path_invalid", "The plugin activation directory is unsafe");
         const temporary = `${target}.tmp-${process.pid}-${randomUUID()}`;
         fs.writeFileSync(temporary, `${JSON.stringify({
-            schemaVersion: 3,
+            schemaVersion: 4,
             installationId,
             activatedAt: new Date().toISOString(),
-            usageCredential,
-            dailySessionLimit,
         }, null, 2)}\n`, { mode: 0o600, flag: "wx" });
         fs.renameSync(temporary, target);
     }
-    async sessionUsage(action, operationId) {
-        const activation = this.readActivation();
-        if (!activation)
-            throw new PluginBootstrapFailure("auth_required", "Run plugin install to activate AgentMemory");
-        const response = await this.request(`${this.apiOrigin}/v1/plugin/sessions/${action}`, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${activation.usageCredential}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({ schemaVersion: 1, operationId }),
-        });
-        const value = (await readJson(response));
-        const decision = value.decision;
-        if (!decision ||
-            typeof decision.allowed !== "boolean" ||
-            !["reserved", "committed", "released", "exhausted", "missing"].includes(String(decision.state)) ||
-            !Number.isSafeInteger(decision.limit) ||
-            Number(decision.limit) <= 0 ||
-            !Number.isSafeInteger(decision.used) ||
-            Number(decision.used) < 0 ||
-            !Number.isSafeInteger(decision.remaining) ||
-            Number(decision.remaining) < 0 ||
-            typeof decision.resetAt !== "string" ||
-            !Number.isFinite(Date.parse(decision.resetAt)) ||
-            typeof decision.idempotent !== "boolean")
-            throw new PluginBootstrapFailure("service_response_invalid", "The session usage response is invalid");
-        return decision;
-    }
     async request(url, init = {}) {
         let response;
         try {

package/dist/upgrade.d.ts

@@ -15,7 +15,7 @@
  * retried before the next cache refresh, and never thrown.
  */
 import { type SpawnOptions } from "node:child_process";
-export type InstallManager = "bun" | "npm" | "pnpm" | "yarn" | "unknown";
+export type InstallManager = "bun" | "homebrew" | "npm" | "pnpm" | "yarn" | "unknown";
 export interface InstallMethod {
     manager: InstallManager;
     global: boolean;
@@ -77,6 +77,14 @@ export declare function readUpgradePolicy(): UpgradePolicy & {
 };
 /** Atomically persist the auto-upgrade policy. Merges with whatever is already on disk. */
 export declare function writeUpgradePolicy(patch: Partial<UpgradePolicy>): UpgradePolicy;
+export declare function resolveSelfLaunch(input: {
+    execPath: string;
+    scriptCandidate: string | undefined;
+    fileExists: (candidate: string) => boolean;
+}): {
+    command: string;
+    args: string[];
+};
 /**
  * Best-effort detection of how `myagentmemory` was installed. Path signatures
  * are heuristic but cover the common managers. On no match we fall back to

package/dist/upgrade.js

@@ -167,12 +167,34 @@ export function writeUpgradePolicy(patch) {
 // ---------------------------------------------------------------------------
 // Install-method detection
 // ---------------------------------------------------------------------------
+export function resolveSelfLaunch(input) {
+    const scriptCandidate = input.scriptCandidate;
+    const isRealScript = typeof scriptCandidate === "string" &&
+        scriptCandidate.length > 0 &&
+        !scriptCandidate.startsWith("/$bunfs/") &&
+        input.fileExists(scriptCandidate);
+    return isRealScript ? { command: input.execPath, args: [scriptCandidate] } : { command: input.execPath, args: [] };
+}
+function currentSelfLaunch() {
+    return resolveSelfLaunch({
+        execPath: process.execPath,
+        scriptCandidate: process.argv[1],
+        fileExists: fs.existsSync,
+    });
+}
 function selfInstallPath() {
+    const launch = currentSelfLaunch();
+    const candidate = launch.args[0] ?? launch.command;
     try {
-        return url.fileURLToPath(import.meta.url);
+        return fs.realpathSync(candidate);
     }
     catch {
-        return process.argv[1] ?? "";
+        try {
+            return url.fileURLToPath(import.meta.url);
+        }
+        catch {
+            return candidate;
+        }
     }
 }
 /**
@@ -184,6 +206,16 @@ export function detectInstallMethod(location = selfInstallPath()) {
     const normalized = location.replace(/\\/g, "/");
     const home = os.homedir().replace(/\\/g, "/");
     const pkg = `${NPM_PACKAGE_NAME}@latest`;
+    // Compiled CLI installed by the official Homebrew formula. Resolve symlinks
+    // before detection so /opt/homebrew/bin/agent-memory reaches its Cellar path.
+    if (normalized.includes("/Cellar/agent-memory/")) {
+        return {
+            manager: "homebrew",
+            global: true,
+            origin: location,
+            command: ["brew", "upgrade", "jayzeng/agentmemory/agent-memory"],
+        };
+    }
     // bun global install
     if (normalized.includes("/.bun/install/global/") || normalized.includes("/bun/install/global/")) {
         return { manager: "bun", global: true, origin: location, command: ["bun", "add", "-g", pkg] };
@@ -241,11 +273,10 @@ export function runInstaller(method, opts = {}) {
  */
 export function refreshUpgradeCacheBackground() {
     try {
-        const binary = process.argv[0];
-        const script = process.argv[1];
-        if (!binary || !script)
+        const launch = currentSelfLaunch();
+        if (!launch.command)
             return;
-        const child = spawn(binary, [script, "upgrade", "--background", "--refresh", "--quiet", "--json"], {
+        const child = spawn(launch.command, [...launch.args, "upgrade", "--background", "--refresh", "--quiet", "--json"], {
             detached: true,
             stdio: "ignore",
             env: { ...process.env, AGENT_MEMORY_UPGRADE_BACKGROUND: "1" },

package/docs/official-plugin-bootstrap.md

@@ -89,7 +89,7 @@ The `pro` namespace is the user-facing surface. The `plugin` namespace remains s
 - `status` is read-only. It reports the installed bundle, selected channel, compatibility, entitlement state, and update availability.
 - `install` authenticates when necessary, then installs, upgrades, or reports current state.
 - `update` requires an existing installation and never starts a new purchase implicitly.
-- `uninstall` removes executable plugin material and the active receipt. It preserves core memory, plugin state, and the permission-restricted activation credential.
+- `uninstall` removes executable plugin material and the active receipt. It preserves core memory, plugin state, and the permission-restricted local activation record.
 - `manage` remains unavailable until authenticated account and billing management exists.
 
 Installed plugins contribute top-level commands including `recall` and `learn`; `dashboard` is a product-facing alias for the lower-level `web` command. Bootstrap command names are reserved by the core and cannot be replaced by a plugin.
@@ -172,7 +172,6 @@ An Enterprise administrator may pre-provision an organization entitlement or man
 The service exposes:
 
 - `POST /v1/plugin/access` for an anonymous free-preview policy, compatibility credential, and short-lived artifact grant;
-- `POST /v1/plugin/sessions/reserve|commit|release` for migration compatibility with activation-v2 clients;
 - `GET /v1/plugin/releases` for an Ed25519-signed release selected from the private R2 catalog;
 - `GET|HEAD /v1/artifacts/download` for the exact content-addressed object authorized by the bearer grant.
 
@@ -191,7 +190,7 @@ The bootstrap may send only:
 - core version, plugin-host API version, platform, and architecture;
 - requested bundle ID, installed bundle version, and release channel;
 - a pseudonymous license or organization identifier;
-- protocol nonces, opaque quota operation IDs, and authentication material required for the request.
+- protocol nonces and authentication material required for the request.
 
 It must never send memory contents, search queries, session contents, raw agent session identifiers, working-directory names, repository names, filesystem paths, or qmd data. The bounded allowance counter is authorization state, not general product telemetry.
 
@@ -267,7 +266,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. 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.
+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 local activation 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 activation state) once the user opts in and confirms.
 
 ## Plugin host API v1
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "myagentmemory",
-	"version": "0.5.3",
+	"version": "0.5.4",
 	"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",
@@ -93,7 +93,6 @@
 		"dist/plugin-runtime.js",
 		"dist/plugin-service.d.ts",
 		"dist/plugin-service.js",
-
 		"dist/mcp-server.d.ts",
 		"dist/mcp-server.js",
 		"dist/upgrade.d.ts",

package/src/cli-spec.ts

@@ -82,7 +82,7 @@ export const PLUGIN_COMMAND_DESCRIPTIONS: Record<(typeof PLUGIN_COMMANDS)[number
 	install: "authenticate if needed, then install or upgrade the official bundle",
 	update: "upgrade an existing official bundle when a compatible release exists",
 	uninstall: "remove official plugin executables while preserving user data",
-	manage: "open the AgentMemory account and billing website",
+	manage: "open account management when that future service is available",
 };
 
 export const WORKER_ACTION_DESCRIPTIONS: Record<(typeof WORKER_ACTIONS)[number], string> = {};

package/src/plugin-host.ts

@@ -176,7 +176,12 @@ export interface PluginMcpToolInputSchema {
 export interface PluginMcpToolV1 {
 	name: string;
 	description: string;
-	requiredCapability: string;
+	/**
+	 * Capability checked on every invocation. Optional only to keep plugin API 1
+	 * source-compatible with bundles built before capability-gated MCP tools
+	 * were introduced; legacy tools load but are denied until updated.
+	 */
+	requiredCapability?: string;
 	inputSchema: PluginMcpToolInputSchema;
 	run(input: Record<string, unknown>): unknown | Promise<unknown>;
 }
@@ -190,6 +195,7 @@ export interface AgentMemoryPluginHostV1 {
 	registerContextProvider?(provider: PluginContextProviderV1): void;
 	registerMcpTool?(tool: PluginMcpToolV1): void;
 	registerMcpStartup?(fn: () => void | Promise<void>): void;
+	registerMcpShutdown?(fn: () => void | Promise<void>): void;
 	getStateDirectory(): string;
 	getMemoryDirectory(): string;
 	getEntitlement(): Promise<PluginEntitlementStatusV1>;