total-recall-brain 3.1.0

package/src/cli/share.mjs

@@ -0,0 +1,180 @@
+import crypto from 'node:crypto';
+import { parseLayerFlag, resolveBrainDir, getBothBrains, defaultLayerForCategory } from './agent-dir.mjs';
+import { writeNode, createMemoryNode } from '../core/vault.mjs';
+import { addToQueue } from '../core/research-queue.mjs';
+import { compileSurface } from '../core/surface.mjs';
+import path from 'node:path';
+
+function printHelp() {
+  console.log(`
+  total-recall share — Share a URL or text snippet to the brain
+
+  Usage: total-recall share [url] [options]
+
+  Arguments:
+    url                     URL to share (optional if --text is provided)
+
+  Options:
+    --text, -x <text>       Text excerpt to remember
+    --action, -a <action>   remember | research | auto (default: auto)
+    --tags, -t <comma-list> Comma-separated tags
+    --brain, -b <brainId>   Target brain ID
+    --title <title>         Custom title for the memory node
+    --global                Save to global brain
+    --project               Save to project brain
+
+  Auto-routing heuristic (when action is 'auto'):
+    - URL + no text         → queues research project
+    - Text < 500 chars      → saves as fact
+    - Text >= 500 chars     → saves as concept
+    - URL + text            → saves as fact/concept with URL citation
+
+  Examples:
+    npx total-recall share "https://example.com"
+    npx total-recall share "https://example.com" --text "Key insight from the article"
+    npx total-recall share --text "Important fact to remember" --tags "work,notes"
+    npx total-recall share "https://example.com" --action research
+`);
+}
+
+/**
+ * Resolve the effective action from the auto-routing heuristic.
+ */
+function resolveAction({ url, text, action }) {
+  if (action && action !== 'auto') {
+    if (action === 'remember') {
+      const category = text && text.length >= 500 ? 'concepts' : 'facts';
+      return { action: 'remember', category };
+    }
+    return { action, category: null };
+  }
+
+  if (url && !text) {
+    return { action: 'research', category: null };
+  }
+  if (text && text.length >= 500) {
+    return { action: 'remember', category: 'concepts' };
+  }
+  if (text) {
+    return { action: 'remember', category: 'facts' };
+  }
+  if (url) {
+    return { action: 'research', category: null };
+  }
+  return { action: 'remember', category: 'facts' };
+}
+
+export default async function share(args) {
+  const { layer: explicitLayer, remainingArgs } = parseLayerFlag(args);
+
+  // Parse positional URL and options
+  let url = null;
+  let text = null;
+  let action = 'auto';
+  let tags = [];
+  let brainId = null;
+  let title = null;
+
+  for (let i = 0; i < remainingArgs.length; i++) {
+    const arg = remainingArgs[i];
+    const val = remainingArgs[i + 1];
+
+    if (arg === '--help' || arg === '-h') {
+      printHelp();
+      return;
+    } else if (arg === '--text' || arg === '-x') {
+      if (val) { text = val; i++; }
+    } else if (arg === '--action' || arg === '-a') {
+      if (val) { action = val.toLowerCase(); i++; }
+    } else if (arg === '--tags' || arg === '-t') {
+      if (val) { tags = val.split(',').map(t => t.trim()); i++; }
+    } else if (arg === '--brain' || arg === '-b') {
+      if (val) { brainId = val; i++; }
+    } else if (arg === '--title') {
+      if (val) { title = val; i++; }
+    } else if (!arg.startsWith('-') && !url) {
+      // First positional arg is the URL
+      url = arg;
+    }
+  }
+
+  if (!url && !text) {
+    printHelp();
+    return;
+  }
+
+  const { action: resolvedAction, category } = resolveAction({ url, text, action });
+
+  if (resolvedAction === 'research') {
+    const topic = title || url || 'Untitled research';
+    const item = addToQueue({
+      topic,
+      priority: 'medium',
+      notes: text || '',
+    });
+    console.log(`  ✅ Queued research: "${topic}" (id: ${item.id})`);
+    return;
+  }
+
+  // action === 'remember'
+  let layer = explicitLayer;
+  if (layer === 'auto') {
+    layer = defaultLayerForCategory(category || 'facts');
+    const project = getBothBrains().project;
+    if (layer === 'project' && !project) {
+      layer = 'global';
+    }
+  }
+
+  const resolvedBrainDir = resolveBrainDir(layer);
+  const vaultDir = path.join(resolvedBrainDir, 'memory-vault');
+  const skillsDir = path.join(resolvedBrainDir, '..', '..');
+  const derivedDir = path.join(resolvedBrainDir, 'memory-derived');
+  const instructionsFile = path.join(skillsDir, '..', 'INSTRUCTIONS.md');
+
+  const slugBase = category || 'facts';
+  const slug = `${slugBase}-${crypto.randomBytes(4).toString('hex')}`;
+  const nodeTitle = title || (text ? text.slice(0, 80) : url || 'Untitled share');
+
+  const node = createMemoryNode({
+    slug,
+    title: nodeTitle,
+    category: category || 'facts',
+    content: text || url || '',
+  });
+
+  node.source.type = 'share-cli';
+
+  if (tags.length > 0) {
+    node.tags = tags;
+  }
+
+  if (url) {
+    node.x_citations = [{
+      url,
+      title: title || url,
+      source: 'share-to-brain',
+      published: node.created,
+      relevance: 1.0,
+      accessed: node.created,
+    }];
+  }
+
+  writeNode(node, vaultDir);
+  const layerLabel = layer === 'project' ? '[project]' : '[global]';
+  console.log(`  ✅ Saved as ${category || 'facts'} ${layerLabel}: ${category || 'facts'}/${slug}.md`);
+
+  // Recompile surfaces
+  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/skill.mjs

@@ -0,0 +1,313 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+// Helper to resolve agent directories dynamically
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '../../');
+const agentDir = path.join(ROOT, '.agent');
+const skillsDir = path.join(agentDir, 'skills');
+
+// Direct dynamic imports for scripts layer to preserve environment paths
+const scriptsPath = path.join(agentDir, 'skills', 'total-recall', 'skills', 'skill', 'scripts');
+
+function printHelp() {
+  console.log(`
+  total-recall skill — Sovereign AI Capability Registry & Manager
+
+  Usage: total-recall skill <command> [options]
+
+  Commands:
+    find <query>          Search skills.sh registry sorted by absolute installs rating
+    install <package>     Download/load a skill, run static security audit, and compile shims (alias: load, add)
+    create <name>         Scaffold a new SSSS-compliant skill folder structure (alias: new)
+    edit <name>           Open the local skill's SKILL.md file in your preferred editor
+    scan <name>           Run security audit scan on an installed local skill directory
+    list                  List all locally active parent skills and nested sub-skills (alias: ls)
+    remove <name>         Safely delete a skill package and hot-recompile shims (alias: rm)
+
+  Options:
+    --help, -h            Show this help menu
+  
+  Examples:
+    npx total-recall skill find git
+    npx total-recall skill load github/awesome-copilot@prd
+    npx total-recall skill create my-awesome-skill
+    npx total-recall skill edit my-awesome-skill
+    npx total-recall skill scan total-recall
+`);
+}
+
+export default async function skillCli(args) {
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return;
+  }
+
+  const command = args[0];
+
+  if (command === 'find') {
+    const query = args[1];
+    if (!query) {
+      console.error('❌ You must provide a search query.');
+      console.error('Usage: npx total-recall skill find <query>');
+      process.exit(1);
+    }
+
+    try {
+      const { searchAndSort } = await import('../../.agent/skills/total-recall/skills/skill/scripts/find-skills.mjs');
+      const results = searchAndSort(query);
+      
+      if (results.length === 0) {
+        console.log('\nℹ️  No matching skills found on skills.sh.');
+        return;
+      }
+
+      console.log('\n✨ --- SKILLS.SH REGISTRY SEARCH RESULTS (Sorted by Installs) --- ✨\n');
+      
+      const nameHeader = 'SKILL PACKAGE';
+      const installsHeader = 'INSTALLS';
+      const urlHeader = 'REGISTRY URL';
+      
+      let maxNameLen = nameHeader.length;
+      let maxInstallsLen = installsHeader.length;
+
+      for (const r of results) {
+        if (r.name.length > maxNameLen) maxNameLen = r.name.length;
+        if (r.installsStr.length > maxInstallsLen) maxInstallsLen = r.installsStr.length;
+      }
+
+      const divider = '-'.repeat(maxNameLen + maxInstallsLen + 35);
+      console.log(divider);
+      console.log(
+        `${nameHeader.padEnd(maxNameLen)}   | ${installsHeader.padEnd(maxInstallsLen)}   | ${urlHeader}`
+      );
+      console.log(divider);
+
+      for (const r of results) {
+        console.log(
+          `${r.name.padEnd(maxNameLen)}   | ${r.installsStr.padEnd(maxInstallsLen)}   | ${r.url}`
+        );
+      }
+
+      console.log(divider);
+      console.log(`💡 Tip: To install any skill, run: npx total-recall skill install <package-name>\n`);
+    } catch (err) {
+      console.error('❌ Error executing search:', err.message);
+      process.exit(1);
+    }
+  } 
+  
+  else if (command === 'install' || command === 'add' || command === 'load') {
+    const pkg = args[1];
+    if (!pkg) {
+      console.error('❌ You must provide a skill package to load.');
+      console.error('Usage: npx total-recall skill load <owner/repo@skill>');
+      process.exit(1);
+    }
+
+    try {
+      const { installSkill } = await import('../../.agent/skills/total-recall/skills/skill/scripts/install-skill.mjs');
+      const res = installSkill(pkg);
+      if (!res.success) {
+        process.exit(1);
+      }
+    } catch (err) {
+      console.error('❌ Loading skill failed:', err.message);
+      process.exit(1);
+    }
+  } 
+  
+  else if (command === 'scan') {
+    const target = args[1];
+    if (!target) {
+      console.error('❌ You must specify a local skill directory to scan.');
+      console.error('Usage: npx total-recall skill scan <skill-name>');
+      process.exit(1);
+    }
+
+    const targetDir = path.resolve(skillsDir, target);
+
+    try {
+      const { runScan } = await import('../../.agent/skills/total-recall/skills/skill/scripts/scan-skill.mjs');
+      const result = runScan(targetDir);
+      process.exit(result.success ? 0 : 1);
+    } catch (err) {
+      console.error('❌ Audit execution failed:', err.message);
+      process.exit(1);
+    }
+  } 
+  
+  else if (command === 'list' || command === 'ls') {
+    if (!fs.existsSync(skillsDir)) {
+      console.log('No skills registry directory initialized yet.');
+      return;
+    }
+
+    const dirs = fs.readdirSync(skillsDir).filter(d => 
+      fs.statSync(path.join(skillsDir, d)).isDirectory()
+    );
+
+    if (dirs.length === 0) {
+      console.log('No installed skills found in the active brain.');
+      return;
+    }
+
+    console.log('\n📦 Installed Sovereign Skills:');
+    console.log('------------------------------------------------------------');
+    for (const d of dirs) {
+      const skillPath = path.join(skillsDir, d);
+      const subSkillsPath = path.join(skillPath, 'skills');
+      let subSkills = [];
+
+      if (fs.existsSync(subSkillsPath) && fs.statSync(subSkillsPath).isDirectory()) {
+        subSkills = fs.readdirSync(subSkillsPath).filter(sd => 
+          fs.statSync(path.join(subSkillsPath, sd)).isDirectory()
+        );
+      }
+
+      console.log(` • ${d.padEnd(20)} [Universal Skill Package]`);
+      if (subSkills.length > 0) {
+        console.log(`   └ Sub-skills: ${subSkills.map(s => `🧩 ${s}`).join(', ')}`);
+      }
+    }
+    console.log('------------------------------------------------------------\n');
+  } 
+  
+  else if (command === 'remove' || command === 'rm') {
+    const target = args[1];
+    if (!target) {
+      console.error('❌ You must specify a skill name to remove.');
+      console.error('Usage: npx total-recall skill remove <skill-name>');
+      process.exit(1);
+    }
+
+    const targetDir = path.join(skillsDir, target);
+    if (!fs.existsSync(targetDir)) {
+      console.error(`❌ Skill "${target}" not found at ${targetDir}`);
+      process.exit(1);
+    }
+
+    console.log(`🗑️  Removing skill "${target}"...`);
+    fs.rmSync(targetDir, { recursive: true, force: true });
+    console.log('✅ Skill files deleted successfully.');
+
+    // Hot-recompile shims to strip the removed rules
+    console.log('🔄 Hot-recompiling active shims to reflect changes...');
+    const child = spawnSync('npx', ['total-recall', 'compile'], { 
+      encoding: 'utf8',
+      cwd: ROOT
+    });
+
+    if (child.error || child.status !== 0) {
+      console.warn('⚠️  Shim hot-recompilation returned warning.');
+    } else {
+      console.log('🚀 Hot-recompilation successful. Skill is fully offline.');
+    }
+  } 
+  
+  else if (command === 'create' || command === 'new') {
+    const target = args[1];
+    if (!target) {
+      console.error('❌ You must specify a skill name to create.');
+      console.error('Usage: npx total-recall skill create <skill-name>');
+      process.exit(1);
+    }
+
+    if (!/^[a-z][a-z0-9-]{1,63}$/.test(target)) {
+      console.error('❌ Invalid skill name. Must be lowercase kebab-case (e.g. my-awesome-skill).');
+      process.exit(1);
+    }
+
+    const newSkillDir = path.join(skillsDir, target);
+    if (fs.existsSync(newSkillDir)) {
+      console.error(`❌ Skill directory already exists: ${newSkillDir}`);
+      process.exit(1);
+    }
+
+    console.log(`📁 Scaffolding skill folder structure for "${target}"...`);
+    fs.mkdirSync(newSkillDir, { recursive: true });
+    
+    const folders = ['scripts', 'references', 'evals', 'subagents'];
+    for (const f of folders) {
+      fs.mkdirSync(path.join(newSkillDir, f), { recursive: true });
+      fs.writeFileSync(path.join(newSkillDir, f, '.gitkeep'), '', 'utf8');
+    }
+
+    // Write template SKILL.md
+    const skillMdContent = `---
+type: skill
+name: ${target}
+description: "Use this skill when [TRIGGER CONDITION]. MANDATORY: You MUST read the full SKILL.md file before executing."
+schema_version: 2
+---
+
+# ${target.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ')} Skill
+
+Provide a high-level explanation of the skill's capabilities and context.
+
+## Core Directives
+
+1. Step-by-step procedural instruction
+2. Concrete action rule
+3. Pitfalls to avoid
+
+## References
+
+* Core specifications or API documentation
+`;
+    fs.writeFileSync(path.join(newSkillDir, 'SKILL.md'), skillMdContent, 'utf8');
+
+    // Write template evals.json
+    const evalsJsonContent = [
+      {
+        "name": "frontmatter-has-name",
+        "assertion": "SKILL.md YAML frontmatter contains a 'name' field",
+        "severity": "error"
+      },
+      {
+        "name": "description-is-trigger-optimized",
+        "assertion": "description field starts with 'Use this skill when'",
+        "severity": "warning"
+      },
+      {
+        "name": "no-empty-directories",
+        "assertion": "All required directories contain at least one non-.gitkeep file",
+        "severity": "error"
+      }
+    ];
+    fs.writeFileSync(path.join(newSkillDir, 'evals', 'evals.json'), JSON.stringify(evalsJsonContent, null, 2), 'utf8');
+
+    console.log(`✨ Skill "${target}" successfully created and SSSS-scaffolded!`);
+    console.log(`📍 Path: ${newSkillDir}`);
+    console.log(`💡 Next steps: edit the SKILL.md and add your automation scripts!`);
+  }
+
+  else if (command === 'edit') {
+    const target = args[1];
+    if (!target) {
+      console.error('❌ You must specify a skill name to edit.');
+      console.error('Usage: npx total-recall skill edit <skill-name>');
+      process.exit(1);
+    }
+
+    const skillPath = path.join(skillsDir, target, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) {
+      console.error(`❌ Skill "${target}" not found at ${skillPath}`);
+      process.exit(1);
+    }
+
+    const editor = process.env.EDITOR || 'vi';
+    console.log(`📝 Opening skill "${target}" in ${editor}...`);
+    const { spawnSync: ss } = await import('node:child_process');
+    const child = ss(editor, [skillPath], { stdio: 'inherit' });
+    process.exit(child.status || 0);
+  }
+
+  else {
+    console.error(`❌ Unknown skill command: ${command}`);
+    printHelp();
+    process.exit(1);
+  }
+}

