myagentmemory 0.4.12 → 0.4.14

package/src/cli.ts

@@ -12,14 +12,21 @@
  *   search     — Search via qmd
  *   init       — Create dirs, detect qmd, setup collection
  *   status     — Show config, qmd status, file counts
+ *   completion — Install or print shell completion
+ *   install-hooks — Install managed session-start hooks
+ *   uninstall-hooks — Remove managed session-start hooks
+ *   plugin     — Discover and bootstrap optional official plugins
  *
  * Global flags:
  *   --dir <path>   Override memory directory
  *   --json         Machine-readable JSON output
  */
 
+import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 
+import { type CompletionShell, detectCompletionShell, generateCompletion, installCompletion } from "./completions.js";
+
 import {
 	_setBaseDir,
 	buildMemoryContext,
@@ -41,9 +48,12 @@ import {
 	getScratchpadFile,
 	getTopicsDir,
 	installSkills,
+	memoryWrite,
 	nowTimestamp,
 	parseScratchpad,
+	probeEmbeddings,
 	readFileSafe,
+	redactSecrets,
 	runQmdEmbedDetached,
 	runQmdSearch,
 	runQmdSync,
@@ -57,9 +67,28 @@ import {
 	topicPath,
 	uninstallSkills,
 } from "./core.js";
+import { detectHookAgents, type HookAgentKey, installHooks, uninstallHooks } from "./hooks.js";
+import {
+	createDefaultPluginBootstrap,
+	PluginBootstrapFailure,
+	type PluginBootstrapResultV1,
+} from "./plugin-bootstrap.js";
+import { InstalledPluginRuntimeV1 } from "./plugin-runtime.js";
 
 declare const __VERSION__: string;
-const VERSION = typeof __VERSION__ !== "undefined" ? __VERSION__ : "dev";
+
+function readPackageVersion(): string {
+	try {
+		const packageJson = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8")) as {
+			version?: unknown;
+		};
+		return typeof packageJson.version === "string" ? packageJson.version : "dev";
+	} catch {
+		return "dev";
+	}
+}
+
+const VERSION = typeof __VERSION__ !== "undefined" ? __VERSION__ : readPackageVersion();
 
 // ---------------------------------------------------------------------------
 // Arg parsing (no external deps)
@@ -133,6 +162,110 @@ function exitError(message: string, json: boolean): never {
 	process.exit(1);
 }
 
+function openExternalUrl(url: string): boolean {
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return false;
+	}
+	if (parsed.protocol !== "https:") return false;
+	try {
+		const child =
+			process.platform === "darwin"
+				? spawn("open", [parsed.toString()], { detached: true, stdio: "ignore" })
+				: process.platform === "win32"
+					? spawn("explorer.exe", [parsed.toString()], { detached: true, stdio: "ignore" })
+					: spawn("xdg-open", [parsed.toString()], { detached: true, stdio: "ignore" });
+		child.unref();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function printProOverview(installed: boolean): void {
+	console.log("");
+	console.log("AgentMemory Pro includes:");
+	console.log("  Session Intelligence  Recall decisions and context across Pi, Codex, and Claude Code sessions.");
+	console.log("  Guided Learning       Turn repeated corrections into reviewable, reversible memory.");
+	console.log("  Local Web Console     Inspect memories, activity, health, and settings in your browser.");
+	console.log("");
+	console.log("Your session content stays on this device.");
+	console.log("");
+	if (installed) {
+		console.log("Try it:");
+		console.log('  agent-memory recall "what did we decide about authentication?"');
+		console.log("  agent-memory learn");
+		console.log("  agent-memory web");
+	} else {
+		console.log("Start your Pro beta:");
+		console.log("  agent-memory plugin install");
+	}
+}
+
+function printPluginResult(result: PluginBootstrapResultV1, json: boolean, allowBrowser: boolean): void {
+	if (json) {
+		output(result, true);
+	} else if (result.command === "plugin.list" && result.plugins) {
+		for (const plugin of result.plugins) {
+			const state = plugin.available ? "available" : plugin.installed ? plugin.entitlement : "not installed";
+			console.log(`${plugin.name}: ${state}`);
+		}
+		printProOverview(Boolean(result.bundle));
+	} else {
+		const version = result.bundle?.version ? ` ${result.bundle.version}` : "";
+		let showOverview = false;
+		switch (result.result) {
+			case "installed":
+				console.log(`AgentMemory Pro${version} installed.`);
+				showOverview = true;
+				break;
+			case "upgraded":
+				console.log(`AgentMemory Pro upgraded to${version}.`);
+				showOverview = true;
+				break;
+			case "current":
+				console.log(
+					result.bundle
+						? `AgentMemory Pro${version} is installed and ready.`
+						: "AgentMemory Pro is not installed.",
+				);
+				showOverview = Boolean(result.bundle);
+				break;
+			case "update_available":
+				console.log(`AgentMemory Pro${version} has an update available.`);
+				break;
+			case "uninstalled":
+				console.log("AgentMemory Pro executable components were removed. Memory and billing state were preserved.");
+				break;
+			case "not_installed":
+				console.log("AgentMemory Pro is not installed.");
+				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.");
+				break;
+			case "renewal_required":
+				console.log("Renew AgentMemory Pro to continue using paid capabilities.");
+				break;
+			default:
+				console.log(result.error?.message ?? "AgentMemory Pro is currently unavailable.");
+		}
+		if (showOverview) printProOverview(true);
+	}
+
+	if (result.nextAction) {
+		if (allowBrowser && openExternalUrl(result.nextAction.url)) {
+			if (!json) console.log("Opened the AgentMemory account website.");
+		} else if (!json) {
+			console.log(`Open: ${result.nextAction.url}`);
+		}
+		if (!json && result.nextAction.userCode) console.log(`Code: ${result.nextAction.userCode}`);
+	}
+	if (!result.ok) process.exitCode = 1;
+}
+
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
@@ -140,9 +273,11 @@ function exitError(message: string, json: boolean): never {
 async function cmdContext(flags: Record<string, string | boolean>) {
 	const json = hasFlag(flags, "json");
 	const noSearch = hasFlag(flags, "no-search");
+	const query = getFlag(flags, "query") ?? "";
 
 	ensureDirs();
-	const searchResults = noSearch ? "" : await searchRelevantMemories("");
+	if (!noSearch && query) await ensureQmdAvailableForSync();
+	const searchResults = noSearch ? "" : await searchRelevantMemories(query);
 	const context = buildMemoryContext(searchResults);
 
 	if (json) {
@@ -161,82 +296,29 @@ async function cmdWrite(flags: Record<string, string | boolean>) {
 	const mode = getFlag(flags, "mode") ?? "append";
 	const topic = getFlag(flags, "topic");
 	const date = getFlag(flags, "date");
+	const sourceUri = getFlag(flags, "source-uri");
 
 	if (!["long_term", "daily", "topic"].includes(target)) {
 		exitError("--target must be 'long_term', 'daily', or 'topic' (default: daily)", json);
 	}
+	if (!["append", "overwrite"].includes(mode)) {
+		exitError("--mode must be 'append' or 'overwrite'", json);
+	}
 	if (!content) {
 		exitError("--content is required", json);
 	}
 
-	ensureDirs();
-	const ts = nowTimestamp();
-	const sid = "cli";
-
-	if (target === "daily") {
-		const filePath = dailyPath(todayStr());
-		const existing = readFileSafe(filePath) ?? "";
-		const separator = existing.trim() ? "\n\n" : "";
-		const stamped = `<!-- ${ts} [${sid}] -->\n${content}`;
-		fs.writeFileSync(filePath, existing + separator + stamped, "utf-8");
-		await ensureQmdAvailableForUpdate();
-		scheduleQmdUpdate();
-		output(
-			json
-				? { ok: true, path: filePath, target, mode: "append", timestamp: ts }
-				: `Appended to daily log: ${filePath}`,
-			json,
-		);
-		return;
-	}
-
-	if (target === "topic") {
-		if (!topic) {
-			exitError("--topic is required when --target is 'topic'", json);
-		}
-		const slug = slugifyTopic(topic);
-		if (!slug) {
-			exitError("--topic must include at least one letter or number", json);
-		}
-		const filePath = topicPath(slug);
-		const existing = readFileSafe(filePath) ?? "";
-		const linkDate = date?.trim() || todayStr();
-		const header = `# Topic: ${topic}\n\n<!-- created: ${ts} [${sid}] -->\n`;
-		const separator = existing.trim() ? "\n\n" : "";
-		const base = existing.trim() ? existing : header.trimEnd();
-		const stamped = `<!-- ${ts} [${sid}] -->\n${content.trim()}\nDaily: [[${linkDate}]]`;
-		fs.writeFileSync(filePath, `${base}${separator}${stamped}`, "utf-8");
-		await ensureQmdAvailableForUpdate();
-		scheduleQmdUpdate();
-		output(
-			json
-				? { ok: true, path: filePath, target, mode: "append", timestamp: ts, topic, slug, date: linkDate }
-				: `Appended to topic: ${filePath}`,
-			json,
-		);
-		return;
-	}
-
-	// long_term
-	const memFile = getMemoryFile();
-	const existing = readFileSafe(memFile) ?? "";
-
-	if (mode === "overwrite") {
-		const stamped = `<!-- last updated: ${ts} [${sid}] -->\n${content}`;
-		fs.writeFileSync(memFile, stamped, "utf-8");
-	} else {
-		const separator = existing.trim() ? "\n\n" : "";
-		const stamped = `<!-- ${ts} [${sid}] -->\n${content}`;
-		fs.writeFileSync(memFile, existing + separator + stamped, "utf-8");
-	}
-	await ensureQmdAvailableForUpdate();
-	scheduleQmdUpdate();
-	output(
-		json
-			? { ok: true, path: memFile, target, mode, timestamp: ts }
-			: `${mode === "overwrite" ? "Overwrote" : "Appended to"} MEMORY.md`,
-		json,
-	);
+	const result = await memoryWrite({
+		target: target as "long_term" | "daily" | "topic",
+		content,
+		mode: mode as "append" | "overwrite",
+		sessionId: "cli",
+		topic,
+		date,
+		sourceUri,
+	});
+	if (result.isError) exitError(result.text.replace(/^Error:\s*/, ""), json);
+	output(json ? { ok: true, ...result.details } : result.text.split("\n\n", 1)[0], json);
 }
 
 async function cmdRead(flags: Record<string, string | boolean>) {
@@ -349,7 +431,11 @@ async function cmdScratchpad(flags: Record<string, string | boolean>, positional
 	ensureDirs();
 	const spFile = getScratchpadFile();
 	const existing = readFileSafe(spFile) ?? "";
-	let items = parseScratchpad(existing);
+	let items = parseScratchpad(existing).map((item) => ({
+		...item,
+		text: redactSecrets(item.text).content,
+		meta: redactSecrets(item.meta).content,
+	}));
 
 	if (action === "list") {
 		if (items.length === 0) {
@@ -374,11 +460,12 @@ async function cmdScratchpad(flags: Record<string, string | boolean>, positional
 	if (action === "add") {
 		if (!text) exitError("--text is required for add", json);
 		const ts = nowTimestamp();
-		items.push({ done: false, text: text!, meta: `<!-- ${ts} [cli] -->` });
+		const safeText = redactSecrets(text!).content;
+		items.push({ done: false, text: safeText, meta: `<!-- ${ts} [cli] -->` });
 		fs.writeFileSync(spFile, serializeScratchpad(items), "utf-8");
 		await ensureQmdAvailableForUpdate();
 		scheduleQmdUpdate();
-		output(json ? { ok: true, action, text } : `Added: - [ ] ${text}`, json);
+		output(json ? { ok: true, action, text: safeText } : `Added: - [ ] ${safeText}`, json);
 		return;
 	}
 
@@ -539,6 +626,90 @@ function cmdInstallSkills(flags: Record<string, string | boolean>) {
 	}
 }
 
+async function promptYesNo(question: string, defaultYes: boolean): Promise<boolean> {
+	const readline = await import("node:readline/promises");
+	const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+	try {
+		const answer = (await rl.question(`${question} ${defaultYes ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
+		if (!answer) return defaultYes;
+		return answer === "y" || answer === "yes";
+	} finally {
+		rl.close();
+	}
+}
+
+async function cmdInstallHooks(flags: Record<string, string | boolean>): Promise<void> {
+	const json = hasFlag(flags, "json");
+	const requested = getFlag(flags, "only");
+	const requestedKeys = requested ? new Set(requested.split(",").map((value) => value.trim())) : null;
+	const { homeDir, targets } = detectHookAgents();
+	if (!homeDir) exitError("Home directory not found.", json);
+	const eligible = targets.filter(
+		(target) => target.supported && target.detected && (!requestedKeys || requestedKeys.has(target.key)),
+	);
+	const selected = new Set<HookAgentKey>();
+	const applyAll = hasFlag(flags, "yes") || hasFlag(flags, "all") || !process.stdin.isTTY;
+	for (const target of eligible) {
+		if (applyAll || (await promptYesNo(`Install SessionStart hook for ${target.label}?`, true)))
+			selected.add(target.key);
+	}
+	const report = installHooks(selected);
+	if (!report.ok) exitError(report.error ?? "install failed", json);
+	if (json) return output(report, true);
+	if (!report.results.length) return output("No eligible agents. Nothing to install.", false);
+	for (const result of report.results) {
+		console.log(
+			result.installed
+				? `Installed ${result.label} hook: ${result.path}`
+				: `Skipped ${result.label} (${result.reason ?? "unknown"})`,
+		);
+	}
+}
+
+function cmdUninstallHooks(flags: Record<string, string | boolean>): void {
+	const json = hasFlag(flags, "json");
+	const only = getFlag(flags, "only");
+	const agents = only ? new Set(only.split(",").map((value) => value.trim()) as HookAgentKey[]) : undefined;
+	const report = uninstallHooks(agents);
+	if (!report.ok) exitError(report.error ?? "uninstall failed", json);
+	if (json) {
+		output(report, true);
+		return;
+	}
+	for (const result of report.results) {
+		console.log(
+			result.installed
+				? `Uninstalled ${result.label}: ${result.path}`
+				: `Skipped ${result.label} (${result.reason ?? "unknown"})`,
+		);
+	}
+}
+
+function cmdCompletion(flags: Record<string, string | boolean>, positional: string[]): void {
+	const requestedShell = positional[0];
+	const shells: CompletionShell[] = ["bash", "zsh", "fish", "powershell"];
+	if (requestedShell && !shells.includes(requestedShell as CompletionShell))
+		exitError(
+			`Unsupported shell '${requestedShell}'. Choose bash, zsh, fish, or powershell.`,
+			hasFlag(flags, "json"),
+		);
+	const shell = (requestedShell as CompletionShell | undefined) ?? detectCompletionShell();
+	if (!shell)
+		exitError("Could not detect your shell. Specify bash, zsh, fish, or powershell.", hasFlag(flags, "json"));
+	if (hasFlag(flags, "stdout")) {
+		process.stdout.write(generateCompletion(shell));
+		return;
+	}
+	const result = installCompletion(shell);
+	if (hasFlag(flags, "json")) {
+		output(result, true);
+		return;
+	}
+	console.log(`Installed ${shell} completion: ${result.completionPath}`);
+	if (result.profilePath)
+		console.log(`${result.profileUpdated ? "Configured" : "Already configured"}: ${result.profilePath}`);
+}
+
 async function cmdSync(flags: Record<string, string | boolean>) {
 	const json = hasFlag(flags, "json");
 
@@ -633,6 +804,18 @@ async function cmdInit(flags: Record<string, string | boolean>) {
 			console.log(`  qmd not found — search features unavailable.`);
 			console.log(`  Install: bun install -g https://github.com/tobi/qmd`);
 		}
+		if (process.stdout.isTTY) {
+			try {
+				const plugin = await createDefaultPluginBootstrap(VERSION).list();
+				if (plugin.result === "not_installed") {
+					console.log("");
+					console.log("Optional: AgentMemory Pro adds session recall and a local Web Console.");
+					console.log("Run: agent-memory plugin install");
+				}
+			} catch {
+				// Commercial discovery must never make core initialization fail.
+			}
+		}
 	}
 }
 
@@ -665,15 +848,37 @@ async function cmdStatus(flags: Record<string, string | boolean>) {
 	const qmdFound = await detectQmd();
 	let hasCollection = false;
 	let health = null;
+	let embeddings: "ready" | "missing" | "unknown" | "n/a" = "n/a";
 	if (qmdFound) {
 		hasCollection = await checkCollection();
 		if (hasCollection) {
 			await ensureQmdAvailableForSync();
 			health = await getQmdHealth();
+			// A live semantic probe confirms embeddings are actually usable, but
+			// it costs a real qmd query (and a possible model load), so it's
+			// opt-in — the cheap pending-embed count below covers the common case.
+			if (hasFlag(flags, "probe")) {
+				embeddings = await probeEmbeddings();
+			}
 		}
 	}
 
 	const embedMode = getQmdEmbedMode();
+	let officialPlugin: { installed: boolean; result: string; entitlement: string } = {
+		installed: false,
+		result: "unavailable",
+		entitlement: "missing",
+	};
+	try {
+		const plugin = await createDefaultPluginBootstrap(VERSION).status();
+		officialPlugin = {
+			installed: Boolean(plugin.bundle),
+			result: plugin.result,
+			entitlement: plugin.entitlement.state,
+		};
+	} catch {
+		// Commercial status must never make core status fail.
+	}
 
 	if (json) {
 		output(
@@ -695,8 +900,10 @@ async function cmdStatus(flags: Record<string, string | boolean>) {
 					available: qmdFound,
 					collection: hasCollection ? getCollectionName() : null,
 					health,
+					embeddings,
 				},
 				embedMode,
+				officialPlugin,
 			},
 			true,
 		);
@@ -725,6 +932,15 @@ async function cmdStatus(flags: Record<string, string | boolean>) {
 				`Collection '${getCollectionName()}': ${hasCollection ? "configured" : "not configured — run: agent-memory init"}`,
 			);
 			console.log(`Embed mode: ${embedMode}`);
+			if (hasCollection && embeddings !== "n/a") {
+				const embLabel =
+					embeddings === "ready"
+						? "ready"
+						: embeddings === "missing"
+							? "missing — run: agent-memory sync"
+							: "unknown (could not verify within probe timeout)";
+				console.log(`Embeddings (semantic/deep search): ${embLabel}`);
+			}
 			if (health) {
 				if (health.totalFiles !== null) console.log(`Files indexed: ${health.totalFiles}`);
 				if (health.vectorsEmbedded !== null) console.log(`Vectors embedded: ${health.vectorsEmbedded}`);
@@ -737,6 +953,11 @@ async function cmdStatus(flags: Record<string, string | boolean>) {
 		} else {
 			console.log("qmd: not installed");
 		}
+		if (!officialPlugin.installed) {
+			console.log("");
+			console.log("Optional official plugins: not installed");
+			console.log("  run: agent-memory plugin install");
+		}
 	}
 }
 
@@ -767,6 +988,116 @@ async function cmdDistil(flags: Record<string, string | boolean>) {
 	}
 }
 
+function printPluginUsage(): void {
+	console.log(`agent-memory plugin — optional official plugins
+
+Usage:
+  agent-memory plugin [list]
+  agent-memory plugin status
+  agent-memory plugin install [--channel stable] [--no-browser]
+  agent-memory plugin update [--channel stable]
+  agent-memory plugin uninstall --yes
+  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.`);
+}
+
+function pluginCommandFailure(command: string, error: unknown): PluginBootstrapResultV1 {
+	return {
+		schemaVersion: 1,
+		command: `plugin.${command}`,
+		ok: false,
+		result: "unavailable",
+		bundle: null,
+		entitlement: {
+			plan: null,
+			state: "missing",
+			features: [],
+			capabilities: {},
+		},
+		nextAction: null,
+		error: {
+			code: error instanceof PluginBootstrapFailure ? error.code : "plugin_command_failed",
+			message: error instanceof Error ? error.message : String(error),
+			...(error instanceof PluginBootstrapFailure && error.retryable ? { retryable: true } : {}),
+		},
+	};
+}
+
+async function cmdPlugin(flags: Record<string, string | boolean>, positional: string[]): Promise<void> {
+	const json = hasFlag(flags, "json");
+	const subcommand = positional[0] ?? "list";
+	if (subcommand === "help" || hasFlag(flags, "help")) {
+		printPluginUsage();
+		return;
+	}
+	const channel = getFlag(flags, "channel") ?? "stable";
+	if (channel !== "stable") {
+		printPluginResult(
+			pluginCommandFailure(
+				subcommand,
+				new PluginBootstrapFailure("channel_invalid", "--channel supports only 'stable'"),
+			),
+			json,
+			false,
+		);
+		return;
+	}
+	const allowBrowser = !json && !hasFlag(flags, "no-browser") && Boolean(process.stdin.isTTY && process.stdout.isTTY);
+	const manager = createDefaultPluginBootstrap(VERSION);
+
+	let result: PluginBootstrapResultV1;
+	try {
+		switch (subcommand) {
+			case "list":
+				result = await manager.list();
+				break;
+			case "status":
+				result = await manager.status(channel);
+				break;
+			case "install":
+				result = await manager.install({ channel, allowAuthentication: allowBrowser });
+				break;
+			case "update":
+				result = await manager.update({ channel, allowAuthentication: false });
+				break;
+			case "uninstall":
+				if (!hasFlag(flags, "yes")) {
+					const status = await manager.status(channel);
+					result = {
+						...status,
+						command: "plugin.uninstall",
+						ok: false,
+						result: "unavailable",
+						error: {
+							code: "confirmation_required",
+							message: "Re-run with --yes to remove AgentMemory Pro executable components",
+						},
+					};
+					break;
+				}
+				result = await manager.uninstall();
+				break;
+			case "manage":
+				result = await manager.manage();
+				break;
+			default:
+				result = pluginCommandFailure(
+					subcommand,
+					new PluginBootstrapFailure(
+						"unknown_plugin_command",
+						`Unknown plugin command: ${subcommand}. Available bootstrap commands: list, status, install, update, uninstall, manage.`,
+					),
+				);
+		}
+	} catch (error) {
+		result = pluginCommandFailure(subcommand, error);
+	}
+	printPluginResult(result, json, allowBrowser && (subcommand === "install" || subcommand === "manage"));
+}
+
 // ---------------------------------------------------------------------------
 // Usage
 // ---------------------------------------------------------------------------
@@ -781,15 +1112,19 @@ Commands:
   version     Show binary version
   install-skills  Install (or --uninstall) bundled skills
   uninstall-skills  Uninstall bundled skills
-  context     Build & print context injection string
-  write       Write to memory files (default: daily)
+  context     Build context; optionally retrieve memories with --query
+  write       Write to memory files (default: daily; optional --source-uri)
   read        Read memory files
   scratchpad  Manage checklist items
   search      Search across memory files (requires qmd)
   distil      Generate compact MEMORY.md index from daily logs + topics
   sync        Re-index and embed all files (requires qmd)
   init        Initialize memory directory and qmd collection
-  status      Show configuration and status
+  status      Show configuration and status (--probe for a live embeddings check)
+  completion  Install or print shell completion
+  install-hooks  Install managed SessionStart hooks
+  uninstall-hooks  Remove only managed SessionStart hooks
+  plugin      Discover, install, update, or remove optional official plugins
 
 Global flags:
   --dir <path>   Override memory directory
@@ -798,7 +1133,7 @@ Global flags:
 Examples:
   agent-memory init
   agent-memory write --content "Fixed auth bug in login flow"
-  agent-memory write --target long_term --content "User prefers dark mode"
+  agent-memory write --target long_term --content "User prefers dark mode" --source-uri "session://agent/turn/12"
   agent-memory write --target topic --topic "auth" --content "Rolled JWT refresh to edge"
   agent-memory read --target long_term
   agent-memory read --target daily --date 2026-02-15
@@ -810,9 +1145,13 @@ Examples:
   agent-memory scratchpad done --text "PR #42"
   agent-memory search --query "database choice" --mode keyword
   agent-memory distil --dry-run
-  agent-memory context --no-search
+  agent-memory context --query "database choice"
   agent-memory sync
-  agent-memory status --json`);
+  agent-memory status --json
+  agent-memory completion zsh
+  agent-memory install-hooks --yes
+  agent-memory plugin status
+  agent-memory plugin install`);
 }
 
 // ---------------------------------------------------------------------------
@@ -834,7 +1173,7 @@ async function main() {
 		return;
 	}
 
-	if (!command || command === "help" || hasFlag(flags, "help")) {
+	if (!command || command === "help" || (hasFlag(flags, "help") && command !== "plugin")) {
 		printUsage();
 		return;
 	}
@@ -874,8 +1213,42 @@ async function main() {
 		case "status":
 			await cmdStatus(flags);
 			break;
-		default:
-			exitError(`Unknown command: ${command}. Run 'agent-memory help' for usage.`, json);
+		case "completion":
+			cmdCompletion(flags, positional);
+			break;
+		case "install-hooks":
+			await cmdInstallHooks(flags);
+			break;
+		case "uninstall-hooks":
+			cmdUninstallHooks(flags);
+			break;
+		case "hook": {
+			if (positional[0] !== "session-start") exitError("hook requires 'session-start'", json);
+			const agent = getFlag(flags, "agent");
+			if (!agent) exitError("hook session-start requires --agent", json);
+			await cmdContext({ "no-search": true });
+			break;
+		}
+		case "plugin":
+			await cmdPlugin(flags, positional);
+			break;
+		default: {
+			const controller = new AbortController();
+			const abort = () => controller.abort();
+			process.once("SIGINT", abort);
+			try {
+				const result = await new InstalledPluginRuntimeV1({ coreVersion: VERSION }).run(command, {
+					args: positional,
+					flags,
+					signal: controller.signal,
+				});
+				if (!result) exitError(`Unknown command: ${command}. Run 'agent-memory help' for usage.`, json);
+				if (!result.ok) exitError(result.error?.message ?? `Plugin command ${command} failed`, json);
+				output(result.data ?? { ok: true }, json);
+			} finally {
+				process.removeListener("SIGINT", abort);
+			}
+		}
 	}
 }