myagentmemory 0.4.17 → 0.5.1

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,9 +2,9 @@
 
 ## Status
 
-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 10 device-local recalls and one device-local learning scan per local day while keeping indexing and Memory Dashboard visibility available. 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
 
@@ -146,7 +146,7 @@ Every bootstrap command supports `--json` and emits one JSON document with a ver
 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, 10 device-local recalls per day, one device-local learning scan per day, and no free automatic background worker.
+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. 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.

package/package.json

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

package/skills/codex/SKILL.md

@@ -19,6 +19,8 @@ agent-memory context --no-search 2>/dev/null
 
 This prints your scratchpad, today's log, long-term memory, and yesterday's log. Review it — especially **open scratchpad items** — before starting work.
 
+Run this even if a SessionStart hook already fired — the hook only injects the narrower "stable" layer (MEMORY.md + scratchpad) to keep per-turn re-injection cheap. Seeing two context blocks in one session is expected; treat this fuller one as authoritative.
+
 If the user's task relates to prior work, search for relevant memories:
 ```bash
 agent-memory search --query "<topic>" --mode keyword
@@ -106,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
@@ -115,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
 ```
@@ -172,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/cursor/SKILL.md

@@ -24,6 +24,8 @@ If the user's task relates to prior work, search for relevant memories:
 agent-memory search --query "<topic>" --mode keyword
 ```
 
+Run the context command above even if a `sessionStart` hook already fired (via `~/.cursor/hooks.json`, installed by `agent-memory install-hooks`) — both fetch the same full layer, so seeing it twice is redundant but harmless, not a sign of drift.
+
 **Tip:** For project-specific rules (linting, formatting, test conventions), prefer `.cursorrules` or project-level config files. Use agent-memory for cross-project and cross-session knowledge.
 
 ## On Session End (After Significant Work)
@@ -108,6 +110,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 +128,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 +185,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)