total-recall-brain 3.1.0

package/src/core/steering.mjs

@@ -0,0 +1,137 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'node:crypto';
+import natural from 'natural';
+import { atomicWrite } from './vault.mjs';
+
+const JACCARD_THRESHOLD = 0.75;
+
+/**
+ * Jaccard similarity for two sets of tokens.
+ */
+function jaccard(setA, setB) {
+  const intersection = new Set([...setA].filter(x => setB.has(x)));
+  const union = new Set([...setA, ...setB]);
+  if (union.size === 0) return 0;
+  return intersection.size / union.size;
+}
+
+/**
+ * Layer 1: Ontology SPO collision check.
+ * Checks if Subject, Predicate, and Object match but modality/sentiment flip.
+ */
+export function checkLayer1(candidate, existing) {
+  if (
+    candidate.subject === existing.subject &&
+    candidate.predicate === existing.predicate &&
+    candidate.object === existing.object
+  ) {
+    const polarityFlip = candidate.sentiment_polarity !== existing.sentiment_polarity ||
+                         candidate.modality !== existing.modality;
+    if (polarityFlip) {
+      return {
+        collision: true,
+        reason: `Layer 1: Polarity flip on SPO (${candidate.subject} -> ${candidate.predicate} -> ${candidate.object})`
+      };
+    }
+  }
+  return { collision: false };
+}
+
+/**
+ * Layer 2: Jaccard + Cosine collision check on node body.
+ */
+export function checkLayer2(candidate, existing) {
+  const tokenizer = new natural.WordTokenizer();
+  const tokensA = new Set(tokenizer.tokenize((candidate.body || '').toLowerCase()));
+  const tokensB = new Set(tokenizer.tokenize((existing.body || '').toLowerCase()));
+  
+  const score = jaccard(tokensA, tokensB);
+  
+  if (score >= JACCARD_THRESHOLD) {
+    const polarityFlip = candidate.sentiment_polarity !== existing.sentiment_polarity;
+    if (polarityFlip) {
+      return {
+        collision: true,
+        similarity: score,
+        reason: `Layer 2: Jaccard similarity ${score.toFixed(2)} >= ${JACCARD_THRESHOLD} with polarity flip`
+      };
+    }
+  }
+  return { collision: false };
+}
+
+/**
+ * Run all collision checks for a candidate against the vault.
+ */
+export function detectConflicts(candidate, existingNodes) {
+  const conflicts = [];
+  
+  for (const existing of existingNodes) {
+    if (existing.status !== 'active') continue;
+    
+    const l1 = checkLayer1(candidate, existing);
+    if (l1.collision) {
+      conflicts.push({
+        type: 'conflict',
+        conflict_id: `conflict-${Date.now()}-${crypto.randomInt(0, 1000)}`,
+        status: 'pending',
+        new_slug: candidate.slug,
+        existing_slug: existing.slug,
+        similarity: 1.0,
+        polarity_flip: true,
+        detected_at: new Date().toISOString(),
+        reason: l1.reason,
+        resolution: null,
+        resolved_at: null
+      });
+      continue;
+    }
+    
+    const l2 = checkLayer2(candidate, existing);
+    if (l2.collision) {
+      conflicts.push({
+        type: 'conflict',
+        conflict_id: `conflict-${Date.now()}-${crypto.randomInt(0, 1000)}`,
+        status: 'pending',
+        new_slug: candidate.slug,
+        existing_slug: existing.slug,
+        similarity: l2.similarity,
+        polarity_flip: true,
+        detected_at: new Date().toISOString(),
+        reason: l2.reason,
+        resolution: null,
+        resolved_at: null
+      });
+    }
+  }
+  
+  return conflicts;
+}
+
+/**
+ * Write conflict record to the memory-inbox/conflicts/ quarantine directory.
+ */
+export function quarantineConflict(conflict, conflictsDir) {
+  if (!fs.existsSync(conflictsDir)) {
+    fs.mkdirSync(conflictsDir, { recursive: true });
+  }
+  const filePath = path.join(conflictsDir, `${conflict.conflict_id}.json`);
+  atomicWrite(filePath, JSON.stringify(conflict, null, 2));
+}
+
+/**
+ * Resolve a conflict.
+ */
+export function resolveConflict(conflictId, resolution, conflictsDir) {
+  const filePath = path.join(conflictsDir, `${conflictId}.json`);
+  if (!fs.existsSync(filePath)) throw new Error('Conflict not found');
+  
+  const conflict = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  conflict.status = 'resolved';
+  conflict.resolution = resolution;
+  conflict.resolved_at = new Date().toISOString();
+  
+  atomicWrite(filePath, JSON.stringify(conflict, null, 2));
+  return conflict;
+}

