autoctxd 0.4.1

package/src/cli/index.ts

@@ -0,0 +1,574 @@
+#!/usr/bin/env bun
+// autoctxd CLI — Full command suite
+
+import { getDb, closeDb } from "../db/sqlite/schema";
+import { hybridSearch } from "../db/vector/search";
+import { closeVectorDb } from "../db/vector/client";
+import { runReclassifyCli } from "./reclassify";
+import { runDoctor } from "./doctor";
+import { runEmbeddingsCommand } from "./embeddings";
+import { getGlobalMetrics } from "../util/metrics";
+import { getFeedbackStats } from "../db/sqlite/feedback";
+import { startDashboardServer } from "../server/dashboard";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+async function main() {
+  try {
+    switch (command) {
+      case "stats":
+        stats();
+        break;
+      case "sessions":
+        sessions();
+        break;
+      case "decisions":
+        decisions(args[1]);
+        break;
+      case "search":
+        await search(args.slice(1).join(" "));
+        break;
+      case "show":
+        show(args[1], args[2]);
+        break;
+      case "patterns":
+        patterns(args[1]);
+        break;
+      case "digest":
+        digest(args[1]);
+        break;
+      case "export":
+        exportContext(args[1]);
+        break;
+      case "init":
+        init();
+        break;
+      case "reset":
+        reset();
+        break;
+      case "reclassify":
+        runReclassifyCli(args.slice(1));
+        break;
+      case "doctor":
+        process.exit(await runDoctor());
+        break;
+      case "metrics":
+        showMetrics();
+        break;
+      case "dashboard":
+        await startDashboardServer(parseInt(args[1] || "4589", 10));
+        return; // keep process alive
+      case "mcp":
+        await import("../mcp/server");
+        return; // server owns the event loop
+      case "feedback":
+        showFeedbackStats();
+        break;
+      case "embeddings":
+        process.exit(await runEmbeddingsCommand(args.slice(1)));
+        break;
+      case "cleanup-decisions":
+        cleanupDecisions(args.slice(1));
+        break;
+      default:
+        help();
+    }
+  } finally {
+    closeDb();
+    await closeVectorDb();
+  }
+}
+
+function help() {
+  console.log(`
+autoctxd — Persistent memory for Claude Code
+
+Commands:
+  stats                  Usage statistics
+  sessions               List recent sessions
+  decisions [project]    Show architectural decisions
+  search <query>         Hybrid search (semantic + full-text)
+  show session <id>      Show session details
+  patterns [project]     Show detected work patterns
+  digest [project]       Show/generate weekly digests
+  export [project]       Export context to markdown
+  init                   Initialize database
+  reset                  Clear all data (careful!)
+  reclassify [--dry-run] [--all] [--recompress] [--project <name>]
+                         Re-run classifier on existing observations.
+                         (defaults to only 'other'; --all for every row)
+                         --recompress also rewrites historical session
+                         summaries with the current compressor.
+                         --project <name> scopes recompression to one project.
+  doctor                 Verify install integrity
+  metrics                Show token-savings metrics
+  dashboard [port]       Launch local web dashboard (default port 4589)
+  mcp                    Run as MCP server (stdio) — for Claude Desktop/Cursor/Windsurf
+  feedback               Show learning stats (feedback accumulated)
+  embeddings <sub>       Manage embedding provider (list/status/switch/reembed)
+  cleanup-decisions [--dry-run]
+                         Delete decisions left over from the pre-0.4 extractor
+                         (npm install of generic words, monitor noise) and
+                         collapse cross-session duplicates.
+
+Examples:
+  autoctxd search "race condition async"
+  autoctxd decisions ./my-app
+  autoctxd export ./my-app > context.md
+  autoctxd stats
+`);
+}
+
+function init() {
+  getDb();
+  console.log("Database initialized successfully.");
+}
+
+function reset() {
+  const db = getDb();
+  const tables = ["observations", "summaries", "decisions", "patterns",
+    "embeddings_cache", "token_metrics", "sessions"];
+  for (const table of tables) {
+    db.exec(`DELETE FROM ${table}`);
+  }
+  // Reset FTS
+  try {
+    db.exec("DELETE FROM observations_fts");
+    db.exec("DELETE FROM decisions_fts");
+  } catch {}
+  console.log("All data cleared.");
+}
+
+function cleanupDecisions(flags: string[]) {
+  const db = getDb();
+  const dryRun = flags.includes("--dry-run");
+
+  // Patterns that the pre-0.4 extractor produced from log noise. Anything
+  // here is verifiably not an architectural decision — it's a generic word
+  // the regex captured because "npm install <word>" appeared in a Monitor
+  // command, a comment, or a task description.
+  const noiseTitles = [
+    "Added npm dep: output",
+    "Added npm dep: progress",
+    "Added npm dep: tsx",
+    "Added npm dep: tests",
+    "Added npm dep: test",
+    "Added npm dep: dev",
+    "Added npm dep: prod",
+    "Added npm dep: build",
+    "Added npm dep: start",
+    "Added npm dep: all",
+    "Added npm dep: true",
+    "Added npm dep: false",
+    "Added npm dep: latest",
+    "Added npm dep: debug",
+    "Added bun dep: output",
+    "Added bun dep: progress",
+    "Added pnpm dep: output",
+    "Added pnpm dep: progress",
+    "Added yarn dep: output",
+    "Added yarn dep: progress",
+    "Added pip dep: output",
+    "Added pip dep: progress",
+  ];
+
+  const placeholders = noiseTitles.map(() => "?").join(",");
+
+  // Tool-prefixed rows that the pre-0.4 extractor allowed through whenever
+  // the classifier scored an observation as type=decision (a stray keyword
+  // would do it). New code rejects these at the source; this clears the
+  // historical leftovers so the dashboard stops showing them.
+  const prefixNoiseClause = `(
+       decision_text LIKE 'Bash:%'
+    OR decision_text LIKE 'PowerShell:%'
+    OR decision_text LIKE 'Edit:%'
+    OR decision_text LIKE 'Edited %'
+    OR decision_text LIKE 'Monitor:%'
+    OR decision_text LIKE 'ToolSearch:%'
+    OR decision_text LIKE 'TodoWrite%'
+    OR decision_text LIKE 'TaskStop:%'
+    OR decision_text LIKE 'TaskOutput:%'
+  )`;
+
+  const before = (db.prepare("SELECT COUNT(*) as c FROM decisions").get() as any).c;
+
+  const noiseCount = (db.prepare(
+    `SELECT COUNT(*) as c FROM decisions WHERE title IN (${placeholders})`
+  ).get(...noiseTitles) as any).c;
+
+  const prefixCount = (db.prepare(
+    `SELECT COUNT(*) as c FROM decisions WHERE ${prefixNoiseClause}`
+  ).get() as any).c;
+
+  const dupCount = (db.prepare(`
+    SELECT COUNT(*) as c FROM decisions
+    WHERE id NOT IN (
+      SELECT MIN(id) FROM decisions
+      GROUP BY COALESCE(project_path, ''), title
+    )
+  `).get() as any).c;
+
+  console.log("\nautoctxd cleanup-decisions");
+  console.log("─".repeat(40));
+  console.log(`  decisions in DB:           ${before}`);
+  console.log(`  generic-word noise:        ${noiseCount}`);
+  console.log(`  tool-prefixed noise:       ${prefixCount}`);
+  console.log(`  cross-session duplicates:  ${dupCount}`);
+
+  if (dryRun) {
+    console.log("\n  (--dry-run — no changes written)");
+    return;
+  }
+
+  db.exec("BEGIN");
+  try {
+    db.prepare(`DELETE FROM decisions WHERE title IN (${placeholders})`).run(...noiseTitles);
+    db.exec(`DELETE FROM decisions WHERE ${prefixNoiseClause}`);
+    db.exec(`
+      DELETE FROM decisions WHERE id NOT IN (
+        SELECT MIN(id) FROM decisions
+        GROUP BY COALESCE(project_path, ''), title
+      )
+    `);
+    db.exec("COMMIT");
+  } catch (e) {
+    db.exec("ROLLBACK");
+    throw e;
+  }
+
+  const after = (db.prepare("SELECT COUNT(*) as c FROM decisions").get() as any).c;
+  console.log(`\n  deleted: ${before - after}`);
+  console.log(`  remaining: ${after}`);
+}
+
+function stats() {
+  const db = getDb();
+  const sessionCount = (db.prepare("SELECT COUNT(*) as c FROM sessions").get() as any).c;
+  const obsCount = (db.prepare("SELECT COUNT(*) as c FROM observations").get() as any).c;
+  const decisionCount = (db.prepare("SELECT COUNT(*) as c FROM decisions").get() as any).c;
+  const patternCount = (db.prepare("SELECT COUNT(*) as c FROM patterns").get() as any).c;
+  const summaryCount = (db.prepare("SELECT COUNT(*) as c FROM summaries").get() as any).c;
+  const cacheCount = (db.prepare("SELECT COUNT(*) as c FROM embeddings_cache").get() as any).c;
+
+  const topTypes = db.prepare(`
+    SELECT type, COUNT(*) as c FROM observations GROUP BY type ORDER BY c DESC LIMIT 8
+  `).all() as Array<{ type: string; c: number }>;
+
+  const topProjects = db.prepare(`
+    SELECT project_path, COUNT(*) as c FROM sessions
+    WHERE project_path IS NOT NULL
+    GROUP BY project_path ORDER BY c DESC LIMIT 5
+  `).all() as Array<{ project_path: string; c: number }>;
+
+  console.log(`
+╔══════════════════════════════════════╗
+║       autoctxd Statistics          ║
+╚══════════════════════════════════════╝
+
+Sessions:       ${sessionCount}
+Observations:   ${obsCount}
+Summaries:      ${summaryCount}
+Decisions:      ${decisionCount}
+Patterns:       ${patternCount}
+Cached embeds:  ${cacheCount}
+`);
+
+  if (topTypes.length > 0) {
+    console.log("Observation types:");
+    for (const t of topTypes) {
+      const bar = "█".repeat(Math.min(20, Math.ceil(t.c / Math.max(1, topTypes[0].c) * 20)));
+      console.log(`  ${t.type.padEnd(15)} ${bar} ${t.c}`);
+    }
+    console.log("");
+  }
+
+  if (topProjects.length > 0) {
+    console.log("Top projects:");
+    for (const p of topProjects) {
+      console.log(`  ${p.project_path} (${p.c} sessions)`);
+    }
+  }
+}
+
+function sessions() {
+  const db = getDb();
+  const rows = db.prepare(`
+    SELECT session_id, project_path, git_branch, started_at, ended_at, total_observations
+    FROM sessions ORDER BY started_at DESC LIMIT 20
+  `).all() as any[];
+
+  console.log("\nRecent Sessions:");
+  console.log("─".repeat(90));
+  for (const r of rows) {
+    const status = r.ended_at ? "done" : "active";
+    const branch = r.git_branch ? ` [${r.git_branch}]` : "";
+    const path = r.project_path ? truncPath(r.project_path, 30) : "?";
+    console.log(`  [${status.padEnd(6)}] ${r.session_id.slice(0, 12)}... | ${path}${branch} | ${r.started_at} | ${r.total_observations || 0} obs`);
+  }
+}
+
+function decisions(project?: string) {
+  const db = getDb();
+  const query = project
+    ? db.prepare("SELECT * FROM decisions WHERE project_path LIKE ? ORDER BY created_at DESC").all(`%${project}%`)
+    : db.prepare("SELECT * FROM decisions ORDER BY created_at DESC LIMIT 20").all();
+
+  console.log("\nArchitectural Decisions:");
+  console.log("─".repeat(80));
+  for (const d of query as any[]) {
+    console.log(`  [${(d.created_at || "").slice(0, 10)}] ${d.title}`);
+    console.log(`    ${d.decision_text.slice(0, 120)}`);
+    if (d.alternatives) console.log(`    Rejected: ${d.alternatives}`);
+    if (d.rationale) console.log(`    Reason: ${d.rationale}`);
+    if (d.files_affected) console.log(`    Files: ${d.files_affected}`);
+    console.log("");
+  }
+
+  if ((query as any[]).length === 0) {
+    console.log("  No decisions recorded yet.");
+  }
+}
+
+async function search(query: string) {
+  if (!query) {
+    console.log("Usage: autoctxd search <query>");
+    return;
+  }
+
+  console.log(`\nSearching for "${query}"...`);
+  console.log("─".repeat(80));
+
+  const results = await hybridSearch(query, { limit: 15 });
+
+  for (const r of results) {
+    const icon = r.source === "vector" ? "~" : r.source === "fts_decisions" ? "!" : ">";
+    console.log(`  [${icon}] ${r.text.slice(0, 120)}`);
+    if (r.metadata.project_path) console.log(`      Project: ${r.metadata.project_path}`);
+    if (r.metadata.created_at) console.log(`      Date: ${r.metadata.created_at}`);
+    if (r.metadata.type) console.log(`      Type: ${r.metadata.type} | Score: ${r.metadata.importance}`);
+    console.log("");
+  }
+
+  if (results.length === 0) {
+    console.log("  No results found.");
+  } else {
+    console.log(`  Legend: [~] semantic match  [!] decision match  [>] text match`);
+  }
+}
+
+function show(type: string, id: string) {
+  if (type !== "session" || !id) {
+    console.log("Usage: autoctxd show session <id>");
+    return;
+  }
+
+  const db = getDb();
+  const session = db.prepare("SELECT * FROM sessions WHERE session_id LIKE ?").get(`${id}%`) as any;
+  if (!session) {
+    console.log("Session not found.");
+    return;
+  }
+
+  console.log(`\n╔══════════════════════════════════════╗`);
+  console.log(`║  Session: ${session.session_id.slice(0, 26)}  ║`);
+  console.log(`╚══════════════════════════════════════╝`);
+  console.log(`Project:  ${session.project_path}`);
+  console.log(`Branch:   ${session.git_branch || "n/a"}`);
+  console.log(`Started:  ${session.started_at}`);
+  console.log(`Ended:    ${session.ended_at || "still active"}`);
+  console.log(`Total obs: ${session.total_observations || 0}`);
+
+  const obs = db.prepare(`
+    SELECT * FROM observations WHERE session_id = ? ORDER BY timestamp ASC
+  `).all(session.session_id) as any[];
+
+  if (obs.length > 0) {
+    console.log("\nTimeline:");
+    console.log("─".repeat(80));
+    for (const o of obs) {
+      const time = o.timestamp.split(" ")[1] || o.timestamp;
+      const imp = "●".repeat(Math.min(5, Math.ceil(o.importance_score / 2)));
+      console.log(`  ${time} [${o.type.padEnd(12)}] ${imp} ${o.summary.slice(0, 80)}`);
+      if (o.file_paths) {
+        console.log(`${"".padEnd(12)}files: ${o.file_paths}`);
+      }
+    }
+  }
+
+  const summaries = db.prepare(`SELECT * FROM summaries WHERE session_id = ?`).all(session.session_id) as any[];
+  if (summaries.length > 0) {
+    console.log("\nSession Summary:");
+    console.log("─".repeat(80));
+    console.log(summaries[0].text);
+  }
+}
+
+function patterns(project?: string) {
+  const db = getDb();
+  const query = project
+    ? db.prepare("SELECT * FROM patterns WHERE project_path LIKE ? ORDER BY frequency DESC").all(`%${project}%`)
+    : db.prepare("SELECT * FROM patterns ORDER BY frequency DESC LIMIT 20").all();
+
+  console.log("\nDetected Patterns:");
+  console.log("─".repeat(80));
+  for (const p of query as any[]) {
+    const freq = "█".repeat(Math.min(10, p.frequency));
+    console.log(`  [${p.pattern_type}] ${p.description}`);
+    console.log(`    Frequency: ${freq} (${p.frequency}x) | Last: ${p.last_seen}`);
+    if (p.examples) console.log(`    Examples: ${p.examples.slice(0, 100)}`);
+    console.log("");
+  }
+
+  if ((query as any[]).length === 0) {
+    console.log("  No patterns detected yet. Patterns emerge after multiple sessions.");
+  }
+}
+
+function digest(project?: string) {
+  const db = getDb();
+  const query = project
+    ? db.prepare("SELECT * FROM summaries WHERE level = 2 AND project_path LIKE ? ORDER BY created_at DESC LIMIT 5").all(`%${project}%`)
+    : db.prepare("SELECT * FROM summaries WHERE level = 2 ORDER BY created_at DESC LIMIT 5").all();
+
+  console.log("\nWeekly Digests:");
+  console.log("─".repeat(80));
+  for (const d of query as any[]) {
+    console.log(`  [${d.created_at}] Project: ${d.project_path || "all"}`);
+    console.log(d.text.split("\n").map((l: string) => `    ${l}`).join("\n"));
+    console.log("");
+  }
+
+  if ((query as any[]).length === 0) {
+    console.log("  No digests yet. Digests are auto-generated weekly when sessions accumulate.");
+  }
+}
+
+function exportContext(project?: string) {
+  const db = getDb();
+  const projectFilter = project || "%";
+  const isFilter = project ? true : false;
+
+  const lines: string[] = [];
+  lines.push("# Claude-CTX Context Export");
+  lines.push(`Generated: ${new Date().toISOString()}`);
+  if (project) lines.push(`Project filter: ${project}`);
+  lines.push("");
+
+  // Decisions
+  const decs = (isFilter
+    ? db.prepare("SELECT * FROM decisions WHERE project_path LIKE ? ORDER BY created_at DESC").all(`%${projectFilter}%`)
+    : db.prepare("SELECT * FROM decisions ORDER BY created_at DESC LIMIT 20").all()
+  ) as any[];
+
+  if (decs.length > 0) {
+    lines.push("## Architectural Decisions");
+    lines.push("");
+    for (const d of decs) {
+      lines.push(`### ${d.title}`);
+      lines.push(`- **Date:** ${d.created_at}`);
+      lines.push(`- **Decision:** ${d.decision_text}`);
+      if (d.alternatives) lines.push(`- **Rejected:** ${d.alternatives}`);
+      if (d.rationale) lines.push(`- **Reason:** ${d.rationale}`);
+      if (d.files_affected) lines.push(`- **Files:** ${d.files_affected}`);
+      lines.push("");
+    }
+  }
+
+  // Recent summaries
+  const sums = (isFilter
+    ? db.prepare("SELECT * FROM summaries WHERE project_path LIKE ? AND level = 1 ORDER BY created_at DESC LIMIT 10").all(`%${projectFilter}%`)
+    : db.prepare("SELECT * FROM summaries WHERE level = 1 ORDER BY created_at DESC LIMIT 10").all()
+  ) as any[];
+
+  if (sums.length > 0) {
+    lines.push("## Recent Session Summaries");
+    lines.push("");
+    for (const s of sums) {
+      lines.push(`### Session ${s.session_id || "unknown"} (${s.created_at})`);
+      lines.push("```");
+      lines.push(s.text);
+      lines.push("```");
+      lines.push("");
+    }
+  }
+
+  // Patterns
+  const pats = (isFilter
+    ? db.prepare("SELECT * FROM patterns WHERE project_path LIKE ? ORDER BY frequency DESC").all(`%${projectFilter}%`)
+    : db.prepare("SELECT * FROM patterns ORDER BY frequency DESC LIMIT 10").all()
+  ) as any[];
+
+  if (pats.length > 0) {
+    lines.push("## Detected Patterns");
+    lines.push("");
+    for (const p of pats as any[]) {
+      lines.push(`- **[${p.pattern_type}]** ${p.description} (seen ${p.frequency}x)`);
+    }
+    lines.push("");
+  }
+
+  // Stats
+  const sessionCount = (db.prepare("SELECT COUNT(*) as c FROM sessions").get() as any).c;
+  const obsCount = (db.prepare("SELECT COUNT(*) as c FROM observations").get() as any).c;
+
+  lines.push("## Statistics");
+  lines.push(`- Total sessions: ${sessionCount}`);
+  lines.push(`- Total observations: ${obsCount}`);
+  lines.push(`- Decisions: ${decs.length}`);
+  lines.push(`- Patterns: ${pats.length}`);
+  lines.push("");
+
+  console.log(lines.join("\n"));
+}
+
+function showFeedbackStats() {
+  const s = getFeedbackStats();
+  console.log(`
+╔══════════════════════════════════════╗
+║     autoctxd Learning Stats        ║
+╚══════════════════════════════════════╝
+
+Total feedback entries:  ${s.total}
+  Useful:                ${s.useful}
+  Irrelevant:            ${s.irrelevant}
+  Wrong:                 ${s.wrong}
+`);
+  if (s.total === 0) {
+    console.log(`  No feedback yet. autoctxd learns as you (or Claude) call
+  the record_feedback MCP tool to rate injected items.
+`);
+    return;
+  }
+  console.log("By target type:");
+  for (const [type, counts] of Object.entries(s.byType)) {
+    console.log(`  ${type.padEnd(14)} useful:${counts.useful}  irrelevant:${counts.irrelevant}  wrong:${counts.wrong}`);
+  }
+}
+
+function showMetrics() {
+  const m = getGlobalMetrics();
+  console.log(`
+╔══════════════════════════════════════╗
+║       autoctxd Token Metrics       ║
+╚══════════════════════════════════════╝
+
+Sessions with injected context:  ${m.sessionsWithContext}
+Total tokens injected:           ${m.totalInjected.toLocaleString()}
+Estimated tokens saved:          ~${m.totalSaved.toLocaleString()}
+Avg tokens per session:          ${m.avgInjectedPerSession}
+
+ROI: for every injected token, you avoid re-explaining ~${
+    m.totalInjected > 0 ? (m.totalSaved / m.totalInjected).toFixed(2) : "0"
+  } tokens of context.
+`);
+}
+
+function truncPath(path: string, maxLen: number): string {
+  if (path.length <= maxLen) return path;
+  const parts = path.split(/[/\\]/);
+  if (parts.length <= 2) return "..." + path.slice(-(maxLen - 3));
+  return "..." + parts.slice(-2).join("/");
+}
+
+main();

