total-recall-brain 3.1.0

package/src/cli/backup.mjs

@@ -0,0 +1,313 @@
+/**
+ * total-recall backup
+ *
+ * Back up the meta-skill folder (the user's brain) to:
+ *   - GitHub repo (diff-based, sovereign)
+ *   - Encrypted/plain tarball
+ *   - Obsidian vault (rsync)
+ *
+ * The meta-skill at .agent/skills/total-recall/ IS the brain — it contains
+ * rules, knowledge, preferences, corrections, research, integrations,
+ * automations, sub-skills, and scripts. Everything else is derived/runtime.
+ *
+ * Usage:
+ *   npx total-recall backup [--output <path>] [--no-encrypt]
+ *   npx total-recall backup --push-git <remote-url>
+ *   npx total-recall backup --obsidian <path>
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { resolveAgentDir, resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
+
+/** The meta-skill folder — this is what gets backed up */
+function getSkillDir(layer = 'auto') {
+  return resolveBrainDir(layer);
+}
+
+function commandExists(cmd) {
+  const r = spawnSync('which', [cmd], { stdio: 'pipe' });
+  return r.status === 0;
+}
+
+function parseArgs(args) {
+  // Parse layer flag first
+  const { layer, remainingArgs } = parseLayerFlag(args);
+  const opts = { output: null, encrypt: true, pushGit: null, obsidian: null, help: false, layer };
+  for (let i = 0; i < remainingArgs.length; i++) {
+    switch (remainingArgs[i]) {
+      case '--output':
+      case '-o':
+        opts.output = remainingArgs[++i];
+        break;
+      case '--no-encrypt':
+        opts.encrypt = false;
+        break;
+      case '--push-git':
+        opts.pushGit = remainingArgs[++i];
+        break;
+      case '--obsidian':
+        opts.obsidian = remainingArgs[++i];
+        break;
+      case '--help':
+      case '-h':
+        opts.help = true;
+        break;
+    }
+  }
+  return opts;
+}
+
+function git(cwd, ...gitArgs) {
+  const result = spawnSync('git', gitArgs, { cwd, stdio: 'pipe' });
+  return {
+    ok: result.status === 0,
+    stdout: result.stdout?.toString().trim() || '',
+    stderr: result.stderr?.toString().trim() || '',
+  };
+}
+
+function defaultOutput(encrypt) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const suffix = encrypt ? '.tar.gz.gpg' : '.tar.gz';
+  return path.join(os.homedir(), `total-recall-backup-${stamp}${suffix}`);
+}
+
+function shellDoubleQuote(value) {
+  return `"${String(value).replace(/(["\\$`])/g, '\\$1')}"`;
+}
+
+function printHelp() {
+  console.log(`
+  total-recall backup — Back up the meta-skill (your brain)
+
+  Usage: total-recall backup [options]
+
+  Options:
+    --output, -o <path>    Destination archive path (tarball mode)
+    --no-encrypt           Write a plain .tar.gz archive (default: gpg-encrypted)
+    --push-git <remote>    Commit brain to a git remote (sovereign, diff-based)
+                           e.g. git@github.com:you/total-recall-brain.git
+                           Initialises the skill folder as a git repo on first run.
+    --obsidian <path>      Rsync brain snapshot into an Obsidian vault folder.
+                           e.g. ~/Documents/Obsidian Vault
+                           Creates/updates "Total Recall/" inside that vault.
+                           Pair with Obsidian Sync or iCloud for cloud backup.
+    --help, -h             Show this help
+
+  What gets backed up:
+    .agent/skills/total-recall/   — The meta-skill (rules, knowledge, skills,
+                                    integrations, automations, scripts)
+
+  What does NOT get backed up (runtime/derived, can be regenerated):
+    memory-derived/               — Embeddings, indexes (inside the brain, but regenerable)
+    sessions/                     — Conversation logs (inside the brain, ingested from IDEs)
+
+  Scheduling:
+    Add --backup-repo <remote> to "total-recall deploy" to install a
+    daily backup job (cron on Linux, launchd on macOS).
+    Add --backup-obsidian <path> to install a daily Obsidian rsync job.
+`);
+}
+
+async function pushGitBackup(remote, layer = 'auto') {
+  const SKILL_DIR = getSkillDir(layer);
+  if (!commandExists('git')) {
+    console.error('  ❌ git not found — cannot push backup');
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(SKILL_DIR)) {
+    console.error(`  ❌ Meta-skill not found: ${SKILL_DIR}`);
+    console.error('  Run: npx total-recall init');
+    process.exit(1);
+  }
+
+  // Initialise the skill folder as a git repo if needed
+  const gitDir = path.join(SKILL_DIR, '.git');
+  if (!fs.existsSync(gitDir)) {
+    console.error(`  🔧 Initialising git repo in ${SKILL_DIR}`);
+    const init = git(SKILL_DIR, 'init', '-b', 'main');
+    if (!init.ok) {
+      git(SKILL_DIR, 'init');
+      git(SKILL_DIR, 'checkout', '-b', 'main');
+    }
+  }
+
+  // Resolve the remote: if the argument is an existing remote name, use its URL.
+  // Otherwise treat it as a URL and configure the 'backup' remote to point there.
+  const remoteCheck = git(SKILL_DIR, 'remote', 'get-url', remote);
+  if (remoteCheck.ok) {
+    // Argument is an existing remote name — use it as-is, don't overwrite
+    console.error(`  🔗 Using existing remote "${remote}" → ${remoteCheck.stdout}`);
+  } else if (remote.includes('/') || remote.includes(':')) {
+    // Argument looks like a URL — add or update the 'backup' remote
+    const backupCheck = git(SKILL_DIR, 'remote', 'get-url', 'backup');
+    if (!backupCheck.ok) {
+      git(SKILL_DIR, 'remote', 'add', 'backup', remote);
+      console.error(`  🔗 Remote "backup" added → ${remote}`);
+    } else if (backupCheck.stdout !== remote) {
+      git(SKILL_DIR, 'remote', 'set-url', 'backup', remote);
+      console.error(`  🔗 Remote "backup" updated → ${remote}`);
+    }
+    // Push to the 'backup' remote name, not the raw URL
+    remote = 'backup';
+  } else {
+    console.error(`  ❌ "${remote}" is not a configured git remote and doesn't look like a URL.`);
+    console.error('  Use a remote name (e.g. "backup") or a full URL (e.g. "https://github.com/user/repo.git")');
+    process.exit(1);
+  }
+
+  // Stage all changes
+  git(SKILL_DIR, 'add', '-A');
+  const status = git(SKILL_DIR, 'status', '--porcelain');
+  const stamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
+
+  if (!status.stdout) {
+    console.error(`  ✅ Brain unchanged — nothing to push (${stamp})`);
+    return;
+  }
+
+  // Commit (fall back to embedded identity if git config is missing)
+  let commit = git(SKILL_DIR, 'commit', '-m', `backup: ${stamp}`);
+  if (!commit.ok) {
+    commit = git(SKILL_DIR, '-c', 'user.email=backup@total-recall', '-c', 'user.name=Total Recall', 'commit', '-m', `backup: ${stamp}`);
+    if (!commit.ok) {
+      console.error(`  ❌ Commit failed: ${commit.stderr}`);
+      process.exit(1);
+    }
+  }
+
+  // Push (use --force-with-lease to guard against diverged history)
+  console.error(`  📤 Pushing brain to ${remote}...`);
+  let push = git(SKILL_DIR, 'push', 'backup', 'HEAD:main', '--force-with-lease');
+  if (!push.ok) {
+    push = git(SKILL_DIR, 'push', 'backup', 'HEAD:main', '--force');
+    if (!push.ok) {
+      console.error(`  ❌ Push failed: ${push.stderr}`);
+      process.exit(1);
+    }
+  }
+  console.error(`  ✅ Brain pushed to ${remote} (${stamp})`);
+}
+
+function obsidianBackup(vaultPath, layer = 'auto') {
+  const SKILL_DIR = getSkillDir(layer);
+  if (!commandExists('rsync')) {
+    console.error('  ❌ rsync not found — install it or use --push-git instead');
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(SKILL_DIR)) {
+    console.error(`  ❌ Meta-skill not found: ${SKILL_DIR}`);
+    process.exit(1);
+  }
+
+  const expanded = vaultPath.startsWith('~')
+    ? path.join(os.homedir(), vaultPath.slice(1))
+    : vaultPath;
+
+  if (!fs.existsSync(expanded)) {
+    console.error(`  ❌ Obsidian vault not found: ${expanded}`);
+    process.exit(1);
+  }
+
+  const dest = path.join(expanded, 'Total Recall');
+  const stamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
+
+  // Remove stale symlinks (e.g. from a prior install that used the wrong path)
+  // so rsync can create the real directory
+  try {
+    const stat = fs.lstatSync(dest);
+    if (stat.isSymbolicLink()) {
+      console.error(`  ⚠️  Removing stale symlink at ${dest}`);
+      fs.unlinkSync(dest);
+    }
+  } catch {
+    // dest doesn't exist yet — that's fine
+  }
+
+  console.error(`  📓 Syncing brain → ${dest} (${stamp})`);
+
+  // rsync with delete so removed files don't linger in Obsidian
+  const result = spawnSync(
+    'rsync',
+    ['-a', '--delete', '--exclude=.git', SKILL_DIR + '/', dest + '/'],
+    { stdio: 'inherit' }
+  );
+
+  if (result.status !== 0) {
+    console.error(`  ❌ rsync failed (exit ${result.status})`);
+    process.exit(result.status || 1);
+  }
+  console.error(`  ✅ Brain synced to Obsidian (${stamp})`);
+}
+
+export default async function backup(args) {
+  const opts = parseArgs(args);
+  const SKILL_DIR = getSkillDir(opts.layer);
+  if (opts.help) {
+    printHelp();
+    return;
+  }
+
+  if (!fs.existsSync(SKILL_DIR)) {
+    console.error(`  ❌ Meta-skill not found: ${SKILL_DIR}`);
+    console.error('  Run: npx total-recall init');
+    process.exit(1);
+  }
+
+  // Git-push mode: sovereign diff-based backup
+  if (opts.pushGit) {
+    await pushGitBackup(opts.pushGit, opts.layer);
+    return;
+  }
+
+  // Obsidian rsync mode
+  if (opts.obsidian) {
+    obsidianBackup(opts.obsidian, opts.layer);
+    return;
+  }
+
+  // Tarball mode: back up the meta-skill folder
+  const output = opts.output || defaultOutput(opts.encrypt);
+  fs.mkdirSync(path.dirname(output), { recursive: true });
+
+  const parentDir = path.dirname(SKILL_DIR);
+  const skillBase = path.basename(SKILL_DIR);
+
+  let command;
+  if (opts.encrypt) {
+    if (!commandExists('gpg')) {
+      console.error('  ❌ gpg not found; use --no-encrypt or install gpg');
+      process.exit(1);
+    }
+    command = [
+      'tar -czf -',
+      '-C', shellDoubleQuote(parentDir),
+      shellDoubleQuote(skillBase),
+      '|',
+      'gpg --symmetric --cipher-algo AES256 --output',
+      shellDoubleQuote(output)
+    ].join(' ');
+  } else {
+    command = [
+      'tar -czf', shellDoubleQuote(output),
+      '-C', shellDoubleQuote(parentDir),
+      shellDoubleQuote(skillBase)
+    ].join(' ');
+  }
+
+  console.error(`  📦 Creating backup: ${output}`);
+  const result = spawnSync('sh', ['-c', command], { stdio: 'inherit' });
+  if (result.status !== 0) {
+    console.error(`  ❌ Backup failed (exit ${result.status})`);
+    process.exit(result.status || 1);
+  }
+
+  const stat = fs.statSync(output);
+  console.error(`  ✅ Backup complete (${stat.size} bytes)`);
+}