package/src/core/surface.mjs

@@ -0,0 +1,444 @@
+import fs from 'fs';
+import path from 'path';
+import { loadNodes, loadSkills, atomicWrite } from './vault.mjs';
+import {
+  buildMemoryLayerIndex,
+  inferMemoryLayer,
+} from './memory-layers.mjs';
+
+/**
+ * Extract [[slug]] wikilink references from body text.
+ * Native TR link resolution; Obsidian renders them as graph edges.
+ */
+export function extractWikilinks(body) {
+  if (!body) return [];
+  const matches = body.match(/\[\[([^\]]+)\]\]/g) || [];
+  return [...new Set(matches.map(m => m.slice(2, -2).split('|')[0].trim()))];
+}
+
+/**
+ * Generate an Obsidian Canvas JSON file from active vault nodes.
+ * Written to memory-vault/graph.canvas; also readable by /api/graph.
+ */
+function generateCanvas(nodes, vaultDir) {
+  const active = nodes.filter(n => n.status === 'active');
+  if (active.length === 0) return;
+
+  const CARD_W = 240, CARD_H = 60, GAP_X = 60, GAP_Y = 30;
+  const cols = Math.max(1, Math.ceil(Math.sqrt(active.length)));
+
+  const canvasNodes = active.map((n, i) => ({
+    id: n.slug,
+    x: (i % cols) * (CARD_W + GAP_X),
+    y: Math.floor(i / cols) * (CARD_H + GAP_Y),
+    width: CARD_W,
+    height: CARD_H,
+    type: 'text',
+    text: `**${n.title}**\n_${n.category}_`
+  }));
+
+  const slugSet = new Set(canvasNodes.map(n => n.id));
+  const seen = new Set();
+  const canvasEdges = [];
+
+  for (const n of active) {
+    const targets = [...(n.related || []), ...extractWikilinks(n.body || '')];
+    for (const target of targets) {
+      if (!slugSet.has(target) || target === n.slug) continue;
+      const key = `${n.slug}→${target}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      canvasEdges.push({
+        id: `e${canvasEdges.length}`,
+        fromNode: n.slug,
+        toNode: target,
+        fromSide: 'right',
+        toSide: 'left'
+      });
+    }
+  }
+
+  const canvasPath = path.join(vaultDir, 'graph.canvas');
+  atomicWrite(canvasPath, JSON.stringify({ nodes: canvasNodes, edges: canvasEdges }, null, 2));
+}
+
+// ─── Legacy injection markers (kept for cleanup of old files) ───
+const INJECTION_BEGIN = '<!-- BEGIN INJECTED MEMORY: do not edit by hand; rebuilt by total-recall surface -->';
+const INJECTION_END = '<!-- END INJECTED MEMORY -->';
+
+export function replaceFirstManagedInjectionBlock(raw, injectionBlock) {
+  const chunks = raw.match(/[^\n]*(?:\n|$)/g) || [];
+  let inFence = false;
+  let offset = 0;
+
+  for (let i = 0; i < chunks.length; i++) {
+    const chunk = chunks[i];
+    if (chunk === '') continue;
+    const line = chunk.endsWith('\n') ? chunk.slice(0, -1) : chunk;
+    const trimmed = line.trim();
+
+    if (trimmed.startsWith('```') || trimmed.startsWith('~~~')) {
+      inFence = !inFence;
+      offset += chunk.length;
+      continue;
+    }
+
+    if (!inFence && line === INJECTION_BEGIN) {
+      let endOffset = offset + chunk.length;
+      for (let j = i + 1; j < chunks.length; j++) {
+        endOffset += chunks[j].length;
+        const endLine = chunks[j].endsWith('\n') ? chunks[j].slice(0, -1) : chunks[j];
+        if (endLine === INJECTION_END) {
+          return `${raw.slice(0, offset)}${injectionBlock}\n${raw.slice(endOffset)}`;
+        }
+      }
+      return null;
+    }
+
+    offset += chunk.length;
+  }
+
+  return null;
+}
+
+const DIRECTIVES_BEGIN = '<!-- BEGIN INJECTED ACTIVE DIRECTIVES: do not edit by hand; rebuilt by total-recall surface -->';
+const DIRECTIVES_END = '<!-- END INJECTED ACTIVE DIRECTIVES -->';
+
+function extractRuleContent(filePath) {
+  if (!fs.existsSync(filePath)) return '';
+  const content = fs.readFileSync(filePath, 'utf8');
+  const parts = content.split('---');
+  if (parts.length >= 3) {
+    return parts.slice(2).join('---').trim();
+  }
+  return content.trim();
+}
+
+export function buildRulesBlock(skillsDir, nodes = [], { vaultDir, consumer = 'ide' } = {}) {
+  let combined;
+
+  if (consumer === 'api') {
+    // API consumers don't need CLI quickstart docs
+    combined = `## Total Recall — Active Memory Context\n\nYour memories and rules are loaded from the active brain vault.\n`;
+  } else {
+    // CLI quickstart is always included so agents know TR is installed
+    combined = `## Total Recall — Sovereign Memory System (Installed)
+
+You have Total Recall installed. Use these CLI commands to remember and recall information.
+
+### npx total-recall remember <category> "<content>" [options]
+Save rules, preferences, corrections, and facts to permanent memory.
+
+**Categories:** invariant, preference, correction, fact, concept, pattern, anti-pattern, decision, lore
+
+**Options:**
+  --tags, -t <list>          Comma-separated tags (e.g. "config,server")
+  --importance, -i <1-5>     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>       Custom kebab-case slug
+  --title <custom-title>     Custom human-readable title
+  --status <state>           active | draft | archived (default: active)
+  --related <list>           Comma-separated related slugs
+  --global                   Save to global brain (identity layer)
+  --project                  Save to project brain (context layer)
+
+**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"
+  npx total-recall remember fact "The server runs on port 3000." --importance 4
+  npx total-recall remember fact "Uses Drizzle ORM" --project
+
+### npx total-recall recall "<query>" [options]
+Semantic search across rules, facts, and session history.
+
+**Options:**
+  --top-k, -k <number>       Results to return (default: 5, max: 20)
+  --no-sessions, -ns         Exclude session chunks, vault only
+  --format, -f <type>        text (default) or json
+  --category, -cat <name>    Filter by SSSS category
+  --tags, -t <list>          Filter by tags
+  --modality, -m <type>      Filter by modality
+  --importance, -i <1-5>     Filter by minimum importance
+  --global                   Search global brain only
+  --project                  Search project brain only
+
+**Examples:**
+  npx total-recall recall "Never run tsc directly"
+  npx total-recall recall "Express server port" --top-k 3
+  npx total-recall recall "tsc" --category invariants --modality must
+
+### npx total-recall forget <slug> [options]
+Delete a memory node by slug. Auto-recompiles surfaces and propagates to project brains.
+
+**Options:**
+  --global                   Delete from global brain
+  --project                  Delete from project brain
+  --no-compile               Skip auto-recompilation after deletion
+
+**Examples:**
+  npx total-recall forget old-invariant-slug
+  npx total-recall forget stale-fact --global
+  npx total-recall forget project-specific-node --project
+
+### npx total-recall help <topic>
+Query interactive local documentation, VFS specifications, and command references.
+
+**Options:**
+  --json, -j               Emit machine-readable JSON (ideal for programmatic retrieval)
+
+**Examples:**
+  npx total-recall help connect
+  npx total-recall help architecture
+  npx total-recall help ssss
+
+### npx total-recall --help
+Show all available commands.
+`;
+  }
+
+  // 1. Filter expired rules and auto-archive them
+  const now = new Date();
+  const isExpired = (n) => n.expires_at && new Date(n.expires_at) <= now;
+
+  const expiredNodes = nodes.filter(n => n.status === 'active' && isExpired(n));
+  for (const expired of expiredNodes) {
+    expired.status = 'deprecated';
+    console.error(`⏰ Auto-archived expired rule: ${expired.slug}`);
+    if (vaultDir) {
+      try {
+        const nodePath = path.join(vaultDir, expired.category, `${expired.slug}.md`);
+        if (fs.existsSync(nodePath)) {
+          let content = fs.readFileSync(nodePath, 'utf8');
+          content = content.replace(/^status:\s*active$/m, 'status: deprecated');
+          atomicWrite(nodePath, content);
+        }
+      } catch { /* non-fatal: archive is best-effort */ }
+    }
+  }
+
+  // 2. Group active (non-expired) rules from SSSS vault nodes
+  const invariants = nodes.filter(n => n.category === 'invariants' && n.status === 'active' && !isExpired(n));
+  const preferences = nodes.filter(n => n.category === 'preferences' && n.status === 'active' && !isExpired(n));
+  const corrections = nodes.filter(n => n.category === 'anti-patterns' && n.status === 'active' && !isExpired(n));
+
+  const formatNodes = (list) => {
+    return list.map(n => {
+      const text = n.body || n.content || '';
+      return text.startsWith('-') ? text : `- ${text}`;
+    }).join('\n');
+  };
+
+  if (invariants.length > 0) {
+    combined += `\n\n## Invariant Rules\n\n${formatNodes(invariants)}`;
+  }
+
+  if (preferences.length > 0) {
+    combined += `\n\n## User Preferences\n\n${formatNodes(preferences)}`;
+  }
+
+  if (corrections.length > 0) {
+    combined += `\n\n## Corrections\n\n${formatNodes(corrections)}`;
+  }
+
+  // 2. Append legacy rule sheet files if they exist
+  if (skillsDir) {
+    const rulesDir = path.join(skillsDir, 'total-recall', 'rules');
+    const legacyInvariants = extractRuleContent(path.join(rulesDir, 'invariants.md'));
+    const legacyPreferences = extractRuleContent(path.join(rulesDir, 'preferences.md'));
+    const legacyCorrections = extractRuleContent(path.join(rulesDir, 'corrections.md'));
+
+    if (legacyInvariants) {
+      combined += `\n\n${legacyInvariants}`;
+    }
+    if (legacyPreferences) {
+      combined += `\n\n${legacyPreferences}`;
+    }
+    if (legacyCorrections) {
+      combined += `\n\n${legacyCorrections}`;
+    }
+  }
+
+  return combined.trim();
+}
+
+function injectDirectives(fileContent, rulesBlock) {
+  const beginIdx = fileContent.indexOf(DIRECTIVES_BEGIN);
+  const endIdx = fileContent.indexOf(DIRECTIVES_END);
+  
+  if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
+    return fileContent.slice(0, beginIdx) + DIRECTIVES_BEGIN + '\n' + rulesBlock + '\n' + DIRECTIVES_END + fileContent.slice(endIdx + DIRECTIVES_END.length);
+  }
+  
+  let content = fileContent.trimEnd();
+  const baseline = 'Read and follow .agent/skills/total-recall/SKILL.md on every turn.';
+  if (!content.includes('SKILL.md')) {
+    content = baseline + '\n\n' + content;
+  }
+  
+  return content.trimEnd() + '\n\n' + DIRECTIVES_BEGIN + '\n' + rulesBlock + '\n' + DIRECTIVES_END + '\n';
+}
+
+/**
+ * Write or update a platform instruction shim with the pointer and active rules.
+ */
+function writeShim(shimPath, skillsDir, nodes = [], { vaultDir } = {}) {
+  const shimDir = path.dirname(shimPath);
+  const rulesBlock = buildRulesBlock(skillsDir, nodes, { vaultDir });
+  const baseline = 'Read and follow .agent/skills/total-recall/SKILL.md on every turn.\n';
+  const fullContent = `${baseline}\n${DIRECTIVES_BEGIN}\n${rulesBlock}\n${DIRECTIVES_END}\n`;
+
+  try {
+    if (fs.existsSync(shimPath)) {
+      const stat = fs.lstatSync(shimPath);
+      if (stat.isSymbolicLink()) {
+        fs.unlinkSync(shimPath);
+        atomicWrite(shimPath, fullContent);
+      } else {
+        const raw = fs.readFileSync(shimPath, 'utf8');
+        let cleaned = raw;
+        if (raw.includes(INJECTION_BEGIN)) {
+          const replaced = replaceFirstManagedInjectionBlock(raw, '');
+          if (replaced !== null) cleaned = replaced;
+        }
+        
+        const updated = injectDirectives(cleaned, rulesBlock);
+        atomicWrite(shimPath, updated);
+      }
+    } else {
+      if (!fs.existsSync(shimDir)) {
+        fs.mkdirSync(shimDir, { recursive: true });
+      }
+      atomicWrite(shimPath, fullContent);
+    }
+  } catch (err) {
+    // Ignore permission errors
+  }
+}
+
+/**
+ * Map of client names → shim file paths they require.
+ */
+const CLIENT_SHIMS = {
+  cursor:        ['.cursorrules'],
+  'claude-code': ['CLAUDE.md', '.clauderules'],
+  antigravity:   ['AGENTS.md'],
+  gemini:        ['GEMINI.md'],
+  codex:         ['CODEX.md', '.codexrules'],
+  vscode:        ['.github/copilot-instructions.md', '.vscode/copilot-instructions.md'],
+  pi:            ['AGENTS.md'],
+  aider:         ['.aider.rules.md'],
+  windsurf:      ['.windsurfrules', 'WINDSURF.md'],
+};
+
+/**
+ * Read the set of connected IDE clients from config/clients.json.
+ * Returns a Set of client name strings, or null if the file is
+ * missing / empty / malformed (null signals "write all shims").
+ */
+function readConnectedClients(clientsPath) {
+  try {
+    if (!fs.existsSync(clientsPath)) return null;
+    const raw = fs.readFileSync(clientsPath, 'utf8').trim();
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed) || parsed.length === 0) return null;
+    return new Set(parsed.map(String));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compile pointers with active rules directly into root instruction shims.
+ *
+ * ALL files (including INSTRUCTIONS.md) are user-owned. TR only injects
+ * content between the <!-- BEGIN/END INJECTED ACTIVE DIRECTIVES --> markers,
+ * preserving any user-written content outside the markers.
+ *
+ * Only shims for connected clients (per config/clients.json) are written.
+ * If clients.json is absent or unreadable, ALL shims are written (backward compat).
+ * INSTRUCTIONS.md is always written as the canonical source.
+ */
+function compilePointers(instructionsFile, skillsDir, nodes = [], { vaultDir } = {}) {
+  const agentDir = path.dirname(instructionsFile);
+  const baseDir = path.basename(agentDir) === '.agent' ? path.dirname(agentDir) : agentDir;
+
+  // Always write the canonical INSTRUCTIONS.md
+  writeShim(path.join(baseDir, 'INSTRUCTIONS.md'), skillsDir, nodes, { vaultDir });
+
+  // Determine which client shims to write
+  const clientsPath = path.join(baseDir, '.agent', 'config', 'clients.json');
+  const connectedClients = readConnectedClients(clientsPath);
+
+  if (connectedClients === null) {
+    // No clients.json → backward compat: write ALL client shims
+    for (const files of Object.values(CLIENT_SHIMS)) {
+      for (const file of files) {
+        writeShim(path.join(baseDir, file), skillsDir, nodes, { vaultDir });
+      }
+    }
+  } else {
+    // Only write shims for connected clients
+    for (const client of connectedClients) {
+      const files = CLIENT_SHIMS[client];
+      if (!files) continue;
+      for (const file of files) {
+        writeShim(path.join(baseDir, file), skillsDir, nodes, { vaultDir });
+      }
+    }
+  }
+}
+
+/**
+ * Main surface compilation entry point.
+ */
+export async function compileSurface({ vaultDir, skillsDir, derivedDir, instructionsFile }) {
+  const nodes = loadNodes(vaultDir);
+
+  // 1. Write pointer and active rules to all instruction shims
+  compilePointers(instructionsFile, skillsDir, nodes, { vaultDir });
+
+  // 2. Build derived indexes (powers semantic search API)
+  if (!fs.existsSync(derivedDir)) {
+    fs.mkdirSync(derivedDir, { recursive: true });
+  }
+
+  const graphIndex = nodes.map(n => ({
+    slug: n.slug,
+    title: n.title,
+    category: n.category,
+    status: n.status,
+    confidence: n.confidence,
+    memory_layer: inferMemoryLayer(n)
+  }));
+  atomicWrite(path.join(derivedDir, 'graph-index.jsonl'), graphIndex.map(n => JSON.stringify(n)).join('\n'));
+  atomicWrite(
+    path.join(derivedDir, 'memory-layers.jsonl'),
+    buildMemoryLayerIndex(nodes).map(n => JSON.stringify(n)).join('\n')
+  );
+
+  // 3. Build semantic embeddings index if available (fire-and-forget)
+  let semanticResult = { indexed: 0, skipped: nodes.length, unavailable: true };
+  try {
+    const { buildSemanticIndex } = await import('./semantic-index.mjs');
+    semanticResult = await buildSemanticIndex(nodes, derivedDir);
+  } catch { /* semantic index is optional — never block compile */ }
+
+  // 4. Generate Obsidian Canvas (fire-and-forget)
+  try {
+    generateCanvas(nodes, vaultDir);
+  } catch { /* non-fatal */ }
+
+  return {
+    nodesProcessed: nodes.length,
+    skillsInjected: 0,  // v2: no more skill injection
+    semanticIndexed: semanticResult.indexed,
+    semanticUnavailable: semanticResult.unavailable
+  };
+}
+// ─── Legacy exports (kept for backward compatibility) ───
+export function routeNodesToSkills() { return []; }
+export function injectSkills() {}
+export function compileTier1(nodes, instructionsFile) { compilePointers(instructionsFile); }

