stackmem 1.0.25 → 1.0.27

package/src/cli.ts

@@ -2,11 +2,13 @@
 import nodeFs from "node:fs";
 import nodeOs from "node:os";
 import nodePath from "node:path";
+import { execFileSync } from "node:child_process";
 import { randomInt } from "node:crypto";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createInterface } from "node:readline/promises";
 import { analyzeCodebase } from "./ast-index.js";
 import { VAULT_URL } from "./config.js";
+import { defaultConfigFileContents, readStackmemConfig, STACKMEM_CONFIG_FILENAME } from "./config-file.js";
 import { getDeviceId } from "./device.js";
 import {
   applyContextBudget,
@@ -20,12 +22,27 @@ import {
   indicatesFailedApproach,
   isAuthRelatedFile,
   isCodeFile,
+  hasTokenOverlap,
   isQualityMessage,
+  parseUtcDate,
   redactSecrets,
   scoreMemoryRelevance,
+  tokenize,
 } from "./scoring.js";
 import { supabase } from "./storage.js";
 
+// Checked as early as ESM import hoisting allows — before any command
+// dispatch, config loading, or network call — so an unsupported Node
+// version fails with a clear message instead of an obscure syntax or
+// API error from deeper in the dependency chain.
+const NODE_MAJOR_VERSION = Number(process.versions.node.split(".")[0]);
+if (NODE_MAJOR_VERSION < 18) {
+  console.error(
+    `Error: stackmem requires Node 18 or higher.\nYou are running Node ${process.versions.node}.\nPlease upgrade: https://nodejs.org`
+  );
+  process.exit(1);
+}
+
 const CONTEXT_BUDGET_TOKENS = 2000;
 const COMPRESSION_THRESHOLD = 20;
 const CLI_PATH = fileURLToPath(import.meta.url);
@@ -41,7 +58,7 @@ const DIST_INDEX_PATH = nodePath.join(nodePath.dirname(CLI_PATH), "..", "dist",
 const STACKMEM_HOOK_MARKER = "# stackmem-managed";
 const CLAUDE_MD_MARKER = "the stackmem MCP server will automatically load memories for this project";
 const RULES_FILE_MARKER = "# stackmem — project memory (auto-updated)";
-const HOOK_BACKUP_FILENAME = "post-commit.pre-stackmem";
+const HOOK_BACKUP_SUFFIX = ".pre-stackmem";
 
 const MEMORY_TYPES = ["decision", "rejection", "constraint", "discovery"] as const;
 type MemoryType = (typeof MEMORY_TYPES)[number];
@@ -55,22 +72,30 @@ const TYPE_LABELS: Record<MemoryType, string> = {
 
 function usage(): never {
   console.error(`Usage:
-  cm start [project]
+  cm start [project] [--hook]
   cm save [project] <type> <content> [--force]  (type: decision|rejection|constraint|discovery)
   cm fix [project] <problem> <solution>
   cm analyze [project] <path>
   cm search [--project <name>] <query>
   cm resolve [project] <memory-id>
+  cm pin [project] <memory-id>
+  cm unpin [project] <memory-id>
+  cm review [--project <name>]
+  cm edit [project] <memory-id>
   cm delete [project] <memory-id>
   cm inspect [project] <memory-id>
   cm compress [project]
-  cm init <project> <path>
+  cm init <project> <path> [--config]
   cm uninstall [project] [path]
   cm link
+  cm open [--project <name>]
+  cm purge [--project <name>] [--all]
   cm sync
-  cm context [--project <name>] <task>
-  cm session-end [project] [--summary <text>] [--errors <a,b>] [--files <a,b>] [--approaches <a,b>]
+  cm context [--project <name>] <task> [--hook]
+  cm why [--project <name>] <file>
+  cm session-end [project] [--summary <text>] [--errors <a,b>] [--files <a,b>] [--approaches <a,b>] [--hook]
   cm doctor [--fix]
+  cm status [--project <name>]
   cm undo [project]
   cm export [filename]
   cm import [project] <filename>
@@ -92,11 +117,13 @@ function cmdHelp() {
   [project] is optional everywhere below if a .stackmem file exists in
   the current directory (written by 'cm init'). Otherwise pass it explicitly.
 
-  cm start [project]
+  cm start [project] [--hook]
       Load all unresolved memories for a project, sorted by decay
       score and capped at a 2000 token context budget, grouped by
       type (decisions, constraints, discoveries, rejections), with
-      linked memory ids shown under each entry.
+      linked memory ids shown under each entry. --hook switches to
+      plain-text output (no ids, scores, or separator lines) for use
+      as a Claude Code SessionStart hook command — see cm init.
 
   cm save [project] <type> <content> [--force]
       Save a new memory. <type> is one of: decision, rejection,
@@ -120,6 +147,26 @@ function cmdHelp() {
   cm resolve [project] <memory-id>
       Mark a memory as resolved.
 
+  cm pin [project] <memory-id>
+      Pin a memory: it scores 999 in decay ranking (always sorts
+      first, never decays) and shows in its own "Pinned" section at
+      the top of 'cm start', ahead of its normal type group.
+
+  cm unpin [project] <memory-id>
+      Un-pin a memory, returning it to normal decay-based ranking.
+
+  cm review [--project <name>]
+      Walk through suggested memories one at a time (hook-captured
+      memories start as suggested — see cm save/cm init). For each:
+      (k)eep promotes it to permanent, (e)dit opens $EDITOR (or an
+      inline prompt) for new content then keeps it, (d)rop deletes
+      it, (s)kip leaves it suggested for next time, (q)uit stops and
+      reports progress so far. Prints a kept/dropped/skipped summary.
+
+  cm edit [project] <memory-id>
+      Open a memory's content in $EDITOR (or an inline prompt if
+      $EDITOR isn't set), save the result.
+
   cm delete [project] <memory-id>
       Delete a memory and any memory_links referencing it.
 
@@ -134,7 +181,7 @@ function cmdHelp() {
       Cluster related unresolved memories (needs 20+) and collapse
       clusters of 3 or more into a single summary memory.
 
-  cm init <project> <path>
+  cm init <project> <path> [--config]
       Install a git post-commit hook in the repo at <path>, register
       the stackmem MCP server with Claude Code, write a CLAUDE.md,
       .cursorrules, .windsurfrules, and .stackmem file, and seed
@@ -142,7 +189,12 @@ function cmdHelp() {
       .windsurfrules are pre-filled with the project's current
       memories (for Cursor and Windsurf) and skipped if they already
       exist. The post-commit hook keeps them fresh afterward by
-      running 'cm sync' on every commit.
+      running 'cm sync' on every commit — on disk only, never
+      committed, so they don't double your commit count or conflict
+      across branches. Both files are added to .gitignore. With
+      --config, also writes a default .stackmem.json (ignore patterns,
+      tokenBudget, decayLambda, captureTypes, minQualityScore — see
+      src/config-file.ts) if one doesn't already exist.
 
   cm uninstall [project] [path]
       Remove everything 'cm init' set up at <path> (defaults to the
@@ -162,19 +214,44 @@ function cmdHelp() {
       single-use and expires after 10 minutes; polling stops when it
       does. Links are per-device, so run this once on each machine.
 
+  cm open [--project <name>]
+      Open the hosted vault's page for this project in the default
+      browser (open on Mac, xdg-open on Linux, start on Windows).
+
+  cm purge [--project <name>] [--all]
+      Permanently delete memories, fixes, and memory_links — with a
+      typed confirmation first, never deletes on a flag alone.
+      --project (or the one in .stackmem): deletes that project's
+      data only, after you type the exact project name to confirm.
+      --all: deletes everything for this device's device_id across
+      every project, after you type DELETE to confirm. Prints the
+      count of deleted records, or "Confirmation did not match" if
+      you abort.
+
   cm sync
       Regenerate .cursorrules and .windsurfrules from the project's
       current unresolved memories (decay-ranked, capped at a 2000
       token budget) and its 5 most recent open execution_log fixes,
-      overwriting both files. Project is read from .stackmem.
+      overwriting both files on disk only (never git add/commit).
+      Project is read from .stackmem.
 
-  cm context [--project <name>] <task>
+  cm context [--project <name>] <task> [--hook]
       Return only the top 5 memories most relevant to a specific
       task, ranked by a blend of task relevance and decay score,
       as a markdown block capped at a 2000 token budget. Use
       --project to target a project other than the one in .stackmem.
-
-  cm session-end [project] [--summary <text>] [--errors <a,b>] [--files <a,b>] [--approaches <a,b>]
+      <task> is optional with --hook (ranks by decay alone) — used
+      as a Claude Code PreCompact hook command; see cm init.
+
+  cm why [--project <name>] <file>
+      Show memories tied to a file: matched by Item 6's file_paths
+      column (hook-captured commits that touched it) plus a plain
+      content search for the file's path or basename, ranked by decay
+      score and grouped by type. Prints a guidance message instead if
+      nothing matches. Use --project to target a project other than
+      the one in .stackmem.
+
+  cm session-end [project] [--summary <text>] [--errors <a,b>] [--files <a,b>] [--approaches <a,b>] [--hook]
       Capture what happened in a session and extract memories: each
       error becomes an unsolved execution_log entry, each approach
       containing "failed", "didn't work", "reverted", or "switched
@@ -184,6 +261,11 @@ function cmdHelp() {
       Accepts the same fields as JSON on stdin instead of flags
       (project, summary, errors_encountered, files_touched,
       approaches_tried) when stdin is piped rather than a terminal.
+      --hook is accepted for use as a Claude Code Stop hook command
+      (see cm init) but is currently a no-op: Claude Code pipes its
+      own hook payload on stdin, not this command's expected shape,
+      so a Stop-triggered run captures 0 memories until a future
+      phase parses the session transcript directly.
 
   cm doctor [--fix]
       Check every integration point in the current directory — backend
@@ -196,6 +278,12 @@ function cmdHelp() {
       — those print guidance instead. Reports "Fixed: <item>" or
       "Could not auto-fix: <item>" for each failing check.
 
+  cm status [--project <name>]
+      One-screen project summary: memory/pinned/suggested counts,
+      recorded fixes, the active token budget (and whether it's the
+      default or from .stackmem.json), time since the last capture,
+      and hook/MCP/backend/editor registration status.
+
   cm undo [project]
       Delete the most recently saved unresolved memory (and any
       memory_links referencing it) for a project.
@@ -224,11 +312,35 @@ function fail(message: string): never {
 
 const STACKMEM_FILE = ".stackmem";
 
+const MONOREPO_PARENT_LOOKUP_DEPTH = 3;
+
+// Checks cwd, then up to 3 parent directories, for a .stackmem file — a
+// monorepo subpackage (e.g. packages/api) won't have its own .stackmem,
+// but the repo root will. When found in an ancestor, the project name
+// gets the intervening path segments appended, e.g. "myapp/packages/api"
+// — so a subpackage still reads/writes under its own namespace within
+// the shared project, rather than silently resolving to just "myapp".
 function readProjectFromFile(): string | null {
-  const stackmemPath = nodePath.join(process.cwd(), STACKMEM_FILE);
-  if (!nodeFs.existsSync(stackmemPath)) return null;
-  const content = nodeFs.readFileSync(stackmemPath, "utf-8").trim();
-  return content.length > 0 ? content : null;
+  let dir = process.cwd();
+  const subdirSegments: string[] = [];
+
+  for (let depth = 0; depth <= MONOREPO_PARENT_LOOKUP_DEPTH; depth++) {
+    const stackmemPath = nodePath.join(dir, STACKMEM_FILE);
+    if (nodeFs.existsSync(stackmemPath)) {
+      const content = nodeFs.readFileSync(stackmemPath, "utf-8").trim();
+      if (content.length === 0) return null;
+      return subdirSegments.length > 0
+        ? `${content}/${subdirSegments.reverse().join("/")}`
+        : content;
+    }
+
+    const parent = nodePath.dirname(dir);
+    if (parent === dir) break; // reached the filesystem root
+    subdirSegments.push(nodePath.basename(dir));
+    dir = parent;
+  }
+
+  return null;
 }
 
 // Catches the common habit-slip of typing `cm fix . "problem" "solution"` by
@@ -293,33 +405,208 @@ function splitProjectFromVariadic(args: string[]): { project: string | null; res
   return { project: null, rest: args };
 }
 
+// Generic "--flag value" extractor for internal/provenance flags (not
+// meant to be remembered by end users — only the hook and MCP server pass
+// these). Unlike splitProjectFromVariadic's --project, these don't need
+// special positional disambiguation, so one generic helper covers all of
+// them: --commit-sha, --author, --source, --confidence, --files.
+function extractValueFlag(args: string[], flag: string): { value: string | null; rest: string[] } {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || args[idx + 1] === undefined) return { value: null, rest: args };
+  return { value: args[idx + 1], rest: [...args.slice(0, idx), ...args.slice(idx + 2)] };
+}
+
 // --- cm start ----------------------------------------------------------
 
-async function cmdStart(project: string) {
+const RECENT_COMMITS_FOR_FILE_SIGNAL = 5;
+const BRANCH_NAME_BOOST = 1.2;
+const RECENT_FILES_BOOST = 1.3;
+const PR_TITLE_BOOST = 1.2;
+
+// null means "signal unavailable" (git/gh failed, not enough history, gh
+// not installed, no open PR, etc.) — every one of these is a soft skip,
+// never an error, per the task spec.
+function getBranchNameTokens(): Set<string> | null {
+  let branch: string;
+  try {
+    // symbolic-ref (not rev-parse --abbrev-ref) specifically because it
+    // fails on a detached HEAD rather than returning the literal string
+    // "HEAD" — that failure is the signal this needs to distinguish a
+    // real detached-HEAD state from "not a git repo at all" below.
+    branch = execFileSync("git", ["symbolic-ref", "--short", "HEAD"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    try {
+      execFileSync("git", ["rev-parse", "HEAD"], { stdio: "pipe" });
+      // HEAD resolves to a real commit but symbolic-ref failed — genuinely
+      // detached, not a missing repo. Still a valid state to rank in, not
+      // a reason to skip the signal entirely.
+      branch = "detached";
+    } catch {
+      return null;
+    }
+  }
+
+  const tokens = tokenize(branch);
+  return tokens.size > 0 ? tokens : null;
+}
+
+function getRecentlyTouchedFiles(): Set<string> | null {
+  try {
+    const isShallow = execFileSync("git", ["rev-parse", "--is-shallow-repository"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    // A shallow clone can't look back RECENT_COMMITS_FOR_FILE_SIGNAL
+    // commits — degrade gracefully rather than attempting (and either
+    // failing, or silently returning an incomplete picture of "recent").
+    if (isShallow === "true") return null;
+  } catch {
+    // --is-shallow-repository itself failing (very old git, or no repo at
+    // all) isn't a reason to skip on its own — the lookback below will
+    // fail (and get caught) or succeed on its own merits either way.
+  }
+
+  try {
+    const output = execFileSync(
+      "git",
+      ["diff", "--name-only", `HEAD~${RECENT_COMMITS_FOR_FILE_SIGNAL}`, "HEAD"],
+      { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }
+    );
+    const files = output.split("\n").map((f) => f.trim()).filter(Boolean);
+    return files.length > 0 ? new Set(files) : null;
+  } catch {
+    // Fewer than RECENT_COMMITS_FOR_FILE_SIGNAL commits in history, or
+    // not a git repo at all — skip gracefully.
+    return null;
+  }
+}
+
+function getOpenPrTitleTokens(): Set<string> | null {
+  try {
+    const title = execFileSync("gh", ["pr", "view", "--json", "title", "-q", ".title"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (!title) return null;
+    const tokens = tokenize(title);
+    return tokens.size > 0 ? tokens : null;
+  } catch {
+    // gh not installed, not authenticated, or no open PR for this branch.
+    return null;
+  }
+}
+
+function fileListOverlaps(filePaths: unknown, recentFiles: Set<string>): boolean {
+  if (!Array.isArray(filePaths)) return false;
+  return filePaths.some((candidate) => {
+    if (typeof candidate !== "string") return false;
+    if (recentFiles.has(candidate)) return true;
+    const base = candidate.split("/").pop();
+    for (const recent of recentFiles) {
+      if (recent.split("/").pop() === base) return true;
+    }
+    return false;
+  });
+}
+
+// Plain-text, no ids/scores/box-drawing — meant to be injected directly
+// into a Claude Code SessionStart hook's context, not read by a human at
+// a terminal (that's the default, non---hook rendering below).
+function printStartHookOutput(
+  project: string,
+  pinnedMemories: any[],
+  unpinnedMemories: any[],
+  budgetedFixes: { problem: string; solution: string | null }[]
+): void {
+  console.log(`# Project memory: ${project}`);
+
+  if (pinnedMemories.length > 0) {
+    console.log("");
+    console.log("## Pinned");
+    for (const memory of pinnedMemories) {
+      console.log(`- ${memory.content}`);
+    }
+  }
+
+  for (const type of MEMORY_TYPES) {
+    const group = unpinnedMemories.filter((m) => m.type === type);
+    if (group.length === 0) continue;
+
+    console.log("");
+    console.log(`## ${TYPE_LABELS[type]}`);
+    for (const memory of group) {
+      console.log(`- ${memory.content}`);
+    }
+  }
+
+  if (budgetedFixes.length > 0) {
+    console.log("");
+    console.log("## Past Fixes");
+    for (const fix of budgetedFixes) {
+      console.log(`- ${fix.problem} -> ${fix.solution ?? "(pending)"}`);
+    }
+  }
+}
+
+async function cmdStart(project: string, hookMode = false) {
   const { data, error } = await supabase
     .from("memories")
     .select("*")
     .eq("project", project)
-    .eq("resolved", false);
+    .eq("resolved", false)
+    .eq("suggested", false);
 
   if (error) fail(`Failed to load memories: ${error.message}`);
 
   const memories = data ?? [];
   if (memories.length === 0) {
-    console.log(`No memories found for "${project}".`);
-    console.log("");
-    console.log("Tip: run 'cm init' to seed tech stack memories from your project files.");
+    if (!hookMode) {
+      console.log(`No memories found for "${project}".`);
+      console.log("");
+      console.log("Tip: run 'cm init' to seed tech stack memories from your project files.");
+    }
     return;
   }
 
+  // Task-aware re-ranking: boost memories relevant to what's actively
+  // being worked on, multiplicatively on top of the base decay score.
+  // Every signal degrades to null (no boost, not an error) if the
+  // repo/branch/gh state it needs isn't available.
+  const branchTokens = getBranchNameTokens();
+  const recentFiles = getRecentlyTouchedFiles();
+  const prTitleTokens = getOpenPrTitleTokens();
+
+  const config = readStackmemConfig();
+  const tokenBudget = config.tokenBudget;
+
   const scoredMemories = memories
-    .map((memory) => ({
-      ...memory,
-      decay_score: computeDecayScore(new Date(memory.created_at), memory.access_count ?? 0),
-    }))
+    .map((memory) => {
+      let decayScore = computeDecayScore(
+        parseUtcDate(memory.created_at),
+        memory.access_count ?? 0,
+        memory.pinned ?? false,
+        config.decayLambda
+      );
+
+      const contentTokens = tokenize(memory.content);
+      if (branchTokens && hasTokenOverlap(contentTokens, branchTokens)) {
+        decayScore *= BRANCH_NAME_BOOST;
+      }
+      if (recentFiles && fileListOverlaps(memory.file_paths, recentFiles)) {
+        decayScore *= RECENT_FILES_BOOST;
+      }
+      if (prTitleTokens && hasTokenOverlap(contentTokens, prTitleTokens)) {
+        decayScore *= PR_TITLE_BOOST;
+      }
+
+      return { ...memory, decay_score: decayScore };
+    })
     .sort((a, b) => b.decay_score - a.decay_score);
 
-  const budgetedMemories = applyContextBudget(scoredMemories, CONTEXT_BUDGET_TOKENS);
+  const budgetedMemories = applyContextBudget(scoredMemories, tokenBudget);
   const omittedCount = scoredMemories.length - budgetedMemories.length;
   let tokensUsed = budgetedMemories.reduce(
     (sum, memory) => sum + estimateTokens(memory.content),
@@ -336,12 +623,12 @@ async function cmdStart(project: string) {
 
   if (fixError) fail(`Failed to load execution log: ${fixError.message}`);
 
-  // Fixes share the same 2000-token budget as memories, which already
-  // consumed their portion above — fixes only get whatever room is left.
+  // Fixes share the same token budget as memories, which already consumed
+  // their portion above — fixes only get whatever room is left.
   const budgetedFixes: { problem: string; solution: string | null }[] = [];
   for (const fix of fixData ?? []) {
     const tokens = estimateTokens(`${fix.problem} ${fix.solution ?? ""}`);
-    if (tokensUsed + tokens > CONTEXT_BUDGET_TOKENS) break;
+    if (tokensUsed + tokens > tokenBudget) break;
     budgetedFixes.push(fix);
     tokensUsed += tokens;
   }
@@ -364,43 +651,63 @@ async function cmdStart(project: string) {
     linkedIdsByMemory.get(link.target_id)!.add(link.source_id);
   }
 
-  console.log(`Loaded ${scoredMemories.length} memory(ies) for "${project}".\n`);
+  const pinnedMemories = budgetedMemories.filter((m) => m.pinned);
+  const unpinnedMemories = budgetedMemories.filter((m) => !m.pinned);
 
-  for (const type of MEMORY_TYPES) {
-    const group = budgetedMemories.filter((m) => m.type === type);
-    if (group.length === 0) continue;
-
-    console.log(`${TYPE_LABELS[type]} (${group.length})`);
-    console.log("-".repeat(TYPE_LABELS[type].length + 4));
-    for (const memory of group) {
-      console.log(`  [${memory.id}] (score: ${memory.decay_score.toFixed(2)}) ${memory.content}`);
-      const linked = Array.from(linkedIdsByMemory.get(memory.id) ?? []);
-      if (linked.length > 0) {
-        console.log(`      linked: ${linked.join(", ")}`);
+  if (hookMode) {
+    printStartHookOutput(project, pinnedMemories, unpinnedMemories, budgetedFixes);
+  } else {
+    console.log(`Loaded ${scoredMemories.length} memory(ies) for "${project}".\n`);
+
+    if (pinnedMemories.length > 0) {
+      console.log(`Pinned (${pinnedMemories.length})`);
+      console.log("-".repeat(11));
+      for (const memory of pinnedMemories) {
+        console.log(`  [${memory.id}] (${memory.type}) ${memory.content}`);
+        const linked = Array.from(linkedIdsByMemory.get(memory.id) ?? []);
+        if (linked.length > 0) {
+          console.log(`      linked: ${linked.join(", ")}`);
+        }
       }
+      console.log("");
     }
-    console.log("");
-  }
 
-  if (budgetedFixes.length > 0) {
-    console.log(`Past Fixes (${budgetedFixes.length})`);
-    console.log("-".repeat(14));
-    for (const fix of budgetedFixes) {
-      console.log(`  Problem: ${fix.problem}`);
-      console.log(`  Solution: ${fix.solution ?? "(pending)"}`);
+    for (const type of MEMORY_TYPES) {
+      const group = unpinnedMemories.filter((m) => m.type === type);
+      if (group.length === 0) continue;
+
+      console.log(`${TYPE_LABELS[type]} (${group.length})`);
+      console.log("-".repeat(TYPE_LABELS[type].length + 4));
+      for (const memory of group) {
+        console.log(`  [${memory.id}] (score: ${memory.decay_score.toFixed(2)}) ${memory.content}`);
+        const linked = Array.from(linkedIdsByMemory.get(memory.id) ?? []);
+        if (linked.length > 0) {
+          console.log(`      linked: ${linked.join(", ")}`);
+        }
+      }
       console.log("");
     }
-  }
 
-  console.log(`Context budget: ${tokensUsed}/${CONTEXT_BUDGET_TOKENS} tokens used`);
-  if (omittedCount > 0) {
-    console.log(`${omittedCount} memories omitted (budget exceeded)`);
-  }
+    if (budgetedFixes.length > 0) {
+      console.log(`Past Fixes (${budgetedFixes.length})`);
+      console.log("-".repeat(14));
+      for (const fix of budgetedFixes) {
+        console.log(`  Problem: ${fix.problem}`);
+        console.log(`  Solution: ${fix.solution ?? "(pending)"}`);
+        console.log("");
+      }
+    }
 
-  const hasTechStackMemory = memories.some((m) => /^tech stack:/i.test(m.content));
-  if (!hasTechStackMemory) {
-    console.log("");
-    console.log("Tip: run 'cm init' to seed tech stack memories from your project files.");
+    console.log(`Context budget: ${tokensUsed}/${tokenBudget} tokens used`);
+    if (omittedCount > 0) {
+      console.log(`${omittedCount} memories omitted (budget exceeded)`);
+    }
+
+    const hasTechStackMemory = memories.some((m) => /^tech stack:/i.test(m.content));
+    if (!hasTechStackMemory) {
+      console.log("");
+      console.log("Tip: run 'cm init' to seed tech stack memories from your project files.");
+    }
   }
 
   const incrementResults = await Promise.all(
@@ -446,7 +753,26 @@ async function confirmSupersede(oldId: string, newContent: string): Promise<bool
   return false;
 }
 
-async function cmdSave(project: string, type: string, content: string, force = false) {
+// Provenance metadata attached to a memory at save time. Manual `cm save`
+// calls (a human at the keyboard) leave this at its defaults — source
+// "manual", confidence 1.0, no commit/file/author info. The hook passes
+// commitSha/filePaths/author and source "hook" with a lower confidence;
+// MCP tool saves pass source "mcp".
+interface SaveProvenance {
+  commitSha?: string;
+  filePaths?: string[];
+  author?: string;
+  source?: "hook" | "manual" | "mcp";
+  confidence?: number;
+}
+
+async function cmdSave(
+  project: string,
+  type: string,
+  content: string,
+  force = false,
+  provenance: SaveProvenance = {}
+) {
   if (!MEMORY_TYPES.includes(type as MemoryType)) {
     fail(`Invalid memory type '${type}'. Valid types: decision, constraint, discovery, rejection.`);
   }
@@ -492,9 +818,27 @@ async function cmdSave(project: string, type: string, content: string, force = f
     if (resolveError) fail(`Failed to resolve superseded memory: ${resolveError.message}`);
   }
 
+  const { commitSha, filePaths, author, source = "manual", confidence = 1.0 } = provenance;
+  const insertPayload: Record<string, unknown> = {
+    project,
+    type,
+    content,
+    device_id: getDeviceId(),
+    source,
+    confidence,
+    // Hook-captured memories are heuristically detected and could be
+    // noisy or wrong — they start as suggested, pending `cm review`, and
+    // are excluded from cm start/context/why until promoted. Manual and
+    // mcp saves are already user-vetted, so they're permanent immediately.
+    suggested: source === "hook",
+  };
+  if (commitSha) insertPayload.commit_sha = commitSha;
+  if (filePaths && filePaths.length > 0) insertPayload.file_paths = filePaths;
+  if (author) insertPayload.author = author;
+
   const { data: inserted, error } = await supabase
     .from("memories")
-    .insert({ project, type, content, device_id: getDeviceId() })
+    .insert(insertPayload)
     .select("id")
     .single();
 
@@ -530,6 +874,40 @@ async function cmdSave(project: string, type: string, content: string, force = f
   }
 }
 
+// --- cm check-commit (internal, used by the hook) --------------------------
+
+// Not a user-facing command (no usage()/help entry) — the hook calls this
+// once per invocation, before doing any diff analysis, to decide whether
+// this commit_sha has already been captured. post-commit and post-rewrite
+// both run the exact same capture logic against current HEAD, so without
+// this guard, a commit that fires both hooks (e.g. `git commit --amend`,
+// which triggers post-commit for the new commit AND post-rewrite for the
+// rewrite) would be captured twice. Checked once per invocation — not
+// inside each individual cmSave call — because a single commit normally
+// produces several distinct memories; a per-save check would see the
+// first save's own commit_sha and wrongly skip the rest.
+async function cmdCheckCommit(project: string, commitSha: string): Promise<void> {
+  const { data, error } = await supabase
+    .from("memories")
+    .select("id")
+    .eq("project", project)
+    .eq("commit_sha", commitSha)
+    .limit(1);
+
+  if (error) {
+    // Fail open: an error here (including "column does not exist" if the
+    // commit_sha migration hasn't landed yet) must not look identical to
+    // "duplicate, skip" below — that would silently suppress every hook
+    // capture with no log trail. Exit 0 so the normal save path runs;
+    // if commit_sha genuinely isn't a column, the save itself fails
+    // there instead, where the hook's outer error handler logs it.
+    console.error(`check-commit: ${error.message}`);
+    process.exit(0);
+  }
+
+  process.exit(data && data.length > 0 ? 1 : 0);
+}
+
 // --- memory compression ----------------------------------------------------
 
 async function compressMemories(
@@ -539,7 +917,8 @@ async function compressMemories(
     .from("memories")
     .select("*")
     .eq("project", project)
-    .eq("resolved", false);
+    .eq("resolved", false)
+    .eq("suggested", false);
 
   if (error) fail(`Failed to load memories for compression: ${error.message}`);
 
@@ -688,6 +1067,34 @@ async function cmdResolve(project: string, memoryId: string) {
   console.log(`Resolved memory [${memoryId}]`);
 }
 
+// --- cm pin / cm unpin -------------------------------------------------
+
+async function setPinned(project: string, memoryId: string, pinned: boolean): Promise<void> {
+  const { data, error } = await supabase
+    .from("memories")
+    .update({ pinned })
+    .eq("project", project)
+    .eq("id", memoryId)
+    .select("id");
+
+  if (error) fail(`Failed to ${pinned ? "pin" : "unpin"} memory: ${error.message}`);
+
+  if (!data || data.length === 0) {
+    console.log(`No memory found with ID [${memoryId}]`);
+    return;
+  }
+
+  console.log(`${pinned ? "Pinned" : "Unpinned"} memory [${memoryId}]`);
+}
+
+async function cmdPin(project: string, memoryId: string): Promise<void> {
+  await setPinned(project, memoryId, true);
+}
+
+async function cmdUnpin(project: string, memoryId: string): Promise<void> {
+  await setPinned(project, memoryId, false);
+}
+
 // --- cm delete -------------------------------------------------------------
 
 async function cmdDelete(project: string, memoryId: string) {
@@ -715,10 +1122,173 @@ async function cmdDelete(project: string, memoryId: string) {
   console.log(`Deleted memory [${memoryId}]`);
 }
 
+// --- shared: relative time + $EDITOR prompt (cm review, cm edit, cm status)
+
+function formatRelativeTime(date: Date): string {
+  const seconds = Math.floor((Date.now() - date.getTime()) / 1000);
+  if (seconds < 60) return `${seconds} second${seconds === 1 ? "" : "s"} ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? "" : "s"} ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+  const days = Math.floor(hours / 24);
+  return `${days} day${days === 1 ? "" : "s"} ago`;
+}
+
+// Opens $EDITOR on a scratch file pre-filled with the current content, or
+// falls back to an inline readline prompt when $EDITOR isn't set. Returns
+// the original content unchanged if the result is blank (an empty save
+// buffer almost certainly means "I didn't mean to clear this", not "make
+// this memory empty").
+async function editContentInteractively(currentContent: string): Promise<string> {
+  const editor = process.env.EDITOR;
+
+  if (editor) {
+    const tmpFile = nodePath.join(nodeOs.tmpdir(), `stackmem-edit-${randomInt(1_000_000_000)}.txt`);
+    nodeFs.writeFileSync(tmpFile, currentContent, "utf-8");
+    try {
+      execFileSync(editor, [tmpFile], { stdio: "inherit" });
+      const edited = nodeFs.readFileSync(tmpFile, "utf-8").trim();
+      return edited.length > 0 ? edited : currentContent;
+    } finally {
+      try {
+        nodeFs.unlinkSync(tmpFile);
+      } catch {
+        // Best-effort cleanup — a leftover temp file isn't worth failing on.
+      }
+    }
+  }
+
+  console.log(`Current: ${currentContent}`);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = (await rl.question("New content (leave blank to keep unchanged): ")).trim();
+  rl.close();
+  return answer.length > 0 ? answer : currentContent;
+}
+
+// --- cm review -------------------------------------------------------------
+
+async function cmdReview(project: string): Promise<void> {
+  const { data, error } = await supabase
+    .from("memories")
+    .select("*")
+    .eq("project", project)
+    .eq("resolved", false)
+    .eq("suggested", true)
+    .order("created_at", { ascending: true });
+
+  if (error) fail(`Failed to load suggested memories: ${error.message}`);
+
+  const memories = data ?? [];
+  if (memories.length === 0) {
+    console.log(`No memories to review for "${project}".`);
+    console.log("Your inbox is empty.");
+    return;
+  }
+
+  console.log(`Reviewing ${memories.length} suggested memories for "${project}"`);
+  console.log("━".repeat(40));
+
+  // Node's readline can't reliably answer multiple sequential
+  // rl.question() calls over piped (non-TTY) stdin — all buffered input
+  // arrives before the second question is even issued, and it never
+  // resolves. A real interactive terminal doesn't hit this (keystrokes
+  // arrive one at a time), so only the non-TTY path needs the
+  // read-everything-up-front workaround.
+  const rl = process.stdin.isTTY ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+  const pipedAnswers: string[] = rl
+    ? []
+    : (
+        await new Promise<string>((resolve) => {
+          let buf = "";
+          process.stdin.setEncoding("utf-8");
+          process.stdin.on("data", (chunk) => (buf += chunk));
+          process.stdin.on("end", () => resolve(buf));
+        })
+      ).split("\n");
+
+  async function nextAnswer(prompt: string): Promise<string> {
+    if (rl) return (await rl.question(prompt)).trim().toLowerCase();
+    console.log(prompt);
+    return (pipedAnswers.shift() ?? "q").trim().toLowerCase();
+  }
+
+  let kept = 0;
+  let dropped = 0;
+  let skipped = 0;
+
+  for (let i = 0; i < memories.length; i++) {
+    const memory = memories[i];
+    console.log(`[${i + 1}/${memories.length}] ${memory.type}: ${memory.content}`);
+    console.log(`      Captured: ${formatRelativeTime(parseUtcDate(memory.created_at))}`);
+    console.log("");
+
+    const answer = await nextAnswer("(k)eep  (e)dit  (d)rop  (s)kip  (q)uit > ");
+    console.log("");
+
+    if (answer === "k") {
+      const { error: updateError } = await supabase
+        .from("memories")
+        .update({ suggested: false })
+        .eq("id", memory.id);
+      if (!updateError) kept++;
+    } else if (answer === "e") {
+      const newContent = redactSecrets(await editContentInteractively(memory.content));
+      const { error: updateError } = await supabase
+        .from("memories")
+        .update({ content: newContent, suggested: false })
+        .eq("id", memory.id);
+      if (!updateError) kept++;
+    } else if (answer === "d") {
+      await supabase
+        .from("memory_links")
+        .delete()
+        .or(`source_id.eq.${memory.id},target_id.eq.${memory.id}`);
+      const { error: deleteError } = await supabase.from("memories").delete().eq("id", memory.id);
+      if (!deleteError) dropped++;
+    } else if (answer === "q") {
+      break;
+    } else {
+      // "s", blank, or anything unrecognized — leave it suggested and
+      // move on rather than erroring on a mistyped key.
+      skipped++;
+    }
+  }
+
+  rl?.close();
+  console.log(`Review complete. Kept ${kept}, dropped ${dropped}, skipped ${skipped}.`);
+}
+
+// --- cm edit ---------------------------------------------------------------
+
+async function cmdEdit(project: string, memoryId: string): Promise<void> {
+  const { data: memory, error } = await supabase
+    .from("memories")
+    .select("id, content")
+    .eq("project", project)
+    .eq("id", memoryId)
+    .single();
+
+  if (error || !memory) {
+    console.log(`No memory found with ID [${memoryId}]`);
+    return;
+  }
+
+  const newContent = redactSecrets(await editContentInteractively(memory.content));
+  const { error: updateError } = await supabase
+    .from("memories")
+    .update({ content: newContent })
+    .eq("id", memoryId);
+
+  if (updateError) fail(`Failed to update memory: ${updateError.message}`);
+
+  console.log(`Updated memory [${memoryId}].`);
+}
+
 // --- cm inspect ------------------------------------------------------------
 
 function formatDate(dateString: string): string {
-  return new Date(dateString).toLocaleDateString("en-US", {
+  return parseUtcDate(dateString).toLocaleDateString("en-US", {
     month: "short",
     day: "numeric",
     year: "numeric",
@@ -735,7 +1305,13 @@ async function cmdInspect(project: string, memoryId: string) {
 
   if (error || !memory) fail(`Memory [${memoryId}] not found for "${project}".`);
 
-  const decayScore = computeDecayScore(new Date(memory.created_at), memory.access_count ?? 0);
+  const config = readStackmemConfig();
+  const decayScore = computeDecayScore(
+    parseUtcDate(memory.created_at),
+    memory.access_count ?? 0,
+    memory.pinned ?? false,
+    config.decayLambda
+  );
 
   const { data: links, error: linksError } = await supabase
     .from("memory_links")
@@ -843,6 +1419,65 @@ try {
 
 const CLI_PATH = ${JSON.stringify(cliPath)};
 
+// Inlined copy of src/config-file.ts's defaults/merge logic — this script
+// runs standalone with no import access to that module.
+const DEFAULT_STACKMEM_CONFIG = {
+  ignore: [],
+  tokenBudget: 2000,
+  decayLambda: 0.05,
+  captureTypes: ["decision", "constraint", "discovery", "rejection"],
+  minQualityScore: 0.3,
+};
+
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function readStackmemConfig() {
+  const configPath = join(process.cwd(), ".stackmem.json");
+  try {
+    const raw = JSON.parse(readFileSync(configPath, "utf8"));
+    return {
+      ignore: isStringArray(raw.ignore) ? raw.ignore : DEFAULT_STACKMEM_CONFIG.ignore,
+      tokenBudget:
+        typeof raw.tokenBudget === "number" && raw.tokenBudget > 0
+          ? raw.tokenBudget
+          : DEFAULT_STACKMEM_CONFIG.tokenBudget,
+      decayLambda:
+        typeof raw.decayLambda === "number" && raw.decayLambda > 0
+          ? raw.decayLambda
+          : DEFAULT_STACKMEM_CONFIG.decayLambda,
+      captureTypes: isStringArray(raw.captureTypes) ? raw.captureTypes : DEFAULT_STACKMEM_CONFIG.captureTypes,
+      minQualityScore:
+        typeof raw.minQualityScore === "number"
+          ? raw.minQualityScore
+          : DEFAULT_STACKMEM_CONFIG.minQualityScore,
+    };
+  } catch {
+    return { ...DEFAULT_STACKMEM_CONFIG };
+  }
+}
+
+function matchesIgnorePattern(filePath, pattern) {
+  const base = filePath.split("/").pop() ?? filePath;
+
+  if (pattern.endsWith("/")) {
+    const dirName = pattern.slice(0, -1);
+    return filePath.split("/").includes(dirName);
+  }
+
+  if (pattern.includes("*")) {
+    const regex = new RegExp(
+      "^" + pattern.split("*").map((part) => part.replace(/[.*+?^\${}()|[\\]\\\\]/g, "\\\\$&")).join(".*") + "$"
+    );
+    return regex.test(base) || regex.test(filePath);
+  }
+
+  return filePath === pattern || base === pattern;
+}
+
+const STACKMEM_CONFIG = readStackmemConfig();
+
 const SECRET_PATTERNS = [
   /AKIA[0-9A-Z]{16}/g,
   /(api[_-]?key|apikey)\\s*[:=]\\s*["']?[\\w-]{20,}["']?/gi,
@@ -899,10 +1534,43 @@ function git(args) {
   return execFileSync("git", args, { encoding: "utf-8" }).trim();
 }
 
+const CURRENT_SHA = git(["rev-parse", "HEAD"]);
+const CURRENT_AUTHOR = (() => {
+  try {
+    return git(["log", "--format=%ae", "-1", "HEAD"]);
+  } catch {
+    return "";
+  }
+})();
+
+// post-commit and post-rewrite both run this exact script against current
+// HEAD, so a single operation that fires both (e.g. \`git commit --amend\`)
+// would otherwise capture the same commit twice. Checked once up front,
+// not per-save — see cmdCheckCommit in src/cli.ts for why.
+try {
+  execFileSync("node", [CLI_PATH, "check-commit", PROJECT, CURRENT_SHA], { stdio: "pipe" });
+} catch {
+  return;
+}
+
+// file_paths is populated with every file the commit touched (not just
+// the filtered diffableFiles below) — "cm why <file>" should still find
+// a commit's decision/discovery even if that specific file's own diff
+// content was skipped as noise (a lockfile, say).
 function cmSave(type, content) {
-  execFileSync("node", [CLI_PATH, "save", PROJECT, type, content, "--force"], {
-    stdio: "inherit",
-  });
+  if (!STACKMEM_CONFIG.captureTypes.includes(type)) return;
+
+  const args = [
+    CLI_PATH, "save", PROJECT, type, content, "--force",
+    "--commit-sha", CURRENT_SHA,
+    "--source", "hook",
+    "--confidence", "0.8",
+  ];
+  if (CURRENT_AUTHOR) args.push("--author", CURRENT_AUTHOR);
+  if (changedFiles.length > 0) args.push("--files", changedFiles.join(","));
+
+  execFileSync("node", args, { stdio: "inherit" });
+  savedItems.push(\`\${type}: \${content}\`);
 }
 
 function basename(filePath) {
@@ -929,6 +1597,29 @@ function isSchemaFile(filePath) {
   );
 }
 
+// Noise that's never worth diffing: lockfiles, build output, vendored/
+// generated code, and timestamp-prefixed SQL migrations (their content is
+// a mechanical dump, not a human decision). Checked against path segments
+// (not just a prefix) so "apps/web/dist/bundle.js" is skipped too, not
+// just a top-level "dist/...".
+const DIFF_SKIP_DIR_NAMES = new Set(["dist", "build", ".next", "coverage", "vendored", "node_modules"]);
+const DIFF_SKIP_LOCK_NAMES = new Set(["package-lock.json", "yarn.lock", "pnpm-lock.yaml"]);
+const MIGRATION_FILE_RE = /^\\d{14}_.*\\.sql$/;
+const DIFF_MAX_BYTES = 50 * 1024;
+
+function shouldSkipDiffFile(filePath) {
+  const base = basename(filePath);
+  if (filePath.split("/").some((segment) => DIFF_SKIP_DIR_NAMES.has(segment))) return true;
+  if (DIFF_SKIP_LOCK_NAMES.has(base) || base.endsWith(".lock")) return true;
+  if (base.endsWith(".min.js") || base.endsWith(".min.css")) return true;
+  if (base.endsWith(".map")) return true;
+  if (base.endsWith(".pb.go")) return true;
+  if (/\\.generated\\./.test(base)) return true;
+  if (MIGRATION_FILE_RE.test(base)) return true;
+  if (STACKMEM_CONFIG.ignore.some((pattern) => matchesIgnorePattern(filePath, pattern))) return true;
+  return false;
+}
+
 const LOW_QUALITY_PREFIXES = [
   "wip", "fix", "update", "misc", "temp", "test", "patch", "minor",
   "tweak", "change", "stuff", "done", "commit", "save", "ok", "m", "x",
@@ -963,11 +1654,10 @@ const savedItems = [];
 
 const commitMessage = git(["log", "-1", "--pretty=%B"]);
 
-// The sync commit below is itself a commit, so it fires this same
-// post-commit hook again — git's --no-verify only skips pre-commit and
-// commit-msg hooks, never post-commit. Without this guard, the hook would
-// save its own commit message as a new decision memory, which changes the
-// rules-file content and triggers another sync commit, indefinitely.
+// Kept as a general escape hatch for other automation (CI bots, scripts)
+// that tags its own commits this way and shouldn't be captured as a
+// memory — cm sync no longer self-commits, so this isn't load-bearing for
+// that anymore, but other tools' commits still deserve the same skip.
 if (commitMessage.includes("[skip ci]")) {
   return;
 }
@@ -991,10 +1681,40 @@ const changedFiles = git(
 
 let diff = "";
 if (!isFirstCommit) {
+  // --numstat marks a binary file's added/deleted columns as "-" — that's
+  // the cheapest way to identify them without fetching their (useless,
+  // and potentially huge) diff content at all.
+  let binaryFiles = new Set();
   try {
-    diff = execFileSync("git", ["diff", "HEAD~1", "HEAD"], { encoding: "utf-8" });
+    const numstat = execFileSync("git", ["diff", "--numstat", "HEAD~1", "HEAD"], {
+      encoding: "utf-8",
+    });
+    for (const line of numstat.split("\\n")) {
+      const parts = line.split("\\t");
+      if (parts[0] === "-" && parts[1] === "-" && parts[2]) {
+        binaryFiles.add(parts[2]);
+      }
+    }
   } catch {
-    diff = "";
+    // Nothing to compare against — leave binaryFiles empty.
+  }
+
+  const diffableFiles = changedFiles.filter(
+    (file) => !binaryFiles.has(file) && !shouldSkipDiffFile(file)
+  );
+
+  if (diffableFiles.length > 0) {
+    try {
+      diff = execFileSync("git", ["diff", "HEAD~1", "HEAD", "--", ...diffableFiles], {
+        encoding: "utf-8",
+      });
+    } catch {
+      diff = "";
+    }
+  }
+
+  if (diff.length > DIFF_MAX_BYTES) {
+    diff = diff.slice(0, DIFF_MAX_BYTES) + "\\n\\n... [diff truncated: exceeded 50KB after filtering]\\n";
   }
 }
 
@@ -1021,17 +1741,14 @@ for (const line of isFirstCommit ? [] : lines) {
       if (/(auth|login|session|token)/i.test(currentFile)) {
         const content = redactSecrets(\`new auth-related file: \${currentFile}\`);
         cmSave("discovery", content);
-        savedItems.push(\`discovery: \${content}\`);
       }
       if (isConfigFile(currentFile)) {
         const content = redactSecrets(\`new config: \${currentFile}\`);
         cmSave("constraint", content);
-        savedItems.push(\`constraint: \${content}\`);
       }
       if (isSchemaFile(currentFile)) {
         const content = redactSecrets(\`schema change: \${currentFile}\`);
         cmSave("discovery", content);
-        savedItems.push(\`discovery: \${content}\`);
       }
     }
     continue;
@@ -1068,7 +1785,6 @@ for (const line of isFirstCommit ? [] : lines) {
     if (removedModulePath) {
       const content = redactSecrets(\`removed dependency: \${removedModulePath}\`);
       cmSave("rejection", content);
-      savedItems.push(\`rejection: \${content}\`);
     }
 
     if (isPackageJson && inDependenciesSection) {
@@ -1076,7 +1792,6 @@ for (const line of isFirstCommit ? [] : lines) {
       if (pkgMatch && pkgMatch[1] !== "dependencies" && pkgMatch[1] !== "devDependencies") {
         const content = redactSecrets(\`removed dependency: \${pkgMatch[1]}\`);
         cmSave("rejection", content);
-        savedItems.push(\`rejection: \${content}\`);
       }
     }
     continue;
@@ -1092,7 +1807,6 @@ for (const line of isFirstCommit ? [] : lines) {
         if (envMatch) {
           const content = redactSecrets(\`new env var required: \${envMatch[1]}\`);
           cmSave("constraint", content);
-          savedItems.push(\`constraint: \${content}\`);
         }
       }
     }
@@ -1102,7 +1816,6 @@ for (const line of isFirstCommit ? [] : lines) {
       if (pkgMatch && pkgMatch[1] !== "dependencies" && pkgMatch[1] !== "devDependencies") {
         const content = redactSecrets(\`added dependency: \${pkgMatch[1]}\`);
         cmSave("decision", content);
-        savedItems.push(\`decision: \${content}\`);
       }
     }
 
@@ -1110,14 +1823,12 @@ for (const line of isFirstCommit ? [] : lines) {
       const truncated = codeLine.trim().slice(0, 80);
       const content = redactSecrets(\`database change: \${truncated}\`);
       cmSave("discovery", content);
-      savedItems.push(\`discovery: \${content}\`);
     }
 
     if (/^\\+\\s*(\\/\\/|#)\\s*(TODO:|FIXME:|HACK:|XXX:)/.test(line)) {
       const truncated = codeLine.trim().slice(0, 100);
       const content = redactSecrets(\`open issue from commit: \${truncated}\`);
       cmSave("discovery", content);
-      savedItems.push(\`discovery: \${content}\`);
     }
   }
 }
@@ -1146,19 +1857,16 @@ if (breakingMatch) {
   const breakingContent = redactSecrets(breakingMatch[1].trim());
   const content = \`BREAKING CHANGE: \${breakingContent}\`;
   cmSave("constraint", content);
-  savedItems.push(\`constraint: \${content}\`);
 }
 
 if (conventionalType && CONVENTIONAL_DECISION_TYPES.has(conventionalType)) {
   const trimmedMessage = redactSecrets(trimmedCommitMessage);
   cmSave("decision", trimmedMessage);
-  savedItems.push(\`decision: \${trimmedMessage}\`);
 } else if (conventionalType && CONVENTIONAL_SKIP_TYPES.has(conventionalType)) {
   // docs/style/test/ci/build/chore — skip entirely, nothing saved.
 } else if (isQualityCommitMessage(commitMessage)) {
   const trimmedMessage = redactSecrets(trimmedCommitMessage);
   cmSave("decision", trimmedMessage);
-  savedItems.push(\`decision: \${trimmedMessage}\`);
 }
 
 console.log(\`coding-memory post-commit summary (\${changedFiles.length} file(s) changed):\`);
@@ -1166,21 +1874,13 @@ for (const item of savedItems) {
   console.log(\`  - \${item}\`);
 }
 
+// Updates .cursorrules/.windsurfrules on disk only — no git add/commit.
+// Editors read these files straight off disk, and they're gitignored by
+// default (see DEFAULT_GITIGNORE_CONTENT), so there's nothing to keep in
+// sync with git history; committing them here used to double the commit
+// count on every real commit and produced constant rules-file merge
+// conflicts on teams.
 execFileSync("node", [CLI_PATH, "sync"], { stdio: "inherit" });
-
-// cm sync rewrites .cursorrules/.windsurfrules, which would otherwise leave
-// the working directory dirty (breaking things like \`npm version patch\`
-// that require a clean tree). Commit the sync ourselves instead. --no-verify
-// skips pre-commit/commit-msg hooks (not post-commit — see the [skip ci]
-// guard above, which is what actually stops this from recursing).
-try {
-  execFileSync("git", ["add", ".cursorrules", ".windsurfrules"], { stdio: "pipe" });
-  execFileSync("git", ["commit", "--no-verify", "-m", "chore: sync memory to rules files [skip ci]"], {
-    stdio: "pipe",
-  });
-} catch {
-  // Nothing to commit (rules files unchanged) — fine, ignore.
-}
 }
 
 async function main() {
@@ -1206,15 +1906,27 @@ main().finally(() => process.exit(0));
 `;
 }
 
-// Installs (or re-installs) the stackmem post-commit hook at `hooksDir`. If
-// a post-commit hook already exists and wasn't written by stackmem, it's
+// Hooks stackmem manages. post-rewrite fires on `git commit --amend` and
+// `git rebase` (neither of which is a plain commit, so post-commit alone
+// misses them) — it runs the exact same capture script as post-commit,
+// against current HEAD, with the check-commit idempotency guard in the
+// script itself preventing a double-capture when a single operation
+// (e.g. --amend) fires both hooks for the same resulting commit.
+const MANAGED_HOOK_NAMES = ["post-commit", "post-rewrite"] as const;
+
+function hookBackupFilename(hookName: string): string {
+  return `${hookName}${HOOK_BACKUP_SUFFIX}`;
+}
+
+// Installs (or re-installs) a stackmem-managed hook at `hooksDir`. If a
+// hook of this name already exists and wasn't written by stackmem, it's
 // preserved as a backup and chained to run before stackmem's own hook,
 // rather than being clobbered — see `uninstallHook` for how it's restored.
-function installHook(hooksDir: string, hookLogicPath: string): void {
+function installHook(hooksDir: string, hookLogicPath: string, hookName: string): void {
   nodeFs.mkdirSync(hooksDir, { recursive: true });
 
-  const hookPath = nodePath.join(hooksDir, "post-commit");
-  const backupPath = nodePath.join(hooksDir, HOOK_BACKUP_FILENAME);
+  const hookPath = nodePath.join(hooksDir, hookName);
+  const backupPath = nodePath.join(hooksDir, hookBackupFilename(hookName));
 
   let chainedOriginal = false;
   if (nodeFs.existsSync(hookPath)) {
@@ -1231,7 +1943,7 @@ function installHook(hooksDir: string, hookLogicPath: string): void {
   }
 
   const chainLine = chainedOriginal
-    ? `"$(dirname "$0")/${HOOK_BACKUP_FILENAME}" "$@"\n`
+    ? `"$(dirname "$0")/${hookBackupFilename(hookName)}" "$@"\n`
     : "";
 
   nodeFs.writeFileSync(
@@ -1242,7 +1954,7 @@ function installHook(hooksDir: string, hookLogicPath: string): void {
   nodeFs.chmodSync(hookPath, 0o755);
 
   if (chainedOriginal) {
-    console.log("Existing post-commit hook found — chained it to run before stackmem's hook.");
+    console.log(`Existing ${hookName} hook found — chained it to run before stackmem's hook.`);
   }
 }
 
@@ -1250,9 +1962,9 @@ function installHook(hooksDir: string, hookLogicPath: string): void {
 // stackmem chained it after an existing hook, restores that original hook
 // in its place. Returns a description of what happened, or null if there
 // was no stackmem-managed hook to remove (nothing done).
-function uninstallHook(hooksDir: string): string | null {
-  const hookPath = nodePath.join(hooksDir, "post-commit");
-  const backupPath = nodePath.join(hooksDir, HOOK_BACKUP_FILENAME);
+function uninstallHook(hooksDir: string, hookName: string): string | null {
+  const hookPath = nodePath.join(hooksDir, hookName);
+  const backupPath = nodePath.join(hooksDir, hookBackupFilename(hookName));
 
   if (!nodeFs.existsSync(hookPath)) return null;
 
@@ -1261,11 +1973,11 @@ function uninstallHook(hooksDir: string): string | null {
 
   if (nodeFs.existsSync(backupPath)) {
     nodeFs.renameSync(backupPath, hookPath);
-    return ".git/hooks/post-commit (restored original hook stackmem had chained)";
+    return `.git/hooks/${hookName} (restored original hook stackmem had chained)`;
   }
 
   nodeFs.unlinkSync(hookPath);
-  return ".git/hooks/post-commit";
+  return `.git/hooks/${hookName}`;
 }
 
 // Overridable so tests (and `cm uninstall`'s own smoke-testing) can point
@@ -1319,6 +2031,122 @@ function unregisterMcpServer(claudeConfigPath = getClaudeConfigPath()): boolean
   return true;
 }
 
+// --- MCP registration for other editors ---------------------------------
+
+// Each entry detects its editor by an existing config directory (never
+// erroring if absent — "skip silently" per the task) and merges stackmem
+// into whatever's already there, same spirit as registerMcpServer above.
+// homeDir is a parameter (not a hardcoded nodeOs.homedir() call) so tests
+// can point at a scratch directory instead of the real one.
+interface EditorMcpTarget {
+  name: string;
+  configPath: (homeDir: string) => string | null;
+  register: (configPath: string, distIndexPath: string) => void;
+}
+
+function mergeMcpServersJson(configPath: string, distIndexPath: string): void {
+  let config: { mcpServers?: Record<string, unknown> } = {};
+  if (nodeFs.existsSync(configPath)) {
+    try {
+      config = JSON.parse(nodeFs.readFileSync(configPath, "utf-8"));
+    } catch {
+      config = {};
+    }
+  }
+  if (!config.mcpServers || typeof config.mcpServers !== "object") {
+    config.mcpServers = {};
+  }
+  config.mcpServers.stackmem = { command: "node", args: [distIndexPath] };
+
+  nodeFs.mkdirSync(nodePath.dirname(configPath), { recursive: true });
+  nodeFs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+}
+
+// VS Code installs the Copilot Chat extension under a version-suffixed
+// directory name (e.g. "github.copilot-chat-0.26.4") — this resolves the
+// "github.copilot-chat*" glob the task describes against whatever's
+// actually installed, rather than assuming a fixed folder name.
+function findCopilotChatExtensionDir(homeDir: string): string | null {
+  const extensionsDir = nodePath.join(homeDir, ".vscode", "extensions");
+  if (!nodeFs.existsSync(extensionsDir)) return null;
+
+  try {
+    const match = nodeFs
+      .readdirSync(extensionsDir)
+      .find((entry) => entry.startsWith("github.copilot-chat"));
+    return match ? nodePath.join(extensionsDir, match) : null;
+  } catch {
+    return null;
+  }
+}
+
+const EDITOR_MCP_TARGETS: EditorMcpTarget[] = [
+  {
+    name: "Cursor",
+    configPath: (homeDir) => {
+      const dir = nodePath.join(homeDir, ".cursor");
+      return nodeFs.existsSync(dir) ? nodePath.join(dir, "mcp.json") : null;
+    },
+    register: mergeMcpServersJson,
+  },
+  {
+    name: "Windsurf",
+    configPath: (homeDir) => {
+      const dir = nodePath.join(homeDir, ".codeium", "windsurf");
+      return nodeFs.existsSync(dir) ? nodePath.join(dir, "mcp_config.json") : null;
+    },
+    register: mergeMcpServersJson,
+  },
+  {
+    name: "VS Code (Copilot)",
+    configPath: (homeDir) => {
+      const extensionDir = findCopilotChatExtensionDir(homeDir);
+      return extensionDir ? nodePath.join(extensionDir, "mcp.json") : null;
+    },
+    register: mergeMcpServersJson,
+  },
+  {
+    name: "Zed",
+    configPath: (homeDir) => {
+      const dir = nodePath.join(homeDir, ".config", "zed");
+      return nodeFs.existsSync(dir) ? nodePath.join(dir, "settings.json") : null;
+    },
+    register: (configPath, distIndexPath) => {
+      let config: { context_servers?: Record<string, unknown> } = {};
+      if (nodeFs.existsSync(configPath)) {
+        try {
+          config = JSON.parse(nodeFs.readFileSync(configPath, "utf-8"));
+        } catch {
+          config = {};
+        }
+      }
+      if (!config.context_servers || typeof config.context_servers !== "object") {
+        config.context_servers = {};
+      }
+      config.context_servers.stackmem = { command: "node", args: [distIndexPath] };
+      nodeFs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+    },
+  },
+];
+
+// Registers stackmem's MCP server with every detected editor, printing a
+// line per success. An editor whose config directory doesn't exist is
+// skipped with no output and never an error.
+function registerEditorMcpServers(distIndexPath: string, homeDir = nodeOs.homedir()): void {
+  for (const target of EDITOR_MCP_TARGETS) {
+    const configPath = target.configPath(homeDir);
+    if (!configPath) continue;
+
+    try {
+      target.register(configPath, distIndexPath);
+      console.log(`✓ MCP registered for ${target.name}`);
+    } catch {
+      // Best-effort — a permissions error or malformed existing config on
+      // one editor shouldn't abort `cm init` or the other editors' writes.
+    }
+  }
+}
+
 const DEFAULT_GITIGNORE_CONTENT = `node_modules/
 dist/
 .env
@@ -1328,6 +2156,9 @@ dist/
 coverage/
 *-memories.json
 *.db
+*cursorrules
+*windsurfrules
+.cursor/rules/stackmem.md
 `;
 
 // Returns true if the file was created, false if it already existed
@@ -1343,28 +2174,131 @@ function writeGitignore(resolvedPath: string): boolean {
   return true;
 }
 
-function writeClaudeMd(project: string, resolvedPath: string): void {
-  const claudeMdPath = nodePath.join(resolvedPath, "CLAUDE.md");
+function writeClaudeMd(project: string, resolvedPath: string): void {
+  const claudeMdPath = nodePath.join(resolvedPath, "CLAUDE.md");
+
+  if (nodeFs.existsSync(claudeMdPath)) {
+    console.log("CLAUDE.md already exists — skipping.");
+    return;
+  }
+
+  const content = `# stackmem
+
+At the start of every session, the stackmem MCP server will automatically load memories for this project. The project name is "${project}".
+
+If the MCP server is not connected, run:
+cm start ${project}
+and paste the output here before starting work.
+
+When you make a decision, discover a constraint, reject an approach, or make a discovery during this session, save it with:
+cm save ${project} <type> "<content>"
+`;
+
+  nodeFs.writeFileSync(claudeMdPath, content, "utf-8");
+  console.log("CLAUDE.md written.");
+}
+
+// Same instructional purpose as writeClaudeMd — point the agent at
+// `cm start` rather than embedding a memory snapshot directly, since a
+// baked-in snapshot goes stale the moment the next commit lands. AGENTS.md
+// is the convention used by OpenAI Codex CLI, Gemini CLI, and others;
+// GEMINI.md is Gemini CLI's own equivalent — both get identical content.
+function writeAgentsMemoryFile(project: string, resolvedPath: string, filename: string): void {
+  const filePath = nodePath.join(resolvedPath, filename);
+
+  if (nodeFs.existsSync(filePath)) {
+    console.log(`${filename} already exists — skipping.`);
+    return;
+  }
+
+  const content = `# ${project} — Agent Memory
+
+This project uses stackmem for persistent agent memory.
+Run \`cm start ${project}\` at the start of every session
+to load relevant context.
+
+## Key decisions, constraints and discoveries
+
+Decisions, constraints, discoveries, and rejections live in the stackmem
+backend, not duplicated in this file — run \`cm start ${project}\` to load
+the current list.
+
+When you make a decision, discover a constraint, reject an approach, or
+make a discovery during this session, save it with:
+cm save ${project} <type> "<content>"
+`;
+
+  nodeFs.writeFileSync(filePath, content, "utf-8");
+  console.log(`${filename} written.`);
+}
+
+// --- Claude Code hooks (.claude/settings.json) ------------------------
+
+interface ClaudeHookHandler {
+  type: string;
+  command: string;
+}
+
+interface ClaudeHookGroup {
+  matcher?: string;
+  hooks: ClaudeHookHandler[];
+}
+
+interface ClaudeSettingsFile {
+  hooks?: Record<string, ClaudeHookGroup[]>;
+  [key: string]: unknown;
+}
+
+// --project (not positional) for the PreCompact command below: cmdContext's
+// CLI convention takes --project like cm search/cm context already do
+// everywhere else — cm start and cm session-end both take a positional
+// project, so those two keep the user's literal command shape.
+const STACKMEM_HOOK_EVENTS: { event: string; buildCommand: (project: string) => string }[] = [
+  { event: "SessionStart", buildCommand: (project) => `cm start ${project} --hook` },
+  { event: "Stop", buildCommand: (project) => `cm session-end ${project} --hook` },
+  { event: "PreCompact", buildCommand: (project) => `cm context --project ${project} --hook` },
+];
 
-  if (nodeFs.existsSync(claudeMdPath)) {
-    console.log("CLAUDE.md already exists — skipping.");
-    return;
+// Writes (or merges into) <resolvedPath>/.claude/settings.json. Merges
+// rather than overwrites — an existing settings.json may have unrelated
+// hooks or settings that must survive this — and is idempotent: re-running
+// `cm init` checks for the exact command string already present in an
+// event's hook groups before adding another one.
+function writeClaudeCodeHooks(project: string, resolvedPath: string): void {
+  const settingsDir = nodePath.join(resolvedPath, ".claude");
+  const settingsPath = nodePath.join(settingsDir, "settings.json");
+
+  let settings: ClaudeSettingsFile = {};
+  if (nodeFs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(nodeFs.readFileSync(settingsPath, "utf-8"));
+    } catch {
+      settings = {};
+    }
   }
 
-  const content = `# stackmem
+  if (!settings.hooks || typeof settings.hooks !== "object") {
+    settings.hooks = {};
+  }
 
-At the start of every session, the stackmem MCP server will automatically load memories for this project. The project name is "${project}".
+  for (const { event, buildCommand } of STACKMEM_HOOK_EVENTS) {
+    const command = buildCommand(project);
 
-If the MCP server is not connected, run:
-cm start ${project}
-and paste the output here before starting work.
+    if (!Array.isArray(settings.hooks[event])) {
+      settings.hooks[event] = [];
+    }
 
-When you make a decision, discover a constraint, reject an approach, or make a discovery during this session, save it with:
-cm save ${project} <type> "<content>"
-`;
+    const alreadyRegistered = settings.hooks[event].some(
+      (group) => Array.isArray(group?.hooks) && group.hooks.some((h) => h?.command === command)
+    );
 
-  nodeFs.writeFileSync(claudeMdPath, content, "utf-8");
-  console.log("CLAUDE.md written.");
+    if (!alreadyRegistered) {
+      settings.hooks[event].push({ hooks: [{ type: "command", command }] });
+    }
+  }
+
+  nodeFs.mkdirSync(settingsDir, { recursive: true });
+  nodeFs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), "utf-8");
 }
 
 // Section order for the generated rules-file markdown — matches the order
@@ -1381,14 +2315,21 @@ async function generateRulesContent(project: string): Promise<string> {
     .from("memories")
     .select("*")
     .eq("project", project)
-    .eq("resolved", false);
+    .eq("resolved", false)
+    .eq("suggested", false);
 
   if (memoriesError) fail(`Failed to load memories: ${memoriesError.message}`);
 
+  const config = readStackmemConfig();
   const scoredMemories = (memoryRows ?? [])
     .map((memory) => ({
       ...memory,
-      decay_score: computeDecayScore(new Date(memory.created_at), memory.access_count ?? 0),
+      decay_score: computeDecayScore(
+        parseUtcDate(memory.created_at),
+        memory.access_count ?? 0,
+        memory.pinned ?? false,
+        config.decayLambda
+      ),
     }))
     .sort((a, b) => b.decay_score - a.decay_score);
 
@@ -1461,6 +2402,19 @@ function writeCursorRules(resolvedPath: string, content: string): boolean {
   return true;
 }
 
+// Cursor's newer rules format (.cursor/rules/*.md) — .cursorrules is
+// legacy but still read by older Cursor versions, so both are written
+// during the transition rather than one replacing the other. Unlike
+// writeCursorRules/writeWindsurfRules (write-once at init, skip if
+// present), this one unconditionally overwrites on every call — both at
+// init and on every `cm sync` — since it's gitignored content meant to
+// always reflect the current memory state, same as the legacy files.
+function writeCursorRulesMdFile(resolvedPath: string, content: string): void {
+  const rulesDir = nodePath.join(resolvedPath, ".cursor", "rules");
+  nodeFs.mkdirSync(rulesDir, { recursive: true });
+  nodeFs.writeFileSync(nodePath.join(rulesDir, "stackmem.md"), content, "utf-8");
+}
+
 // Returns true if the file was written, false if it already existed
 // (and was skipped).
 function writeWindsurfRules(resolvedPath: string, content: string): boolean {
@@ -1507,6 +2461,10 @@ export async function trySeedMemory(
     type,
     content,
     device_id: getDeviceId(),
+    // Seeded by `cm init` scanning project files — an explicit user-run
+    // command, not an auto-captured commit, so it's "manual" like cm save,
+    // not the memories.source column's default of "hook".
+    source: "manual",
   });
   return !error;
 }
@@ -1621,7 +2579,20 @@ async function verifyBackendConnection(project: string): Promise<boolean> {
   return !error;
 }
 
-async function cmdInit(project: string, targetPath: string) {
+// Returns true if the file was created, false if it already existed
+// (and was left untouched).
+function writeStackmemConfigFile(resolvedPath: string): boolean {
+  const configPath = nodePath.join(resolvedPath, STACKMEM_CONFIG_FILENAME);
+
+  if (nodeFs.existsSync(configPath)) {
+    return false;
+  }
+
+  nodeFs.writeFileSync(configPath, defaultConfigFileContents(), "utf-8");
+  return true;
+}
+
+async function cmdInit(project: string, targetPath: string, writeConfig = false): Promise<void> {
   const resolvedPath = nodePath.resolve(targetPath);
   const gitDir = nodePath.join(resolvedPath, ".git");
 
@@ -1641,12 +2612,18 @@ async function cmdInit(project: string, targetPath: string) {
   const hooksDir = nodePath.join(gitDir, "hooks");
   nodeFs.mkdirSync(hooksDir, { recursive: true });
 
-  installHook(hooksDir, hookLogicPath);
+  for (const hookName of MANAGED_HOOK_NAMES) {
+    installHook(hooksDir, hookLogicPath, hookName);
+  }
 
   console.log(`coding-memory hook installed for project ${project} at ${targetPath}`);
 
   registerMcpServer(DIST_INDEX_PATH);
+  registerEditorMcpServers(DIST_INDEX_PATH);
   writeClaudeMd(project, resolvedPath);
+  writeAgentsMemoryFile(project, resolvedPath, "AGENTS.md");
+  writeAgentsMemoryFile(project, resolvedPath, "GEMINI.md");
+  writeClaudeCodeHooks(project, resolvedPath);
 
   const seededCount = await seedMemories(project, resolvedPath);
   console.log(`Seeded ${seededCount} initial memories from project scan.`);
@@ -1654,22 +2631,32 @@ async function cmdInit(project: string, targetPath: string) {
   const rulesContent = await generateRulesContent(project);
   const cursorRulesWritten = writeCursorRules(resolvedPath, rulesContent);
   const windsurfRulesWritten = writeWindsurfRules(resolvedPath, rulesContent);
+  writeCursorRulesMdFile(resolvedPath, rulesContent);
 
   const backendOk = await verifyBackendConnection(project);
 
+  const configFileWritten = writeConfig ? writeStackmemConfigFile(resolvedPath) : false;
+
   console.log("");
   if (gitignoreCreated) {
     console.log("✓ .gitignore created");
   }
+  if (writeConfig) {
+    console.log(`✓ .stackmem.json ${configFileWritten ? "written" : "already exists"}`);
+  }
   console.log("✓ Git hook installed");
   console.log("✓ MCP server registered");
+  console.log("✓ Claude Code hooks registered (.claude/settings.json)");
   console.log("✓ CLAUDE.md written");
+  console.log("✓ AGENTS.md written");
+  console.log("✓ GEMINI.md written");
   console.log(
     `✓ .cursorrules ${cursorRulesWritten ? "written" : "already exists"}`
   );
   console.log(
     `✓ .windsurfrules ${windsurfRulesWritten ? "written" : "already exists"}`
   );
+  console.log("✓ .cursor/rules/stackmem.md written");
   console.log(`✓ Seeded ${seededCount} memories from project scan`);
   if (backendOk) {
     console.log("✓ Backend connection verified");
@@ -1695,8 +2682,9 @@ async function cmdSync(project: string) {
 
   nodeFs.writeFileSync(nodePath.join(resolvedPath, ".cursorrules"), rulesContent, "utf-8");
   nodeFs.writeFileSync(nodePath.join(resolvedPath, ".windsurfrules"), rulesContent, "utf-8");
+  writeCursorRulesMdFile(resolvedPath, rulesContent);
 
-  console.log("Synced memories to .cursorrules and .windsurfrules");
+  console.log("Synced memories to .cursorrules, .windsurfrules, and .cursor/rules/stackmem.md");
 }
 
 // --- cm link ---------------------------------------------------------------
@@ -1781,45 +2769,178 @@ async function cmdLink() {
   console.log("Link code expired. Run cm link again.");
 }
 
+// --- cm open -----------------------------------------------------------
+
+// Separated from cmdOpen so the platform-selection logic is unit-testable
+// without actually launching a browser — exercising this for real on
+// every platform isn't something a test (or a verification pass) should
+// do as a side effect.
+export function getOpenCommand(platform: string, url: string): { command: string; args: string[] } {
+  if (platform === "darwin") return { command: "open", args: [url] };
+  if (platform === "win32") return { command: "cmd", args: ["/c", "start", "", url] };
+  return { command: "xdg-open", args: [url] };
+}
+
+async function cmdOpen(project: string): Promise<void> {
+  const url = `${VAULT_URL}/project/${project}`;
+  const { command, args } = getOpenCommand(process.platform, url);
+
+  try {
+    execFileSync(command, args, { stdio: "ignore" });
+    console.log(`Opened ${url}`);
+  } catch (error) {
+    fail(
+      `Failed to open browser (${error instanceof Error ? error.message : String(error)}). Visit ${url} manually.`
+    );
+  }
+}
+
+// --- cm purge ------------------------------------------------------------
+
+async function cmdPurgeProject(project: string): Promise<void> {
+  const { count: total, error: countError } = await supabase
+    .from("memories")
+    .select("id", { count: "exact", head: true })
+    .eq("project", project);
+  if (countError) fail(`Failed to count memories: ${countError.message}`);
+
+  console.log(`This will permanently delete all ${total ?? 0} memories for "${project}".`);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = (await rl.question("Type the project name to confirm: ")).trim();
+  rl.close();
+
+  if (answer !== project) {
+    console.log("Confirmation did not match — aborted. Nothing was deleted.");
+    return;
+  }
+
+  const { data: memRows, error: memFetchError } = await supabase
+    .from("memories")
+    .select("id")
+    .eq("project", project);
+  if (memFetchError) fail(`Failed to load memories: ${memFetchError.message}`);
+
+  const ids = (memRows ?? []).map((m) => m.id);
+  let linksDeleted = 0;
+  if (ids.length > 0) {
+    const idList = ids.join(",");
+    const { count, error: linksError } = await supabase
+      .from("memory_links")
+      .delete({ count: "exact" })
+      .or(`source_id.in.(${idList}),target_id.in.(${idList})`);
+    if (linksError) fail(`Failed to delete memory links: ${linksError.message}`);
+    linksDeleted = count ?? 0;
+  }
+
+  const { count: memoriesDeleted, error: memError } = await supabase
+    .from("memories")
+    .delete({ count: "exact" })
+    .eq("project", project);
+  if (memError) fail(`Failed to delete memories: ${memError.message}`);
+
+  const { count: fixesDeleted, error: fixError } = await supabase
+    .from("execution_log")
+    .delete({ count: "exact" })
+    .eq("project", project);
+  if (fixError) fail(`Failed to delete fixes: ${fixError.message}`);
+
+  console.log(
+    `Deleted ${memoriesDeleted ?? 0} memories, ${fixesDeleted ?? 0} fixes, and ${linksDeleted} links for "${project}".`
+  );
+}
+
+// RLS already scopes every table read/write to this device's device_id
+// via the x-device-id header (see src/storage.ts) — a filter-less delete
+// here is already confined to this device, never another one. PostgREST
+// still requires an explicit filter clause to allow a DELETE at all, so
+// `.not("id", "is", null)` (every row has a non-null id) is used purely
+// to satisfy that, not to narrow the scope further.
+async function cmdPurgeAll(): Promise<void> {
+  console.log("This will permanently delete ALL memories across ALL projects for this device.");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = (await rl.question("Type DELETE to confirm: ")).trim();
+  rl.close();
+
+  if (answer !== "DELETE") {
+    console.log("Confirmation did not match — aborted. Nothing was deleted.");
+    return;
+  }
+
+  const { count: linksDeleted, error: linksError } = await supabase
+    .from("memory_links")
+    .delete({ count: "exact" })
+    .not("id", "is", null);
+  if (linksError) fail(`Failed to delete memory links: ${linksError.message}`);
+
+  const { count: memoriesDeleted, error: memError } = await supabase
+    .from("memories")
+    .delete({ count: "exact" })
+    .not("id", "is", null);
+  if (memError) fail(`Failed to delete memories: ${memError.message}`);
+
+  const { count: fixesDeleted, error: fixError } = await supabase
+    .from("execution_log")
+    .delete({ count: "exact" })
+    .not("id", "is", null);
+  if (fixError) fail(`Failed to delete fixes: ${fixError.message}`);
+
+  console.log(
+    `Deleted ${memoriesDeleted ?? 0} memories, ${fixesDeleted ?? 0} fixes, and ${linksDeleted ?? 0} links across all projects.`
+  );
+}
+
 // --- cm context ------------------------------------------------------------
 
 const CONTEXT_TYPE_ORDER: MemoryType[] = ["decision", "constraint", "rejection", "discovery"];
 const CONTEXT_TOP_N = 5;
 
-async function cmdContext(project: string, task: string) {
+// task is null for the PreCompact hook — there's no user-typed task at a
+// compaction boundary, just "save the most relevant context" generically
+// — so ranking falls back to decay score alone instead of diluting it
+// with a relevance score computed against an empty string.
+async function cmdContext(project: string, task: string | null, hookMode = false) {
   const { data, error } = await supabase
     .from("memories")
     .select("*")
     .eq("project", project)
-    .eq("resolved", false);
+    .eq("resolved", false)
+    .eq("suggested", false);
 
   if (error) fail(`Failed to load memories: ${error.message}`);
 
   const memories = data ?? [];
   if (memories.length === 0) {
-    console.log(`No memories found for "${project}".`);
+    if (!hookMode) console.log(`No memories found for "${project}".`);
     return;
   }
 
+  const config = readStackmemConfig();
+  const tokenBudget = config.tokenBudget;
+
   const scoredMemories = memories
     .map((memory) => {
-      const decayScore = computeDecayScore(new Date(memory.created_at), memory.access_count ?? 0);
-      const relevanceScore = scoreMemoryRelevance(memory.content, task);
-      return {
-        ...memory,
-        combined_score: relevanceScore * 0.6 + decayScore * 0.4,
-      };
+      const decayScore = computeDecayScore(
+        parseUtcDate(memory.created_at),
+        memory.access_count ?? 0,
+        memory.pinned ?? false,
+        config.decayLambda
+      );
+      const combinedScore =
+        task == null ? decayScore : scoreMemoryRelevance(memory.content, task) * 0.6 + decayScore * 0.4;
+      return { ...memory, combined_score: combinedScore };
     })
     .sort((a, b) => b.combined_score - a.combined_score);
 
   const topMemories = scoredMemories.slice(0, CONTEXT_TOP_N);
-  const budgetedMemories = applyContextBudget(topMemories, CONTEXT_BUDGET_TOKENS);
+  const budgetedMemories = applyContextBudget(topMemories, tokenBudget);
   const tokensUsed = budgetedMemories.reduce(
     (sum, memory) => sum + estimateTokens(memory.content),
     0
   );
 
-  const lines: string[] = [`## Project Context: ${project}`, `### Task: ${task}`, ""];
+  const lines: string[] = [`## Project Context: ${project}`];
+  if (task != null) lines.push(`### Task: ${task}`);
+  lines.push("");
 
   for (const type of CONTEXT_TYPE_ORDER) {
     const group = budgetedMemories.filter((memory) => memory.type === type);
@@ -1832,11 +2953,83 @@ async function cmdContext(project: string, task: string) {
     lines.push("");
   }
 
-  lines.push(`*(${tokensUsed}/${CONTEXT_BUDGET_TOKENS} tokens used)*`);
+  if (!hookMode) lines.push(`*(${tokensUsed}/${tokenBudget} tokens used)*`);
 
   console.log(lines.join("\n"));
 }
 
+// --- cm why --------------------------------------------------------------
+
+function fileMatchesPaths(filePaths: unknown, file: string, baseName: string): boolean {
+  if (!Array.isArray(filePaths)) return false;
+  return filePaths.some((p) => typeof p === "string" && (p === file || p.split("/").pop() === baseName));
+}
+
+function fileMentionedInContent(content: string, file: string, baseName: string): boolean {
+  const lower = content.toLowerCase();
+  return lower.includes(file.toLowerCase()) || lower.includes(baseName.toLowerCase());
+}
+
+async function cmdWhy(project: string, file: string) {
+  const baseName = file.split("/").pop() ?? file;
+
+  const { data, error } = await supabase
+    .from("memories")
+    .select("*")
+    .eq("project", project)
+    .eq("resolved", false)
+    .eq("suggested", false);
+
+  if (error) fail(`Failed to load memories: ${error.message}`);
+
+  const memories = data ?? [];
+
+  // file_paths (structured, from Item 6) and a content substring search
+  // are combined into one match set rather than one gating the other as
+  // a strict fallback — most memories predate file_paths existing at all
+  // (manual saves and seeds never set it), so content search is the
+  // primary signal for everything except recent hook-captured commits,
+  // not a rare last resort.
+  const matched = memories.filter(
+    (memory) =>
+      fileMatchesPaths(memory.file_paths, file, baseName) ||
+      fileMentionedInContent(memory.content, file, baseName)
+  );
+
+  if (matched.length === 0) {
+    console.log(`No memories found for ${file}.`);
+    console.log("Make some commits touching this file to build up context.");
+    return;
+  }
+
+  const config = readStackmemConfig();
+  const scoredMemories = matched
+    .map((memory) => ({
+      ...memory,
+      decay_score: computeDecayScore(
+        parseUtcDate(memory.created_at),
+        memory.access_count ?? 0,
+        memory.pinned ?? false,
+        config.decayLambda
+      ),
+    }))
+    .sort((a, b) => b.decay_score - a.decay_score);
+
+  console.log(`Decisions and constraints tied to ${file}:\n`);
+
+  for (const type of MEMORY_TYPES) {
+    const group = scoredMemories.filter((memory) => memory.type === type);
+    if (group.length === 0) continue;
+
+    console.log(`${TYPE_LABELS[type]} (${group.length})`);
+    console.log("-".repeat(TYPE_LABELS[type].length + 4));
+    for (const memory of group) {
+      console.log(`  [${memory.id}] (score: ${memory.decay_score.toFixed(2)}) ${memory.content}`);
+    }
+    console.log("");
+  }
+}
+
 // --- cm session-end --------------------------------------------------------
 
 interface SessionEndInput {
@@ -1885,6 +3078,10 @@ function parseSessionEndFlags(args: string[]): SessionEndInput {
     } else if (flag === "--approaches") {
       approaches = splitCommaList(value);
       i++;
+    } else if (flag === "--hook") {
+      // Recognized explicitly (not just silently skipped as an unknown
+      // flag) — see the comment on cmdSessionEnd for why it's currently
+      // a no-op here specifically.
     }
   }
 
@@ -1907,6 +3104,16 @@ async function readStdinJson(): Promise<Record<string, unknown> | null> {
   }
 }
 
+// --hook is accepted (see parseSessionEndFlags) but currently a no-op:
+// Claude Code's Stop hook pipes ITS OWN JSON payload on stdin (session
+// id, transcript path, cwd — see the Claude Code hooks docs), not the
+// {summary, errors_encountered, files_touched, approaches_tried} shape
+// this command expects. readStdinJson() parses that payload successfully
+// (it's valid JSON) but finds none of the fields it looks for, so every
+// array below comes back empty and this reports 0 memories saved — a
+// real, known limitation, not a bug. Extracting genuine learnings from
+// the Stop hook would mean parsing the session transcript itself, which
+// is out of scope here (Phase 2, per the user).
 async function cmdSessionEnd(project: string, input: Omit<SessionEndInput, "project">) {
   let memoriesSaved = 0;
   let errorsLogged = 0;
@@ -2020,6 +3227,136 @@ function isHookExecutable(hookPath: string): boolean {
   }
 }
 
+// --- cm status ---------------------------------------------------------
+
+function hasMcpServersStackmemKey(configPath: string): boolean {
+  if (!nodeFs.existsSync(configPath)) return false;
+  try {
+    const config = JSON.parse(nodeFs.readFileSync(configPath, "utf-8"));
+    return Boolean(config?.mcpServers?.stackmem);
+  } catch {
+    return false;
+  }
+}
+
+function hasContextServersStackmemKey(configPath: string): boolean {
+  if (!nodeFs.existsSync(configPath)) return false;
+  try {
+    const config = JSON.parse(nodeFs.readFileSync(configPath, "utf-8"));
+    return Boolean(config?.context_servers?.stackmem);
+  } catch {
+    return false;
+  }
+}
+
+const EDITOR_STATUS_CHECKS: { name: string; isRegistered: (homeDir: string) => boolean }[] = [
+  { name: "Claude Code", isRegistered: (homeDir) => isMcpRegistered(nodePath.join(homeDir, ".claude.json")) },
+  { name: "Cursor", isRegistered: (homeDir) => hasMcpServersStackmemKey(nodePath.join(homeDir, ".cursor", "mcp.json")) },
+  {
+    name: "Windsurf",
+    isRegistered: (homeDir) =>
+      hasMcpServersStackmemKey(nodePath.join(homeDir, ".codeium", "windsurf", "mcp_config.json")),
+  },
+  {
+    name: "VS Code",
+    isRegistered: (homeDir) => {
+      const dir = findCopilotChatExtensionDir(homeDir);
+      return dir ? hasMcpServersStackmemKey(nodePath.join(dir, "mcp.json")) : false;
+    },
+  },
+  {
+    name: "Zed",
+    isRegistered: (homeDir) => hasContextServersStackmemKey(nodePath.join(homeDir, ".config", "zed", "settings.json")),
+  },
+];
+
+async function cmdStatus(project: string): Promise<void> {
+  const { count: totalCount, error: totalError } = await supabase
+    .from("memories")
+    .select("id", { count: "exact", head: true })
+    .eq("project", project)
+    .eq("resolved", false);
+  if (totalError) fail(`Failed to load memory count: ${totalError.message}`);
+
+  const { count: pinnedCount, error: pinnedError } = await supabase
+    .from("memories")
+    .select("id", { count: "exact", head: true })
+    .eq("project", project)
+    .eq("resolved", false)
+    .eq("pinned", true);
+  if (pinnedError) fail(`Failed to load pinned count: ${pinnedError.message}`);
+
+  const { count: suggestedCount, error: suggestedError } = await supabase
+    .from("memories")
+    .select("id", { count: "exact", head: true })
+    .eq("project", project)
+    .eq("resolved", false)
+    .eq("suggested", true);
+  if (suggestedError) fail(`Failed to load suggested count: ${suggestedError.message}`);
+
+  const { count: fixesCount, error: fixesError } = await supabase
+    .from("execution_log")
+    .select("id", { count: "exact", head: true })
+    .eq("project", project)
+    .eq("resolved", false);
+  if (fixesError) fail(`Failed to load fixes count: ${fixesError.message}`);
+
+  const { data: lastCaptureRows, error: lastCaptureError } = await supabase
+    .from("memories")
+    .select("content, created_at")
+    .eq("project", project)
+    .order("created_at", { ascending: false })
+    .limit(1);
+  if (lastCaptureError) fail(`Failed to load last capture: ${lastCaptureError.message}`);
+
+  const config = readStackmemConfig();
+  const configPath = nodePath.join(process.cwd(), STACKMEM_CONFIG_FILENAME);
+  let usesCustomBudget = false;
+  if (nodeFs.existsSync(configPath)) {
+    try {
+      const raw = JSON.parse(nodeFs.readFileSync(configPath, "utf-8"));
+      usesCustomBudget = typeof raw.tokenBudget === "number";
+    } catch {
+      // Malformed config — readStackmemConfig already falls back to the
+      // default in this case too, so "default" is the accurate label.
+    }
+  }
+
+  const hookOk = isHookExecutable(nodePath.join(process.cwd(), ".git", "hooks", "post-commit"));
+  const mcpOk = isMcpRegistered(getClaudeConfigPath());
+  const backendOk = await verifyBackendConnection(project);
+
+  const homeDir = nodeOs.homedir();
+  const registeredEditors = EDITOR_STATUS_CHECKS.filter((e) => e.isRegistered(homeDir)).map((e) => e.name);
+
+  console.log(`stackmem status for "${project}"`);
+  console.log("━".repeat(27));
+  console.log(
+    `Memories:     ${totalCount ?? 0} total (${pinnedCount ?? 0} pinned, ${suggestedCount ?? 0} suggested)`
+  );
+  console.log(`Fixes:        ${fixesCount ?? 0} recorded`);
+  console.log(`Token budget: ${config.tokenBudget} (${usesCustomBudget ? "from .stackmem.json" : "default"})`);
+
+  const lastCapture = (lastCaptureRows ?? [])[0];
+  if (lastCapture) {
+    const ago = formatRelativeTime(parseUtcDate(lastCapture.created_at));
+    const snippet =
+      lastCapture.content.length > 50 ? `${lastCapture.content.slice(0, 50)}…` : lastCapture.content;
+    console.log(`Last capture: ${ago} (${snippet})`);
+  } else {
+    console.log("Last capture: none yet");
+  }
+
+  console.log(`Hook:         ${hookOk ? "✓ installed" : "✗ not installed"}`);
+  console.log(`MCP:          ${mcpOk ? "✓ registered" : "✗ not registered"}`);
+  console.log(`Backend:      ${backendOk ? "✓ connected" : "✗ not connected"}`);
+  console.log(
+    `Editors:      ${
+      registeredEditors.length > 0 ? registeredEditors.map((name) => `${name} ✓`).join("  ") : "(none registered)"
+    }`
+  );
+}
+
 async function cmdDoctor(fix: boolean) {
   let issues = 0;
   const project = readProjectFromFile();
@@ -2087,7 +3424,9 @@ async function cmdDoctor(fix: boolean) {
         nodeFs.mkdirSync(codingMemoryDir, { recursive: true });
         const hookLogicPath = nodePath.join(codingMemoryDir, "post-commit-hook.mjs");
         nodeFs.writeFileSync(hookLogicPath, buildHookLogicScript(DIST_CLI_PATH), "utf-8");
-        installHook(hooksDir, hookLogicPath);
+        for (const name of MANAGED_HOOK_NAMES) {
+          installHook(hooksDir, hookLogicPath, name);
+        }
 
         if (isHookExecutable(hookPath)) {
           console.log("Fixed: git hook");
@@ -2284,8 +3623,10 @@ async function cmdUninstall(project: string, targetPath: string) {
   const gitDir = nodePath.join(targetPath, ".git");
   const hooksDir = nodePath.join(gitDir, "hooks");
 
-  const hookResult = uninstallHook(hooksDir);
-  if (hookResult) console.log(`Removed ${hookResult}`);
+  for (const hookName of MANAGED_HOOK_NAMES) {
+    const hookResult = uninstallHook(hooksDir, hookName);
+    if (hookResult) console.log(`Removed ${hookResult}`);
+  }
 
   const codingMemoryDir = nodePath.join(targetPath, ".coding-memory");
 
@@ -2330,19 +3671,34 @@ async function main() {
 
   switch (command) {
     case "start": {
-      const split = splitOptionalProject(args, 0);
+      const hookIndex = args.indexOf("--hook");
+      const hookMode = hookIndex !== -1;
+      const positional = hookMode ? [...args.slice(0, hookIndex), ...args.slice(hookIndex + 1)] : args;
+
+      const split = splitOptionalProject(positional, 0);
       if (!split) usage();
       const project = requireProject(split.project);
-      await cmdStart(project);
+      await cmdStart(project, hookMode);
       break;
     }
     case "save": {
       const forceIndex = args.indexOf("--force");
       const force = forceIndex !== -1;
-      const positional = force
+      let positional = force
         ? [...args.slice(0, forceIndex), ...args.slice(forceIndex + 1)]
         : args;
 
+      const commitShaFlag = extractValueFlag(positional, "--commit-sha");
+      positional = commitShaFlag.rest;
+      const authorFlag = extractValueFlag(positional, "--author");
+      positional = authorFlag.rest;
+      const sourceFlag = extractValueFlag(positional, "--source");
+      positional = sourceFlag.rest;
+      const confidenceFlag = extractValueFlag(positional, "--confidence");
+      positional = confidenceFlag.rest;
+      const filesFlag = extractValueFlag(positional, "--files");
+      positional = filesFlag.rest;
+
       let explicitProject: string | null;
       let type: string | undefined;
       let rest: string[];
@@ -2367,7 +3723,28 @@ async function main() {
 
       if (!type || rest.length === 0) usage();
       const project = requireProject(explicitProject);
-      await cmdSave(project, type, rest.join(" "), force);
+
+      const provenance: SaveProvenance = {};
+      if (commitShaFlag.value) provenance.commitSha = commitShaFlag.value;
+      if (authorFlag.value) provenance.author = authorFlag.value;
+      if (sourceFlag.value === "hook" || sourceFlag.value === "manual" || sourceFlag.value === "mcp") {
+        provenance.source = sourceFlag.value;
+      }
+      if (confidenceFlag.value) {
+        const parsed = Number(confidenceFlag.value);
+        if (!Number.isNaN(parsed)) provenance.confidence = parsed;
+      }
+      if (filesFlag.value) {
+        provenance.filePaths = filesFlag.value.split(",").map((f) => f.trim()).filter(Boolean);
+      }
+
+      await cmdSave(project, type, rest.join(" "), force, provenance);
+      break;
+    }
+    case "check-commit": {
+      const [project, commitSha] = args;
+      if (!project || !commitSha) usage();
+      await cmdCheckCommit(project, commitSha);
       break;
     }
     case "fix": {
@@ -2401,6 +3778,37 @@ async function main() {
       await cmdResolve(project, memoryId);
       break;
     }
+    case "pin": {
+      const split = splitOptionalProject(args, 1);
+      if (!split) usage();
+      const project = requireProject(split.project);
+      const [memoryId] = split.rest;
+      await cmdPin(project, memoryId);
+      break;
+    }
+    case "unpin": {
+      const split = splitOptionalProject(args, 1);
+      if (!split) usage();
+      const project = requireProject(split.project);
+      const [memoryId] = split.rest;
+      await cmdUnpin(project, memoryId);
+      break;
+    }
+    case "review": {
+      const split = splitProjectFromVariadic(args);
+      if (split.rest.length > 0) usage();
+      const project = requireProject(split.project);
+      await cmdReview(project);
+      break;
+    }
+    case "edit": {
+      const split = splitOptionalProject(args, 1);
+      if (!split) usage();
+      const project = requireProject(split.project);
+      const [memoryId] = split.rest;
+      await cmdEdit(project, memoryId);
+      break;
+    }
     case "delete": {
       const split = splitOptionalProject(args, 1);
       if (!split) usage();
@@ -2425,9 +3833,15 @@ async function main() {
       break;
     }
     case "init": {
-      const [project, targetPath] = args;
+      const configIndex = args.indexOf("--config");
+      const writeConfig = configIndex !== -1;
+      const positional = writeConfig
+        ? [...args.slice(0, configIndex), ...args.slice(configIndex + 1)]
+        : args;
+
+      const [project, targetPath] = positional;
       if (!project || !targetPath) usage();
-      await cmdInit(project, targetPath);
+      await cmdInit(project, targetPath, writeConfig);
       break;
     }
     case "link": {
@@ -2435,6 +3849,29 @@ async function main() {
       await cmdLink();
       break;
     }
+    case "open": {
+      const split = splitProjectFromVariadic(args);
+      if (split.rest.length > 0) usage();
+      const project = requireProject(split.project);
+      await cmdOpen(project);
+      break;
+    }
+    case "purge": {
+      const allIndex = args.indexOf("--all");
+      const isAll = allIndex !== -1;
+      const withoutAllFlag = isAll ? [...args.slice(0, allIndex), ...args.slice(allIndex + 1)] : args;
+
+      const split = splitProjectFromVariadic(withoutAllFlag);
+      if (split.rest.length > 0) usage();
+
+      if (isAll) {
+        await cmdPurgeAll();
+      } else {
+        const project = requireProject(split.project);
+        await cmdPurgeProject(project);
+      }
+      break;
+    }
     case "sync": {
       if (args.length > 0) usage();
       const project = requireProject(null);
@@ -2442,10 +3879,24 @@ async function main() {
       break;
     }
     case "context": {
+      const hookIndex = args.indexOf("--hook");
+      const hookMode = hookIndex !== -1;
+      const withoutHookFlag = hookMode ? [...args.slice(0, hookIndex), ...args.slice(hookIndex + 1)] : args;
+
+      const split = splitProjectFromVariadic(withoutHookFlag);
+      const project = requireProject(split.project);
+      // task is optional only in --hook mode (the PreCompact hook has no
+      // user-typed task to pass) — interactive use still requires one.
+      if (split.rest.length === 0 && !hookMode) usage();
+      const task = split.rest.length > 0 ? split.rest.join(" ") : null;
+      await cmdContext(project, task, hookMode);
+      break;
+    }
+    case "why": {
       const split = splitProjectFromVariadic(args);
       const project = requireProject(split.project);
       if (split.rest.length === 0) usage();
-      await cmdContext(project, split.rest.join(" "));
+      await cmdWhy(project, split.rest.join(" "));
       break;
     }
     case "session-end": {
@@ -2457,6 +3908,13 @@ async function main() {
       await cmdDoctor(fix);
       break;
     }
+    case "status": {
+      const split = splitProjectFromVariadic(args);
+      if (split.rest.length > 0) usage();
+      const project = requireProject(split.project);
+      await cmdStatus(project);
+      break;
+    }
     case "undo": {
       const split = splitOptionalProject(args, 0);
       if (!split) usage();