codemem 0.20.0-alpha.2 → 0.20.0-alpha.4

package/dist/index.js

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
-import { MemoryStore, ObserverClient, RawEventSweeper, VERSION, buildRawEventEnvelopeFromHook, connect, ensureDeviceIdentity, exportMemories, getRawEventStatus, importMemories, initDatabase, loadSqliteVec, rawEventsGate, readCodememConfigFile, readImportPayload, resolveDbPath, resolveProject, retryRawEventFailures, runSyncDaemon, schema, stripJsonComments, stripPrivateObj, stripTrailingCommas, vacuumDatabase, writeCodememConfigFile } from "@codemem/core";
+import { MemoryStore, ObserverClient, RawEventSweeper, VERSION, buildRawEventEnvelopeFromHook, connect, ensureDeviceIdentity, exportMemories, fingerprintPublicKey, getRawEventStatus, importMemories, initDatabase, loadPublicKey, loadSqliteVec, rawEventsGate, readCodememConfigFile, readImportPayload, resolveDbPath, resolveProject, retryRawEventFailures, runSyncDaemon, runSyncPass, schema, setPeerProjectFilter, stripJsonComments, stripPrivateObj, stripTrailingCommas, syncPassPreflight, updatePeerAddresses, vacuumDatabase, writeCodememConfigFile } from "@codemem/core";
 import { Command } from "commander";
 import omelette from "omelette";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { styleText } from "node:util";
 import * as p from "@clack/prompts";
-import { homedir } from "node:os";
+import { homedir, networkInterfaces } from "node:os";
 import { dirname, join } from "node:path";
-import { desc } from "drizzle-orm";
+import { spawn } from "node:child_process";
+import net from "node:net";
+import { desc, eq } from "drizzle-orm";
 import { drizzle } from "drizzle-orm/better-sqlite3";
 //#region src/help-style.ts
 /**
@@ -117,7 +119,7 @@ function directEnqueue(payload, dbPath) {
 		db.close();
 	}
 }
-var claudeHookIngestCommand = new Command("claude-hook-ingest").configureHelp(helpStyle).description("Ingest a Claude Code hook payload from stdin").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--host <host>", "viewer server host", "127.0.0.1").option("--port <port>", "viewer server port", "38888").action(async (opts) => {
+var claudeHookIngestCommand = new Command("claude-hook-ingest").configureHelp(helpStyle).description("Ingest a Claude Code hook payload from stdin").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--host <host>", "viewer server host", "127.0.0.1").option("--port <port>", "viewer server port", "38888").action(async (opts) => {
 	let raw;
 	try {
 		raw = readFileSync(0, "utf8").trim();
@@ -153,7 +155,7 @@ var claudeHookIngestCommand = new Command("claude-hook-ingest").configureHelp(he
 		return;
 	}
 	try {
-		const dbPath = resolveDbPath(opts.db);
+		const dbPath = resolveDbPath(opts.db ?? opts.dbPath);
 		const directResult = directEnqueue(payload, dbPath);
 		console.log(JSON.stringify({
 			...directResult,
@@ -165,19 +167,24 @@ var claudeHookIngestCommand = new Command("claude-hook-ingest").configureHelp(he
 });
 //#endregion
 //#region src/commands/db.ts
+function formatBytes(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
 var dbCommand = new Command("db").configureHelp(helpStyle).description("Database maintenance");
-dbCommand.addCommand(new Command("init").configureHelp(helpStyle).description("Verify the SQLite database is present and schema-ready").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").action((opts) => {
-	const result = initDatabase(opts.db);
+dbCommand.addCommand(new Command("init").configureHelp(helpStyle).description("Verify the SQLite database is present and schema-ready").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").action((opts) => {
+	const result = initDatabase(opts.db ?? opts.dbPath);
 	p.intro("codemem db init");
 	p.log.success(`Database ready: ${result.path}`);
 	p.outro(`Size: ${result.sizeBytes.toLocaleString()} bytes`);
-})).addCommand(new Command("vacuum").configureHelp(helpStyle).description("Run VACUUM on the SQLite database").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").action((opts) => {
-	const result = vacuumDatabase(opts.db);
+})).addCommand(new Command("vacuum").configureHelp(helpStyle).description("Run VACUUM on the SQLite database").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").action((opts) => {
+	const result = vacuumDatabase(opts.db ?? opts.dbPath);
 	p.intro("codemem db vacuum");
 	p.log.success(`Vacuumed: ${result.path}`);
 	p.outro(`Size: ${result.sizeBytes.toLocaleString()} bytes`);
-})).addCommand(new Command("raw-events-status").configureHelp(helpStyle).description("Show pending raw-event backlog by source stream").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("-n, --limit <n>", "max rows to show", "25").option("--json", "output as JSON").action((opts) => {
-	const result = getRawEventStatus(opts.db, Number.parseInt(opts.limit, 10) || 25);
+})).addCommand(new Command("raw-events-status").configureHelp(helpStyle).description("Show pending raw-event backlog by source stream").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("-n, --limit <n>", "max rows to show", "25").option("--json", "output as JSON").action((opts) => {
+	const result = getRawEventStatus(opts.db ?? opts.dbPath, Number.parseInt(opts.limit, 10) || 25);
 	if (opts.json) {
 		console.log(JSON.stringify(result, null, 2));
 		return;
@@ -190,12 +197,12 @@ dbCommand.addCommand(new Command("init").configureHelp(helpStyle).description("V
 	}
 	for (const item of result.items) p.log.message(`${item.source}:${item.stream_id} pending=${Math.max(0, item.last_received_event_seq - item.last_flushed_event_seq)} received=${item.last_received_event_seq} flushed=${item.last_flushed_event_seq} project=${item.project ?? ""}`);
 	p.outro("done");
-})).addCommand(new Command("raw-events-retry").configureHelp(helpStyle).description("Requeue failed raw-event flush batches").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("-n, --limit <n>", "max failed batches to requeue", "25").action((opts) => {
-	const result = retryRawEventFailures(opts.db, Number.parseInt(opts.limit, 10) || 25);
+})).addCommand(new Command("raw-events-retry").configureHelp(helpStyle).description("Requeue failed raw-event flush batches").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("-n, --limit <n>", "max failed batches to requeue", "25").action((opts) => {
+	const result = retryRawEventFailures(opts.db ?? opts.dbPath, Number.parseInt(opts.limit, 10) || 25);
 	p.intro("codemem db raw-events-retry");
 	p.outro(`Requeued ${result.retried.toLocaleString()} failed batch(es)`);
-})).addCommand(new Command("raw-events-gate").configureHelp(helpStyle).description("Validate raw-event reliability thresholds (non-zero exit on failure)").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--min-flush-success-rate <rate>", "minimum flush success rate", "0.95").option("--max-dropped-event-rate <rate>", "maximum dropped event rate", "0.05").option("--min-session-boundary-accuracy <rate>", "minimum session boundary accuracy", "0.9").option("--window-hours <hours>", "lookback window in hours", "24").option("--json", "output as JSON").action((opts) => {
-	const result = rawEventsGate(opts.db, {
+})).addCommand(new Command("raw-events-gate").configureHelp(helpStyle).description("Validate raw-event reliability thresholds (non-zero exit on failure)").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--min-flush-success-rate <rate>", "minimum flush success rate", "0.95").option("--max-dropped-event-rate <rate>", "maximum dropped event rate", "0.05").option("--min-session-boundary-accuracy <rate>", "minimum session boundary accuracy", "0.9").option("--window-hours <hours>", "lookback window in hours", "24").option("--json", "output as JSON").action((opts) => {
+	const result = rawEventsGate(opts.db ?? opts.dbPath, {
 		minFlushSuccessRate: Number.parseFloat(opts.minFlushSuccessRate),
 		maxDroppedEventRate: Number.parseFloat(opts.maxDroppedEventRate),
 		minSessionBoundaryAccuracy: Number.parseFloat(opts.minSessionBoundaryAccuracy),
@@ -219,6 +226,115 @@ dbCommand.addCommand(new Command("init").configureHelp(helpStyle).description("V
 		p.outro("reliability gate FAILED");
 		process.exitCode = 1;
 	}
+})).addCommand(new Command("rename-project").configureHelp(helpStyle).description("Rename a project across sessions and related tables").argument("<old-name>", "current project name").argument("<new-name>", "new project name").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--apply", "apply changes (default is dry-run)").action((oldName, newName, opts) => {
+	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+	try {
+		const dryRun = !opts.apply;
+		const suffixPattern = `%/${oldName.replace(/%/g, "\\%").replace(/_/g, "\\_")}`;
+		const tables = ["sessions", "raw_event_sessions"];
+		const counts = {};
+		const run = () => {
+			for (const table of tables) {
+				const rows = store.db.prepare(`SELECT COUNT(*) as cnt FROM ${table} WHERE project = ? OR project LIKE ? ESCAPE '\\'`).get(oldName, suffixPattern);
+				counts[table] = rows.cnt;
+				if (!dryRun && rows.cnt > 0) {
+					store.db.prepare(`UPDATE ${table} SET project = ? WHERE project = ?`).run(newName, oldName);
+					store.db.prepare(`UPDATE ${table} SET project = ? WHERE project LIKE ? ESCAPE '\\' AND project != ?`).run(newName, suffixPattern, newName);
+				}
+			}
+		};
+		if (dryRun) run();
+		else store.db.transaction(run)();
+		const action = dryRun ? "Will rename" : "Renamed";
+		p.intro("codemem db rename-project");
+		p.log.info(`${action} ${oldName} → ${newName}`);
+		p.log.info([`Sessions: ${counts.sessions}`, `Raw event sessions: ${counts.raw_event_sessions}`].join("\n"));
+		if (dryRun) p.outro("Pass --apply to execute");
+		else p.outro("done");
+	} finally {
+		store.close();
+	}
+})).addCommand(new Command("normalize-projects").configureHelp(helpStyle).description("Normalize path-like project identifiers to their basename").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--apply", "apply changes (default is dry-run)").action((opts) => {
+	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+	try {
+		const dryRun = !opts.apply;
+		const tables = ["sessions", "raw_event_sessions"];
+		const rewrites = /* @__PURE__ */ new Map();
+		const counts = {};
+		const run = () => {
+			for (const table of tables) {
+				const projects = store.db.prepare(`SELECT DISTINCT project FROM ${table} WHERE project IS NOT NULL AND project LIKE '%/%'`).all();
+				let updated = 0;
+				for (const row of projects) {
+					const basename = row.project.split("/").pop() ?? row.project;
+					if (basename !== row.project) {
+						rewrites.set(row.project, basename);
+						if (!dryRun) {
+							const info = store.db.prepare(`UPDATE ${table} SET project = ? WHERE project = ?`).run(basename, row.project);
+							updated += info.changes;
+						} else {
+							const cnt = store.db.prepare(`SELECT COUNT(*) as cnt FROM ${table} WHERE project = ?`).get(row.project);
+							updated += cnt.cnt;
+						}
+					}
+				}
+				counts[table] = updated;
+			}
+		};
+		if (dryRun) run();
+		else store.db.transaction(run)();
+		p.intro("codemem db normalize-projects");
+		p.log.info(`Dry run: ${dryRun}`);
+		p.log.info([`Sessions to update: ${counts.sessions}`, `Raw event sessions to update: ${counts.raw_event_sessions}`].join("\n"));
+		if (rewrites.size > 0) {
+			p.log.info("Rewritten paths:");
+			for (const [from, to] of [...rewrites.entries()].sort()) p.log.message(`  ${from} → ${to}`);
+		}
+		if (dryRun) p.outro("Pass --apply to execute");
+		else p.outro("done");
+	} finally {
+		store.close();
+	}
+})).addCommand(new Command("size-report").configureHelp(helpStyle).description("Show SQLite file size and major storage consumers").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--limit <n>", "number of largest tables/indexes to show", "12").option("--json", "output as JSON").action((opts) => {
+	const dbPath = resolveDbPath(opts.db ?? opts.dbPath);
+	const db = connect(dbPath);
+	try {
+		const limit = Math.max(1, Number.parseInt(opts.limit, 10) || 12);
+		const fileSizeBytes = statSync(dbPath).size;
+		const pageInfo = db.prepare("SELECT page_count * page_size as total FROM pragma_page_count, pragma_page_size").get();
+		const freePages = db.prepare("SELECT freelist_count FROM pragma_freelist_count").get();
+		const pageSize = db.prepare("PRAGMA page_size").get();
+		const tables = db.prepare(`SELECT name, SUM(pgsize) as size_bytes
+							 FROM dbstat
+							 GROUP BY name
+							 ORDER BY size_bytes DESC
+							 LIMIT ?`).all(limit);
+		if (opts.json) {
+			console.log(JSON.stringify({
+				file_size_bytes: fileSizeBytes,
+				db_size_bytes: pageInfo?.total ?? 0,
+				free_bytes: (freePages?.freelist_count ?? 0) * (pageSize?.page_size ?? 4096),
+				tables: tables.map((t) => ({
+					name: t.name,
+					size_bytes: t.size_bytes
+				}))
+			}, null, 2));
+			return;
+		}
+		p.intro("codemem db size-report");
+		p.log.info([
+			`File size:     ${formatBytes(fileSizeBytes)}`,
+			`DB size:       ${formatBytes(pageInfo?.total ?? 0)}`,
+			`Free space:    ${formatBytes((freePages?.freelist_count ?? 0) * (pageSize?.page_size ?? 4096))}`
+		].join("\n"));
+		if (tables.length > 0) {
+			p.log.info("Largest objects:");
+			for (const t of tables) p.log.message(`  ${t.name.padEnd(40)} ${formatBytes(t.size_bytes).padStart(10)}`);
+		}
+		p.outro("done");
+	} finally {
+		db.close();
+	}
 }));
 //#endregion
 //#region src/commands/enqueue-raw-event.ts