package/src/cli/reclassify.ts

@@ -0,0 +1,134 @@
+// Re-runs classifier on existing observations to clean up historical "other" entries.
+
+import { getDb } from "../db/sqlite/schema";
+import { classifyObservation } from "../ai/classifier";
+import { compressSession } from "../ai/compressor";
+import { insertSummary } from "../db/sqlite/summaries";
+import { getObservationsBySession } from "../db/sqlite/observations";
+
+interface StoredObs {
+  id: number;
+  tool_name: string | null;
+  summary: string;
+  file_paths: string | null;
+  type: string;
+  importance_score: number;
+}
+
+export function reclassifyAll(options: { onlyOther?: boolean; dryRun?: boolean } = {}): {
+  scanned: number;
+  updated: number;
+  changes: Map<string, number>;
+} {
+  const { onlyOther = false, dryRun = false } = options;
+  const db = getDb();
+
+  const rows = (onlyOther
+    ? db.prepare("SELECT id, tool_name, summary, file_paths, type, importance_score FROM observations WHERE type = 'other'").all()
+    : db.prepare("SELECT id, tool_name, summary, file_paths, type, importance_score FROM observations").all()
+  ) as StoredObs[];
+
+  const update = db.prepare("UPDATE observations SET type = ?, importance_score = ? WHERE id = ?");
+  const changes = new Map<string, number>();
+  let updated = 0;
+
+  for (const row of rows) {
+    const filePaths = row.file_paths ? row.file_paths.split(",").map(s => s.trim()).filter(Boolean) : [];
+    const result = classifyObservation(row.tool_name || "", row.summary, filePaths);
+
+    if (result.type !== row.type || result.importance !== row.importance_score) {
+      const key = `${row.type} → ${result.type}`;
+      changes.set(key, (changes.get(key) || 0) + 1);
+
+      if (!dryRun) {
+        update.run(result.type, result.importance, row.id);
+      }
+      updated++;
+    }
+  }
+
+  return { scanned: rows.length, updated, changes };
+}
+
+export interface RecompressResult {
+  sessionsScanned: number;
+  summariesRewritten: number;
+}
+
+export function recompressAll(options: { dryRun?: boolean; project?: string } = {}): RecompressResult {
+  const { dryRun = false, project } = options;
+  const db = getDb();
+
+  // Pick sessions that already have a Level-1 summary — those are the rows that
+  // show up in "RECENT SESSIONS" in the injected context block.
+  const rows = (project
+    ? db.prepare(`
+        SELECT DISTINCT s.session_id, s.project_path
+        FROM summaries s
+        WHERE s.level = 1 AND s.session_id IS NOT NULL
+          AND s.project_path LIKE ?
+      `).all(`%${project}%`)
+    : db.prepare(`
+        SELECT DISTINCT session_id, project_path FROM summaries
+        WHERE level = 1 AND session_id IS NOT NULL
+      `).all()
+  ) as Array<{ session_id: string; project_path: string | null }>;
+
+  let rewritten = 0;
+  for (const row of rows) {
+    const observations = getObservationsBySession(row.session_id);
+    if (observations.length === 0) continue;
+
+    const summary = compressSession(observations, row.project_path || undefined);
+    if (!dryRun) {
+      // insertSummary upserts on (session_id, level=1) — see summaries.ts
+      insertSummary({
+        session_id: row.session_id,
+        level: 1,
+        text: summary.text,
+        project_path: row.project_path || undefined,
+      });
+    }
+    rewritten++;
+  }
+
+  return { sessionsScanned: rows.length, summariesRewritten: rewritten };
+}
+
+export function runReclassifyCli(args: string[]): void {
+  const dryRun = args.includes("--dry-run");
+  const recompress = args.includes("--recompress");
+  const onlyOther = args.includes("--only-other") || !args.includes("--all");
+  const projectIdx = args.indexOf("--project");
+  const project = projectIdx >= 0 ? args[projectIdx + 1] : undefined;
+
+  console.log(`\nReclassifying observations...`);
+  console.log(`  Mode: ${onlyOther ? "only 'other' type" : "all observations"}${dryRun ? " (DRY RUN)" : ""}`);
+  console.log("─".repeat(60));
+
+  const { scanned, updated, changes } = reclassifyAll({ onlyOther, dryRun });
+
+  console.log(`\n  Scanned: ${scanned}`);
+  console.log(`  Updated: ${updated}${dryRun ? " (not applied)" : ""}`);
+
+  if (changes.size > 0) {
+    console.log(`\n  Type transitions:`);
+    const sorted = [...changes.entries()].sort((a, b) => b[1] - a[1]);
+    for (const [transition, count] of sorted) {
+      console.log(`    ${transition}  (${count}x)`);
+    }
+  } else {
+    console.log(`\n  No changes needed — classifier agrees with stored types.`);
+  }
+
+  if (recompress) {
+    console.log(`\nRecompressing historical session summaries${project ? ` for project matching "${project}"` : ""}...`);
+    console.log("─".repeat(60));
+    const r = recompressAll({ dryRun, project });
+    console.log(`  Sessions scanned:     ${r.sessionsScanned}`);
+    console.log(`  Summaries rewritten:  ${r.summariesRewritten}${dryRun ? " (not applied)" : ""}`);
+    if (r.summariesRewritten === 0 && r.sessionsScanned === 0) {
+      console.log(`  Nothing to rewrite — no level-1 summaries found.`);
+    }
+  }
+}