package/src/cli/brain.mjs

@@ -0,0 +1,224 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { getBothBrains, resolveBrainDir, getGlobalAgentDir } from './agent-dir.mjs';
+
+function printHelp() {  console.log(`
+  total-recall brain — Manage brain layers, contexts, and registrations
+
+  Usage: total-recall brain <command> [options]
+
+  Commands:
+    list                       List global and all registered project brains (default)
+    status                     Show active context resolution paths and loaded layers
+    register <project-path>    Register a project directory path in the registry
+    unregister <project-path>  Remove a project directory path from the registry
+
+  Examples:
+    npx total-recall brain
+    npx total-recall brain status
+    npx total-recall brain register .
+    npx total-recall brain unregister /path/to/project
+  `);
+}
+
+export default async function brain(args) {
+  const subcommand = args[0] || 'list';
+
+  if (subcommand === '--help' || subcommand === '-h') {
+    printHelp();
+    return;
+  }
+  const globalAgentDir = getGlobalAgentDir();
+  const globalBrainDir = path.join(globalAgentDir, 'skills', 'total-recall');
+  const registryPath = path.join(globalBrainDir, 'config', 'project-registry.json');
+  switch (subcommand.toLowerCase()) {
+    case 'list':
+      await handleList(registryPath, globalBrainDir);
+      break;
+    case 'status':
+      await handleStatus();
+      break;
+    case 'register':
+      await handleRegister(registryPath, args.slice(1));
+      break;
+    case 'unregister':
+      await handleUnregister(registryPath, args.slice(1));
+      break;
+    default:
+      console.error(`  ⚠️  Unknown brain command: "${subcommand}". Run total-recall brain --help for details.`);
+      process.exit(1);
+  }
+}
+
+async function handleList(registryPath, globalBrainDir) {
+  const brains = getBothBrains();
+  const activeProjectDir = brains.project ? brains.project.brainDir : null;
+
+  console.log('\n  🧠 Active Total Recall Brain Registry:\n');
+
+  // Print Global Brain
+  let globalCount = 0;
+  const globalVault = path.join(globalBrainDir, 'memory-vault');
+  if (fs.existsSync(globalVault)) {
+    globalCount = countMdFiles(globalVault);
+  }
+  const isGlobalActive = !activeProjectDir;
+  const activeGlobalMarker = isGlobalActive ? ' ⭐️ [ACTIVE]' : '';
+  console.log(`  🌐 Global Brain${activeGlobalMarker}`);
+  console.log(`     ├── Path:  ${globalBrainDir}`);
+  console.log(`     └── Nodes: ${globalCount} compiled SSSS memory nodes`);
+  console.log('');
+
+  // Print Project Brains
+  if (fs.existsSync(registryPath)) {
+    try {
+      const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+      if (registry.length === 0) {
+        console.log('  📁 No registered project brains yet. Run `total-recall brain register .` to track one.');
+        return;
+      }
+
+      console.log(`  📁 Registered Project Brains (${registry.length}):`);
+      for (const project of registry) {
+        const isActive = activeProjectDir && path.resolve(activeProjectDir) === path.resolve(project.brainDir);
+        const marker = isActive ? ' ⭐️ [ACTIVE]' : '';
+        const exists = fs.existsSync(project.brainDir);
+        const existsLabel = exists ? '' : ' ⚠️ [NOT FOUND]';
+        const projectVault = path.join(project.brainDir, 'memory-vault');
+        const nodeCount = exists ? countMdFiles(projectVault) : 0;
+
+        console.log(`     ├── 📄 ${project.name}${marker}${existsLabel}`);
+        console.log(`     │   ├── Root:  ${project.path}`);
+        console.log(`     │   ├── Brain: ${project.brainDir}`);
+        console.log(`     │   └── Nodes: ${nodeCount} memory nodes`);
+      }
+    } catch (err) {
+      console.error(`  ⚠️  Failed to read project registry: ${err.message}`);
+    }
+  } else {
+    console.log('  📁 No registered project brains yet. Run `total-recall brain register .` to track one.');
+  }
+  console.log('');
+}
+
+async function handleStatus() {
+  const brains = getBothBrains();
+
+  console.log('\n  🧠 Active Brain Context Status:\n');
+  
+  console.log(`  Current Working Dir: ${process.cwd()}`);
+  
+  if (brains.global) {
+    console.log(`  🌐 Global Layer:`);
+    console.log(`     ├── Resolved Path:  ${brains.global.brainDir}`);
+    console.log(`     └── Status:         Initialized & Available`);
+  } else {
+    console.log(`  🌐 Global Layer:       ⚠️  Not Resolved`);
+  }
+  if (brains.project) {
+    console.log(`  📁 Project Layer:`);
+    console.log(`     ├── Resolved Path:  ${brains.project.brainDir}`);
+    console.log(`     ├── Project Root:   ${path.dirname(brains.project.agentDir)}`);
+    console.log(`     └── Status:         ACTIVE (Cascades over Global)`);
+  } else {
+    console.log(`  📁 Project Layer:       None Detected (Context defaults fully to Global)`);
+  }
+  console.log('');
+}
+
+async function handleRegister(registryPath, targetArgs) {
+  const targetPath = targetArgs[0];
+  if (!targetPath) {
+    console.error('  ⚠️  Missing project path. Usage: npx total-recall brain register <project-path>');
+    process.exit(1);
+  }
+
+  const absoluteRoot = path.resolve(targetPath);
+  if (!fs.existsSync(absoluteRoot) || !fs.statSync(absoluteRoot).isDirectory()) {
+    console.error(`  ⚠️  Directory not found: "${absoluteRoot}"`);
+    process.exit(1);
+  }
+
+  const brainDir = path.join(absoluteRoot, '.agent', 'skills', 'total-recall');
+  const name = path.basename(absoluteRoot);
+
+  // Ensure registry folder exists
+  fs.mkdirSync(path.dirname(registryPath), { recursive: true });
+
+  let registry = [];
+  if (fs.existsSync(registryPath)) {
+    try {
+      registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    } catch {
+      registry = [];
+    }
+  }
+
+  // Check if already exists
+  const existingIndex = registry.findIndex(p => path.resolve(p.path) === absoluteRoot);
+  const nowStr = new Date().toISOString();
+
+  if (existingIndex !== -1) {
+    registry[existingIndex].brainDir = brainDir;
+    registry[existingIndex].name = name;
+  } else {
+    registry.push({
+      name,
+      path: absoluteRoot,
+      brainDir,
+      registered_at: nowStr
+    });
+  }
+
+  fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2), 'utf8');
+  console.log(`  ✅ Successfully registered project brain: "${name}"`);
+  console.log(`     ├── Root:  ${absoluteRoot}`);
+  console.log(`     └── Brain: ${brainDir}`);
+}
+
+async function handleUnregister(registryPath, targetArgs) {
+  const targetPath = targetArgs[0];
+  if (!targetPath) {
+    console.error('  ⚠️  Missing project path. Usage: npx total-recall brain unregister <project-path>');
+    process.exit(1);
+  }
+
+  const absoluteRoot = path.resolve(targetPath);
+  if (!fs.existsSync(registryPath)) {
+    console.log('  ℹ️  No project registry exists yet.');
+    return;
+  }
+
+  let registry = [];
+  try {
+    registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+  } catch {
+    console.error('  ⚠️  Failed to read project registry.');
+    process.exit(1);
+  }
+
+  const beforeLen = registry.length;
+  registry = registry.filter(p => path.resolve(p.path) !== absoluteRoot);
+
+  if (registry.length === beforeLen) {
+    console.log(`  ℹ️  Path not registered: "${absoluteRoot}"`);
+    return;
+  }
+
+  fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2), 'utf8');
+  console.log(`  ✅ Successfully unregistered project: "${absoluteRoot}"`);
+}
+
+function countMdFiles(dir) {
+  if (!fs.existsSync(dir)) return 0;
+  let count = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      count += countMdFiles(path.join(dir, entry.name));
+    } else if (entry.name.endsWith('.md')) {
+      count++;
+    }
+  }
+  return count;
+}