@@ -253,7 +369,7 @@ async function readStdinJson() {
 	if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("payload must be an object");
 	return parsed;
 }
-var enqueueRawEventCommand = new Command("enqueue-raw-event").configureHelp(helpStyle).description("Enqueue one raw event from stdin into the durable queue").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").action(async (opts) => {
+var enqueueRawEventCommand = new Command("enqueue-raw-event").configureHelp(helpStyle).description("Enqueue one raw event from stdin into the durable queue").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").action(async (opts) => {
 	const payload = await readStdinJson();
 	const sessionId = resolveSessionStreamId(payload);
 	if (!sessionId) throw new Error("session id required");
@@ -267,7 +383,7 @@ var enqueueRawEventCommand = new Command("enqueue-raw-event").configureHelp(help
 	const tsMonoMs = Number.isFinite(Number(payload.ts_mono_ms)) ? Number(payload.ts_mono_ms) : null;
 	const eventId = typeof payload.event_id === "string" ? payload.event_id.trim() : "";
 	const eventPayload = payload.payload && typeof payload.payload === "object" && !Array.isArray(payload.payload) ? stripPrivateObj(payload.payload) : {};
-	const store = new MemoryStore(resolveDbPath(opts.db));
+	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
 	try {
 		store.updateRawEventSessionMeta({
 			opencodeSessionId: sessionId,
@@ -293,9 +409,9 @@ var enqueueRawEventCommand = new Command("enqueue-raw-event").configureHelp(help
 function expandUserPath(value) {
 	return value.startsWith("~/") ? join(homedir(), value.slice(2)) : value;
 }
-var exportMemoriesCommand = new Command("export-memories").configureHelp(helpStyle).description("Export memories to a JSON file for sharing or backup").argument("<output>", "output file path (use '-' for stdout)").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--project <project>", "filter by project (defaults to git repo root)").option("--all-projects", "export all projects").option("--include-inactive", "include deactivated memories").option("--since <iso>", "only export memories created after this ISO timestamp").action((output, opts) => {
+var exportMemoriesCommand = new Command("export-memories").configureHelp(helpStyle).description("Export memories to a JSON file for sharing or backup").argument("<output>", "output file path (use '-' for stdout)").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--project <project>", "filter by project (defaults to git repo root)").option("--all-projects", "export all projects").option("--include-inactive", "include deactivated memories").option("--since <iso>", "only export memories created after this ISO timestamp").action((output, opts) => {
 	const payload = exportMemories({
-		dbPath: resolveDbPath(opts.db),
+		dbPath: resolveDbPath(opts.db ?? opts.dbPath),
 		project: opts.project,
 		allProjects: opts.allProjects,
 		includeInactive: opts.includeInactive,
@@ -320,7 +436,7 @@ var exportMemoriesCommand = new Command("export-memories").configureHelp(helpSty
 });
 //#endregion
 //#region src/commands/import-memories.ts
-var importMemoriesCommand = new Command("import-memories").configureHelp(helpStyle).description("Import memories from an exported JSON file").argument("<inputFile>", "input JSON file (use '-' for stdin)").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--remap-project <path>", "remap all projects to this path on import").option("--dry-run", "preview import without writing").action((inputFile, opts) => {
+var importMemoriesCommand = new Command("import-memories").configureHelp(helpStyle).description("Import memories from an exported JSON file").argument("<inputFile>", "input JSON file (use '-' for stdin)").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--remap-project <path>", "remap all projects to this path on import").option("--dry-run", "preview import without writing").action((inputFile, opts) => {
 	let payload;
 	try {
 		payload = readImportPayload(inputFile);
@@ -339,7 +455,7 @@ var importMemoriesCommand = new Command("import-memories").configureHelp(helpSty
 		`Prompts:        ${payload.user_prompts.length.toLocaleString()}`
 	].join("\n"));
 	const result = importMemories(payload, {
-		dbPath: resolveDbPath(opts.db),
+		dbPath: resolveDbPath(opts.db ?? opts.dbPath),
 		remapProject: opts.remapProject,
 		dryRun: opts.dryRun
 	});
@@ -357,8 +473,9 @@ var importMemoriesCommand = new Command("import-memories").configureHelp(helpSty
 });
 //#endregion
 //#region src/commands/mcp.ts
-var mcpCommand = new Command("mcp").configureHelp(helpStyle).description("Start the MCP stdio server").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").action(async (opts) => {
-	if (opts.db) process.env.CODEMEM_DB = opts.db;
+var mcpCommand = new Command("mcp").configureHelp(helpStyle).description("Start the MCP stdio server").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").action(async (opts) => {
+	const dbPath = opts.db ?? opts.dbPath;
+	if (dbPath) process.env.CODEMEM_DB = dbPath;
 	await import("@codemem/mcp");
 });
 //#endregion
@@ -376,15 +493,14 @@ function parseStrictPositiveId(value) {
 	const n = Number(value.trim());
 	return Number.isFinite(n) && n >= 1 && Number.isInteger(n) ? n : null;
 }
-var memoryCommand = new Command("memory").configureHelp(helpStyle).description("Memory item management");
-memoryCommand.addCommand(new Command("show").configureHelp(helpStyle).description("Print a memory item as JSON").argument("<id>", "memory ID").option("--db <path>", "database path").action((idStr, opts) => {
+function showMemoryAction(idStr, opts) {
 	const memoryId = parseStrictPositiveId(idStr);
 	if (memoryId === null) {
 		p.log.error(`Invalid memory ID: ${idStr}`);
 		process.exitCode = 1;
 		return;
 	}
-	const store = new MemoryStore(resolveDbPath(opts.db));
+	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
 	try {
 		const item = store.get(memoryId);
 		if (!item) {
@@ -396,24 +512,24 @@ memoryCommand.addCommand(new Command("show").configureHelp(helpStyle).descriptio
 	} finally {
 		store.close();
 	}
-}));
-memoryCommand.addCommand(new Command("forget").configureHelp(helpStyle).description("Deactivate a memory item").argument("<id>", "memory ID").option("--db <path>", "database path").action((idStr, opts) => {
+}
+function forgetMemoryAction(idStr, opts) {
 	const memoryId = parseStrictPositiveId(idStr);
 	if (memoryId === null) {
 		p.log.error(`Invalid memory ID: ${idStr}`);
 		process.exitCode = 1;
 		return;
 	}
-	const store = new MemoryStore(resolveDbPath(opts.db));
+	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
 	try {
 		store.forget(memoryId);
 		p.log.success(`Memory ${memoryId} marked inactive`);
 	} finally {
 		store.close();
 	}
-}));
-memoryCommand.addCommand(new Command("remember").configureHelp(helpStyle).description("Manually add a memory item").requiredOption("-k, --kind <kind>", "memory kind (discovery, decision, feature, bugfix, etc.)").requiredOption("-t, --title <title>", "memory title").requiredOption("-b, --body <body>", "memory body text").option("--tags <tags...>", "tags (space-separated)").option("--project <project>", "project name (defaults to git repo root)").option("--db <path>", "database path").action((opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db));
+}
+function rememberMemoryAction(opts) {
+	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
 	let sessionId = null;
 	try {
 		const project = resolveProject(process.cwd(), opts.project ?? null);
@@ -438,15 +554,41 @@ memoryCommand.addCommand(new Command("remember").configureHelp(helpStyle).descri
 	} finally {
 		store.close();
 	}
-}));
+}
+function createShowMemoryCommand() {
+	return new Command("show").configureHelp(helpStyle).description("Print a memory item as JSON").argument("<id>", "memory ID").option("--db <path>", "database path").option("--db-path <path>", "database path").action(showMemoryAction);
+}
+function createForgetMemoryCommand() {
+	return new Command("forget").configureHelp(helpStyle).description("Deactivate a memory item").argument("<id>", "memory ID").option("--db <path>", "database path").option("--db-path <path>", "database path").action(forgetMemoryAction);
+}
+function createRememberMemoryCommand() {
+	return new Command("remember").configureHelp(helpStyle).description("Manually add a memory item").requiredOption("-k, --kind <kind>", "memory kind (discovery, decision, feature, bugfix, etc.)").requiredOption("-t, --title <title>", "memory title").requiredOption("-b, --body <body>", "memory body text").option("--tags <tags...>", "tags (space-separated)").option("--project <project>", "project name (defaults to git repo root)").option("--db <path>", "database path").option("--db-path <path>", "database path").action(rememberMemoryAction);
+}
+var showMemoryCommand = createShowMemoryCommand();
+var forgetMemoryCommand = createForgetMemoryCommand();
+var rememberMemoryCommand = createRememberMemoryCommand();
+var memoryCommand = new Command("memory").configureHelp(helpStyle).description("Memory item management");
+memoryCommand.addCommand(createShowMemoryCommand());
+memoryCommand.addCommand(createForgetMemoryCommand());
+memoryCommand.addCommand(createRememberMemoryCommand());
 //#endregion
 //#region src/commands/pack.ts
-var packCommand = new Command("pack").configureHelp(helpStyle).description("Build a context-aware memory pack").argument("<context>", "context string to search for").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("-n, --limit <n>", "max items", "10").option("--budget <tokens>", "token budget").option("--json", "output as JSON").action((context, opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db));
+function collectWorkingSetFile(value, previous) {
+	return [...previous, value];
+}
+var packCommand = new Command("pack").configureHelp(helpStyle).description("Build a context-aware memory pack").argument("<context>", "context string to search for").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("-n, --limit <n>", "max items", "10").option("--budget <tokens>", "token budget").option("--token-budget <tokens>", "token budget").option("--working-set-file <path>", "recently modified file path used as ranking hint", collectWorkingSetFile, []).option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "search across all projects").option("--json", "output as JSON").action((context, opts) => {
+	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
 	try {
 		const limit = Number.parseInt(opts.limit, 10) || 10;
-		const budget = opts.budget ? Number.parseInt(opts.budget, 10) : void 0;
-		const result = store.buildMemoryPack(context, limit, budget);
+		const budgetRaw = opts.tokenBudget ?? opts.budget;
+		const budget = budgetRaw ? Number.parseInt(budgetRaw, 10) : void 0;
+		const filters = {};
+		if (!opts.allProjects) {
+			const project = process.env.CODEMEM_PROJECT?.trim() || resolveProject(process.cwd(), opts.project ?? null);
+			if (project) filters.project = project;
+		}
+		if ((opts.workingSetFile?.length ?? 0) > 0) p.log.warn("--working-set-file is accepted for compatibility but is not yet used by the TS pack builder.");
+		const result = store.buildMemoryPack(context, limit, budget, filters);
 		if (opts.json) {
 			console.log(JSON.stringify(result, null, 2));
 			return;
@@ -468,11 +610,16 @@ var packCommand = new Command("pack").configureHelp(helpStyle).description("Buil
 });
 //#endregion
 //#region src/commands/recent.ts
-var recentCommand = new Command("recent").configureHelp(helpStyle).description("Show recent memories").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--limit <n>", "max results", "5").option("--kind <kind>", "filter by memory kind").action((opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db));
+var recentCommand = new Command("recent").configureHelp(helpStyle).description("Show recent memories").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--limit <n>", "max results", "5").option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "search across all projects").option("--kind <kind>", "filter by memory kind").action((opts) => {
+	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
 	try {
 		const limit = Math.max(1, Number.parseInt(opts.limit, 10) || 5);
-		const filters = opts.kind ? { kind: opts.kind } : void 0;
+		const filters = {};
+		if (opts.kind) filters.kind = opts.kind;
+		if (!opts.allProjects) {
+			const project = process.env.CODEMEM_PROJECT?.trim() || resolveProject(process.cwd(), opts.project ?? null);
+			if (project) filters.project = project;
+		}
 		const items = store.recent(limit, filters);
 		for (const item of items) console.log(`#${item.id} [${item.kind}] ${item.title}`);
 	} finally {
@@ -481,11 +628,16 @@ var recentCommand = new Command("recent").configureHelp(helpStyle).description("
 });
 //#endregion
 //#region src/commands/search.ts
-var searchCommand = new Command("search").configureHelp(helpStyle).description("Search memories by query").argument("<query>", "search query").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("-n, --limit <n>", "max results", "10").option("--kind <kind>", "filter by memory kind").option("--json", "output as JSON").action((query, opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db));
+var searchCommand = new Command("search").configureHelp(helpStyle).description("Search memories by query").argument("<query>", "search query").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("-n, --limit <n>", "max results", "5").option("--project <project>", "project identifier (defaults to git repo root)").option("--all-projects", "search across all projects").option("--kind <kind>", "filter by memory kind").option("--json", "output as JSON").action((query, opts) => {
+	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
 	try {
-		const limit = Number.parseInt(opts.limit, 10) || 10;
-		const filters = opts.kind ? { kind: opts.kind } : void 0;
+		const limit = Math.max(1, Number.parseInt(opts.limit, 10) || 5);
+		const filters = {};
+		if (opts.kind) filters.kind = opts.kind;
+		if (!opts.allProjects) {
+			const project = process.env.CODEMEM_PROJECT?.trim() || resolveProject(process.cwd(), opts.project ?? null);
+			if (project) filters.project = project;
+		}
 		const results = store.search(query, limit, filters);
 		if (opts.json) {
 			console.log(JSON.stringify(results, null, 2));
@@ -520,6 +672,49 @@ function timeSince(isoDate) {
 	return `${Math.floor(days / 30)}mo ago`;
 }
 //#endregion
+//#region src/commands/serve-invocation.ts
+function parsePort(rawPort) {
+	const port = Number.parseInt(rawPort, 10);
+	if (!Number.isFinite(port) || port < 1 || port > 65535) throw new Error(`Invalid port: ${rawPort}`);
+	return port;
+}
+function resolveLegacyServeInvocation(opts) {
+	if (opts.stop && opts.restart) throw new Error("Use only one of --stop or --restart");
+	if (opts.foreground && opts.background) throw new Error("Use only one of --background or --foreground");
+	const dbPath = opts.db ?? opts.dbPath ?? null;
+	return {
+		mode: opts.stop ? "stop" : opts.restart ? "restart" : "start",
+		dbPath,
+		host: opts.host,
+		port: parsePort(opts.port),
+		background: opts.restart ? true : opts.background ? true : false
+	};
+}
+function resolveServeInvocation(action, opts) {
+	if (action === void 0) return resolveLegacyServeInvocation(opts);
+	if (opts.stop || opts.restart) throw new Error("Do not combine lifecycle flags with a serve action");
+	if (action === "start") return resolveStartServeInvocation(opts);
+	return resolveStopRestartInvocation(action, opts);
+}
+function resolveStartServeInvocation(opts) {
+	return {
+		mode: "start",
+		dbPath: opts.db ?? opts.dbPath ?? null,
+		host: opts.host,
+		port: parsePort(opts.port),
+		background: !opts.foreground
+	};
+}
+function resolveStopRestartInvocation(mode, opts) {
+	return {
+		mode,
+		dbPath: opts.db ?? opts.dbPath ?? null,
+		host: opts.host,
+		port: parsePort(opts.port),
+		background: mode === "restart"
+	};
+}
+//#endregion
 //#region src/commands/serve.ts
 function pidFilePath(dbPath) {
 	return join(dirname(dbPath), "viewer.pid");
@@ -545,6 +740,14 @@ function readViewerPidRecord(dbPath) {
 	}
 	return null;
 }
+function isProcessRunning(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
 async function respondsLikeCodememViewer(record) {
 	try {
 		const controller = new AbortController();
@@ -556,19 +759,37 @@ async function respondsLikeCodememViewer(record) {
 		return false;
 	}
 }
+async function isPortOpen(host, port) {
+	return new Promise((resolve) => {
+		const socket = net.createConnection({
+			host,
+			port
+		});
+		const done = (open) => {
+			socket.removeAllListeners();
+			socket.destroy();
+			resolve(open);
+		};
+		socket.setTimeout(300);
+		socket.once("connect", () => done(true));
+		socket.once("timeout", () => done(false));
+		socket.once("error", () => done(false));
+	});
+}
 async function waitForProcessExit(pid, timeoutMs = 5e3) {
 	const deadline = Date.now() + timeoutMs;
-	while (Date.now() < deadline) try {
-		process.kill(pid, 0);
+	while (Date.now() < deadline) {
+		if (!isProcessRunning(pid)) return;
 		await new Promise((resolve) => setTimeout(resolve, 100));
-	} catch {
-		return;
 	}
 }
 async function stopExistingViewer(dbPath) {
 	const pidPath = pidFilePath(dbPath);
 	const record = readViewerPidRecord(dbPath);
-	if (!record) return;
+	if (!record) return {
+		stopped: false,
+		pid: null
+	};
 	if (await respondsLikeCodememViewer(record)) try {
 		process.kill(record.pid, "SIGTERM");
 		await waitForProcessExit(record.pid);
@@ -576,17 +797,60 @@ async function stopExistingViewer(dbPath) {
 	try {
 		rmSync(pidPath);
 	} catch {}
+	return {
+		stopped: true,
+		pid: record.pid
+	};
+}
+function buildForegroundRunnerArgs(scriptPath, invocation, execArgv = process.execArgv) {
+	const args = [
+		...execArgv,
+		scriptPath,
+		"serve",
+		"start",
+		"--foreground",
+		"--host",
+		invocation.host,
+		"--port",
+		String(invocation.port)
+	];
+	if (invocation.dbPath) args.push("--db-path", invocation.dbPath);
+	return args;
+}
+async function startBackgroundViewer(invocation) {
+	if (await isPortOpen(invocation.host, invocation.port)) {
+		p.log.warn(`Viewer already running at http://${invocation.host}:${invocation.port}`);
+		return;
+	}
+	const scriptPath = process.argv[1];
+	if (!scriptPath) throw new Error("Unable to resolve CLI entrypoint for background launch");
+	const child = spawn(process.execPath, buildForegroundRunnerArgs(scriptPath, invocation), {
+		cwd: process.cwd(),
+		detached: true,
+		stdio: "ignore",
+		env: {
+			...process.env,
+			...invocation.dbPath ? { CODEMEM_DB: invocation.dbPath } : {}
+		}
+	});
+	child.unref();
+	if (invocation.dbPath) writeFileSync(pidFilePath(invocation.dbPath), JSON.stringify({
+		pid: child.pid,
+		host: invocation.host,
+		port: invocation.port
+	}), "utf-8");
+	p.intro("codemem viewer");
+	p.outro(`Viewer started in background (pid ${child.pid}) at http://${invocation.host}:${invocation.port}`);
 }
-var serveCommand = new Command("serve").configureHelp(helpStyle).description("Start the viewer server").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--host <host>", "bind host", "127.0.0.1").option("--port <port>", "bind port", "38888").option("--background", "run under a caller-managed background process").option("--stop", "stop an existing viewer process").option("--restart", "restart an existing viewer process").action(async (opts) => {
+async function startForegroundViewer(invocation) {
 	const { createApp, closeStore, getStore } = await import("@codemem/server");
 	const { serve } = await import("@hono/node-server");
-	const dbPath = resolveDbPath(opts.db);
-	if (opts.stop || opts.restart) {
-		await stopExistingViewer(dbPath);
-		if (opts.stop && !opts.restart) return;
+	if (invocation.dbPath) process.env.CODEMEM_DB = invocation.dbPath;
+	if (await isPortOpen(invocation.host, invocation.port)) {
+		p.log.warn(`Viewer already running at http://${invocation.host}:${invocation.port}`);
+		process.exitCode = 1;
+		return;
 	}
-	process.env.CODEMEM_DB = dbPath;
-	const port = Number.parseInt(opts.port, 10);
 	const observer = new ObserverClient();
 	const sweeper = new RawEventSweeper(getStore(), { observer });
 	sweeper.start();
@@ -595,11 +859,12 @@ var serveCommand = new Command("serve").configureHelp(helpStyle).description("St
 	const config = readCodememConfigFile();
 	if (config.sync_enabled === true || process.env.CODEMEM_SYNC_ENABLED?.toLowerCase() === "true" || process.env.CODEMEM_SYNC_ENABLED === "1") {
 		syncRunning = true;
+		const syncIntervalS = typeof config.sync_interval_s === "number" ? config.sync_interval_s : 120;
 		runSyncDaemon({
-			dbPath,
-			intervalS: typeof config.sync_interval_s === "number" ? config.sync_interval_s : 120,
-			host: opts.host,
-			port,
+			dbPath: resolveDbPath(invocation.dbPath ?? void 0),
+			intervalS: syncIntervalS,
+			host: invocation.host,
+			port: invocation.port,
 			signal: syncAbort.signal
 		}).catch((err) => {
 			const msg = err instanceof Error ? err.message : String(err);
@@ -612,16 +877,17 @@ var serveCommand = new Command("serve").configureHelp(helpStyle).description("St
 		storeFactory: getStore,
 		sweeper
 	});
+	const dbPath = resolveDbPath(invocation.dbPath ?? void 0);
 	const pidPath = pidFilePath(dbPath);
 	const server = serve({
 		fetch: app.fetch,
-		hostname: opts.host,
-		port
+		hostname: invocation.host,
+		port: invocation.port
 	}, (info) => {
 		writeFileSync(pidPath, JSON.stringify({
 			pid: process.pid,
-			host: opts.host,
-			port
+			host: invocation.host,
+			port: invocation.port
 		}), "utf-8");
 		p.intro("codemem viewer");
 		p.log.success(`Listening on http://${info.address}:${info.port}`);
@@ -629,6 +895,11 @@ var serveCommand = new Command("serve").configureHelp(helpStyle).description("St
 		p.log.step("Raw event sweeper started");
 		if (syncRunning) p.log.step("Sync daemon started");
 	});
+	server.on("error", (err) => {
+		if (err.code === "EADDRINUSE") p.log.warn(`Viewer already running at http://${invocation.host}:${invocation.port}`);
+		else p.log.error(err.message);
+		process.exit(1);
+	});
 	const shutdown = async () => {
 		p.outro("shutting down");
 		syncAbort.abort();
@@ -654,8 +925,74 @@ var serveCommand = new Command("serve").configureHelp(helpStyle).description("St
 	process.on("SIGTERM", () => {
 		shutdown();
 	});
+}
+async function runServeInvocation(invocation) {
+	const dbPath = resolveDbPath(invocation.dbPath ?? void 0);
+	if (invocation.mode === "stop" || invocation.mode === "restart") {
+		const result = await stopExistingViewer(dbPath);
+		if (result.stopped) {
+			p.intro("codemem viewer");
+			p.log.success(`Stopped viewer${result.pid ? ` (pid ${result.pid})` : ""}`);
+			if (invocation.mode === "stop") {
+				p.outro("done");
+				return;
+			}
+		} else if (invocation.mode === "stop") {
+			p.intro("codemem viewer");
+			p.outro("No background viewer found");
+			return;
+		}
+	}
+	if (invocation.mode === "start" || invocation.mode === "restart") {
+		if (invocation.background) {
+			await startBackgroundViewer({
+				...invocation,
+				dbPath
+			});
+			return;
+		}
+		await startForegroundViewer({
+			...invocation,
+			dbPath
+		});
+	}
+}
+function addSharedServeOptions(command) {
+	return command.option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--host <host>", "bind host", "127.0.0.1").option("--port <port>", "bind port", "38888");
+}
+var serveCommand = addSharedServeOptions(new Command("serve").configureHelp(helpStyle).description("Run or manage the viewer").argument("[action]", "lifecycle action (start|stop|restart)")).option("--background", "run viewer in background").option("--foreground", "run viewer in foreground").option("--stop", "stop background viewer").option("--restart", "restart background viewer").action(async (action, opts) => {
+	const normalizedAction = action === void 0 ? void 0 : action === "start" || action === "stop" || action === "restart" ? action : null;
+	if (normalizedAction === null) {
+		p.log.error(`Unknown serve action: ${action}`);
+		process.exitCode = 1;
+		return;
+	}
+	await runServeInvocation(resolveServeInvocation(normalizedAction, opts));
 });
 //#endregion
+//#region src/commands/setup-config.ts
+function resolveOpencodeConfigPath(configDir) {
+	const jsonPath = join(configDir, "opencode.json");
+	if (existsSync(jsonPath)) return jsonPath;
+	const jsoncPath = join(configDir, "opencode.jsonc");
+	if (existsSync(jsoncPath)) return jsoncPath;
+	return jsoncPath;
+}
+function loadJsoncConfig(path) {
+	if (!existsSync(path)) return {};
+	const raw = readFileSync(path, "utf-8");
+	try {
+		return JSON.parse(raw);
+	} catch {
+		const cleaned = stripTrailingCommas(stripJsonComments(raw));
+		return JSON.parse(cleaned);
+	}
+}
+function writeJsonConfig(path, data) {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
+}
+//#endregion
 //#region src/commands/setup.ts
 /**
 * codemem setup — one-command installation for OpenCode plugin + MCP config.
@@ -677,17 +1014,15 @@ function claudeConfigDir() {
 }
 /**
 * Find the plugin source file — walk up from this module's location
-* to find the .opencode/plugin/codemem.js in the package tree.
+* to find the .opencode/plugins/codemem.js in the package tree.
 */
 function findPluginSource() {
 	let dir = dirname(import.meta.url.replace("file://", ""));
 	for (let i = 0; i < 6; i++) {
-		const candidate = join(dir, ".opencode", "plugin", "codemem.js");
+		const candidate = join(dir, ".opencode", "plugins", "codemem.js");
 		if (existsSync(candidate)) return candidate;
-		const nmCandidate = join(dir, "node_modules", "codemem", ".opencode", "plugin", "codemem.js");
+		const nmCandidate = join(dir, "node_modules", "codemem", ".opencode", "plugins", "codemem.js");
 		if (existsSync(nmCandidate)) return nmCandidate;
-		const legacyCandidate = join(dir, "node_modules", "@kunickiaj", "codemem", ".opencode", "plugin", "codemem.js");
-		if (existsSync(legacyCandidate)) return legacyCandidate;
 		const parent = dirname(dir);
 		if (parent === dir) break;
 		dir = parent;
@@ -709,27 +1044,13 @@ function findCompatSource() {
 	}
 	return null;
 }
-function loadJsoncConfig(path) {
-	if (!existsSync(path)) return {};
-	const raw = readFileSync(path, "utf-8");
-	try {
-		return JSON.parse(raw);
-	} catch {
-		const cleaned = stripTrailingCommas(stripJsonComments(raw));
-		return JSON.parse(cleaned);
-	}
-}
-function writeJsonConfig(path, data) {
-	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
-}
 function installPlugin(force) {
 	const source = findPluginSource();
 	if (!source) {
 		p.log.error("Plugin file not found in package tree");
 		return false;
 	}
-	const destDir = join(opencodeConfigDir(), "plugin");
+	const destDir = join(opencodeConfigDir(), "plugins");
 	const dest = join(destDir, "codemem.js");
 	if (existsSync(dest) && !force) p.log.info(`Plugin already installed at ${dest}`);
 	else {
@@ -746,7 +1067,7 @@ function installPlugin(force) {
 	return true;
 }
 function installMcp(force) {
-	const configPath = join(opencodeConfigDir(), "opencode.json");
+	const configPath = resolveOpencodeConfigPath(opencodeConfigDir());
 	let config;
 	try {
 		config = loadJsoncConfig(configPath);
@@ -838,8 +1159,8 @@ function fmtTokens(n) {
 	if (n >= 1e3) return `~${(n / 1e3).toFixed(0)}K`;
 	return `${n}`;
 }
-var statsCommand = new Command("stats").configureHelp(helpStyle).description("Show database statistics").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--json", "output as JSON").action((opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db));
+var statsCommand = new Command("stats").configureHelp(helpStyle).description("Show database statistics").option("--db <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--db-path <path>", "database path (default: $CODEMEM_DB or ~/.codemem/mem.sqlite)").option("--json", "output as JSON").action((opts) => {
+	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
 	try {
 		const result = store.stats();
 		if (opts.json) {
@@ -876,14 +1197,382 @@ var statsCommand = new Command("stats").configureHelp(helpStyle).description("Sh
 	}
 });
 //#endregion
+//#region src/commands/sync-helpers.ts
+function formatSyncAttempt(row) {
+	const status = row.ok ? "ok" : "error";
+	const error = String(row.error || "");
+	const suffix = error ? ` | ${error}` : "";
+	return `${row.peer_device_id}|${status}|in=${row.ops_in}|out=${row.ops_out}|${row.finished_at ?? ""}${suffix}`;
+}
+function buildServeLifecycleArgs(action, opts, scriptPath, execArgv = []) {
+	if (!scriptPath) throw new Error("Unable to resolve CLI entrypoint for sync lifecycle command");
+	const args = [
+		...execArgv,
+		scriptPath,
+		"serve"
+	];
+	if (action === "start") args.push("--restart");
+	else if (action === "stop") args.push("--stop");
+	else args.push("--restart");
+	if (opts.db ?? opts.dbPath) args.push("--db-path", opts.db ?? opts.dbPath ?? "");
+	if (opts.host) args.push("--host", opts.host);
+	if (opts.port) args.push("--port", opts.port);
+	return args;
+}
+function formatSyncOnceResult(peerDeviceId, result) {
+	if (result.ok) return `- ${peerDeviceId}: ok`;
+	return `- ${peerDeviceId}: error${result.error ? `: ${result.error}` : ""}`;
+}
+function parseProjectList(value) {
+	if (!value) return [];
+	return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function collectAdvertiseAddresses(explicitAddress, configuredHost, port, interfaces) {
+	if (explicitAddress && !["auto", "default"].includes(explicitAddress.toLowerCase())) return [explicitAddress];
+	if (configuredHost && configuredHost !== "0.0.0.0") return [`${configuredHost}:${port}`];
+	const addresses = Object.values(interfaces).flatMap((entries) => entries ?? []).filter((entry) => !entry.internal).map((entry) => entry.address).filter((address) => address && address !== "127.0.0.1" && address !== "::1").map((address) => `${address}:${port}`);
+	return [...new Set(addresses)];
+}
+//#endregion
 //#region src/commands/sync.ts
 /**
 * Sync CLI commands — enable/disable/status/peers/connect.
 */
+function parseAttemptsLimit(value) {
+	if (!/^\d+$/.test(value.trim())) throw new Error(`Invalid --limit: ${value}`);
+	return Number.parseInt(value, 10);
+}
+async function portOpen(host, port) {
+	return new Promise((resolve) => {
+		const socket = net.createConnection({
+			host,
+			port
+		});
+		const done = (ok) => {
+			socket.removeAllListeners();
+			socket.destroy();
+			resolve(ok);
+		};
+		socket.setTimeout(300);
+		socket.once("connect", () => done(true));
+		socket.once("timeout", () => done(false));
+		socket.once("error", () => done(false));
+	});
+}
+function readViewerBinding(dbPath) {
+	try {
+		const raw = readFileSync(join(dirname(dbPath), "viewer.pid"), "utf8");
+		const parsed = JSON.parse(raw);
+		if (typeof parsed.host === "string" && typeof parsed.port === "number") return {
+			host: parsed.host,
+			port: parsed.port
+		};
+	} catch {}
+	return null;
+}
+function parseStoredAddressEndpoint(value) {
+	try {
+		const normalized = value.includes("://") ? value : `http://${value}`;
+		const url = new URL(normalized);
+		const port = url.port ? Number.parseInt(url.port, 10) : url.protocol === "https:" ? 443 : 80;
+		if (!url.hostname || !Number.isFinite(port)) return null;
+		return {
+			host: url.hostname,
+			port
+		};
+	} catch {
+		return null;
+	}
+}
+async function runServeLifecycle(action, opts) {
+	if (opts.user === false || opts.system === true) p.log.warn("TS sync lifecycle currently manages the local viewer process, not separate user/system services.");
+	if (action === "start") {
+		const config = readCodememConfigFile();
+		if (config.sync_enabled !== true) {
+			p.log.error("Sync is disabled. Run `codemem sync enable` first.");
+			process.exitCode = 1;
+			return;
+		}
+		const configuredHost = typeof config.sync_host === "string" ? config.sync_host : "0.0.0.0";
+		const configuredPort = typeof config.sync_port === "number" ? String(config.sync_port) : "7337";
+		opts.host ??= configuredHost;
+		opts.port ??= configuredPort;
+	} else if (action === "restart") {
+		const config = readCodememConfigFile();
+		const configuredHost = typeof config.sync_host === "string" ? config.sync_host : "0.0.0.0";
+		const configuredPort = typeof config.sync_port === "number" ? String(config.sync_port) : "7337";
+		opts.host ??= configuredHost;
+		opts.port ??= configuredPort;
+	}
+	const args = buildServeLifecycleArgs(action, opts, process.argv[1] ?? "", process.execArgv);
+	await new Promise((resolve, reject) => {
+		const child = spawn(process.execPath, args, {
+			cwd: process.cwd(),
+			stdio: "inherit",
+			env: {
+				...process.env,
+				...opts.db ?? opts.dbPath ? { CODEMEM_DB: opts.db ?? opts.dbPath } : {}
+			}
+		});
+		child.once("error", reject);
+		child.once("exit", (code) => {
+			if (code && code !== 0) process.exitCode = code;
+			resolve();
+		});
+	});
+}
 var syncCommand = new Command("sync").configureHelp(helpStyle).description("Sync configuration and peer management");
-syncCommand.addCommand(new Command("status").configureHelp(helpStyle).description("Show sync configuration and peer summary").option("--db <path>", "database path").option("--json", "output as JSON").action((opts) => {
+syncCommand.addCommand(new Command("attempts").configureHelp(helpStyle).description("Show recent sync attempts").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--limit <n>", "max attempts", "10").option("--json", "output as JSON").action((opts) => {
+	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+	try {
+		const d = drizzle(store.db, { schema });
+		const limit = parseAttemptsLimit(opts.limit);
+		const rows = d.select({
+			peer_device_id: schema.syncAttempts.peer_device_id,
+			ok: schema.syncAttempts.ok,
+			ops_in: schema.syncAttempts.ops_in,
+			ops_out: schema.syncAttempts.ops_out,
+			error: schema.syncAttempts.error,
+			finished_at: schema.syncAttempts.finished_at
+		}).from(schema.syncAttempts).orderBy(desc(schema.syncAttempts.finished_at)).limit(limit).all();
+		if (opts.json) {
+			console.log(JSON.stringify(rows, null, 2));
+			return;
+		}
+		for (const row of rows) console.log(formatSyncAttempt(row));
+	} finally {
+		store.close();
+	}
+}));
+syncCommand.addCommand(new Command("start").configureHelp(helpStyle).description("Start sync daemon").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--host <host>", "viewer host").option("--port <port>", "viewer port").option("--user", "accepted for compatibility", true).option("--system", "accepted for compatibility").action(async (opts) => {
+	await runServeLifecycle("start", opts);
+}));
+syncCommand.addCommand(new Command("stop").configureHelp(helpStyle).description("Stop sync daemon").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--host <host>", "viewer host").option("--port <port>", "viewer port").option("--user", "accepted for compatibility", true).option("--system", "accepted for compatibility").action(async (opts) => {
+	await runServeLifecycle("stop", opts);
+}));
+syncCommand.addCommand(new Command("restart").configureHelp(helpStyle).description("Restart sync daemon").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--host <host>", "viewer host").option("--port <port>", "viewer port").option("--user", "accepted for compatibility", true).option("--system", "accepted for compatibility").action(async (opts) => {
+	await runServeLifecycle("restart", opts);
+}));
+syncCommand.addCommand(new Command("once").configureHelp(helpStyle).description("Run a single sync pass").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--peer <peer>", "peer device id or name").action(async (opts) => {
+	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
+	try {
+		syncPassPreflight(store.db);
+		const d = drizzle(store.db, { schema });
+		const rows = opts.peer ? (() => {
+			const deviceMatches = d.select({ peer_device_id: schema.syncPeers.peer_device_id }).from(schema.syncPeers).where(eq(schema.syncPeers.peer_device_id, opts.peer)).all();
+			if (deviceMatches.length > 0) return deviceMatches;
+			const nameMatches = d.select({ peer_device_id: schema.syncPeers.peer_device_id }).from(schema.syncPeers).where(eq(schema.syncPeers.name, opts.peer)).all();
+			if (nameMatches.length > 1) {
+				p.log.error(`Peer name is ambiguous: ${opts.peer}`);
+				process.exitCode = 1;
+				return [];
+			}
+			return nameMatches;
+		})() : d.select({ peer_device_id: schema.syncPeers.peer_device_id }).from(schema.syncPeers).all();
+		if (rows.length === 0) {
+			p.log.warn("No peers available for sync");
+			process.exitCode = 1;
+			return;
+		}
+		let hadFailure = false;
+		for (const row of rows) {
+			const result = await runSyncPass(store.db, row.peer_device_id);
+			if (!result.ok) hadFailure = true;
+			console.log(formatSyncOnceResult(row.peer_device_id, result));
+		}
+		if (hadFailure) process.exitCode = 1;
+	} finally {
+		store.close();
+	}
+}));
+syncCommand.addCommand(new Command("pair").configureHelp(helpStyle).description("Print pairing payload or accept a peer payload").option("--accept <json>", "accept pairing payload JSON from another device").option("--accept-file <path>", "accept pairing payload from file path, or '-' for stdin").option("--payload-only", "when generating pairing payload, print JSON only").option("--name <name>", "label for the peer").option("--address <host:port>", "override peer address (host:port)").option("--include <projects>", "outbound-only allowlist for accepted peer").option("--exclude <projects>", "outbound-only blocklist for accepted peer").option("--all", "with --accept, push all projects to that peer").option("--default", "with --accept, use default/global push filters").option("--db-path <path>", "database path").action(async (opts) => {
+	const store = new MemoryStore(resolveDbPath(opts.dbPath));
+	try {
+		const acceptModeRequested = opts.accept != null || opts.acceptFile != null;
+		if (opts.payloadOnly && acceptModeRequested) {
+			p.log.error("--payload-only cannot be combined with --accept or --accept-file");
+			process.exitCode = 1;
+			return;
+		}
+		if (opts.accept && opts.acceptFile) {
+			p.log.error("Use only one of --accept or --accept-file");
+			process.exitCode = 1;
+			return;
+		}
+		let acceptText = opts.accept;
+		if (opts.acceptFile) try {
+			acceptText = opts.acceptFile === "-" ? await new Promise((resolve, reject) => {
+				let text = "";
+				process.stdin.setEncoding("utf8");
+				process.stdin.on("data", (chunk) => {
+					text += chunk;
+				});
+				process.stdin.on("end", () => resolve(text));
+				process.stdin.on("error", reject);
+			}) : readFileSync(opts.acceptFile, "utf8");
+		} catch (error) {
+			p.log.error(error instanceof Error ? `Failed to read pairing payload from ${opts.acceptFile}: ${error.message}` : `Failed to read pairing payload from ${opts.acceptFile}`);
+			process.exitCode = 1;
+			return;
+		}
+		if (acceptModeRequested && !(acceptText ?? "").trim()) {
+			p.log.error("Empty pairing payload; provide JSON via --accept or --accept-file");
+			process.exitCode = 1;
+			return;
+		}
+		if (!acceptText && (opts.include || opts.exclude || opts.all || opts.default)) {
+			p.log.error("Project filters are outbound-only and must be set on the device running --accept");
+			process.exitCode = 1;
+			return;
+		}
+		if (acceptText?.trim()) {
+			if (opts.all && opts.default) {
+				p.log.error("Use only one of --all or --default");
+				process.exitCode = 1;
+				return;
+			}
+			if ((opts.all || opts.default) && (opts.include || opts.exclude)) {
+				p.log.error("--include/--exclude cannot be combined with --all/--default");
+				process.exitCode = 1;
+				return;
+			}
+			let payload;
+			try {
+				payload = JSON.parse(acceptText);
+			} catch (error) {
+				p.log.error(error instanceof Error ? `Invalid pairing payload: ${error.message}` : "Invalid pairing payload");
+				process.exitCode = 1;
+				return;
+			}
+			const deviceId = String(payload.device_id || "").trim();
+			const fingerprint = String(payload.fingerprint || "").trim();
+			const publicKey = String(payload.public_key || "").trim();
+			const resolvedAddresses = opts.address?.trim() ? [opts.address.trim()] : Array.isArray(payload.addresses) ? payload.addresses.filter((item) => typeof item === "string" && item.trim().length > 0).map((item) => item.trim()) : [];
+			if (!deviceId || !fingerprint || !publicKey || resolvedAddresses.length === 0) {
+				p.log.error("Pairing payload missing device_id, fingerprint, public_key, or addresses");
+				process.exitCode = 1;
+				return;
+			}
+			if (fingerprintPublicKey(publicKey) !== fingerprint) {
+				p.log.error("Pairing payload fingerprint mismatch");
+				process.exitCode = 1;
+				return;
+			}
+			updatePeerAddresses(store.db, deviceId, resolvedAddresses, {
+				name: opts.name,
+				pinnedFingerprint: fingerprint,
+				publicKey
+			});
+			if (opts.default) setPeerProjectFilter(store.db, deviceId, {
+				include: null,
+				exclude: null
+			});
+			else if (opts.all || opts.include || opts.exclude) setPeerProjectFilter(store.db, deviceId, {
+				include: opts.all ? [] : parseProjectList(opts.include),
+				exclude: opts.all ? [] : parseProjectList(opts.exclude)
+			});
+			p.log.success(`Paired with ${deviceId}`);
+			return;
+		}
+		const keysDir = process.env.CODEMEM_KEYS_DIR?.trim() || void 0;
+		const [deviceId, fingerprint] = ensureDeviceIdentity(store.db, { keysDir });
+		const publicKey = loadPublicKey(keysDir);
+		if (!publicKey) {
+			p.log.error("Public key missing");
+			process.exitCode = 1;
+			return;
+		}
+		const config = readCodememConfigFile();
+		const explicitAddress = opts.address?.trim();
+		const configuredHost = typeof config.sync_host === "string" ? config.sync_host : null;
+		const configuredPort = typeof config.sync_port === "number" ? config.sync_port : 7337;
+		const addresses = collectAdvertiseAddresses(explicitAddress ?? null, configuredHost, configuredPort, networkInterfaces());
+		const payload = {
+			device_id: deviceId,
+			fingerprint,
+			public_key: publicKey,
+			address: addresses[0] ?? "",
+			addresses
+		};
+		const payloadText = JSON.stringify(payload);
+		if (opts.payloadOnly) {
+			process.stdout.write(`${payloadText}\n`);
+			return;
+		}
+		const escaped = payloadText.replaceAll("'", "'\\''");
+		console.log("Pairing payload");
+		console.log(payloadText);
+		console.log("On the other device, save this JSON to pairing.json, then run:");
+		console.log("  codemem sync pair --accept-file pairing.json");
+		console.log("If you prefer inline JSON, run:");
+		console.log(`  codemem sync pair --accept '${escaped}'`);
+		console.log("For machine-friendly output next time, run:");
+		console.log("  codemem sync pair --payload-only");
+		console.log("On the accepting device, --include/--exclude only control what it sends to peers.");
+		console.log("This device does not yet enforce incoming project filters.");
+	} finally {
+		store.close();
+	}
+}));
+syncCommand.addCommand(new Command("doctor").configureHelp(helpStyle).description("Diagnose common sync setup and connectivity issues").option("--db <path>", "database path").option("--db-path <path>", "database path").action(async (opts) => {
 	const config = readCodememConfigFile();
-	const store = new MemoryStore(resolveDbPath(opts.db));
+	const dbPath = resolveDbPath(opts.db ?? opts.dbPath);
+	const store = new MemoryStore(dbPath);
+	try {
+		const d = drizzle(store.db, { schema });
+		const device = d.select({ device_id: schema.syncDevice.device_id }).from(schema.syncDevice).limit(1).get();
+		const daemonState = d.select().from(schema.syncDaemonState).where(eq(schema.syncDaemonState.id, 1)).get();
+		const peers = d.select({
+			peer_device_id: schema.syncPeers.peer_device_id,
+			addresses_json: schema.syncPeers.addresses_json,
+			pinned_fingerprint: schema.syncPeers.pinned_fingerprint,
+			public_key: schema.syncPeers.public_key
+		}).from(schema.syncPeers).all();
+		const issues = [];
+		const syncHost = typeof config.sync_host === "string" ? config.sync_host : "0.0.0.0";
+		const syncPort = typeof config.sync_port === "number" ? config.sync_port : 7337;
+		const viewerBinding = readViewerBinding(dbPath);
+		console.log("Sync doctor");
+		console.log(`- Enabled: ${config.sync_enabled === true}`);
+		console.log(`- Listen: ${syncHost}:${syncPort}`);
+		console.log(`- mDNS: ${process.env.CODEMEM_SYNC_MDNS ? "env-configured" : "default/off"}`);
+		const reachable = viewerBinding ? await portOpen(viewerBinding.host, viewerBinding.port) : false;
+		console.log(`- Daemon: ${reachable ? "running" : "not running"}`);
+		if (!reachable) issues.push("daemon not running");
+		if (!device) {
+			console.log("- Identity: missing (run `codemem sync enable`)");
+			issues.push("identity missing");
+		} else console.log(`- Identity: ${device.device_id}`);
+		if (daemonState?.last_error && (!daemonState.last_ok_at || daemonState.last_ok_at < (daemonState.last_error_at ?? ""))) {
+			console.log(`- Daemon error: ${daemonState.last_error} (at ${daemonState.last_error_at ?? "unknown"})`);
+			issues.push("daemon error");
+		}
+		if (peers.length === 0) {
+			console.log("- Peers: none (pair a device first)");
+			issues.push("no peers");
+		} else {
+			console.log(`- Peers: ${peers.length}`);
+			for (const peer of peers) {
+				const addresses = peer.addresses_json ? JSON.parse(peer.addresses_json) : [];
+				const endpoint = parseStoredAddressEndpoint(addresses[0] ?? "");
+				const reach = endpoint ? await portOpen(endpoint.host, endpoint.port) ? "ok" : "unreachable" : "unknown";
+				const pinned = Boolean(peer.pinned_fingerprint);
+				const hasKey = Boolean(peer.public_key);
+				console.log(`  - ${peer.peer_device_id}: addresses=${addresses.length} reach=${reach} pinned=${pinned} public_key=${hasKey}`);
+				if (reach !== "ok") issues.push(`peer ${peer.peer_device_id} unreachable`);
+				if (!pinned || !hasKey) issues.push(`peer ${peer.peer_device_id} not pinned`);
+			}
+		}
+		if (!config.sync_enabled) issues.push("sync is disabled");
+		if (issues.length > 0) console.log(`WARN: ${[...new Set(issues)].slice(0, 3).join(", ")}`);
+		else console.log("OK: sync looks healthy");
+	} finally {
+		store.close();
+	}
+}));
+syncCommand.addCommand(new Command("status").configureHelp(helpStyle).description("Show sync configuration and peer summary").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--json", "output as JSON").action((opts) => {
+	const config = readCodememConfigFile();
+	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
 	try {
 		const d = drizzle(store.db, { schema });
 		const deviceRow = d.select({
@@ -934,8 +1623,8 @@ syncCommand.addCommand(new Command("status").configureHelp(helpStyle).descriptio
 		store.close();
 	}
 }));
-syncCommand.addCommand(new Command("enable").configureHelp(helpStyle).description("Enable sync and initialize device identity").option("--db <path>", "database path").option("--host <host>", "sync listen host").option("--port <port>", "sync listen port").option("--interval <seconds>", "sync interval in seconds").action((opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db));
+syncCommand.addCommand(new Command("enable").configureHelp(helpStyle).description("Enable sync and initialize device identity").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--host <host>", "sync listen host").option("--port <port>", "sync listen port").option("--interval <seconds>", "sync interval in seconds").action((opts) => {
+	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
 	try {
 		const [deviceId, fingerprint] = ensureDeviceIdentity(store.db);
 		const config = readCodememConfigFile();
@@ -964,8 +1653,8 @@ syncCommand.addCommand(new Command("disable").configureHelp(helpStyle).descripti
 	p.intro("codemem sync disable");
 	p.outro("Sync disabled — restart `codemem serve` to take effect");
 }));
-syncCommand.addCommand(new Command("peers").configureHelp(helpStyle).description("List known sync peers").option("--db <path>", "database path").option("--json", "output as JSON").action((opts) => {
-	const store = new MemoryStore(resolveDbPath(opts.db));
+syncCommand.addCommand(new Command("peers").configureHelp(helpStyle).description("List known sync peers").option("--db <path>", "database path").option("--db-path <path>", "database path").option("--json", "output as JSON").action((opts) => {
+	const store = new MemoryStore(resolveDbPath(opts.db ?? opts.dbPath));
 	try {
 		const peers = drizzle(store.db, { schema }).select({
 			peer_device_id: schema.syncPeers.peer_device_id,
@@ -1026,12 +1715,15 @@ completion.on("command", ({ reply }) => {
 		"claude-hook-ingest",
 		"db",
 		"export-memories",
+		"forget",
 		"memory",
 		"import-memories",
 		"setup",
+		"show",
 		"sync",
 		"stats",
 		"recent",
+		"remember",
 		"search",
 		"pack",
 		"serve",
@@ -1044,16 +1736,24 @@ completion.on("command", ({ reply }) => {
 	]);
 });
 completion.init();
-if (process.argv.includes("--setup-completion")) {
+function hasRootFlag(flag) {
+	for (const arg of process.argv.slice(2)) {
+		if (arg === "--") return false;
+		if (arg === flag) return true;
+		if (!arg.startsWith("-")) return false;
+	}
+	return false;
+}
+var program = new Command();
+program.name("codemem").description("codemem — persistent memory for AI coding agents").version(VERSION).configureHelp(helpStyle);
+if (hasRootFlag("--setup-completion")) {
 	completion.setupShellInitFile();
 	process.exit(0);
 }
-if (process.argv.includes("--cleanup-completion")) {
+if (hasRootFlag("--cleanup-completion")) {
 	completion.cleanupShellInitFile();
 	process.exit(0);
 }
-var program = new Command();
-program.name("codemem").description("codemem — persistent memory for AI coding agents").version(VERSION).configureHelp(helpStyle);
 program.addCommand(serveCommand);
 program.addCommand(mcpCommand);
 program.addCommand(claudeHookIngestCommand);
@@ -1064,6 +1764,9 @@ program.addCommand(statsCommand);
 program.addCommand(recentCommand);
 program.addCommand(searchCommand);
 program.addCommand(packCommand);
+program.addCommand(showMemoryCommand);
+program.addCommand(forgetMemoryCommand);
+program.addCommand(rememberMemoryCommand);
 program.addCommand(memoryCommand);
 program.addCommand(syncCommand);
 program.addCommand(setupCommand);