myagentmemory 0.4.14 → 0.4.15

package/README.md

@@ -30,7 +30,7 @@ AgentMemory is free, open-source software under the MIT License. The core is a l
 
 ### Optional official plugins
 
-The MIT-licensed core can discover and host separately distributed, signed first-party plugins while remaining fully useful on its own. Optional plugins may use their own license and distribution terms; their implementation and browser assets are not part of the `myagentmemory` package. `agent-memory plugin list` and `plugin status` report local state. In an interactive terminal, `agent-memory plugin install` opens a nonce-bound loopback page for an email address, resumes the waiting command, verifies signed release metadata and the downloaded bundle, and installs atomically. This temporary beta grants unlimited local use. The email remains in a mode-0600 local activation record and is also sent with bounded activation metadata to the private commercial service; memory, sessions, queries, repository paths, IP addresses, and user-agent strings are not stored in the activation database. Authentication and payment will replace this temporary flow later. See the [official plugin bootstrap and host contract](docs/official-plugin-bootstrap.md).
+The MIT-licensed core can discover and host separately distributed, signed first-party plugins while remaining fully useful on its own. Optional plugins may use their own license and distribution terms; their implementation and browser assets are not part of the `myagentmemory` package. `agent-memory plugin list` and `plugin status` report local state. In an interactive terminal, `agent-memory plugin install` opens a nonce-bound loopback page for an email address, resumes the waiting command, verifies signed release metadata and the downloaded bundle, and installs atomically. The free plan uses a configurable daily agent-session allowance keyed by normalized email. D1 stores bounded activation metadata, a credential hash, and opaque SessionStart usage operations; it never receives memory, session content, queries, repository paths, raw agent session identifiers, IP addresses, or user-agent strings. Authentication and payment can extend this free activation flow later. See the [official plugin bootstrap and host contract](docs/official-plugin-bootstrap.md).
 
 ## Installation
 

package/dist/cli.js