package/src/cli/chat.mjs

@@ -0,0 +1,74 @@
+import readline from 'readline';
+import path from 'path';
+import { resolveBrainDir } from './agent-dir.mjs';
+import { callLocalRuntime, loadRuntimeConfig, checkRuntimeHealth } from '../core/runtime.mjs';
+
+/**
+ * Total Recall CLI Chat Interface
+ * Allows direct conversation with the Sovereign OS kernel from the terminal.
+ */
+export default async function runChat(args) {
+  console.log('🤖 Total Recall CLI Chat initialized. Type "exit" to quit.\n');
+
+  const configDir = path.join(resolveBrainDir(), 'config');
+  
+  let config;
+  let caller;
+  
+  try {
+    config = loadRuntimeConfig(path.join(configDir, 'runtime.yml'));
+    const health = await checkRuntimeHealth(config);
+    if (health.status === 'degraded') {
+      console.warn(`[!] Local runtime degraded: ${health.reason}`);
+    }
+    caller = (prompt, system) => callLocalRuntime(prompt, system, config);
+    console.log(`[Config] Connected to Local Runtime (${config.agents?.[0]?.name || 'default'})\n`);
+  } catch (e) {
+    console.error(`[!] Failed to load configuration: ${e.message}`);
+    process.exit(1);
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: 'You: '
+  });
+
+  const systemMessage = 'You are the Total Recall Sovereign OS kernel. Keep responses concise and direct.';
+  const messages = [];
+
+  rl.prompt();
+
+  rl.on('line', async (line) => {
+    const input = line.trim();
+    if (input.toLowerCase() === 'exit' || input.toLowerCase() === 'quit') {
+      console.log('Goodbye.');
+      process.exit(0);
+    }
+
+    if (!input) {
+      rl.prompt();
+      return;
+    }
+
+    // Build the prompt with history
+    const contextStr = messages.map(m => `${m.role}: ${m.content}`).join('\n');
+    const fullPrompt = contextStr ? `${contextStr}\nuser: ${input}\nassistant: ` : input;
+
+    messages.push({ role: 'user', content: input });
+    
+    try {
+      const response = await caller(fullPrompt, systemMessage);
+      console.log(`\nBrain: ${response}\n`);
+      messages.push({ role: 'assistant', content: response });
+    } catch (err) {
+      console.error(`\n[!] Error: ${err.message}\n`);
+      messages.pop(); // Remove user message if failed
+    }
+
+    rl.prompt();
+  }).on('close', () => {
+    console.log('Goodbye.');
+    process.exit(0);
+  });
+}