package/src/core/task_runner.mjs

@@ -0,0 +1,125 @@
+import fs from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+import { atomicWrite, safeStringify } from './vault.mjs';
+import { logger } from './logger.mjs';
+
+/**
+ * Task Runner for Total Recall
+ * Reads pending tasks from .agent/scheduler/queue/, sorts by priority, and executes them.
+ */
+
+export function loadPendingTasks(queueDir) {
+  if (!fs.existsSync(queueDir)) return [];
+
+  const tasks = [];
+  const files = fs.readdirSync(queueDir);
+
+  for (const file of files) {
+    if (!file.endsWith('.md')) continue;
+    const filePath = path.join(queueDir, file);
+    try {
+      const raw = fs.readFileSync(filePath, 'utf8');
+      const { data, content } = matter(raw);
+      if (data.type === 'task' && data.status === 'pending') {
+        tasks.push({ ...data, body: content.trim(), filepath: filePath });
+      }
+    } catch (err) {
+      logger.warn('task-runner', `Failed to parse task ${file}`, { err: err.message });
+    }
+  }
+
+  // Sort by priority (higher priority = lower number)
+  return tasks.sort((a, b) => a.priority - b.priority);
+}
+
+export function updateTaskStatus(task, newStatus, error = null) {
+  const { filepath, body, ...frontmatter } = task;
+  frontmatter.status = newStatus;
+  
+  if (error) {
+    frontmatter.error = error;
+  }
+
+  const raw = safeStringify(body || '', frontmatter);
+  atomicWrite(filepath, raw);
+  return { ...task, status: newStatus };
+}
+
+/**
+ * Executes a single task.
+ */
+export async function executeTask(task, context) {
+  logger.info('task-runner', `Executing Task [P${task.priority}]: ${task.target}`);
+  updateTaskStatus(task, 'in_progress');
+
+  try {
+    // In a real implementation, this would route to specific subagents/workflows
+    // based on task.category. For now, we simulate execution.
+    switch (task.category) {
+      case 'skill-engineering':
+        await handleSkillEngineering(task, context);
+        break;
+      case 'memory-maintenance':
+        await handleMemoryMaintenance(task, context);
+        break;
+      case 'system2-deliberation':
+        await handleSystem2Deliberation(task, context);
+        break;
+      case 'proactive-research':
+        logger.info('task-runner', 'Handling Deep Research...');
+        const { handleProactiveResearch } = await import('./research.mjs');
+        const report = await handleProactiveResearch(task, context);
+        task.body = `# Deep Research Report\n\n${report}`;
+        break;
+      case 'self-evaluation':
+      case 'exploration':
+        logger.info('task-runner', `Handling ${task.category}...`);
+        // Simulated work
+        await new Promise(resolve => setTimeout(resolve, 500));
+        break;
+      default:
+        throw new Error(`Unknown task category: ${task.category}`);
+    }
+
+    updateTaskStatus(task, 'done');
+    logger.info('task-runner', `Completed Task: ${task.target}`);
+  } catch (err) {
+    logger.error('task-runner', `Failed Task: ${task.target}`, { err: err.message });
+    updateTaskStatus(task, 'failed', err.message);
+  }
+}
+
+async function handleSkillEngineering(task, context) {
+  // E.g., spawn an agent with the template to create a skill
+  logger.info('task-runner', `Engineering skill: ${task.target}`);
+}
+
+async function handleMemoryMaintenance(task, context) {
+  logger.info('task-runner', `Running memory maintenance for: ${task.target}`);
+}
+
+async function handleSystem2Deliberation(task, context) {
+  logger.info('task-runner', `Running System 2 deliberation for: ${task.target}`);
+}
+
+/**
+ * Main loop for the task runner.
+ */
+export async function runTaskQueue(queueDir, context) {
+  logger.info('task-runner', 'Starting Task Runner...');
+  const pending = loadPendingTasks(queueDir);
+
+  if (pending.length === 0) {
+    logger.info('task-runner', 'No pending tasks in queue.');
+    return;
+  }
+
+  logger.info('task-runner', `Found ${pending.length} pending tasks.`);
+
+  for (const task of pending) {
+    await executeTask(task, context);
+  }
+
+  logger.info('task-runner', 'Task Runner queue empty.');
+}