myagentmemory 0.4.16 → 0.5.1

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)

package/src/cli-spec.ts

@@ -10,20 +10,30 @@ export interface CliOptionSpec {
 
 export const COMMANDS = [
 	"context",
+	"save",
+	"note",
 	"write",
 	"read",
 	"scratchpad",
 	"search",
 	"distil",
 	"sync",
-	"init",
+	"setup",
 	"status",
+	"doctor",
+	"tutorial",
 	"install-skills",
 	"uninstall-skills",
 	"install-hooks",
 	"uninstall-hooks",
 	"completion",
+	"pro",
+	"recall",
+	"learn",
+	"dashboard",
 	"plugin",
+	"serve",
+	"upgrade",
 	"version",
 	"help",
 ] as const;
@@ -35,22 +45,32 @@ export const SCRATCHPAD_ACTIONS = ["add", "done", "undo", "clear_done", "list"]
 
 export const COMMAND_DESCRIPTIONS: Record<(typeof COMMANDS)[number], string> = {
 	context: "build context from scratchpad, logs, topics, and long-term memory",
+	save: 'shortcut: agent-memory save "<text>" → daily memory entry',
+	note: 'shortcut: agent-memory note "<text>" → scratchpad checklist item',
 	write: "append or overwrite a daily, topic, or long-term memory entry",
 	read: "read daily, topic, scratchpad, or long-term memory",
 	scratchpad: "add, complete, reopen, list, or clear persistent checklist items",
 	search: "search indexed memory with keyword, semantic, or deep qmd modes",
 	distil: "rebuild a compact MEMORY.md index from logs and topics",
 	sync: "update the qmd index and semantic embeddings",
-	init: "create memory storage and configure qmd when available",
+	setup: "one-shot idempotent installer: init + skills + hooks + plugin + mcp",
 	status: "show memory paths, file counts, qmd, and embedding health",
+	doctor: "run a one-shot health check across memory, qmd, skills, hooks, and Pro",
+	tutorial: "guided 3-minute walkthrough in a throwaway sandbox",
 	"install-skills": "install core instructions for detected agents",
 	"uninstall-skills": "remove core instructions from detected agents",
-	"install-hooks": "install automatic SessionStart indexing and context hooks",
-	"uninstall-hooks": "remove only SessionStart hooks managed by agent-memory",
+	"install-hooks": "install managed context and memory-write reminder hooks",
+	"uninstall-hooks": "remove only hooks managed by agent-memory",
 	completion: "install or print Bash, Zsh, Fish, or PowerShell completion",
-	plugin: "index, recall, learn from, and evaluate prior agent sessions",
+	pro: "install, inspect, or upgrade AgentMemory Pro",
+	recall: "recall decisions and context from prior coding sessions with Pro",
+	learn: "find repeated corrections worth remembering with Pro",
+	dashboard: "open the private local Memory Dashboard",
+	plugin: "discover, install, update, or remove optional official plugins",
+	serve: "run as a Model Context Protocol (MCP) server over stdio",
+	upgrade: "check for and install newer agent-memory CLI and Pro plugin releases",
 	version: "print the installed agent-memory version",
-	help: "show top-level, command, or nested plugin help",
+	help: "show this command overview",
 };
 
 export const PLUGIN_COMMAND_DESCRIPTIONS: Record<(typeof PLUGIN_COMMANDS)[number], string> = {
@@ -75,20 +95,41 @@ export const SCRATCHPAD_ACTION_DESCRIPTIONS: Record<(typeof SCRATCHPAD_ACTIONS)[
 export const GLOBAL_OPTIONS = ["--dir", "--json", "--help", "--version", "-h", "-V"] as const;
 
 export const COMMAND_OPTIONS: Record<string, readonly string[]> = {
-	context: ["--query", "--no-search"],
+	context: ["--query", "--no-search", "--layer"],
+	save: ["--target"],
+	note: [],
 	write: ["--content", "--target", "--mode", "--topic", "--date", "--source-uri"],
 	read: ["--target", "--date", "--topic"],
 	scratchpad: ["--text"],
 	search: ["--query", "--mode", "--limit"],
 	distil: ["--dry-run"],
 	sync: [],
-	init: [],
+	init: ["--yes", "--skip-skills", "--skip-hooks"],
+	setup: ["--yes", "--skip-skills", "--skip-hooks", "--skip-plugin", "--skip-mcp"],
 	status: ["--probe"],
-	"install-skills": [],
+	doctor: [],
+	tutorial: [],
+	"install-skills": ["--uninstall"],
 	"uninstall-skills": [],
-	"install-hooks": ["--yes", "--all", "--only"],
+	"install-hooks": ["--yes", "--all", "--only", "--mode"],
 	"uninstall-hooks": ["--only"],
 	completion: ["--stdout"],
+	pro: [],
+	recall: [
+		"--scope",
+		"--cwd",
+		"--limit",
+		"--context",
+		"--queries",
+		"--multi",
+		"--sessions",
+		"--events",
+		"--per-query",
+	],
+	learn: ["--preview"],
+	dashboard: ["--no-browser"],
+	serve: ["--mcp", "--register", "--only"],
+	upgrade: ["--check", "--refresh", "--yes", "--quiet", "--cli", "--plugin"],
 	version: [],
 	help: [],
 };
@@ -100,6 +141,12 @@ export const PLUGIN_COMMAND_OPTIONS: Record<string, readonly string[]> = {
 	update: ["--channel"],
 	uninstall: ["--yes"],
 	manage: ["--no-browser"],
+	// Plugin runtime commands forwarded to the installed bundle
+	index: ["--date", "--since"],
+	recall: ["--query", "--limit", "--cwd", "--host", "--mode"],
+	worker: ["--token"],
+	learn: ["--limit", "--dry-run"],
+	eval: ["--limit"],
 };
 
 export const WORKER_ACTION_OPTIONS: Record<string, readonly string[]> = {};
@@ -123,7 +170,14 @@ export const OPTION_SPECS: Record<string, CliOptionSpec> = {
 	"--no-search": { description: "build context without invoking qmd" },
 	"--content": { description: "memory entry content to persist", value: { label: "text", kind: "value" } },
 	"--target": { description: "memory destination or collection to read", value: { label: "target", kind: "value" } },
-	"--mode": { description: "write behavior or qmd search strategy", value: { label: "mode", kind: "value" } },
+	"--mode": {
+		description: "write behavior, qmd search strategy, or hook mode (stable|per-turn)",
+		value: { label: "mode", kind: "value" },
+	},
+	"--layer": {
+		description: "context layer to emit: stable, dynamic, or full (default)",
+		value: { label: "layer", kind: "value" },
+	},
 	"--topic": { description: "topic name used to resolve a topic file", value: { label: "name", kind: "value" } },
 	"--date": { description: "daily-log date in YYYY-MM-DD form", value: { label: "date", kind: "value" } },
 	"--source-uri": {
@@ -142,8 +196,13 @@ export const OPTION_SPECS: Record<string, CliOptionSpec> = {
 	"--state": { description: "override the plugin state root", value: { label: "directory", kind: "directory" } },
 	"--with-plugin": { description: "include both the core and optional plugin skills" },
 	"--plugin-only": { description: "operate only on the optional plugin skill" },
-	"--yes": { description: "apply eligible hook changes without confirmation" },
+	"--yes": { description: "apply eligible changes without interactive prompts" },
 	"--all": { description: "apply eligible hook changes without confirmation" },
+	"--skip-skills": { description: "init: don't prompt to install agent skills" },
+	"--skip-hooks": { description: "init: don't prompt to install SessionStart hooks" },
+	"--skip-plugin": { description: "setup: don't offer to install the paid plugin bundle" },
+	"--skip-mcp": { description: "setup: don't register the MCP server in detected local harnesses" },
+	"--preview": { description: "learn: show detected patterns without writing or consuming quota" },
 	"--only": {
 		description: "restrict hook changes to comma-separated agent keys",
 		value: { label: "agents", kind: "value" },
@@ -166,6 +225,23 @@ export const OPTION_SPECS: Record<string, CliOptionSpec> = {
 		description: "surrounding events included with each recall hit",
 		value: { label: "number", kind: "number" },
 	},
+	"--queries": {
+		description: "JSON array of query strings for one-shot multi-query recall",
+		value: { label: "json", kind: "value" },
+	},
+	"--multi": { description: "treat each positional argument as a separate recall query" },
+	"--sessions": {
+		description: "maximum sessions returned by multi-query recall",
+		value: { label: "number", kind: "number" },
+	},
+	"--events": {
+		description: "top events per session returned by multi-query recall",
+		value: { label: "number", kind: "number" },
+	},
+	"--per-query": {
+		description: "candidate hits considered per query before fusion",
+		value: { label: "number", kind: "number" },
+	},
 	"--pi": { description: "override the Pi session root", value: { label: "directory", kind: "directory" } },
 	"--codex": { description: "override the Codex session root", value: { label: "directory", kind: "directory" } },
 	"--claude": {
@@ -218,6 +294,13 @@ export const OPTION_SPECS: Record<string, CliOptionSpec> = {
 	"--agent": { description: "internal SessionStart host key", value: { label: "agent", kind: "value" } },
 	"--token": { description: "internal session-worker lease token", value: { label: "token", kind: "value" } },
 	"--uninstall": { description: "use install-skills compatibility uninstall mode" },
+	"--mcp": { description: "serve as an MCP server over stdio (used by Claude Code)" },
+	"--register": { description: "register the MCP server in detected supported agents and exit" },
+	"--check": { description: "upgrade: report available updates without installing" },
+	"--refresh": { description: "upgrade: force a live registry lookup and rewrite the 24h cache" },
+	"--quiet": { description: "upgrade: suppress non-error output (used by the passive session-start refresh)" },
+	"--cli": { description: "upgrade: limit action to the CLI binary" },
+	"--plugin": { description: "upgrade: limit action to the Pro plugin bundle" },
 };
 
 export const SHELL_DESCRIPTIONS: Record<string, string> = {
@@ -234,3 +317,138 @@ export function optionDescription(option: string): string {
 export function optionTakesValue(option: string): boolean {
 	return OPTION_SPECS[option]?.value !== undefined;
 }
+
+// One-line usage template per command — shows the shape agents/humans should type.
+const COMMAND_USAGE: Record<string, string> = {
+	context: 'agent-memory context [--query "text"] [--no-search] [--json]',
+	save: 'agent-memory save "<text>" [--target daily|topic|long_term]',
+	note: 'agent-memory note "<text>"',
+	write: 'agent-memory write "<text>" [--target daily|topic|long_term] [--mode append|overwrite] [--topic <name>] [--date YYYY-MM-DD]',
+	read: "agent-memory read [--target daily|topic|long_term|scratchpad] [--date YYYY-MM-DD] [--topic <name>]",
+	scratchpad: 'agent-memory scratchpad <add|done|undo|clear_done|list> [--text "text"]',
+	search: 'agent-memory search --query "text" [--mode keyword|semantic|deep] [--limit N]',
+	distil: "agent-memory distil [--dry-run]",
+	sync: "agent-memory sync",
+	init: "agent-memory init [--yes] [--skip-skills] [--skip-hooks]",
+	setup: "agent-memory setup [--yes] [--json]",
+	status: "agent-memory status [--probe] [--json]",
+	doctor: "agent-memory doctor [--json]",
+	tutorial: "agent-memory tutorial",
+	"install-skills": "agent-memory install-skills [--json]",
+	"uninstall-skills": "agent-memory uninstall-skills [--json]",
+	"install-hooks":
+		"agent-memory install-hooks [--yes] [--all] [--only claude,codex,cursor] [--mode stable|per-turn] [--json]",
+	"uninstall-hooks": "agent-memory uninstall-hooks [--only claude,codex,cursor] [--json]",
+	completion: "agent-memory completion [bash|zsh|fish|powershell] [--stdout]",
+	pro: "agent-memory pro <install|status|upgrade> [--channel stable] [--yes]",
+	recall:
+		'agent-memory recall "<query>" [--limit N] [--context N] [--scope current|global] [--cwd <path>] [--json]\n  Multi-query: agent-memory recall --queries \'["q1","q2","q3"]\' [--sessions N] [--events N]',
+	learn: "agent-memory learn [--preview] [--json]",
+	dashboard: "agent-memory dashboard [--no-browser]",
+	plugin:
+		"agent-memory plugin <list|status|install|update|uninstall|manage> [--channel stable] [--yes] [--no-browser]",
+	upgrade: "agent-memory upgrade [--check] [--yes] [--cli|--plugin] [--refresh] [--json]",
+	version: "agent-memory version",
+	help: "agent-memory help [<command>]",
+};
+
+// Concrete examples per command — what an agent or dev is most likely to want.
+const COMMAND_EXAMPLES: Record<string, string[]> = {
+	save: [
+		'agent-memory save "shipped the new recall path — bundle at 1.2.3"',
+		'agent-memory save --target long_term "prefer bun test over npm test in example-api"',
+	],
+	note: ['agent-memory note "verify the digest backfill against a real corpus"'],
+	write: [
+		'agent-memory write "keep sessions in reverse-chron order" --target long_term --mode overwrite',
+		'agent-memory write "half-line summary" --target topic --topic scheduling-machine',
+	],
+	read: [
+		"agent-memory read --target long_term",
+		"agent-memory read --target daily --date 2026-08-24",
+		"agent-memory read --target topic --topic scheduling-machine",
+	],
+	scratchpad: [
+		'agent-memory scratchpad add --text "chase down the flake in test/web.test.ts"',
+		'agent-memory scratchpad done --text "chase down the flake"',
+		"agent-memory scratchpad list",
+	],
+	search: [
+		'agent-memory search --query "API test collection credentials"',
+		'agent-memory search --query "grafana alert routing" --mode semantic --limit 10',
+	],
+	recall: [
+		'agent-memory recall "API test collection for booking service"',
+		'agent-memory recall --queries \'["API test collection for booking service","booking client integration","client credential setup"]\' --sessions 5',
+		'agent-memory recall "auth refresh" --scope current --limit 5',
+	],
+	context: ["agent-memory context", 'agent-memory context --query "grafana alerts" --json'],
+	status: ["agent-memory status", "agent-memory status --json"],
+	init: ["agent-memory init", "agent-memory init --yes --skip-hooks"],
+	setup: ["agent-memory setup", "agent-memory setup --json"],
+	"install-hooks": [
+		"agent-memory install-hooks",
+		"agent-memory install-hooks --yes",
+		"agent-memory install-hooks --only claude,codex",
+		"agent-memory install-hooks --mode stable  # SessionStart only (skip UserPromptSubmit)",
+	],
+	distil: ["agent-memory distil", "agent-memory distil --dry-run"],
+	learn: ["agent-memory learn", "agent-memory learn --preview  # see patterns without consuming quota or writing"],
+};
+
+/**
+ * Render per-command help using existing spec metadata. Called when the user
+ * runs `agent-memory <cmd> --help` — should list the command's real flags with
+ * descriptions and one or two concrete examples, not the top-level command list.
+ */
+export function renderCommandHelp(command: string): string {
+	const canonical = command === "distill" ? "distil" : command;
+	const known = new Set<string>([...COMMANDS, "distill", "setup"]);
+	if (!known.has(canonical)) {
+		return `agent-memory: unknown command '${command}'. Run 'agent-memory help' for the full list.`;
+	}
+	const description =
+		COMMAND_DESCRIPTIONS[canonical as (typeof COMMANDS)[number]] ??
+		(canonical === "setup" ? "one-shot idempotent installer: init + skills + hooks + plugin + mcp" : "");
+	const usage = COMMAND_USAGE[canonical] ?? `agent-memory ${canonical} [options]`;
+	const options = COMMAND_OPTIONS[canonical] ?? [];
+	const examples = COMMAND_EXAMPLES[canonical] ?? [];
+
+	const optLines: string[] = [];
+	// Command-specific options
+	for (const opt of options) {
+		const spec = OPTION_SPECS[opt];
+		if (!spec) continue;
+		const label = spec.value ? `${opt} <${spec.value.label}>` : opt;
+		optLines.push(`  ${label.padEnd(24)}  ${spec.description}`);
+	}
+	// Global options that are always available
+	const globalKeys = ["--dir", "--json", "--help", "--version"];
+	const globalLines = globalKeys
+		.map((opt) => {
+			const spec = OPTION_SPECS[opt];
+			if (!spec) return "";
+			const label = spec.value ? `${opt} <${spec.value.label}>` : opt;
+			return `  ${label.padEnd(24)}  ${spec.description}`;
+		})
+		.filter(Boolean);
+
+	// Command-specific subactions
+	let subactionLines = "";
+	if (canonical === "scratchpad") {
+		subactionLines = `\nActions:\n${SCRATCHPAD_ACTIONS.map((a) => `  ${a.padEnd(24)}  ${SCRATCHPAD_ACTION_DESCRIPTIONS[a]}`).join("\n")}\n`;
+	}
+	if (canonical === "plugin" || canonical === "pro") {
+		subactionLines = `\nSubcommands:\n${PLUGIN_COMMANDS.map((a) => `  ${a.padEnd(24)}  ${PLUGIN_COMMAND_DESCRIPTIONS[a]}`).join("\n")}\n`;
+	}
+
+	const parts = [`agent-memory ${canonical} — ${description}`, "", "Usage:", `  ${usage}`];
+	if (subactionLines) parts.push(subactionLines);
+	if (optLines.length) parts.push("\nOptions:", ...optLines);
+	if (globalLines.length) parts.push("\nGlobal:", ...globalLines);
+	if (examples.length) {
+		parts.push("\nExamples:");
+		for (const ex of examples) parts.push(`  $ ${ex}`);
+	}
+	return parts.join("\n");
+}

package/src/completions.ts

@@ -33,6 +33,14 @@ function words(values: readonly string[]): string {
 	return values.join(" ");
 }
 
+function shellSingleQuote(value: string): string {
+	return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+function powerShellSingleQuote(value: string): string {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+
 function zshOptionValue(command: string, option: string): string {
 	if (option === "--target") {
 		return command === "read"
@@ -52,7 +60,7 @@ function zshOptionValue(command: string, option: string): string {
 
 function zshOptionSpecs(command: string, options: readonly string[] = COMMAND_OPTIONS[command] ?? []): string {
 	return options
-		.map((option) => `'${option}[${optionDescription(option)}]${zshOptionValue(command, option)}'`)
+		.map((option) => shellSingleQuote(`${option}[${optionDescription(option)}]${zshOptionValue(command, option)}`))
 		.join(" ");
 }
 
@@ -71,7 +79,7 @@ function fishOption(command: string, condition: string, option: string): string
 	else if (option === "--only") suggestions = " -a 'claude codex cursor opencode pi'";
 	else if (spec?.value?.kind === "directory") suggestions = " -a '(__fish_complete_directories)'";
 	else if (spec?.value?.kind === "file") suggestions = " -F";
-	return `complete -c agent-memory -n '${condition}' -l ${option.slice(2)}${value}${suggestions} -d '${optionDescription(option)}'`;
+	return `complete -c agent-memory -n ${shellSingleQuote(condition)} -l ${option.slice(2)}${value}${suggestions} -d ${shellSingleQuote(optionDescription(option))}`;
 }
 
 function bashCompletion(): string {
@@ -162,12 +170,12 @@ _agent-memory() {
   local subcommand="$words[3]"
 	local action="$words[4]"
   local command_position=$CURRENT
-  commands=(${COMMANDS.map((command) => `'${command}:${COMMAND_DESCRIPTIONS[command] ?? command}'`).join(" ")})
-  plugin_commands=(${PLUGIN_COMMANDS.map((command) => `'${command}:${PLUGIN_COMMAND_DESCRIPTIONS[command]}'`).join(" ")})
-  worker_actions=(${WORKER_ACTIONS.map((action) => `'${action}:${WORKER_ACTION_DESCRIPTIONS[action]}'`).join(" ")})
-  scratchpad_actions=(${SCRATCHPAD_ACTIONS.map((action) => `'${action}:${SCRATCHPAD_ACTION_DESCRIPTIONS[action]}'`).join(" ")})
+  commands=(${COMMANDS.map((command) => shellSingleQuote(`${command}:${COMMAND_DESCRIPTIONS[command] ?? command}`)).join(" ")})
+  plugin_commands=(${PLUGIN_COMMANDS.map((command) => shellSingleQuote(`${command}:${PLUGIN_COMMAND_DESCRIPTIONS[command]}`)).join(" ")})
+  worker_actions=(${WORKER_ACTIONS.map((action) => shellSingleQuote(`${action}:${WORKER_ACTION_DESCRIPTIONS[action]}`)).join(" ")})
+  scratchpad_actions=(${SCRATCHPAD_ACTIONS.map((action) => shellSingleQuote(`${action}:${SCRATCHPAD_ACTION_DESCRIPTIONS[action]}`)).join(" ")})
   shells=(${Object.entries(SHELL_DESCRIPTIONS)
-		.map(([shell, description]) => `'${shell}:${description}'`)
+		.map(([shell, description]) => shellSingleQuote(`${shell}:${description}`))
 		.join(" ")})
 
   _arguments -C \\
@@ -237,23 +245,23 @@ function fishCompletion(): string {
 		"complete -c agent-memory -f",
 		...COMMANDS.map(
 			(command) =>
-				`complete -c agent-memory -n '__fish_use_subcommand' -a '${command}' -d '${COMMAND_DESCRIPTIONS[command] ?? command}'`,
+				`complete -c agent-memory -n '__fish_use_subcommand' -a '${command}' -d ${shellSingleQuote(COMMAND_DESCRIPTIONS[command] ?? command)}`,
 		),
 		...PLUGIN_COMMANDS.map(
 			(command) =>
-				`complete -c agent-memory -n '__fish_seen_subcommand_from plugin; and not __fish_seen_subcommand_from ${words(PLUGIN_COMMANDS)}' -a '${command}' -d '${PLUGIN_COMMAND_DESCRIPTIONS[command]}'`,
+				`complete -c agent-memory -n '__fish_seen_subcommand_from plugin; and not __fish_seen_subcommand_from ${words(PLUGIN_COMMANDS)}' -a '${command}' -d ${shellSingleQuote(PLUGIN_COMMAND_DESCRIPTIONS[command])}`,
 		),
 		...WORKER_ACTIONS.map(
 			(action) =>
-				`complete -c agent-memory -n '__fish_seen_subcommand_from plugin; and __fish_seen_subcommand_from worker; and not __fish_seen_subcommand_from ${words(WORKER_ACTIONS)}' -a '${action}' -d '${WORKER_ACTION_DESCRIPTIONS[action]}'`,
+				`complete -c agent-memory -n '__fish_seen_subcommand_from plugin; and __fish_seen_subcommand_from worker; and not __fish_seen_subcommand_from ${words(WORKER_ACTIONS)}' -a '${action}' -d ${shellSingleQuote(WORKER_ACTION_DESCRIPTIONS[action])}`,
 		),
 		...SCRATCHPAD_ACTIONS.map(
 			(action) =>
-				`complete -c agent-memory -n '__fish_seen_subcommand_from scratchpad; and not __fish_seen_subcommand_from ${words(SCRATCHPAD_ACTIONS)}' -a '${action}' -d '${SCRATCHPAD_ACTION_DESCRIPTIONS[action]}'`,
+				`complete -c agent-memory -n '__fish_seen_subcommand_from scratchpad; and not __fish_seen_subcommand_from ${words(SCRATCHPAD_ACTIONS)}' -a '${action}' -d ${shellSingleQuote(SCRATCHPAD_ACTION_DESCRIPTIONS[action])}`,
 		),
 		...Object.entries(SHELL_DESCRIPTIONS).map(
 			([shell, description]) =>
-				`complete -c agent-memory -n '__fish_seen_subcommand_from completion' -a '${shell}' -d '${description}'`,
+				`complete -c agent-memory -n '__fish_seen_subcommand_from completion' -a '${shell}' -d ${shellSingleQuote(description)}`,
 		),
 		"complete -c agent-memory -l dir -r -a '(__fish_complete_directories)' -d 'override the active memory directory'",
 		"complete -c agent-memory -l json -d 'emit command-specific structured JSON'",
@@ -330,32 +338,32 @@ Register-ArgumentCompleter -Native -CommandName agent-memory -ScriptBlock {
   $shells = @('bash','zsh','fish','powershell')
   $commandDescriptions = @{
 ${Object.entries(COMMAND_DESCRIPTIONS)
-	.map(([command, description]) => `    '${command}' = '${description}'`)
+	.map(([command, description]) => `    '${command}' = ${powerShellSingleQuote(description)}`)
 	.join("\n")}
   }
   $pluginCommandDescriptions = @{
 ${Object.entries(PLUGIN_COMMAND_DESCRIPTIONS)
-	.map(([command, description]) => `    '${command}' = '${description}'`)
+	.map(([command, description]) => `    '${command}' = ${powerShellSingleQuote(description)}`)
 	.join("\n")}
   }
   $workerActionDescriptions = @{
 ${Object.entries(WORKER_ACTION_DESCRIPTIONS)
-	.map(([action, description]) => `    '${action}' = '${description}'`)
+	.map(([action, description]) => `    '${action}' = ${powerShellSingleQuote(String(description))}`)
 	.join("\n")}
   }
   $scratchpadActionDescriptions = @{
 ${Object.entries(SCRATCHPAD_ACTION_DESCRIPTIONS)
-	.map(([action, description]) => `    '${action}' = '${description}'`)
+	.map(([action, description]) => `    '${action}' = ${powerShellSingleQuote(description)}`)
 	.join("\n")}
   }
   $shellDescriptions = @{
 ${Object.entries(SHELL_DESCRIPTIONS)
-	.map(([shell, description]) => `    '${shell}' = '${description}'`)
+	.map(([shell, description]) => `    '${shell}' = ${powerShellSingleQuote(description)}`)
 	.join("\n")}
   }
   $optionDescriptions = @{
 ${Object.keys(OPTION_SPECS)
-	.map((option) => `    '${option}' = '${optionDescription(option)}'`)
+	.map((option) => `    '${option}' = ${powerShellSingleQuote(optionDescription(option))}`)
 	.join("\n")}
   }
   $globalOptions = @('${GLOBAL_OPTIONS.join("','")}')