total-recall-brain 3.1.0

package/src/cli/remember.mjs

@@ -0,0 +1,306 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { resolveAgentDir, resolveBrainDir, parseLayerFlag, getBothBrains, defaultLayerForCategory } from './agent-dir.mjs';
+import { compileSurface } from '../core/surface.mjs';
+import { writeNode } from '../core/vault.mjs';
+
+function printHelp() {
+  console.log(`
+  total-recall remember — Remember rules, preferences, corrections, and facts in real time
+
+  Usage: total-recall remember <category> "<content>" [options]
+
+  Categories:
+    invariant     - Mandatory behavioral directive (appends to rules/invariants.md & writes to vault)
+    preference    - User style preference (appends to rules/preferences.md & writes to vault)
+    correction    - Learned correction (appends to rules/corrections.md & writes to vault)
+    fact          - Factual memory node
+    concept       - Domain concept node
+    pattern       - Positive design/behavior pattern
+    anti-pattern  - Negative design/behavior anti-pattern
+    decision      - Architectural decision
+    lore          - Backstory and system context
+
+  Options (SSSS v2 Frontmatter):
+    --tags, -t <list>         Comma-separated list of tags (e.g. "config,server")
+    --importance, -i <1-5>    Numerical importance level (default: 3)
+    --priority, -p <level>    absolute | high | normal | low (default: normal)
+    --modality, -m <type>     must | must_not | should | should_not | descriptive | preference
+    --confidence, -c <0-1>    Confidence level (default: 1.0)
+    --slug <custom-slug>      Define custom kebab-case slug
+    --title <custom-title>    Define custom human-readable title
+    --status <state>          active | draft | archived (default: active)
+    --subject <string>        SPO Subject (default: system)
+    --predicate <string>      SPO Predicate (default: remembers_fact)
+    --object <string>         SPO Object (default: brain)
+    --related <list>          Comma-separated list of related slugs
+    --expires <duration>       TTL for temporary rules (e.g. "7d", "2w", "30d", "6h", "3m")
+
+  Examples:
+    npx total-recall remember invariant "Never run tsc directly." --importance 5 --priority absolute
+    npx total-recall remember preference "Always use single quotes." --tags "style,js" --modality preference
+    npx total-recall remember fact "The server runs on port 3000." --tags "config,port" --importance 4
+    npx total-recall remember fact "Uses Drizzle ORM" --project   # Saves to project brain
+    npx total-recall remember invariant "No var" --global          # Saves to global brain
+`);
+}
+
+/**
+ * Parse a human-friendly duration string and return a Date in the future.
+ * Supported units: h (hours), d (days), w (weeks), m (months).
+ * E.g. "7d" → 7 days from now, "2w" → 14 days from now.
+ */
+function parseDuration(str) {
+  if (!str || typeof str !== 'string') {
+    throw new Error(`Invalid duration: "${str}". Expected format like "7d", "2w", "30d", "6h", "3m".`);
+  }
+  const match = str.trim().match(/^(\d+)([hdwm])$/i);
+  if (!match) {
+    throw new Error(`Invalid duration: "${str}". Expected format like "7d", "2w", "30d", "6h", "3m".`);
+  }
+  const amount = parseInt(match[1], 10);
+  const unit = match[2].toLowerCase();
+  const date = new Date();
+  switch (unit) {
+    case 'h': date.setHours(date.getHours() + amount); break;
+    case 'd': date.setDate(date.getDate() + amount); break;
+    case 'w': date.setDate(date.getDate() + amount * 7); break;
+    case 'm': date.setMonth(date.getMonth() + amount); break;
+    default: throw new Error(`Unknown duration unit: "${unit}".`);
+  }
+  return date;
+}
+
+export default async function remember(args) {
+  // Parse layer flag first
+  const { layer: explicitLayer, remainingArgs: layerArgs } = parseLayerFlag(args);
+  const type = layerArgs[0];
+  const bodyContent = layerArgs[1];
+
+  if (!type || !bodyContent || type === '--help' || type === '-h') {
+    printHelp();
+    return;
+  }
+
+  const categoryMap = {
+    invariant: 'invariants',
+    preference: 'preferences',
+    correction: 'anti-patterns',
+    'anti-pattern': 'anti-patterns',
+    pattern: 'patterns',
+    decision: 'decisions',
+    concept: 'concepts',
+    fact: 'facts',
+    lore: 'lore'
+  };
+
+  const category = categoryMap[type.toLowerCase()];
+
+  if (!category) {
+    console.error(`Invalid memory category: "${type}". Run total-recall remember --help for details.`);
+    process.exit(1);
+  }
+
+  // Resolve layer: explicit flag > category heuristic > auto-detect
+  let layer = explicitLayer;
+  if (layer === 'auto') {
+    layer = defaultLayerForCategory(category);
+    // Fall back to global if no project brain exists
+    const project = getBothBrains().project;
+    if (layer === 'project' && !project) {
+      layer = 'global';
+    }
+  }
+
+  // Parse Options
+  let tags = [];
+  let importance = 3;
+  let priority = 'normal';
+  let modality = 'descriptive';
+  let confidence = 1.0;
+  let slug = null;
+  let title = null;
+  let status = 'active';
+  let subject = 'system';
+  let predicate = 'remembers_fact';
+  let object = 'brain';
+  let related = [];
+  let expiresAt = null;
+
+  for (let i = 2; i < layerArgs.length; i++) {
+    const arg = layerArgs[i];
+    const val = layerArgs[i + 1];
+
+    if (arg === '--tags' || arg === '-t') {
+      if (val) {
+        tags = val.split(',').map(t => t.trim());
+        i++;
+      }
+    } else if (arg === '--importance' || arg === '-i') {
+      if (val) {
+        const num = parseInt(val, 10);
+        if (!isNaN(num)) importance = num;
+        i++;
+      }
+    } else if (arg === '--priority' || arg === '-p') {
+      if (val) {
+        priority = val.toLowerCase();
+        i++;
+      }
+    } else if (arg === '--modality' || arg === '-m') {
+      if (val) {
+        modality = val.toLowerCase();
+        i++;
+      }
+    } else if (arg === '--confidence' || arg === '-c') {
+      if (val) {
+        const num = parseFloat(val);
+        if (!isNaN(num)) confidence = num;
+        i++;
+      }
+    } else if (arg === '--slug') {
+      if (val) {
+        slug = val.trim();
+        i++;
+      }
+    } else if (arg === '--title') {
+      if (val) {
+        title = val.trim();
+        i++;
+      }
+    } else if (arg === '--status') {
+      if (val) {
+        status = val.toLowerCase();
+        i++;
+      }
+    } else if (arg === '--subject') {
+      if (val) {
+        subject = val.trim();
+        i++;
+      }
+    } else if (arg === '--predicate') {
+      if (val) {
+        predicate = val.trim();
+        i++;
+      }
+    } else if (arg === '--object') {
+      if (val) {
+        object = val.trim();
+        i++;
+      }
+    } else if (arg === '--related') {
+      if (val) {
+        related = val.split(',').map(r => r.trim());
+        i++;
+      }
+    } else if (arg === '--expires') {
+      if (val) {
+        try {
+          expiresAt = parseDuration(val).toISOString();
+        } catch (err) {
+          console.error(`❌ ${err.message}`);
+          process.exit(1);
+        }
+        i++;
+      }
+    }
+  }
+
+  const resolvedAgentDir = resolveAgentDir(layer);
+  const resolvedBrainDir = resolveBrainDir(layer);
+  const skillsDir = path.join(resolvedAgentDir, 'skills');
+  const vaultDir = path.join(resolvedBrainDir, 'memory-vault');
+  const derivedDir = path.join(resolvedBrainDir, 'memory-derived');
+  const instructionsFile = path.join(resolvedAgentDir, 'INSTRUCTIONS.md');
+  const layerLabel = layer === 'project' ? '[project]' : '[global]';
+
+  // Rule sheet mapping (for push rules projection)
+  const ruleFiles = {
+    invariant:  { file: 'invariants.md' },
+    preference: { file: 'preferences.md' },
+    correction: { file: 'corrections.md' }
+  };
+
+  const ruleConfig = ruleFiles[type.toLowerCase()];
+
+  if (ruleConfig) {
+    const rulePath = path.join(skillsDir, 'total-recall', 'rules', ruleConfig.file);
+    if (fs.existsSync(rulePath)) {
+      let fileContent = fs.readFileSync(rulePath, 'utf8').trimEnd();
+      const normalizedBody = bodyContent.startsWith('-') ? bodyContent : `- ${bodyContent}`;
+      fileContent += `\n${normalizedBody}\n`;
+      fs.writeFileSync(rulePath, fileContent, 'utf8');
+      console.log(`  ✅ Rule successfully appended to rules sheet: ${ruleConfig.file}`);
+    }
+  }
+
+  // Create individual SSSS v2 node in the vault
+  const finalSlug = slug || `${category}-${crypto.randomBytes(4).toString('hex')}`;
+  const truncatedContent = bodyContent.slice(0, 50) + (bodyContent.length > 50 ? '...' : '');
+  const finalTitle = title || `Self-captured memory: ${truncatedContent.replace(/\n/g, ' ')}`;
+
+  const now = new Date().toISOString();
+  
+  // Construct schema-compliant SSSS node
+  const node = {
+    type: 'memory',
+    slug: finalSlug,
+    category,
+    title: finalTitle,
+    status,
+    confidence,
+    importance,
+    created: now,
+    updated: now,
+    last_accessed: now,
+    source: {
+      type: 'remember-cli',
+      session_id: process.env.TR_SESSION_ID || 'remember-session',
+      evidence_count: 1
+    },
+    supersedes: [],
+    superseded_by: null,
+    contradicts: [],
+    tags,
+    related,
+    routes_to_skills: [],
+    sentiment_polarity: type.toLowerCase() === 'preference' ? 'preference' : 'descriptive',
+    sentiment_target: subject,
+    modality,
+    subject,
+    predicate,
+    object,
+    decay: {
+      half_life_days: 180,
+      access_count: 1
+    },
+    schema_version: 2,
+    ...(expiresAt ? { expires_at: expiresAt } : {}),
+    x_temporal_context: now,
+    body: bodyContent
+  };
+
+  // Add absolute invariant properties if priority is absolute
+  if (priority === 'absolute') {
+    node.priority = 'absolute';
+    node.immutable = true;
+  }
+
+  writeNode(node, vaultDir);
+  console.log(`  ✅ Permanent SSSS memory node created ${layerLabel} in vault: memory-vault/${category}/${finalSlug}.md`);
+
+  // Instantly recompile instructions and vector indexes in the exact same turn!
+  console.log('  ⏳ Recompiling active memory surfaces and indexes...');
+  try {
+    const compileResult = await compileSurface({
+      vaultDir,
+      skillsDir,
+      derivedDir,
+      instructionsFile
+    });
+    console.log(`  ✅ Recompilation successful! Processed ${compileResult.nodesProcessed} SSSS nodes.`);
+  } catch (err) {
+    console.warn(`  ⚠️  Memory saved, but surface recompilation failed: ${err.message}`);
+  }
+}