@@ -178,7 +178,7 @@ function printPluginResult(result, json, allowBrowser) {
                 console.log("Run: agent-memory plugin install");
                 break;
             case "auth_required":
-                console.log("Run this command in an interactive terminal to enter an email and activate temporary access.");
+                console.log("Run this command in an interactive terminal to enter an email and activate free daily access.");
                 break;
             case "renewal_required":
                 console.log("Renew AgentMemory Pro to continue using paid capabilities.");
@@ -893,8 +893,8 @@ Usage:
   agent-memory plugin manage [--no-browser]
 
 The public core remains fully usable without AgentMemory Pro. Interactive install
-opens a loopback website for temporary email activation and unlimited local use.
-Authentication and payment will be added later.`);
+opens a loopback website for email activation and a configurable free daily
+agent-session allowance. Memory and session content stay on this device.`);
 }
 function pluginCommandFailure(command, error) {
     return {
@@ -1099,6 +1099,18 @@ async function main() {
             if (!agent)
                 exitError("hook session-start requires --agent", json);
             await cmdContext({ "no-search": true });
+            try {
+                const decision = await new InstalledPluginRuntimeV1({ coreVersion: VERSION }).runSessionStart({
+                    host: agent,
+                    cwd: process.cwd(),
+                    signal: new AbortController().signal,
+                });
+                if (decision?.state === "exhausted")
+                    console.error(`AgentMemory free session allowance resets at ${decision.resetAt}`);
+            }
+            catch {
+                // Paid SessionStart work must never make public-core context unavailable.
+            }
             break;
         }
         case "plugin":

package/dist/plugin-bootstrap.d.ts

@@ -13,6 +13,15 @@ export interface PluginNextActionV1 {
     userCode?: string;
     message?: string;
 }
+export interface PluginSessionUsageDecisionV1 {
+    allowed: boolean;
+    state: "reserved" | "committed" | "released" | "exhausted" | "missing";
+    limit: number;
+    used: number;
+    remaining: number;
+    resetAt: string;
+    idempotent: boolean;
+}
 export interface PluginInstallReceiptV1 {
     schemaVersion: 1;
     bundleId: string;
@@ -105,6 +114,9 @@ export interface PluginBootstrapBackendV1 {
         release: SignedPluginReleaseV1;
         artifactGrant: string;
     }): Promise<Uint8Array>;
+    reserveSession?(operationId: string): Promise<PluginSessionUsageDecisionV1>;
+    commitSession?(operationId: string): Promise<PluginSessionUsageDecisionV1>;
+    releaseSession?(operationId: string): Promise<PluginSessionUsageDecisionV1>;
     getManagementAction(): Promise<PluginNextActionV1 | null>;
 }
 export interface PluginReleaseVerifierV1 {

package/dist/plugin-host.d.ts

@@ -5,7 +5,7 @@ export type PluginPlanV1 = "free" | "trial" | "pro" | "team" | "enterprise";
 export interface PluginCapabilityQuotaV1 {
     limit: number;
     window: "day";
-    scope: "device";
+    scope: "device" | "account";
 }
 export interface PluginCapabilityGrantV1 {
     enabled: boolean;

package/dist/plugin-host.js

@@ -61,7 +61,7 @@ export function validatePluginEntitlementStatusV1(entitlement) {
         if (grant.quota) {
             if (!Number.isInteger(grant.quota.limit) || grant.quota.limit <= 0)
                 throw new Error(`Capability ${capability} has an invalid quota limit`);
-            if (grant.quota.window !== "day" || grant.quota.scope !== "device")
+            if (grant.quota.window !== "day" || !["device", "account"].includes(grant.quota.scope))
                 throw new Error(`Capability ${capability} has an invalid quota policy`);
         }
     }

package/dist/plugin-runtime.d.ts

@@ -1,5 +1,5 @@
-import { type PluginBootstrapBackendV1, type PluginInstallStoreV1, type SignedPluginReleaseV1 } from "./plugin-bootstrap.js";
-import { type PluginCommandContextV1, type PluginCommandResultV1 } from "./plugin-host.js";
+import { type PluginBootstrapBackendV1, type PluginInstallStoreV1, type PluginSessionUsageDecisionV1, type SignedPluginReleaseV1 } from "./plugin-bootstrap.js";
+import { type PluginCommandContextV1, type PluginCommandResultV1, type PluginSessionStartHookV1 } from "./plugin-host.js";
 export interface PluginRuntimeOptionsV1 {
     coreVersion: string;
     store?: PluginInstallStoreV1;
@@ -15,6 +15,7 @@ export declare class InstalledPluginRuntimeV1 {
     constructor(options: PluginRuntimeOptionsV1);
     load(): Promise<boolean>;
     run(name: string, context: PluginCommandContextV1): Promise<PluginCommandResultV1 | null>;
+    runSessionStart(context: Parameters<PluginSessionStartHookV1["run"]>[0]): Promise<PluginSessionUsageDecisionV1 | null>;
     private createHost;
     private refreshEntitlement;
 }

package/dist/plugin-runtime.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -102,6 +103,35 @@ export class InstalledPluginRuntimeV1 {
             };
         return registered.command.run(context);
     }
+    async runSessionStart(context) {
+        if (!(await this.load()) || this.hooks.length === 0)
+            return null;
+        const entitlement = await this.refreshEntitlement();
+        const eligible = this.hooks.filter((hook) => isPluginCapabilityEnabled(entitlement, hook.requiredCapability));
+        if (eligible.length === 0)
+            return null;
+        const metered = eligible.some((hook) => entitlement.capabilities[hook.requiredCapability]?.quota?.scope === "account");
+        if (!metered) {
+            for (const hook of eligible)
+                await hook.run(context);
+            return null;
+        }
+        if (!this.backend.reserveSession || !this.backend.commitSession || !this.backend.releaseSession)
+            throw new PluginBootstrapFailure("session_usage_unavailable", "Account session metering is unavailable");
+        const operationId = randomUUID();
+        const reservation = await this.backend.reserveSession(operationId);
+        if (!reservation.allowed)
+            return reservation;
+        try {
+            for (const hook of eligible)
+                await hook.run(context);
+            return await this.backend.commitSession(operationId);
+        }
+        catch (error) {
+            await this.backend.releaseSession(operationId);
+            throw error;
+        }
+    }
     createHost(manifest) {
         const descriptors = new Map(manifest.commands.map((command) => [command.name, command]));
         const stateRoot = path.join(this.store.root, "state");

package/dist/plugin-service.d.ts

@@ -1,4 +1,4 @@
-import { type PluginAccessDecisionV1, type PluginBootstrapBackendV1, type PluginNextActionV1, type SignedPluginReleaseV1 } from "./plugin-bootstrap.js";
+import { type PluginAccessDecisionV1, type PluginBootstrapBackendV1, type PluginNextActionV1, type PluginSessionUsageDecisionV1, type SignedPluginReleaseV1 } from "./plugin-bootstrap.js";
 import { type PluginEntitlementStatusV1 } from "./plugin-host.js";
 interface TemporaryPluginBackendOptions {
     root?: string;
@@ -27,6 +27,9 @@ export declare class TemporaryPluginBackend implements PluginBootstrapBackendV1
         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;
@@ -40,6 +43,7 @@ export declare class TemporaryPluginBackend implements PluginBootstrapBackendV1
     private activationPath;
     private readActivation;
     private writeActivation;
+    private sessionUsage;
     private request;
 }
 export {};

package/dist/plugin-service.js

@@ -12,31 +12,37 @@ const REQUEST_TIMEOUT_MS = 30_000;
 const EMAIL_MAX_BYTES = 254;
 const FORM_MAX_BYTES = 2_048;
 const SERVICE_JSON_MAX_BYTES = 1024 * 1024;
+const ACTIVATION_CREDENTIAL = /^am_activation_[A-Za-z0-9_-]{32,256}$/;
 const MISSING_ENTITLEMENT = {
     plan: null,
     state: "missing",
     features: [],
     capabilities: {},
-    reason: "Enter an email address to activate temporary unlimited local use",
-};
-const TEMPORARY_ENTITLEMENT = {
-    plan: "pro",
-    state: "active",
-    features: ["session-intelligence", "web-console"],
-    capabilities: Object.fromEntries([
-        "session-index",
-        "session-worker",
-        "learning",
-        "retrieval-evaluation",
-        "operational-metrics",
-        "web-console",
-        "memory-explorer",
-    ].map((capability) => [capability, { enabled: true }])),
-    reason: "Temporary email activation grants unlimited local use",
+    reason: "Enter an email address to activate the free daily session allowance",
 };
 function cloneEntitlement(value) {
     return structuredClone(value);
 }
+function freeEntitlement(dailySessionLimit) {
+    return {
+        plan: "free",
+        state: "active",
+        features: ["session-intelligence", "web-console"],
+        capabilities: {
+            "session-index": { enabled: true },
+            "session-worker": {
+                enabled: true,
+                quota: { limit: dailySessionLimit, window: "day", scope: "account" },
+            },
+            learning: { enabled: true },
+            "retrieval-evaluation": { enabled: true },
+            "operational-metrics": { enabled: true },
+            "web-console": { enabled: true },
+            "memory-explorer": { enabled: true },
+        },
+        reason: `${dailySessionLimit} free agent sessions per UTC day`,
+    };
+}
 function isEmail(value) {
     return (Buffer.byteLength(value, "utf-8") <= EMAIL_MAX_BYTES &&
         [...value].every((character) => character.charCodeAt(0) >= 32 && character.charCodeAt(0) !== 127) &&
@@ -53,7 +59,7 @@ function securityHeaders(contentType) {
 }
 function activationPage(action, error) {
     const errorHtml = error ? `<p class="error">${error}</p>` : "";
-    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Activate AgentMemory Pro</title><style>body{font:16px system-ui;max-width:34rem;margin:10vh auto;padding:0 1.5rem;color:#18212b}form{display:grid;gap:1rem}input,button{font:inherit;padding:.8rem;border-radius:.5rem;border:1px solid #aab4bf}button{background:#18212b;color:#fff;cursor:pointer}.muted{color:#586574}.error{color:#a21d24}</style></head><body><h1>Activate AgentMemory Pro</h1><p>Enter an email address to enable temporary unlimited use on this device.</p>${errorHtml}<form method="post" action="${action}"><label>Email <input type="email" name="email" autocomplete="email" maxlength="254" required autofocus></label><button type="submit">Activate and return to terminal</button></form><p class="muted">The AgentMemory CLI sends your email plus core, bundle, platform, architecture, and release-channel metadata to the private activation service. The activation record never includes memory, session content, queries, repository paths, IP addresses, or user-agent strings, and expires after 365 days without activation.</p></body></html>`;
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Activate AgentMemory</title><style>body{font:16px system-ui;max-width:34rem;margin:10vh auto;padding:0 1.5rem;color:#18212b}form{display:grid;gap:1rem}input,button{font:inherit;padding:.8rem;border-radius:.5rem;border:1px solid #aab4bf}button{background:#18212b;color:#fff;cursor:pointer}.muted{color:#586574}.error{color:#a21d24}</style></head><body><h1>Activate AgentMemory</h1><p>Enter an email address to enable the free daily agent-session allowance on this device.</p>${errorHtml}<form method="post" action="${action}"><label>Email <input type="email" name="email" autocomplete="email" maxlength="254" required autofocus></label><button type="submit">Activate and return to terminal</button></form><p class="muted">The AgentMemory CLI sends your email plus core, bundle, platform, architecture, and release-channel metadata to the private activation service. D1 stores a daily count of opaque SessionStart operations for your normalized email. The request never includes memory, session content, queries, repository paths, raw agent session identifiers, IP addresses, or user-agent strings. Activation records expire after 365 days without use.</p></body></html>`;
 }
 function completionPage() {
     return '<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>AgentMemory activated</title></head><body><h1>Activation complete</h1><p>You can close this tab and return to the terminal.</p></body></html>';
@@ -253,11 +259,13 @@ export class TemporaryPluginBackend {
         this.activate = options.activate ?? (() => collectTemporaryActivation(this.openUrl));
     }
     async getLocalEntitlement() {
-        return this.readActivation() ? cloneEntitlement(TEMPORARY_ENTITLEMENT) : cloneEntitlement(MISSING_ENTITLEMENT);
+        const activation = this.readActivation();
+        return activation ? freeEntitlement(activation.dailySessionLimit) : cloneEntitlement(MISSING_ENTITLEMENT);
     }
     async resolveAccess(request) {
-        let activation = this.readActivation();
-        if (!activation) {
+        const activation = this.readActivation();
+        let email = activation?.email;
+        if (!email) {
             if (!request.allowAuthentication)
                 return {
                     kind: "auth_required",
@@ -268,33 +276,48 @@ export class TemporaryPluginBackend {
                         message: "Run plugin install in an interactive terminal to enter an email address",
                     },
                 };
-            const email = await this.activate();
-            this.writeActivation(email);
-            activation = this.readActivation();
+            email = await this.activate();
         }
-        if (!activation)
-            throw new PluginBootstrapFailure("activation_failed", "The local activation record could not be loaded");
         const response = await this.request(`${this.apiOrigin}/v1/plugin/access`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
                 schemaVersion: 1,
-                email: activation.email,
+                email,
                 bundleId: request.bundleId,
                 installedVersion: request.installedVersion ?? null,
                 coreVersion: this.coreVersion,
                 channel: request.channel,
                 platform: process.platform,
                 architecture: process.arch,
-                consentVersion: "activation-v1",
+                consentVersion: "activation-v2",
             }),
         });
         const value = (await readJson(response));
         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 freeQuota = value.entitlement.capabilities["session-worker"]?.quota;
+        if (value.entitlement.plan !== "free" ||
+            value.entitlement.state !== "active" ||
+            !freeQuota ||
+            freeQuota.scope !== "account" ||
+            freeQuota.window !== "day")
+            throw new PluginBootstrapFailure("service_response_invalid", "The free session policy is invalid");
+        this.writeActivation(email, value.usageCredential, freeQuota.limit);
         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}` },
@@ -338,17 +361,27 @@ export class TemporaryPluginBackend {
             if (!stat.isFile() || stat.isSymbolicLink() || (process.platform !== "win32" && (stat.mode & 0o077) !== 0))
                 return null;
             const value = JSON.parse(fs.readFileSync(activationPath, "utf-8"));
-            return value.schemaVersion === 1 && isEmail(value.email) && Number.isFinite(Date.parse(value.activatedAt))
-                ? value
-                : null;
+            if (value.schemaVersion !== 2 ||
+                !isEmail(value.email) ||
+                !Number.isFinite(Date.parse(value.activatedAt)) ||
+                !ACTIVATION_CREDENTIAL.test(value.usageCredential) ||
+                !Number.isSafeInteger(value.dailySessionLimit) ||
+                value.dailySessionLimit <= 0 ||
+                value.dailySessionLimit > 10_000)
+                return null;
+            return value;
         }
         catch {
             return null;
         }
     }
-    writeActivation(email) {
+    writeActivation(email, usageCredential, dailySessionLimit) {
         if (!isEmail(email))
             throw new PluginBootstrapFailure("email_invalid", "Enter a valid email address");
+        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);
@@ -361,9 +394,38 @@ export class TemporaryPluginBackend {
         if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink())
             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: 1, email, activatedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+        fs.writeFileSync(temporary, `${JSON.stringify({ schemaVersion: 2, email, 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/docs/official-plugin-bootstrap.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Accepted design on 2026-08-16. The public core now implements host types, temporary loopback activation, live catalog and artifact retrieval, Ed25519 release verification, bounded package validation, transactional install, bundle health checks, and paid-command dispatch. The temporary beta grants unlimited local use after email entry; durable authentication, payment, renewal, and account management remain deferred.
+Accepted design on 2026-08-16 and revised on 2026-08-17. The public core implements host types, loopback email activation, live catalog and artifact retrieval, Ed25519 release verification, bounded package validation, transactional install, bundle health checks, paid-command dispatch, and SessionStart hook dispatch. The free plan grants a configurable number of agent sessions per normalized email and UTC day; durable account authentication, payment, renewal, and account management remain deferred.
 
 The public `agentmemory` repository and `myagentmemory` npm package remain the free, MIT-licensed core. The public bootstrap client and host contracts are also MIT-licensed. Official commercial implementations and browser assets are built and distributed separately from the private `agent-memory-plugin` workspace under their own terms. Pricing, the billing provider, device limits, offline-grace duration, and Enterprise contract terms are intentionally not decided here. The temporary beta currently uses allowlisted `*.agentmemory.paperpilot.me` service origins; changing those origins is a public-client release change.
 
@@ -23,11 +23,11 @@ agent-memory plugin install
 | Plugin absent | Active or grace | Install the compatible signed bundle |
 | Plugin older than the selected release | Active or grace | Upgrade atomically |
 | Plugin current | Active or grace | Report that it is current |
-| Any | Missing | Start temporary loopback email activation in an interactive terminal |
+| Any | Missing | Start loopback email activation in an interactive terminal |
 | Any | Expired | Direct the user to renewal; leave core available |
 | Incompatible bundle | Any | Leave the current version untouched and explain the required core version |
 
-An absent plugin cannot activate itself. The public bootstrap performs temporary local activation, obtains a short-lived artifact grant, and verifies the release and artifact. After installation, the public host validates the local activation record and checks the required capability before every paid command. Signed long-lived entitlements will replace this temporary record when authentication and payment ship.
+An absent plugin cannot activate itself. The public bootstrap collects an email locally, obtains a server-issued usage credential and short-lived artifact grant, and verifies the release and artifact. The credential is persisted only after the service accepts activation. After installation, the public host reconstructs the free account-metered capability policy in core code and checks required capabilities before commands and hooks. Signed long-lived entitlements can extend this credential when authentication and payment ship.
 
 ## Ownership boundary
 
@@ -81,7 +81,7 @@ agent-memory plugin manage [--no-browser]
 - `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 temporary activation record.
+- `uninstall` removes executable plugin material and the active receipt. It preserves core memory, plugin state, and the permission-restricted activation credential.
 - `manage` remains unavailable until authenticated account and billing management exists.
 
 Installed plugins contribute top-level commands such as `recall`, `learn`, `worker`, and `web`. Bootstrap command names are reserved by the core and cannot be replaced by a plugin.
@@ -133,16 +133,17 @@ Every bootstrap command supports `--json` and emits one JSON document with a ver
 
 `result` is one of `not_installed`, `installed`, `upgraded`, `current`, `update_available`, `uninstalled`, `auth_required`, `renewal_required`, or `unavailable`. Failures use `ok: false` plus a stable `error.code` and redacted `error.message`. Output must never contain access tokens, download credentials, signed entitlement contents, local memory paths, or URLs containing bearer credentials.
 
-## Temporary activation flow
+## Free activation flow
 
 1. `agent-memory plugin install` starts an HTTP server bound to `127.0.0.1` on an ephemeral port.
 2. The CLI prints and opens a nonce-bearing local URL. The page accepts one email address with bounded input, an exact Host and nonce path, same-origin browser request validation, restrictive response headers, and a five-minute deadline.
-3. Submission writes a mode-0600 record under the plugin install root and returns a completion page.
-4. The waiting CLI sends the email plus core, installed-bundle, platform, architecture, release-channel, and consent-version fields to the private control plane. Its activation database stores none of the user's memory, sessions, queries, repository paths, IP address, or user-agent string, and deletes records after 365 days without activation.
-5. The CLI requests temporary unlimited capabilities and a short-lived object-bound artifact grant, verifies the Ed25519-signed release plus package digest and limits, imports it for health checks, then atomically activates the receipt.
-6. Installed paid commands reload the local entitlement and enforce their declared capability before execution.
+3. Submission returns a completion page but does not create a local credential yet.
+4. The waiting CLI sends the email plus core, installed-bundle, platform, architecture, release-channel, and consent-version fields to the private control plane. Its activation database stores none of the user's memory, session content, queries, repository paths, raw agent session identifiers, IP address, or user-agent string.
+5. The service normalizes the email, stores only a hash of a random usage credential, and returns the credential, a free account-metered entitlement, and a short-lived object-bound artifact grant. Only then does the CLI atomically write a mode-0600 activation record.
+6. The CLI verifies the Ed25519-signed release plus package digest and limits, imports it for health checks, and atomically activates the receipt.
+7. Each paid SessionStart hook reserves one opaque operation against the email's UTC-day allowance, commits after useful hook work, and releases on failure. Exhaustion skips paid hook work without affecting public-core context.
 
-This is explicitly temporary. Authentication, payment, renewal, account management, server-side entitlement state, and durable credential storage are not implemented yet.
+Email ownership is not verified in this free flow. Authentication, payment, renewal, account management, and signed paid entitlements are not implemented yet.
 
 ## Future authentication and purchase flow
 
@@ -160,13 +161,14 @@ An Enterprise administrator may pre-provision an organization entitlement or man
 
 ## Control-plane boundary
 
-The temporary service exposes:
+The service exposes:
 
-- `POST /v1/plugin/access` for unlimited temporary capability grants plus a short-lived artifact grant;
+- `POST /v1/plugin/access` for a free account-metered entitlement, a usage credential, and a short-lived artifact grant;
+- `POST /v1/plugin/sessions/reserve|commit|release` for atomic daily allowance enforcement;
 - `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.
 
-The temporary access request contains the submitted email plus the bounded core, bundle, platform, architecture, release-channel, and consent-version fields described above. Its application payload contains no memory content, search query, session content, path, repository name, qmd data, IP address, user-agent string, or plugin-derived metric; the activation database stores neither IP addresses nor user-agent strings. Future authenticated service responsibilities include:
+The access request contains the submitted email plus the bounded core, bundle, platform, architecture, release-channel, and consent-version fields described above. Session metering sends only a random operation ID and bearer credential; D1 associates those values with a normalized email and UTC-day counter. Application payloads contain no memory content, search query, session content, path, repository name, raw agent session identifier, qmd data, IP address, or user-agent string. The activation database stores neither IP addresses nor user-agent strings. Future authenticated service responsibilities include:
 
 - create and poll a device authorization;
 - read the authenticated principal's effective entitlement;
@@ -181,9 +183,9 @@ 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 and authentication material required for the request.
+- protocol nonces, opaque quota operation IDs, and authentication material required for the request.
 
-It must never send memory contents, search queries, session contents, working-directory names, repository names, filesystem paths, qmd data, or plugin-derived metrics. Product telemetry is not part of this protocol.
+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.
 
 Production builds use an allowlisted HTTPS origin. Development endpoint overrides must be explicit, must not silently affect production builds, and must never weaken TLS verification.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "myagentmemory",
-	"version": "0.4.14",
+	"version": "0.4.15",
 	"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",

package/src/cli.ts

@@ -244,7 +244,9 @@ function printPluginResult(result: PluginBootstrapResultV1, json: boolean, allow
 				console.log("Run: agent-memory plugin install");
 				break;
 			case "auth_required":
-				console.log("Run this command in an interactive terminal to enter an email and activate temporary access.");
+				console.log(
+					"Run this command in an interactive terminal to enter an email and activate free daily access.",
+				);
 				break;
 			case "renewal_required":
 				console.log("Renew AgentMemory Pro to continue using paid capabilities.");
@@ -1000,8 +1002,8 @@ Usage:
   agent-memory plugin manage [--no-browser]
 
 The public core remains fully usable without AgentMemory Pro. Interactive install
-opens a loopback website for temporary email activation and unlimited local use.
-Authentication and payment will be added later.`);
+opens a loopback website for email activation and a configurable free daily
+agent-session allowance. Memory and session content stay on this device.`);
 }
 
 function pluginCommandFailure(command: string, error: unknown): PluginBootstrapResultV1 {
@@ -1227,6 +1229,17 @@ async function main() {
 			const agent = getFlag(flags, "agent");
 			if (!agent) exitError("hook session-start requires --agent", json);
 			await cmdContext({ "no-search": true });
+			try {
+				const decision = await new InstalledPluginRuntimeV1({ coreVersion: VERSION }).runSessionStart({
+					host: agent,
+					cwd: process.cwd(),
+					signal: new AbortController().signal,
+				});
+				if (decision?.state === "exhausted")
+					console.error(`AgentMemory free session allowance resets at ${decision.resetAt}`);
+			} catch {
+				// Paid SessionStart work must never make public-core context unavailable.
+			}
 			break;
 		}
 		case "plugin":

package/src/plugin-bootstrap.ts

@@ -39,6 +39,16 @@ export interface PluginNextActionV1 {
 	message?: string;
 }
 
+export interface PluginSessionUsageDecisionV1 {
+	allowed: boolean;
+	state: "reserved" | "committed" | "released" | "exhausted" | "missing";
+	limit: number;
+	used: number;
+	remaining: number;
+	resetAt: string;
+	idempotent: boolean;
+}
+
 export interface PluginInstallReceiptV1 {
 	schemaVersion: 1;
 	bundleId: string;
@@ -139,6 +149,9 @@ export interface PluginBootstrapBackendV1 {
 		artifactGrant: string;
 	}): Promise<SignedPluginReleaseV1[]>;
 	downloadArtifact(request: { release: SignedPluginReleaseV1; artifactGrant: string }): Promise<Uint8Array>;
+	reserveSession?(operationId: string): Promise<PluginSessionUsageDecisionV1>;
+	commitSession?(operationId: string): Promise<PluginSessionUsageDecisionV1>;
+	releaseSession?(operationId: string): Promise<PluginSessionUsageDecisionV1>;
 	getManagementAction(): Promise<PluginNextActionV1 | null>;
 }
 

package/src/plugin-host.ts

@@ -17,7 +17,7 @@ export type PluginPlanV1 = "free" | "trial" | "pro" | "team" | "enterprise";
 export interface PluginCapabilityQuotaV1 {
 	limit: number;
 	window: "day";
-	scope: "device";
+	scope: "device" | "account";
 }
 
 export interface PluginCapabilityGrantV1 {
@@ -218,7 +218,7 @@ export function validatePluginEntitlementStatusV1(
 		if (grant.quota) {
 			if (!Number.isInteger(grant.quota.limit) || grant.quota.limit <= 0)
 				throw new Error(`Capability ${capability} has an invalid quota limit`);
-			if (grant.quota.window !== "day" || grant.quota.scope !== "device")
+			if (grant.quota.window !== "day" || !["device", "account"].includes(grant.quota.scope))
 				throw new Error(`Capability ${capability} has an invalid quota policy`);
 		}
 	}

package/src/plugin-runtime.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -10,6 +11,7 @@ import {
 	PluginBootstrapFailure,
 	type PluginInstallReceiptV1,
 	type PluginInstallStoreV1,
+	type PluginSessionUsageDecisionV1,
 	type SignedPluginReleaseV1,
 } from "./plugin-bootstrap.js";
 import {
@@ -172,6 +174,34 @@ export class InstalledPluginRuntimeV1 {
 		return registered.command.run(context);
 	}
 
+	async runSessionStart(
+		context: Parameters<PluginSessionStartHookV1["run"]>[0],
+	): Promise<PluginSessionUsageDecisionV1 | null> {
+		if (!(await this.load()) || this.hooks.length === 0) return null;
+		const entitlement = await this.refreshEntitlement();
+		const eligible = this.hooks.filter((hook) => isPluginCapabilityEnabled(entitlement, hook.requiredCapability));
+		if (eligible.length === 0) return null;
+		const metered = eligible.some(
+			(hook) => entitlement.capabilities[hook.requiredCapability]?.quota?.scope === "account",
+		);
+		if (!metered) {
+			for (const hook of eligible) await hook.run(context);
+			return null;
+		}
+		if (!this.backend.reserveSession || !this.backend.commitSession || !this.backend.releaseSession)
+			throw new PluginBootstrapFailure("session_usage_unavailable", "Account session metering is unavailable");
+		const operationId = randomUUID();
+		const reservation = await this.backend.reserveSession(operationId);
+		if (!reservation.allowed) return reservation;
+		try {
+			for (const hook of eligible) await hook.run(context);
+			return await this.backend.commitSession(operationId);
+		} catch (error) {
+			await this.backend.releaseSession(operationId);
+			throw error;
+		}
+	}
+
 	private createHost(manifest: AgentMemoryPluginManifestV1): AgentMemoryPluginHostV1 {
 		const descriptors = new Map(manifest.commands.map((command) => [command.name, command]));
 		const stateRoot = path.join(this.store.root, "state");

package/src/plugin-service.ts

@@ -10,6 +10,7 @@ import {
 	type PluginBootstrapBackendV1,
 	PluginBootstrapFailure,
 	type PluginNextActionV1,
+	type PluginSessionUsageDecisionV1,
 	type SignedPluginReleaseV1,
 } from "./plugin-bootstrap.js";
 import { type PluginEntitlementStatusV1, validatePluginEntitlementStatusV1 } from "./plugin-host.js";
@@ -21,37 +22,22 @@ const REQUEST_TIMEOUT_MS = 30_000;
 const EMAIL_MAX_BYTES = 254;
 const FORM_MAX_BYTES = 2_048;
 const SERVICE_JSON_MAX_BYTES = 1024 * 1024;
+const ACTIVATION_CREDENTIAL = /^am_activation_[A-Za-z0-9_-]{32,256}$/;
 
 const MISSING_ENTITLEMENT: PluginEntitlementStatusV1 = {
 	plan: null,
 	state: "missing",
 	features: [],
 	capabilities: {},
-	reason: "Enter an email address to activate temporary unlimited local use",
-};
-
-const TEMPORARY_ENTITLEMENT: PluginEntitlementStatusV1 = {
-	plan: "pro",
-	state: "active",
-	features: ["session-intelligence", "web-console"],
-	capabilities: Object.fromEntries(
-		[
-			"session-index",
-			"session-worker",
-			"learning",
-			"retrieval-evaluation",
-			"operational-metrics",
-			"web-console",
-			"memory-explorer",
-		].map((capability) => [capability, { enabled: true }]),
-	),
-	reason: "Temporary email activation grants unlimited local use",
+	reason: "Enter an email address to activate the free daily session allowance",
 };
 
 interface TemporaryActivationV1 {
-	schemaVersion: 1;
+	schemaVersion: 2;
 	email: string;
 	activatedAt: string;
+	usageCredential: string;
+	dailySessionLimit: number;
 }
 
 interface TemporaryPluginBackendOptions {
@@ -68,6 +54,27 @@ function cloneEntitlement(value: PluginEntitlementStatusV1): PluginEntitlementSt
 	return structuredClone(value);
 }
 
+function freeEntitlement(dailySessionLimit: number): PluginEntitlementStatusV1 {
+	return {
+		plan: "free",
+		state: "active",
+		features: ["session-intelligence", "web-console"],
+		capabilities: {
+			"session-index": { enabled: true },
+			"session-worker": {
+				enabled: true,
+				quota: { limit: dailySessionLimit, window: "day", scope: "account" },
+			},
+			learning: { enabled: true },
+			"retrieval-evaluation": { enabled: true },
+			"operational-metrics": { enabled: true },
+			"web-console": { enabled: true },
+			"memory-explorer": { enabled: true },
+		},
+		reason: `${dailySessionLimit} free agent sessions per UTC day`,
+	};
+}
+
 function isEmail(value: string): boolean {
 	return (
 		Buffer.byteLength(value, "utf-8") <= EMAIL_MAX_BYTES &&
@@ -89,7 +96,7 @@ function securityHeaders(contentType: string): Record<string, string> {
 
 function activationPage(action: string, error?: string): string {
 	const errorHtml = error ? `<p class="error">${error}</p>` : "";
-	return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Activate AgentMemory Pro</title><style>body{font:16px system-ui;max-width:34rem;margin:10vh auto;padding:0 1.5rem;color:#18212b}form{display:grid;gap:1rem}input,button{font:inherit;padding:.8rem;border-radius:.5rem;border:1px solid #aab4bf}button{background:#18212b;color:#fff;cursor:pointer}.muted{color:#586574}.error{color:#a21d24}</style></head><body><h1>Activate AgentMemory Pro</h1><p>Enter an email address to enable temporary unlimited use on this device.</p>${errorHtml}<form method="post" action="${action}"><label>Email <input type="email" name="email" autocomplete="email" maxlength="254" required autofocus></label><button type="submit">Activate and return to terminal</button></form><p class="muted">The AgentMemory CLI sends your email plus core, bundle, platform, architecture, and release-channel metadata to the private activation service. The activation record never includes memory, session content, queries, repository paths, IP addresses, or user-agent strings, and expires after 365 days without activation.</p></body></html>`;
+	return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Activate AgentMemory</title><style>body{font:16px system-ui;max-width:34rem;margin:10vh auto;padding:0 1.5rem;color:#18212b}form{display:grid;gap:1rem}input,button{font:inherit;padding:.8rem;border-radius:.5rem;border:1px solid #aab4bf}button{background:#18212b;color:#fff;cursor:pointer}.muted{color:#586574}.error{color:#a21d24}</style></head><body><h1>Activate AgentMemory</h1><p>Enter an email address to enable the free daily agent-session allowance on this device.</p>${errorHtml}<form method="post" action="${action}"><label>Email <input type="email" name="email" autocomplete="email" maxlength="254" required autofocus></label><button type="submit">Activate and return to terminal</button></form><p class="muted">The AgentMemory CLI sends your email plus core, bundle, platform, architecture, and release-channel metadata to the private activation service. D1 stores a daily count of opaque SessionStart operations for your normalized email. The request never includes memory, session content, queries, repository paths, raw agent session identifiers, IP addresses, or user-agent strings. Activation records expire after 365 days without use.</p></body></html>`;
 }
 
 function completionPage(): string {
@@ -294,7 +301,8 @@ export class TemporaryPluginBackend implements PluginBootstrapBackendV1 {
 	}
 
 	async getLocalEntitlement(): Promise<PluginEntitlementStatusV1> {
-		return this.readActivation() ? cloneEntitlement(TEMPORARY_ENTITLEMENT) : cloneEntitlement(MISSING_ENTITLEMENT);
+		const activation = this.readActivation();
+		return activation ? freeEntitlement(activation.dailySessionLimit) : cloneEntitlement(MISSING_ENTITLEMENT);
 	}
 
 	async resolveAccess(request: {
@@ -303,8 +311,9 @@ export class TemporaryPluginBackend implements PluginBootstrapBackendV1 {
 		channel: string;
 		allowAuthentication: boolean;
 	}): Promise<PluginAccessDecisionV1> {
-		let activation = this.readActivation();
-		if (!activation) {
+		const activation = this.readActivation();
+		let email = activation?.email;
+		if (!email) {
 			if (!request.allowAuthentication)
 				return {
 					kind: "auth_required",
@@ -315,34 +324,61 @@ export class TemporaryPluginBackend implements PluginBootstrapBackendV1 {
 						message: "Run plugin install in an interactive terminal to enter an email address",
 					},
 				};
-			const email = await this.activate();
-			this.writeActivation(email);
-			activation = this.readActivation();
+			email = await this.activate();
 		}
-		if (!activation)
-			throw new PluginBootstrapFailure("activation_failed", "The local activation record could not be loaded");
 		const response = await this.request(`${this.apiOrigin}/v1/plugin/access`, {
 			method: "POST",
 			headers: { "Content-Type": "application/json" },
 			body: JSON.stringify({
 				schemaVersion: 1,
-				email: activation.email,
+				email,
 				bundleId: request.bundleId,
 				installedVersion: request.installedVersion ?? null,
 				coreVersion: this.coreVersion,
 				channel: request.channel,
 				platform: process.platform,
 				architecture: process.arch,
-				consentVersion: "activation-v1",
+				consentVersion: "activation-v2",
 			}),
 		});
-		const value = (await readJson(response)) as { entitlement?: unknown; artifactGrant?: unknown };
+		const value = (await readJson(response)) as {
+			entitlement?: unknown;
+			artifactGrant?: unknown;
+			usageCredential?: unknown;
+		};
 		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 freeQuota = value.entitlement.capabilities["session-worker"]?.quota;
+		if (
+			value.entitlement.plan !== "free" ||
+			value.entitlement.state !== "active" ||
+			!freeQuota ||
+			freeQuota.scope !== "account" ||
+			freeQuota.window !== "day"
+		)
+			throw new PluginBootstrapFailure("service_response_invalid", "The free session policy is invalid");
+		this.writeActivation(email, value.usageCredential, freeQuota.limit);
 		return { kind: "granted", entitlement: value.entitlement, artifactGrant: value.artifactGrant };
 	}
 
+	async reserveSession(operationId: string): Promise<PluginSessionUsageDecisionV1> {
+		return this.sessionUsage("reserve", operationId);
+	}
+
+	async commitSession(operationId: string): Promise<PluginSessionUsageDecisionV1> {
+		return this.sessionUsage("commit", operationId);
+	}
+
+	async releaseSession(operationId: string): Promise<PluginSessionUsageDecisionV1> {
+		return this.sessionUsage("release", operationId);
+	}
+
 	async listReleases(request: {
 		bundleId: string;
 		channel: string;
@@ -395,16 +431,28 @@ export class TemporaryPluginBackend implements PluginBootstrapBackendV1 {
 			if (!stat.isFile() || stat.isSymbolicLink() || (process.platform !== "win32" && (stat.mode & 0o077) !== 0))
 				return null;
 			const value = JSON.parse(fs.readFileSync(activationPath, "utf-8")) as TemporaryActivationV1;
-			return value.schemaVersion === 1 && isEmail(value.email) && Number.isFinite(Date.parse(value.activatedAt))
-				? value
-				: null;
+			if (
+				value.schemaVersion !== 2 ||
+				!isEmail(value.email) ||
+				!Number.isFinite(Date.parse(value.activatedAt)) ||
+				!ACTIVATION_CREDENTIAL.test(value.usageCredential) ||
+				!Number.isSafeInteger(value.dailySessionLimit) ||
+				value.dailySessionLimit <= 0 ||
+				value.dailySessionLimit > 10_000
+			)
+				return null;
+			return value;
 		} catch {
 			return null;
 		}
 	}
 
-	private writeActivation(email: string): void {
+	private writeActivation(email: string, usageCredential: string, dailySessionLimit: number): void {
 		if (!isEmail(email)) throw new PluginBootstrapFailure("email_invalid", "Enter a valid email address");
+		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);
@@ -418,12 +466,50 @@ export class TemporaryPluginBackend implements PluginBootstrapBackendV1 {
 		const temporary = `${target}.tmp-${process.pid}-${randomUUID()}`;
 		fs.writeFileSync(
 			temporary,
-			`${JSON.stringify({ schemaVersion: 1, email, activatedAt: new Date().toISOString() }, null, 2)}\n`,
+			`${JSON.stringify(
+				{ schemaVersion: 2, email, activatedAt: new Date().toISOString(), usageCredential, dailySessionLimit },
+				null,
+				2,
+			)}\n`,
 			{ mode: 0o600, flag: "wx" },
 		);
 		fs.renameSync(temporary, target);
 	}
 
+	private async sessionUsage(
+		action: "reserve" | "commit" | "release",
+		operationId: string,
+	): Promise<PluginSessionUsageDecisionV1> {
+		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)) as { decision?: Partial<PluginSessionUsageDecisionV1> };
+		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 as PluginSessionUsageDecisionV1;
+	}
+
 	private async request(url: string, init: RequestInit = {}): Promise<Response> {
 		let response: Response;
 		try {