tribunal-kit 9.2.4 → 9.2.6

package/src/commands/marathon.js

@@ -0,0 +1,68 @@
+'use strict';
+const __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.cmdMarathon = cmdMarathon;
+const fs_1 = __importDefault(require('fs'));
+const path_1 = __importDefault(require('path'));
+const logger_1 = require('../utils/logger');
+const helpers_1 = require('../utils/helpers');
+async function cmdMarathon(flags, processArgs, quiet = false) {
+  const targetDir = flags.path ? path_1.default.resolve(flags.path) : process.cwd();
+  const agentDest = path_1.default.join(targetDir, '.agent');
+  if (!fs_1.default.existsSync(agentDest)) {
+    (0, logger_1.err)('.agent/ not found. Run: npx tribunal-kit init');
+    process.exit(1);
+  }
+  const args = processArgs.slice(3);
+  if (args.length === 0 || args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
+    (0, helpers_1.banner)(quiet);
+    (0, logger_1.log)(`  ${(0, logger_1.c)('cyan', '╔' + '═'.repeat(60) + '╗')}`);
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('cyan', '║')}\x1b[1m\x1b[97m  Marathon — Long-Running Agent Harness                  \x1b[0m${(0, logger_1.c)('cyan', '║')}`,
+    );
+    (0, logger_1.log)(`  ${(0, logger_1.c)('cyan', '╚' + '═'.repeat(60) + '╝')}`);
+    console.log();
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('cyan', 'init'.padEnd(16))}  ${(0, logger_1.c)('gray', 'Start a new marathon (init "spec")')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('cyan', 'status'.padEnd(16))}  ${(0, logger_1.c)('gray', 'Show progress dashboard')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('cyan', 'next'.padEnd(16))}  ${(0, logger_1.c)('gray', 'Show next unfinished feature')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('cyan', 'mark'.padEnd(16))}  ${(0, logger_1.c)('gray', 'Mark feature pass/fail (mark <id> pass)')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('cyan', 'log'.padEnd(16))}  ${(0, logger_1.c)('gray', 'Add a progress note')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('cyan', 'session-start'.padEnd(16))}  ${(0, logger_1.c)('gray', 'Begin a new work session')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('cyan', 'session-end'.padEnd(16))}  ${(0, logger_1.c)('gray', 'End session with summary')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('cyan', 'add-feature'.padEnd(16))}  ${(0, logger_1.c)('gray', 'Add feature: "category" "desc" "step1" ...')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('cyan', 'reset'.padEnd(16))}  ${(0, logger_1.c)('gray', 'Archive and start fresh')}`,
+    );
+    console.log();
+    return;
+  }
+  const marathonScript = path_1.default.join(agentDest, 'scripts', 'marathon_harness.js');
+  try {
+    await (0, helpers_1.runShellAsync)('node', [marathonScript, ...args], {
+      stdio: 'inherit',
+      cwd: targetDir,
+    });
+  } catch {
+    process.exit(1);
+  }
+}

package/src/commands/memory.js

@@ -0,0 +1,609 @@
+'use strict';
+const __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.cmdMemory = cmdMemory;
+const fs_1 = __importDefault(require('fs'));
+const path_1 = __importDefault(require('path'));
+const logger_1 = require('../utils/logger');
+const helpers_1 = require('../utils/helpers');
+
+/**
+ * Tribunal Memory Engine — Node.js CLI Handler
+ *
+ * Routes memory subcommands to the Rust binary when available,
+ * with a pure JS fallback for environments without native binaries.
+ *
+ * Commands:
+ *   tk memory store --type semantic --content "..." --tags "db,orm"
+ *   tk memory recall --query "database" --budget 2000
+ *   tk memory gc
+ *   tk memory stats
+ *   tk memory export
+ */
+
+// ── Memory Index I/O (JS fallback) ──────────────────────────────────────────
+
+const MEMORY_DIR = 'history/memory';
+const INDEX_FILE = '.memory.idx';
+const PROJECTION_FILE = 'MEMORY.md';
+const MAX_ENTRIES = 500;
+const EPISODIC_TTL_DAYS = 30;
+
+function acquireLock(agentDest) {
+  const lockPath = getIndexPath(agentDest) + '.lock';
+  const maxRetries = 10;
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const fd = fs_1.default.openSync(lockPath, 'wx');
+      fs_1.default.closeSync(fd);
+      return lockPath;
+    } catch (err) {
+      if (err.code !== 'EEXIST') {
+        throw err;
+      }
+      // Non-blocking sleep — avoids busy-wait event loop blocking
+      const waitBuf = new Int32Array(new SharedArrayBuffer(4));
+      Atomics.wait(waitBuf, 0, 0, 50);
+    }
+  }
+  try {
+    const stats = fs_1.default.statSync(lockPath);
+    if (Date.now() - stats.mtimeMs > 10000) {
+      fs_1.default.unlinkSync(lockPath);
+      const fd = fs_1.default.openSync(lockPath, 'wx');
+      fs_1.default.closeSync(fd);
+      return lockPath;
+    }
+  } catch {}
+  throw new Error('Could not acquire lock for memory index');
+}
+
+function releaseLock(lockPath) {
+  try {
+    if (lockPath && fs_1.default.existsSync(lockPath)) {
+      fs_1.default.unlinkSync(lockPath);
+    }
+  } catch {}
+}
+
+function getMemoryDir(agentDest) {
+  return path_1.default.join(agentDest, MEMORY_DIR);
+}
+
+function getIndexPath(agentDest) {
+  return path_1.default.join(getMemoryDir(agentDest), INDEX_FILE);
+}
+
+function getProjectionPath(agentDest) {
+  return path_1.default.join(getMemoryDir(agentDest), PROJECTION_FILE);
+}
+
+function loadIndex(agentDest) {
+  const indexPath = getIndexPath(agentDest);
+  if (!fs_1.default.existsSync(indexPath)) {
+    return { version: 1, entries: [], next_id: 1 };
+  }
+  try {
+    const content = fs_1.default.readFileSync(indexPath, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return { version: 1, entries: [], next_id: 1 };
+  }
+}
+
+function saveIndex(agentDest, index) {
+  const memDir = getMemoryDir(agentDest);
+  fs_1.default.mkdirSync(memDir, { recursive: true });
+  const indexPath = getIndexPath(agentDest);
+  // Atomic write: write temp, rename
+  const tmpPath = indexPath + '.tmp';
+  fs_1.default.writeFileSync(tmpPath, JSON.stringify(index, null, 2), 'utf8');
+  fs_1.default.renameSync(tmpPath, indexPath);
+}
+
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+function nowEpochStr() {
+  return `${Math.floor(Date.now() / 1000)}Z`;
+}
+
+function daysSince(ts) {
+  const created = parseInt(ts.replace('Z', ''), 10) || 0;
+  const now = Math.floor(Date.now() / 1000);
+  return Math.floor((now - created) / 86400);
+}
+
+// ── Scoring Engine ──────────────────────────────────────────────────────────
+
+const TYPE_PRIORITY = { semantic: 1.0, procedural: 0.9, episodic: 0.7, working: 0.5 };
+
+function computeScore(entry, query) {
+  const queryLower = query.toLowerCase();
+  const contentLower = entry.content.toLowerCase();
+
+  let relevance = 0;
+  if (contentLower.includes(queryLower)) {
+    relevance = 1.0;
+  } else if (entry.tags.some(t => t.toLowerCase().includes(queryLower))) {
+    relevance = 0.8;
+  } else if (queryLower.split(/\s+/).some(word => contentLower.includes(word))) {
+    relevance = 0.3;
+  }
+
+  if (relevance === 0) return 0;
+
+  const priority = TYPE_PRIORITY[entry.memory_type] || 0.5;
+  let recency = 0;
+  if (entry.memory_type === 'episodic') {
+    const age = daysSince(entry.created_at);
+    recency = Math.exp(-age / 30);
+  }
+  const freqBoost = Math.max(0, Math.log(entry.access_count || 1)) * 0.05;
+
+  return relevance * priority + recency + freqBoost;
+}
+
+// ── Store ───────────────────────────────────────────────────────────────────
+
+function memoryStore(agentDest, type, content, tags, sessionId) {
+  const VALID_TYPES = ['episodic', 'semantic', 'procedural', 'working'];
+  if (!VALID_TYPES.includes(type)) {
+    throw new Error(`Invalid memory type: "${type}". Must be one of: ${VALID_TYPES.join(', ')}`);
+  }
+  if (!content || content.trim().length === 0) {
+    throw new Error('Memory content cannot be empty');
+  }
+
+  const lockPath = acquireLock(agentDest);
+  try {
+    const index = loadIndex(agentDest);
+
+    // Enforce cap — auto-GC if needed
+    if (index.entries.length >= MAX_ENTRIES) {
+      index.entries = index.entries.filter(e => e.memory_type !== 'working');
+      if (index.entries.length >= MAX_ENTRIES) {
+        index.entries = index.entries.filter(e => {
+          if (e.memory_type === 'episodic') {
+            return daysSince(e.created_at) < EPISODIC_TTL_DAYS; // Typo correction or TTL match
+          }
+          return true;
+        });
+      }
+      if (index.entries.length >= MAX_ENTRIES) {
+        throw new Error(`Memory at capacity (${MAX_ENTRIES}). Run: tk memory gc`);
+      }
+    }
+
+    const now = nowEpochStr();
+    const id =
+      index.next_id ||
+      (index.entries.length > 0 ? Math.max(...index.entries.map(e => e.id)) + 1 : 1);
+    const entry = {
+      id,
+      memory_type: type,
+      content: content.trim(),
+      tags: tags.filter(t => t.length > 0),
+      created_at: now,
+      last_accessed: now,
+      access_count: 0,
+      token_estimate: estimateTokens(content),
+      source: type === 'working' ? 'session' : 'manual',
+      session_id: sessionId || null,
+    };
+
+    index.entries.push(entry);
+    index.next_id = id + 1;
+    saveIndex(agentDest, index);
+    generateProjection(agentDest, index);
+
+    return { id, token_estimate: entry.token_estimate };
+  } finally {
+    releaseLock(lockPath);
+  }
+}
+
+// ── Recall ──────────────────────────────────────────────────────────────────
+
+function memoryRecall(agentDest, query, budget = 2000) {
+  const lockPath = acquireLock(agentDest);
+  try {
+    const index = loadIndex(agentDest);
+
+    const scored = index.entries
+      .map(entry => ({ entry, score: computeScore(entry, query) }))
+      .filter(s => s.score > 0)
+      .sort((a, b) => b.score - a.score);
+
+    let totalTokens = 0;
+    const results = [];
+
+    for (const { entry, score } of scored) {
+      if (totalTokens + entry.token_estimate > budget) break;
+      totalTokens += entry.token_estimate;
+      entry.last_accessed = nowEpochStr();
+      entry.access_count = (entry.access_count || 0) + 1;
+      results.push({ ...entry, score });
+    }
+
+    // Save updated access counts
+    saveIndex(agentDest, index);
+
+    return { results, tokens_used: totalTokens, budget };
+  } finally {
+    releaseLock(lockPath);
+  }
+}
+
+// ── Garbage Collect ─────────────────────────────────────────────────────────
+
+function memoryGc(agentDest) {
+  const lockPath = acquireLock(agentDest);
+  try {
+    const index = loadIndex(agentDest);
+    const before = index.entries.length;
+
+    let workingRemoved = 0;
+    let episodicRemoved = 0;
+
+    index.entries = index.entries.filter(e => {
+      if (e.memory_type === 'working') {
+        workingRemoved++;
+        return false;
+      }
+      if (e.memory_type === 'episodic' && daysSince(e.created_at) >= EPISODIC_TTL_DAYS) {
+        episodicRemoved++;
+        return false;
+      }
+      return true;
+    });
+
+    saveIndex(agentDest, index);
+    generateProjection(agentDest, index);
+
+    return {
+      working_removed: workingRemoved,
+      episodic_removed: episodicRemoved,
+      before,
+      after: index.entries.length,
+    };
+  } finally {
+    releaseLock(lockPath);
+  }
+}
+
+// ── Stats ───────────────────────────────────────────────────────────────────
+
+function memoryStats(agentDest) {
+  const index = loadIndex(agentDest);
+  const total = index.entries.length;
+  const semantic = index.entries.filter(e => e.memory_type === 'semantic').length;
+  const procedural = index.entries.filter(e => e.memory_type === 'procedural').length;
+  const episodic = index.entries.filter(e => e.memory_type === 'episodic').length;
+  const working = index.entries.filter(e => e.memory_type === 'working').length;
+  const totalTokens = index.entries.reduce((sum, e) => sum + (e.token_estimate || 0), 0);
+  return {
+    total,
+    semantic,
+    procedural,
+    episodic,
+    working,
+    total_tokens: totalTokens,
+    capacity: MAX_ENTRIES,
+  };
+}
+
+// ── Projection Generator ───────────────────────────────────────────────────
+
+function generateProjection(agentDest, index) {
+  if (!index) index = loadIndex(agentDest);
+
+  let md = '# 🧠 Tribunal Memory Index\n';
+  md += '> Auto-generated by `tribunal-kit memory export`. Do not edit manually.\n';
+
+  const sem = index.entries.filter(e => e.memory_type === 'semantic');
+  const proc = index.entries.filter(e => e.memory_type === 'procedural');
+  const ep = index.entries.filter(e => e.memory_type === 'episodic');
+  const work = index.entries.filter(e => e.memory_type === 'working');
+
+  md += `> Entries: ${index.entries.length} | Semantic: ${sem.length} | Procedural: ${proc.length} | Episodic: ${ep.length} | Working: ${work.length}\n\n`;
+
+  if (sem.length > 0) {
+    md += '## SEMANTIC (Permanent Facts)\n';
+    md += '| ID | Content | Tags | Source | Created |\n';
+    md += '|----|---------|------|--------|---------|\n';
+    for (const e of sem) {
+      md += `| ${e.id} | ${e.content.replace(/\|/g, '\\|')} | ${e.tags.join(', ')} | ${e.source} | ${e.created_at} |\n`;
+    }
+    md += '\n';
+  }
+
+  if (proc.length > 0) {
+    md += '## PROCEDURAL (How-To Recipes)\n';
+    md += '| ID | Content | Tags | Source | Created |\n';
+    md += '|----|---------|------|--------|---------|\n';
+    for (const e of proc) {
+      md += `| ${e.id} | ${e.content.replace(/\|/g, '\\|')} | ${e.tags.join(', ')} | ${e.source} | ${e.created_at} |\n`;
+    }
+    md += '\n';
+  }
+
+  if (ep.length > 0) {
+    md += '## EPISODIC (Session History — auto-decays after 30 days)\n';
+    md += '| ID | Content | Tags | Source | Created | Days Remaining |\n';
+    md += '|----|---------|------|--------|---------|----------------|\n';
+    for (const e of ep) {
+      const remaining = Math.max(0, EPISODIC_TTL_DAYS - daysSince(e.created_at));
+      md += `| ${e.id} | ${e.content.replace(/\|/g, '\\|')} | ${e.tags.join(', ')} | ${e.source} | ${e.created_at} | ${remaining} |\n`;
+    }
+    md += '\n';
+  }
+
+  if (work.length > 0) {
+    md += '## WORKING (Current Session — cleared on GC)\n';
+    md += '| ID | Content | Tags | Session |\n';
+    md += '|----|---------|------|---------|\n';
+    for (const e of work) {
+      md += `| ${e.id} | ${e.content.replace(/\|/g, '\\|')} | ${e.tags.join(', ')} | ${e.session_id || '—'} |\n`;
+    }
+    md += '\n';
+  }
+
+  if (index.entries.length === 0) {
+    md += '*No memories recorded yet. Run `tk memory store` to add your first memory.*\n';
+  }
+
+  const projPath = getProjectionPath(agentDest);
+  fs_1.default.mkdirSync(path_1.default.dirname(projPath), { recursive: true });
+  fs_1.default.writeFileSync(projPath, md, 'utf8');
+
+  return projPath;
+}
+
+// ── CLI Router ──────────────────────────────────────────────────────────────
+
+async function cmdMemory(flags, processArgs, quiet = false) {
+  const targetDir = flags.path ? path_1.default.resolve(flags.path) : process.cwd();
+  const agentDest = path_1.default.join(targetDir, '.agent');
+
+  if (!fs_1.default.existsSync(agentDest)) {
+    (0, logger_1.err)('.agent/ not found. Run: npx tribunal-kit init');
+    process.exit(1);
+  }
+
+  const args = processArgs.slice(3);
+  const subcommand = args[0];
+
+  if (!subcommand || subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+    (0, helpers_1.banner)(quiet);
+    const W = 62;
+    const title = '  Tribunal Memory — 4-Type Taxonomy Engine';
+    const trail = ' '.repeat(Math.max(0, W - title.length));
+    console.log(`  ${(0, logger_1.c)('cyan', '\u2554' + '\u2550'.repeat(W) + '\u2557')}`);
+    console.log(
+      `  ${(0, logger_1.c)('cyan', '\u2551')}${(0, logger_1.bold)((0, logger_1.c)('white', title))}${trail}${(0, logger_1.c)('cyan', '\u2551')}`,
+    );
+    console.log(`  ${(0, logger_1.c)('cyan', '\u255a' + '\u2550'.repeat(W) + '\u255d')}`);
+    console.log();
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('cyan', 'store'.padEnd(10))}  ${(0, logger_1.c)('gray', 'Store a new memory entry')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('cyan', 'recall'.padEnd(10))}  ${(0, logger_1.c)('gray', 'Budget-constrained memory recall')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('cyan', 'gc'.padEnd(10))}  ${(0, logger_1.c)('gray', 'Garbage collect expired/working memories')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('cyan', 'stats'.padEnd(10))}  ${(0, logger_1.c)('gray', 'Show memory index statistics')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('cyan', 'export'.padEnd(10))}  ${(0, logger_1.c)('gray', 'Export MEMORY.md projection')}`,
+    );
+    console.log();
+    (0, logger_1.log)((0, logger_1.bold)('  Memory Types'));
+    (0, logger_1.log)(`  ${(0, logger_1.c)('gray', '─'.repeat(40))}`);
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('green', 'semantic'.padEnd(14))}  ${(0, logger_1.c)('gray', 'Permanent project facts & rules')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('green', 'procedural'.padEnd(14))}  ${(0, logger_1.c)('gray', 'How-to recipes & build steps')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('yellow', 'episodic'.padEnd(14))}  ${(0, logger_1.c)('gray', 'Session events (30-day TTL)')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('yellow', 'working'.padEnd(14))}  ${(0, logger_1.c)('gray', 'Scratch memory (cleared on GC)')}`,
+    );
+    console.log();
+    (0, logger_1.log)((0, logger_1.bold)('  Examples'));
+    (0, logger_1.log)(`  ${(0, logger_1.c)('gray', '─'.repeat(40))}`);
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('gray', '▸')} ${(0, logger_1.c)('white', 'tk memory store --type semantic --content "Uses PostgreSQL" --tags db,orm')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('gray', '▸')} ${(0, logger_1.c)('white', 'tk memory recall --query "database" --budget 2000')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('gray', '▸')} ${(0, logger_1.c)('white', 'tk memory gc')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('gray', '▸')} ${(0, logger_1.c)('white', 'tk memory stats')}`,
+    );
+    (0, logger_1.log)(
+      `  ${(0, logger_1.c)('gray', '▸')} ${(0, logger_1.c)('white', 'tk memory export')}`,
+    );
+    console.log();
+    process.exit(0);
+  }
+
+  // Parse flags from remaining args
+  function getFlag(name) {
+    const idx = args.indexOf(`--${name}`);
+    if (idx === -1) return null;
+    return args[idx + 1] || null;
+  }
+
+  try {
+    switch (subcommand) {
+      case 'store': {
+        const type = getFlag('type');
+        const content = getFlag('content');
+        const tagsRaw = getFlag('tags') || '';
+        const sessionId = getFlag('session-id');
+        if (!type || !content) {
+          (0, logger_1.err)(
+            'Usage: tk memory store --type <type> --content "<text>" [--tags tag1,tag2]',
+          );
+          process.exit(1);
+        }
+        const tags = tagsRaw
+          .split(',')
+          .map(t => t.trim())
+          .filter(t => t.length > 0);
+        const result = memoryStore(agentDest, type, content, tags, sessionId);
+        if (!quiet) {
+          (0, logger_1.log)(
+            `  ${(0, logger_1.c)('green', '✔')} ${(0, logger_1.bold)('Memory stored')} #${result.id} (${type})`,
+          );
+          (0, logger_1.log)(
+            `    ${(0, logger_1.c)('gray', '▶')} ${(0, logger_1.c)('gray', content)}`,
+          );
+          if (tags.length > 0) {
+            (0, logger_1.log)(
+              `    ${(0, logger_1.c)('gray', '▶')} Tags: ${(0, logger_1.c)('gray', tags.join(', '))}`,
+            );
+          }
+          (0, logger_1.log)(`    ${(0, logger_1.c)('gray', '▶')} ~${result.token_estimate} tokens`);
+        }
+        break;
+      }
+
+      case 'recall': {
+        const query = getFlag('query');
+        const budgetStr = getFlag('budget');
+        const budget = budgetStr ? parseInt(budgetStr, 10) : 2000;
+        if (!query) {
+          (0, logger_1.err)('Usage: tk memory recall --query "<search>" [--budget 2000]');
+          process.exit(1);
+        }
+        const { results, tokens_used } = memoryRecall(agentDest, query, budget);
+        if (!quiet) {
+          if (results.length === 0) {
+            (0, logger_1.log)(
+              `  ${(0, logger_1.c)('yellow', '⚠')} No memories match query: "${query}"`,
+            );
+          } else {
+            (0, logger_1.log)(
+              `  ${(0, logger_1.c)('green', '✔')} ${results.length} memories recalled (budget: ${budget} tokens)`,
+            );
+            for (const entry of results) {
+              const typeLabel = entry.memory_type.toUpperCase();
+              (0, logger_1.log)(
+                `    ${(0, logger_1.c)('gray', '▶')} [${(0, logger_1.c)('cyan', typeLabel)}] #${entry.id}: ${entry.content} ${(0, logger_1.c)('gray', `(score: ${entry.score.toFixed(2)}, ~${entry.token_estimate}tok)`)}`,
+              );
+            }
+            (0, logger_1.log)(
+              `    ${(0, logger_1.c)('gray', '▶')} Total: ~${tokens_used} tokens used of ${budget} budget`,
+            );
+          }
+        }
+        // Machine output for agent consumption
+        console.log(
+          JSON.stringify({
+            action: 'recall',
+            query,
+            budget,
+            tokens_used,
+            count: results.length,
+            entries: results.map(e => ({
+              id: e.id,
+              memory_type: e.memory_type,
+              content: e.content,
+              tags: e.tags,
+              score: e.score,
+              token_estimate: e.token_estimate,
+            })),
+          }),
+        );
+        break;
+      }
+
+      case 'gc': {
+        const result = memoryGc(agentDest);
+        if (!quiet) {
+          (0, logger_1.log)(
+            `  ${(0, logger_1.c)('green', '✔')} ${(0, logger_1.bold)('Garbage collection complete')}`,
+          );
+          (0, logger_1.log)(
+            `    ${(0, logger_1.c)('gray', '▶')} Working removed: ${result.working_removed}`,
+          );
+          (0, logger_1.log)(
+            `    ${(0, logger_1.c)('gray', '▶')} Episodic expired: ${result.episodic_removed}`,
+          );
+          (0, logger_1.log)(
+            `    ${(0, logger_1.c)('gray', '▶')} Entries: ${result.before} → ${result.after}`,
+          );
+        }
+        break;
+      }
+
+      case 'stats': {
+        const stats = memoryStats(agentDest);
+        if (!quiet) {
+          (0, logger_1.log)(`\n  🧠  ${(0, logger_1.bold)('Tribunal Memory Index')}`);
+          (0, logger_1.log)(`    ${(0, logger_1.c)('gray', '▶')} Total entries:  ${stats.total}`);
+          (0, logger_1.log)(
+            `    ${(0, logger_1.c)('gray', '▶')} Semantic:       ${stats.semantic} (permanent)`,
+          );
+          (0, logger_1.log)(
+            `    ${(0, logger_1.c)('gray', '▶')} Procedural:     ${stats.procedural} (permanent)`,
+          );
+          (0, logger_1.log)(
+            `    ${(0, logger_1.c)('gray', '▶')} Episodic:       ${stats.episodic} (30-day TTL)`,
+          );
+          (0, logger_1.log)(
+            `    ${(0, logger_1.c)('gray', '▶')} Working:        ${stats.working} (session-scoped)`,
+          );
+          (0, logger_1.log)(
+            `    ${(0, logger_1.c)('gray', '▶')} Token budget:   ~${stats.total_tokens} tokens indexed`,
+          );
+          (0, logger_1.log)(
+            `    ${(0, logger_1.c)('gray', '▶')} Capacity:       ${stats.total}/${stats.capacity}\n`,
+          );
+        }
+        break;
+      }
+
+      case 'export': {
+        const projPath = generateProjection(agentDest);
+        if (!quiet) {
+          (0, logger_1.log)(
+            `  ${(0, logger_1.c)('green', '✔')} ${(0, logger_1.bold)('MEMORY.md exported')} → ${projPath}`,
+          );
+        }
+        break;
+      }
+
+      default:
+        (0, logger_1.err)(`Unknown memory subcommand: "${subcommand}"`);
+        (0, logger_1.log)('  Run: tk memory --help');
+        process.exit(1);
+    }
+  } catch (e) {
+    (0, logger_1.err)(e.message || String(e));
+    process.exit(1);
+  }
+}
+
+// Export internal functions for MCP server and learn/case integration
+exports._memoryStore = memoryStore;
+exports._memoryRecall = memoryRecall;
+exports._memoryGc = memoryGc;
+exports._memoryStats = memoryStats;
+exports._generateProjection = generateProjection;