package/src/cli/research.mjs

@@ -0,0 +1,381 @@
+/**
+ * src/cli/research.mjs
+ *
+ * Dedicated CLI subcommand for managing ongoing research projects.
+ * Usage:
+ *   npx total-recall research list
+ *   npx total-recall research add "<topic>" [--priority high|medium|low] [--notes "..."]
+ *   npx total-recall research status
+ *   npx total-recall research show <id-or-topic>
+ *   npx total-recall research report <id-or-topic>
+ *   npx total-recall research cancel <id>
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
+import {
+  listQueue,
+  addToQueue,
+  removeFromQueue,
+  loadQueue
+} from '../core/research-queue.mjs';
+
+// ANSI escape helpers
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const grey = (s) => `\x1b[90m${s}\x1b[0m`;
+const boldCyan = (s) => `\x1b[1m\x1b[36m${s}\x1b[0m`;
+const boldGreen = (s) => `\x1b[1m\x1b[32m${s}\x1b[0m`;
+const boldYellow = (s) => `\x1b[1m\x1b[33m${s}\x1b[0m`;
+const boldRed = (s) => `\x1b[1m\x1b[31m${s}\x1b[0m`;
+
+function getStatusBadge(status) {
+  switch (status) {
+    case 'in_progress':
+      return boldCyan('[IN PROGRESS 🧪]');
+    case 'pending':
+      return boldYellow('[PENDING ⏳]');
+    case 'done':
+      return boldGreen('[COMPLETED ✅]');
+    case 'failed':
+      return boldRed('[FAILED ❌]');
+    default:
+      return bold(`[${status.toUpperCase()}]`);
+  }
+}
+
+function getPhaseLabel(phase) {
+  switch (phase) {
+    case 'acquisition': return 'Acquisition (1/5)';
+    case 'deliberation': return 'Deliberation (2/5)';
+    case 'improvement': return 'Refinement & Clarity (3/5)';
+    case 'monitoring': return 'Sources & Feeds (4/5)';
+    case 'expansion': return 'Tangent Expansion (5/5)';
+    default: return phase || 'unknown';
+  }
+}
+
+function timeSince(dateString) {
+  if (!dateString) return 'unknown';
+  const seconds = Math.floor((new Date() - new Date(dateString)) / 1000);
+  if (seconds < 60) return 'just now';
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+function printHeader() {
+  console.log(grey('┌─────────────────────────────────────────────────────────────┐'));
+  console.log(grey('│ ') + boldCyan('Total Recall — Active Autonomous Research Engine') + grey('           │'));
+  console.log(grey('└─────────────────────────────────────────────────────────────┘'));
+}
+
+function printUsage() {
+  console.log(`
+  Usage: total-recall research <command> [options]
+
+  Commands:
+    list [--status <pending|in_progress|done|failed>] [--query <text>]
+                         List all research projects with status & phase (default)
+    add "<topic>" [--priority low|medium|high] [--notes "<text>"]
+                         Queue a new research topic
+    status               Summary counts of all research projects
+    show <id-or-topic>   Show the current summary, conclusions, & directions
+    report <id-or-topic> Read the full research report from the vault
+    cancel <id>          Cancel and remove a research project
+
+  Options:
+    --help, -h           Show this help manual
+`);
+}
+
+function findProject(idOrTopic, resolvedBrainDir) {
+  const queue = loadQueue(resolvedBrainDir);
+  // Try ID prefix match first
+  let match = queue.find(p => p.id.startsWith(idOrTopic));
+  if (!match) {
+    // Try case-insensitive topic match
+    const q = idOrTopic.toLowerCase();
+    match = queue.find(p => p.topic.toLowerCase().includes(q));
+  }
+  return match;
+}
+
+function getReportContent(nodeSlug, resolvedBrainDir) {
+  if (!nodeSlug) return null;
+  const vaultFile = path.join(resolvedBrainDir, 'memory-vault', 'facts', `${nodeSlug}.md`);
+  const inboxFile = path.join(resolvedBrainDir, 'memory-inbox', 'pending', `${nodeSlug}.md`);
+
+  if (fs.existsSync(vaultFile)) {
+    return { path: vaultFile, content: fs.readFileSync(vaultFile, 'utf8'), promoted: true };
+  } else if (fs.existsSync(inboxFile)) {
+    return { path: inboxFile, content: fs.readFileSync(inboxFile, 'utf8'), promoted: false };
+  }
+  return null;
+}
+
+// ─── Command Handlers ────────────────────────────────────────────────────────
+
+function handleList(args, resolvedBrainDir) {
+  let status = 'all';
+  let query = '';
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--status') status = args[++i];
+    else if (args[i] === '--query') query = args[++i];
+  }
+
+  const { items, total } = listQueue({ status, query, brainDir: resolvedBrainDir });
+
+  printHeader();
+  if (items.length === 0) {
+    console.log(`  No research projects found matching status: ${bold(status)}`);
+    console.log();
+    return;
+  }
+
+  console.log(`  Displaying ${bold(items.length)} of ${bold(total)} research projects:`);
+  console.log();
+
+  for (const item of items) {
+    const badge = getStatusBadge(item.status);
+    const phase = getPhaseLabel(item.research_phase);
+    console.log(`  ${badge}  ${bold(item.topic)}`);
+    console.log(`      ${grey('ID:')} ${item.id.slice(0, 8)}... | ${grey('Phase:')} ${cyan(phase)} | ${grey('Updated:')} ${timeSince(item.updated_at)}`);
+    if (item.summary?.conclusions && item.summary.conclusions.length > 0 && item.summary.conclusions[0] !== 'Initial facts gathered and indexed in the knowledge base.') {
+      console.log(`      ${grey('↳')} ${item.summary.conclusions[0].slice(0, 100)}...`);
+    }
+    console.log();
+  }
+}
+
+function handleAdd(args, resolvedBrainDir) {
+  const topic = args[0];
+  if (!topic || topic.startsWith('--')) {
+    console.error(red('  Error: topic string is required.'));
+    printUsage();
+    process.exit(1);
+  }
+
+  let priority = 'medium';
+  let notes = '';
+
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--priority') priority = args[++i];
+    else if (args[i] === '--notes') notes = args[++i];
+  }
+
+  try {
+    const item = addToQueue({ topic, priority, notes, brainDir: resolvedBrainDir });
+    console.log();
+    console.log(`  ${green('✅ Successfully enqueued research project:')}`);
+    console.log(`  ${bold('Topic:')}    "${item.topic}"`);
+    console.log(`  ${bold('ID:')}       ${item.id}`);
+    console.log(`  ${bold('Priority:')} ${item.priority}`);
+    console.log();
+  } catch (err) {
+    console.error(red(`  Error: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+function handleStatus(resolvedBrainDir) {
+  const queue = loadQueue(resolvedBrainDir);
+  const counts = { pending: 0, in_progress: 0, done: 0, failed: 0 };
+  const phaseCounts = { acquisition: 0, deliberation: 0, improvement: 0, monitoring: 0, expansion: 0 };
+
+  for (const item of queue) {
+    if (counts[item.status] !== undefined) counts[item.status]++;
+    const phase = item.research_phase || 'acquisition';
+    if (phaseCounts[phase] !== undefined) phaseCounts[phase]++;
+  }
+
+  printHeader();
+  console.log(`  ${bold('Overall Project Statistics:')}`);
+  console.log(`    🧪 ${boldCyan('In Progress:')}  ${counts.in_progress}`);
+  console.log(`    ⏳ ${boldYellow('Pending:')}      ${counts.pending}`);
+  console.log(`    ✅ ${boldGreen('Completed:')}    ${counts.done}`);
+  console.log(`    ❌ ${boldRed('Failed:')}       ${counts.failed}`);
+  console.log();
+  console.log(`  ${bold('Active Phase Breakdown:')}`);
+  console.log(`    1. ${grey('Acquisition:')}         ${phaseCounts.acquisition} enqueued`);
+  console.log(`    2. ${grey('Deliberation:')}        ${phaseCounts.deliberation} enqueued`);
+  console.log(`    3. ${grey('Refinement & Clarity:')} ${phaseCounts.improvement} enqueued`);
+  console.log(`    4. ${grey('Sources & Feeds:')}      ${phaseCounts.monitoring} enqueued`);
+  console.log(`    5. ${grey('Tangent Expansion:')}    ${phaseCounts.expansion} enqueued`);
+  console.log();
+}
+
+function handleShow(args, resolvedBrainDir) {
+  const query = args[0];
+  if (!query) {
+    console.error(red('  Error: project ID or topic string required.'));
+    printUsage();
+    process.exit(1);
+  }
+
+  const project = findProject(query, resolvedBrainDir);
+  if (!project) {
+    console.error(red(`  Error: no research project found for query: "${query}"`));
+    process.exit(1);
+  }
+
+  printHeader();
+  console.log(`  ${bold('Research Topic:')}  ${boldCyan(`"${project.topic}"`)}`);
+  console.log(`  ${grey('ID:')}              ${project.id}`);
+  console.log(`  ${grey('Status:')}          ${getStatusBadge(project.status)}`);
+  console.log(`  ${grey('Active Phase:')}    ${cyan(getPhaseLabel(project.research_phase))}`);
+  console.log(`  ${grey('Last Updated:')}    ${timeSince(project.updated_at)} (${new Date(project.updated_at).toLocaleString()})`);
+  console.log();
+
+  const summary = project.summary;
+  if (!summary) {
+    console.log(`  ${boldYellow('⚠️  No summary available yet for this project.')}`);
+    console.log();
+    return;
+  }
+
+  console.log(grey('  ───────────────────────────────────────────────────────────'));
+  console.log(`  ${bold('🔑 Key Conclusions & Insights')}`);
+  if (summary.conclusions && summary.conclusions.length > 0) {
+    for (const c of summary.conclusions) {
+      console.log(`    ✨ ${c}`);
+    }
+  } else {
+    console.log(`    ${grey('(Pending phase completion to extract insights)')}`);
+  }
+  console.log();
+
+  console.log(`  ${bold('🚀 Ongoing Directions & Gaps')}`);
+  if (summary.ongoing_directions && summary.ongoing_directions.length > 0) {
+    for (const d of summary.ongoing_directions) {
+      console.log(`    ↳ ${d}`);
+    }
+  } else {
+    console.log(`    ${grey('(Pending phase completion to extract future directions)')}`);
+  }
+  console.log();
+
+  if (project.node_slug) {
+    console.log(grey('  ───────────────────────────────────────────────────────────'));
+    console.log(`  ${bold('Full Report Details:')}`);
+    console.log(`    ${grey('Vault Node Slug:')}   [[${project.node_slug}]]`);
+    console.log(`    ${grey('Status in Vault:')}  ${project.summary?.node_status === 'active' ? green('Promoted (Active Fact)') : yellow('Staged (Pending Validation)')}`);
+    console.log(`    ${grey('Sources Consulted:')} ${summary.sources_count || 0} unique references`);
+    console.log();
+    console.log(`  ${grey('To read the full raw markdown report, run:')}`);
+    console.log(`    ${boldCyan(`npx total-recall research report ${project.id.slice(0, 8)}`)}`);
+  }
+  console.log();
+}
+
+function handleReport(args, resolvedBrainDir) {
+  const query = args[0];
+  if (!query) {
+    console.error(red('  Error: project ID or topic string required.'));
+    printUsage();
+    process.exit(1);
+  }
+
+  const project = findProject(query, resolvedBrainDir);
+  if (!project) {
+    console.error(red(`  Error: no research project found for query: "${query}"`));
+    process.exit(1);
+  }
+
+  if (!project.node_slug) {
+    console.error(red(`  Error: research project "${project.topic}" has not produced a report slug yet. Let the daemon run its acquisition cycle.`));
+    process.exit(1);
+  }
+
+  const report = getReportContent(project.node_slug, resolvedBrainDir);
+  if (!report) {
+    console.error(red(`  Error: report file not found for slug [[${project.node_slug}]].`));
+    process.exit(1);
+  }
+
+  console.log(grey('┌─────────────────────────────────────────────────────────────┐'));
+  console.log(grey('│ ') + boldCyan(`Report: [[${project.node_slug}]]`) + grey(' '.repeat(Math.max(0, 43 - project.node_slug.length))) + grey('│'));
+  console.log(grey('│ ') + grey(`Location: ${report.path}`) + grey(' '.repeat(Math.max(0, 48 - report.path.length))) + grey('│'));
+  console.log(grey('│ ') + (report.promoted ? boldGreen('PROMOTED ACTIVE FACT') : boldYellow('PENDING VALIDATION DRAFT')) + grey(' '.repeat(report.promoted ? 38 : 34)) + grey('│'));
+  console.log(grey('└─────────────────────────────────────────────────────────────┘'));
+  console.log();
+  console.log(report.content);
+  console.log();
+}
+
+function handleCancel(args, resolvedBrainDir) {
+  const id = args[0];
+  if (!id) {
+    console.error(red('  Error: project ID is required.'));
+    printUsage();
+    process.exit(1);
+  }
+
+  try {
+    const result = removeFromQueue(id, resolvedBrainDir);
+    console.log();
+    console.log(`  ${green('✅ Successfully cancelled and removed research project:')}`);
+    console.log(`  ${bold('Topic:')} "${result.topic}"`);
+    console.log(`  ${bold('ID:')}    ${result.id}`);
+    console.log();
+  } catch (err) {
+    console.error(red(`  Error: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+// ─── CLI Entrypoint ──────────────────────────────────────────────────────────
+
+export default async function research(args) {
+  // Parse layer flag from args
+  const { layer, remainingArgs } = parseLayerFlag(args);
+  const resolvedBrainDir = resolveBrainDir(layer);
+  const cmd = remainingArgs[0] || 'list';
+
+  if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
+    printHeader();
+    printUsage();
+    return;
+  }
+
+  const subArgs = remainingArgs.slice(1);
+
+  switch (cmd) {
+    case 'list':
+      handleList(subArgs, resolvedBrainDir);
+      break;
+    case 'add':
+      handleAdd(subArgs, resolvedBrainDir);
+      break;
+    case 'status':
+      handleStatus(resolvedBrainDir);
+      break;
+    case 'show':
+      handleShow(subArgs, resolvedBrainDir);
+      break;
+    case 'report':
+      handleReport(subArgs, resolvedBrainDir);
+      break;
+    case 'cancel':
+      handleCancel(subArgs, resolvedBrainDir);
+      break;
+    default:
+      const matched = findProject(cmd, resolvedBrainDir);
+      if (matched) {
+        handleShow([cmd, ...subArgs], resolvedBrainDir);
+      } else {
+        console.error(red(`  Error: unknown research subcommand: "${cmd}"`));
+        printUsage();
+        process.exit(1);
+      }
+  }
+}