myagentmemory 0.4.16 → 0.5.1

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;

package/dist/upgrade.js

@@ -0,0 +1,243 @@
+/**
+ * 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 { spawn, spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as url from "node:url";
+import { getMemoryDir } from "./core.js";
+import { compareVersions } from "./plugin-bootstrap.js";
+const NPM_PACKAGE_NAME = "myagentmemory";
+const NPM_LATEST_URL = `https://registry.npmjs.org/${NPM_PACKAGE_NAME}/latest`;
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+const FETCH_TIMEOUT_MS = 1_500;
+// ---------------------------------------------------------------------------
+// npm registry lookup
+// ---------------------------------------------------------------------------
+async function fetchLatestFromNpm(fetchImpl = globalThis.fetch) {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+        try {
+            const response = await fetchImpl(NPM_LATEST_URL, {
+                signal: controller.signal,
+                headers: { accept: "application/json" },
+            });
+            if (!response.ok)
+                return null;
+            const body = (await response.json());
+            return typeof body.version === "string" ? body.version : null;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Cache
+// ---------------------------------------------------------------------------
+function upgradeCachePath() {
+    return path.join(getMemoryDir(), "state", "upgrade-check.json");
+}
+export function readUpgradeCache() {
+    try {
+        const raw = fs.readFileSync(upgradeCachePath(), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.checkedAt !== "string" ||
+            typeof parsed.cliCurrent !== "string" ||
+            (parsed.cliLatest !== null && typeof parsed.cliLatest !== "string") ||
+            (parsed.pluginCurrent !== null &&
+                typeof parsed.pluginCurrent !== "string" &&
+                parsed.pluginCurrent !== undefined) ||
+            (parsed.pluginLatest !== null && typeof parsed.pluginLatest !== "string" && parsed.pluginLatest !== undefined)) {
+            return null;
+        }
+        return {
+            checkedAt: parsed.checkedAt,
+            cliCurrent: parsed.cliCurrent,
+            cliLatest: parsed.cliLatest ?? null,
+            pluginCurrent: parsed.pluginCurrent ?? null,
+            pluginLatest: parsed.pluginLatest ?? null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeUpgradeCache(record) {
+    const file = upgradeCachePath();
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`);
+    }
+    catch {
+        // Cache write failures are non-fatal.
+    }
+}
+export function isCacheFresh(record, now = Date.now()) {
+    if (!record)
+        return false;
+    const checked = Date.parse(record.checkedAt);
+    if (!Number.isFinite(checked))
+        return false;
+    return now - checked < CACHE_TTL_MS;
+}
+// ---------------------------------------------------------------------------
+// Install-method detection
+// ---------------------------------------------------------------------------
+function selfInstallPath() {
+    try {
+        return url.fileURLToPath(import.meta.url);
+    }
+    catch {
+        return process.argv[1] ?? "";
+    }
+}
+/**
+ * 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 function detectInstallMethod(location = selfInstallPath()) {
+    const normalized = location.replace(/\\/g, "/");
+    const home = os.homedir().replace(/\\/g, "/");
+    const pkg = `${NPM_PACKAGE_NAME}@latest`;
+    // 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] };
+    }
+    // pnpm global (Linux, macOS layouts)
+    if (normalized.includes("/.local/share/pnpm/global/") ||
+        normalized.includes("/Library/pnpm/global/") ||
+        normalized.includes("/AppData/Local/pnpm/global/") ||
+        normalized.includes("/pnpm-global/")) {
+        return { manager: "pnpm", global: true, origin: location, command: ["pnpm", "add", "-g", pkg] };
+    }
+    // yarn global
+    if (normalized.includes("/yarn/global/") || normalized.includes("/.config/yarn/global/")) {
+        return { manager: "yarn", global: true, origin: location, command: ["yarn", "global", "add", pkg] };
+    }
+    // npm global — common prefixes across nvm, homebrew, system node, npm-global override
+    const npmGlobalSignatures = ["/lib/node_modules/", "/npm-global/", "/.nvm/versions/node/", "/AppData/Roaming/npm/"];
+    if (npmGlobalSignatures.some((sig) => normalized.includes(sig))) {
+        return { manager: "npm", global: true, origin: location, command: ["npm", "install", "-g", pkg] };
+    }
+    // Local checkout, npx cache, or unknown — best-effort with npm -g.
+    void home;
+    return {
+        manager: "unknown",
+        global: false,
+        origin: location,
+        command: ["npm", "install", "-g", pkg],
+    };
+}
+export function runInstaller(method, opts = {}) {
+    const [cmd, ...args] = method.command;
+    const result = spawnSync(cmd, args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+        env: process.env,
+        ...opts,
+    });
+    return {
+        ok: result.status === 0,
+        code: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        command: method.command,
+    };
+}
+// ---------------------------------------------------------------------------
+// Passive: refresh cache in background
+// ---------------------------------------------------------------------------
+/**
+ * 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 function refreshUpgradeCacheBackground() {
+    try {
+        const binary = process.argv[0];
+        const script = process.argv[1];
+        if (!binary || !script)
+            return;
+        const child = spawn(binary, [script, "upgrade", "--check", "--refresh", "--quiet", "--json"], {
+            detached: true,
+            stdio: "ignore",
+            env: { ...process.env, AGENT_MEMORY_UPGRADE_BACKGROUND: "1" },
+        });
+        child.unref();
+    }
+    catch {
+        // Background refresh is best-effort.
+    }
+}
+export async function checkForUpgrades(opts) {
+    const cached = readUpgradeCache();
+    const fresh = isCacheFresh(cached);
+    const useCache = !opts.refresh && (opts.cacheOnly || fresh);
+    let cliLatest = null;
+    let pluginLatest = null;
+    let checkedAt;
+    let fromCache = false;
+    if (useCache && cached) {
+        cliLatest = cached.cliLatest;
+        pluginLatest = opts.pluginLatestHint ?? cached.pluginLatest;
+        checkedAt = cached.checkedAt;
+        fromCache = true;
+    }
+    else if (opts.cacheOnly) {
+        // Cache miss and network is disallowed — return an empty snapshot.
+        checkedAt = new Date().toISOString();
+        fromCache = true;
+    }
+    else {
+        const fetcher = opts.fetchCliLatest ?? (() => fetchLatestFromNpm());
+        cliLatest = await fetcher();
+        pluginLatest = opts.pluginLatestHint ?? null;
+        checkedAt = new Date().toISOString();
+        writeUpgradeCache({
+            checkedAt,
+            cliCurrent: opts.cliCurrent,
+            cliLatest,
+            pluginCurrent: opts.pluginCurrent,
+            pluginLatest,
+        });
+    }
+    return {
+        cli: {
+            current: opts.cliCurrent,
+            latest: cliLatest,
+            upgradeAvailable: Boolean(cliLatest && compareVersions(cliLatest, opts.cliCurrent) > 0),
+        },
+        plugin: {
+            current: opts.pluginCurrent,
+            latest: pluginLatest,
+            upgradeAvailable: Boolean(opts.pluginUpgradeAvailable) ||
+                Boolean(pluginLatest && opts.pluginCurrent && compareVersions(pluginLatest, opts.pluginCurrent) > 0),
+        },
+        checkedAt,
+        fromCache,
+    };
+}
+export function formatUpgradeNotice(status) {
+    const parts = [];
+    if (status.cli.upgradeAvailable)
+        parts.push(`CLI ${status.cli.current} → ${status.cli.latest ?? "new"}`);
+    if (status.plugin.upgradeAvailable)
+        parts.push(`Pro ${status.plugin.current ?? "?"} → ${status.plugin.latest ?? "new"}`);
+    if (!parts.length)
+        return null;
+    return `agent-memory: upgrade available (${parts.join(", ")}). Run: agent-memory upgrade`;
+}

package/docs/official-plugin-bootstrap.md

@@ -2,18 +2,18 @@
 
 ## Status
 
-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.
+Accepted design on 2026-08-16 and revised on 2026-08-17. The public core implements host types, anonymous preview 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 preview grants 20 device-local recalls and 5 device-local learning scans per local day while keeping indexing and Memory Dashboard visibility available. 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.
+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 commercial 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.
 
 ## Decision
 
 The public core will provide a small bootstrap and host surface for signed first-party plugins. It will not contain paid implementations, browser assets, commercial entitlement logic, or a general third-party marketplace.
 
-The primary user command is:
+The primary product-facing command is:
 
 ```bash
-agent-memory plugin install
+agent-memory pro install
 ```
 
 `plugin install` is an idempotent reconcile operation:
@@ -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 loopback email activation in an interactive terminal |
+| Any | Missing | Request an anonymous free-preview entitlement and signed artifact grant |
 | 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 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.
+An absent plugin cannot activate itself. The public bootstrap creates a random installation identifier, obtains a server-issued free-preview policy and short-lived artifact grant, and verifies the release and artifact. A mode-0600 activation record is persisted only after the service accepts the request. After installation, the public host reconstructs the free capability policy in core code and checks required capabilities before commands and hooks. Signed long-lived paid entitlements can extend this record when authentication and payment ship.
 
 ## Ownership boundary
 
@@ -67,6 +67,12 @@ Core memory operations must continue to work when the service is unreachable, a
 ### Bootstrap commands
 
 ```text
+agent-memory pro
+agent-memory pro install
+agent-memory pro status
+agent-memory pro upgrade
+agent-memory pro manage
+
 agent-memory plugin
 agent-memory plugin list
 agent-memory plugin status
@@ -76,6 +82,8 @@ agent-memory plugin uninstall [--yes]
 agent-memory plugin manage [--no-browser]
 ```
 
+The `pro` namespace is the user-facing surface. The `plugin` namespace remains supported for low-level administration and compatibility.
+
 - `plugin` with no subcommand prints a discovery summary and the next relevant command.
 - `list` reports known official plugins and whether each is installed and available. It does not download artifacts or inspect memory.
 - `status` is read-only. It reports the installed bundle, selected channel, compatibility, entitlement state, and update availability.
@@ -84,7 +92,7 @@ agent-memory plugin manage [--no-browser]
 - `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.
+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.
 
 The current private compatibility CLI uses `plugin install` and `plugin uninstall` for skill files only. During migration, those meanings move to `install-skills --plugin-only` and `uninstall-skills --plugin-only`; the bootstrap command names above become authoritative.
 
@@ -93,13 +101,13 @@ The current private compatibility CLI uses `plugin install` and `plugin uninstal
 After a successful interactive `agent-memory init`, the core may print one informational line:
 
 ```text
-Optional: AgentMemory Pro adds session recall and a local Web Console.
-Run: agent-memory plugin install
+Core remembers what you save. Pro learns from what you do.
+Run: agent-memory pro install
 ```
 
-Top-level help includes an `Optional official plugins` section. Human-readable `status` may include the same recommendation while no official plugin is installed. Routine `context`, `read`, `write`, `search`, and scratchpad commands never show commercial prompts.
+Top-level help includes a Pro section. Human-readable `status` may include the same recommendation while Pro is not installed. Routine `context`, `read`, `write`, `search`, and scratchpad commands never show commercial prompts.
 
-The core must not open a browser during package installation, `init`, `help`, `status`, or any normal memory operation. A browser may open only after an explicit interactive `plugin install`. `--no-browser`, non-interactive execution, and `--json` fail closed with `auth_required` when no activation record exists.
+The free preview does not open a browser or request identity. Browsers remain restricted to explicit `dashboard`, future `pro manage`, and future paid upgrade/authentication flows. Non-interactive and `--json` installs use the same anonymous access request and still fail closed when the commercial service is unavailable.
 
 ### Machine-readable output
 
@@ -133,17 +141,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.
 
-## Free activation flow
+## Anonymous free-preview 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 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.
+1. `agent-memory pro install` creates a random installation identifier locally when no activation record exists.
+2. The CLI sends that identifier plus core, installed-bundle, platform, architecture, and release-channel fields to the private control plane. It sends no email, memory, session content, query, repository path, raw agent session identifier, IP address, or user-agent string.
+3. The service stores the pseudonymous identifier and only the hash of a random compatibility credential, then returns a free-preview capability policy and short-lived object-bound artifact grant.
+4. The CLI validates the explicit free policy: local indexing and Memory Dashboard access, 20 device-local recalls per day, 5 device-local learning scans per day, and no free automatic background worker.
+5. 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.
+7. Device-local quota operations reserve before work, commit after useful work, and release on abstention or failure. A zero-result recall does not consume allowance.
 
-Email ownership is not verified in this free flow. Authentication, payment, renewal, account management, and signed paid entitlements are not implemented yet.
+Authentication, payment, renewal, account management, and signed paid entitlements are not implemented yet.
 
 ## Future authentication and purchase flow
 
@@ -163,12 +171,12 @@ An Enterprise administrator may pre-provision an organization entitlement or man
 
 The service exposes:
 
-- `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;
+- `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.
 
-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:
+The access request contains a random installation identifier plus the bounded core, bundle, platform, architecture, and release-channel fields described above. Application payloads contain no email, 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;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "myagentmemory",
-	"version": "0.4.16",
+	"version": "0.5.1",
 	"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",
@@ -65,9 +65,16 @@
 	},
 	"homepage": "https://github.com/jayzeng/agentmemory#readme",
 	"files": [
-		"src",
+		"src/core.ts",
+		"src/cli-spec.ts",
+		"src/completions.ts",
+		"src/hooks.ts",
+		"src/plugin-host.ts",
+		"src/plugin-bootstrap.ts",
 		"skills",
-		"scripts",
+		"scripts/install-skills.sh",
+		"scripts/install-skills.ps1",
+		"scripts/postinstall.cjs",
 		"dist/cli.d.ts",
 		"dist/cli.js",
 		"dist/core.d.ts",
@@ -86,6 +93,11 @@
 		"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",
+		"dist/upgrade.js",
 		"docs/official-plugin-bootstrap.md",
 		"README.md",
 		"LICENSE"
@@ -100,13 +112,21 @@
 		"build:lib": "tsc -p tsconfig.build.json",
 		"build:cli": "bun build src/cli.ts --compile --outfile dist/agent-memory --define __VERSION__=\"'$(node -p \"require('./package.json').version\")'\"",
 		"eval:feedback": "bun eval/run.ts",
+		"eval:regression": "bun eval/run.ts --dataset eval/datasets/agent-memory-regression-v1.json",
+		"eval:longmemeval": "bun eval/longmemeval.ts",
+		"eval:token-savings": "bun eval/token-savings.ts",
 		"prepare": "npm run build:lib",
 		"prepack": "npm run build:lib",
 		"lint": "biome check .",
 		"test": "bun test test/unit.test.ts",
 		"test:unit": "bun test test/unit.test.ts",
-		"test:cli": "bun test test/cli.test.ts",
+		"test:cli": "bun test test/cli.test.ts --timeout 15000",
 		"test:eval": "bun test test/eval.test.ts",
+		"test:harness": "npm run build:cli && bun test test/harness.test.ts --timeout 60000",
+		"test:token-savings": "bun test test/token-savings.test.ts",
+		"eval:harness": "bun eval/harness.ts",
+		"verify": "bash scripts/verify.sh",
+		"verify:quick": "bash scripts/verify.sh --quick",
 		"install-skills": "bash scripts/install-skills.sh"
 	},
 	"devDependencies": {

package/scripts/install-skills.sh

@@ -110,4 +110,4 @@ else
   echo "  $AGENT_MEMORY_BIN"
 fi
 echo ""
-echo "Initialize memory: agent-memory init"
+echo "Finish setup: agent-memory setup"

package/skills/agent/SKILL.md

@@ -108,6 +108,15 @@ agent-memory search --query "how we handle auth" --mode semantic # Finds related
 agent-memory search --query "performance" --mode deep --limit 10 # Hybrid + reranking
 ```
 
+`search` only looks at what you saved (daily logs, MEMORY.md, topics, scratchpad). For **prior sessions** — things you or the agent said in a past chat — use `recall`:
+
+```bash
+agent-memory recall "deploy-to-dev label workflow"          # Cross-session, verbatim events
+agent-memory recall "auth refresh" --scope current --limit 5 # Restrict to this workspace
+```
+
+When qmd search returns no hits and AgentMemory Pro is installed, `search` automatically falls back to `recall` — but calling `recall` directly is faster and clearer when you know you want session history.
+
 If qmd is not installed, fall back to reading files directly:
 ```bash
 agent-memory read --target long_term
@@ -117,7 +126,7 @@ agent-memory read --target daily
 ### Setup
 
 ```bash
-agent-memory init      # Create dirs, detect qmd, setup collection
+agent-memory setup     # Idempotent: memory dir, qmd collection, skills, hooks, MCP
 agent-memory sync      # Re-index and embed all files (requires qmd)
 agent-memory status    # Show config, file counts, qmd status
 ```
@@ -174,5 +183,6 @@ Distil scans daily logs and topic notes, groups entries by their `#tags`, and ge
 - Use `--target long_term` sparingly: architecture, preferences, key commands, hard-won lessons
 - Prefer the scratchpad for any TODOs or follow-ups (persistent, cross-session tracking)
 - Use `#tags` and `[[links]]` in content to improve search recall
-- Use `agent-memory search` to recall past work before starting related tasks
+- Use `agent-memory search` to find things you saved (daily logs, MEMORY.md, topics) before starting related tasks
+- Use `agent-memory recall "<query>"` to find things from prior chat sessions (Pro) — not the same as `search`
 - All `agent-memory` commands are safe — they read/write only to the memory directory (`~/.agent-memory/` by default)

package/skills/claude-code/SKILL.md

@@ -14,6 +14,8 @@ Pi users can choose the native extension (`pi-memory`: https://github.com/jayzen
 
 !`agent-memory context --no-search 2>/dev/null`
 
+This deliberately fetches the full layer (today's log + MEMORY.md + yesterday's log), not just the narrower "stable" layer (MEMORY.md + scratchpad only) that an installed SessionStart hook injects to keep per-turn re-injection cheap. If a hook already ran this session, you may see two context blocks — that's expected, not a bug; treat this one (the fuller one) as authoritative.
+
 ## Session Lifecycle
 
 ### On session start
@@ -28,6 +30,8 @@ Pi users can choose the native extension (`pi-memory`: https://github.com/jayzen
 2. Mark completed scratchpad items as done; add new follow-ups
 3. Only write to long-term memory if you discovered a **durable fact** that doesn't already exist there
 
+If Claude Code's `Stop` hook is installed, you may occasionally see a reminder to do this check even if you weren't planning to stop — that's the harness backing up this step for long sessions; treat it the same as the guidance above.
+
 ## Where to Write — Decision Guide
 
 **Default to daily. Long-term is rare.**
@@ -104,6 +108,15 @@ agent-memory search --query "how we handle auth" --mode semantic # Finds related
 agent-memory search --query "performance" --mode deep --limit 10 # Hybrid + reranking
 ```
 
+`search` only looks at what you saved (daily logs, MEMORY.md, topics, scratchpad). For **prior sessions** — things you or the agent said in a past Claude/Codex/pi chat — use `recall`:
+
+```bash
+agent-memory recall "deploy-to-dev label workflow"          # Cross-session, verbatim events
+agent-memory recall "auth refresh" --scope current --limit 5 # Restrict to this workspace
+```
+
+When qmd search returns no hits and AgentMemory Pro is installed, `search` automatically falls back to `recall` — but calling `recall` directly is faster and clearer when you know you want session history.
+
 If qmd is not installed, fall back to reading files directly:
 ```bash
 agent-memory read --target long_term
@@ -113,7 +126,7 @@ agent-memory read --target daily
 ### Setup
 
 ```bash
-agent-memory init      # Create dirs, detect qmd, setup collection
+agent-memory setup     # Idempotent: memory dir, qmd collection, skills, hooks, MCP
 agent-memory sync      # Re-index and embed all files (requires qmd)
 agent-memory status    # Show config, file counts, qmd status
 ```
@@ -170,4 +183,6 @@ Distil scans daily logs and topic notes, groups entries by their `#tags`, and ge
 - Use `--target long_term` sparingly: architecture, preferences, key commands, hard-won lessons
 - Prefer the scratchpad for any TODOs or follow-ups (persistent, cross-session tracking)
 - Use `#tags` and `[[links]]` in content to improve search recall
-- Use `agent-memory search` to recall past work before starting related tasks
+- Use `agent-memory search` to find things you saved (daily logs, MEMORY.md, topics) before starting related tasks
+- Use `agent-memory recall "<query>"` to find things from prior chat sessions (Pro) — not the same as `search`
+- All `agent-memory` commands are safe — they read/write only to the memory directory (`~/.agent-memory/` by default)