package/src/cli/snapshot.mjs

@@ -0,0 +1,108 @@
+import { createSnapshot, listSnapshots, rollbackVault } from '../core/snapshot.mjs';
+import { resolveAgentDir, resolveBrainDir } from './agent-dir.mjs';
+import { compileSurface } from '../core/surface.mjs';
+import path from 'path';
+
+/**
+ * total-recall snapshot [command]
+ *
+ * Commands:
+ *   create [reason]    Create a new point-in-time snapshot of the vault
+ *   list               List all available snapshots
+ *   rollback <id>      Restore the vault to a specific snapshot
+ */
+
+function printHelp() {
+  console.log(`
+  total-recall snapshot — VFS Point-in-Time Recovery
+
+  Usage: total-recall snapshot <command> [options]
+
+  Commands:
+    create [reason]    Create a fast local snapshot of the memory-vault
+    list               List all available snapshots
+    rollback <id>      Restore the vault to a specific snapshot ID
+
+  Options:
+    --help, -h         Show this help
+`);
+}
+
+export default async function snapshotCli(args) {
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return;
+  }
+
+  const command = args[0];
+
+  if (command === 'create') {
+    const reason = args.slice(1).join(' ') || 'manual';
+    console.log('📸 Creating snapshot...');
+    const result = createSnapshot(reason);
+    if (result.success) {
+      console.log(`✅ Snapshot created successfully!`);
+      console.log(`   ID:     ${result.snapshot_id}`);
+      console.log(`   Path:   ${result.path}`);
+      console.log(`   Reason: ${reason}`);
+    } else {
+      console.error(`❌ Failed to create snapshot: ${result.error}`);
+      process.exit(1);
+    }
+  } 
+  
+  else if (command === 'list') {
+    const snaps = listSnapshots();
+    if (snaps.length === 0) {
+      console.log('No snapshots found.');
+      return;
+    }
+    console.log('📸 Available Snapshots:');
+    console.log('------------------------------------------------------------');
+    for (const snap of snaps) {
+      const date = new Date(snap.created_at).toLocaleString();
+      console.log(`ID:      ${snap.snapshot_id}`);
+      console.log(`Date:    ${date}`);
+      console.log(`Reason:  ${snap.reason}`);
+      console.log('------------------------------------------------------------');
+    }
+  }
+
+  else if (command === 'rollback') {
+    const id = args[1];
+    if (!id) {
+      console.error('❌ You must provide a snapshot ID to rollback to.');
+      console.error('Usage: total-recall snapshot rollback <id>');
+      process.exit(1);
+    }
+
+    console.log(`⚠️  Rolling back memory-vault to snapshot: ${id}`);
+    console.log(`   (A pre-rollback safety snapshot will be created automatically)`);
+    
+    const result = rollbackVault(id);
+    if (result.success) {
+      console.log(`✅ Rollback successful.`);
+      console.log(`🔄 Recompiling derived indexes from restored vault...`);
+      
+      const agentDir = resolveAgentDir();
+      const brainDir = resolveBrainDir();
+      await compileSurface({
+        vaultDir: path.join(brainDir, 'memory-vault'),
+        skillsDir: path.join(agentDir, 'skills'),
+        derivedDir: path.join(brainDir, 'memory-derived'),
+        instructionsFile: path.join(agentDir, 'INSTRUCTIONS.md')
+      });
+      
+      console.log(`✅ Vault restoration and projection rebuild complete.`);
+    } else {
+      console.error(`❌ Rollback failed: ${result.error}`);
+      process.exit(1);
+    }
+  }
+
+  else {
+    console.error(`❌ Unknown snapshot command: ${command}`);
+    printHelp();
+    process.exit(1);
+  }
+}

package/src/cli/start.mjs

@@ -0,0 +1,63 @@
+/**
+ * total-recall start
+ *
+ * Start the brain server in the foreground.
+ * This is the same as running `node src/server/index.mjs` but works correctly
+ * regardless of install method (npx, global npm, local clone).
+ *
+ * Usage:
+ *   npx total-recall start [--port 3000] [--host 127.0.0.1]
+ */
+
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { port as configPort, host as configHost, nodeEnv } from '../core/config.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SERVER = path.join(__dirname, '..', 'server', 'index.mjs');
+
+export default function start(args) {
+  const port = (() => {
+    const i = args.indexOf('--port');
+    return i !== -1 ? args[i + 1] : String(configPort);
+  })();
+  const host = (() => {
+    const i = args.indexOf('--host');
+    return i !== -1 ? args[i + 1] : configHost;
+  })();
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+  total-recall start — Start the brain server
+
+  Usage: total-recall start [options]
+
+  Options:
+    --port <port>    Port to listen on (default: 3000, or \$PORT)
+    --host <host>    Host to bind to  (default: 127.0.0.1, or \$HOST)
+    --help           Show this help
+
+  The server reads config from ~/.agent/config/security.yml.
+  Use Cloudflare or Caddy in front for HTTPS when accessing remotely.
+`);
+    return;
+  }
+
+  console.log(`  ⚡ Starting Total Recall brain server on ${host}:${port}`);
+  console.log(`  Press Ctrl+C to stop.\n`);
+
+  const result = spawnSync(process.execPath, [SERVER], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      PORT: port,
+      HOST: host,
+      NODE_ENV: nodeEnv,
+    },
+  });
+
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}