memoir-cli 1.5.1 → 2.0.0

package/bin/memoir.js

@@ -9,6 +9,8 @@ import { restoreCommand } from '../src/commands/restore.js';
 import { statusCommand } from '../src/commands/status.js';
 import { viewCommand } from '../src/commands/view.js';
 import { migrateCommand } from '../src/commands/migrate.js';
+import { snapshotCommand } from '../src/commands/snapshot.js';
+import { resumeCommand } from '../src/commands/resume.js';
 import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
@@ -20,10 +22,13 @@ if (process.argv.length <= 2) {
     gradient.pastel.multiline('  memoir  ') + '\n' +
     chalk.gray('  Your AI remembers everything.') + '\n\n' +
     chalk.white.bold('Quick Start:') + '\n' +
-    chalk.cyan('  memoir init     ') + chalk.gray('— first-time setup') + '\n' +
-    chalk.cyan('  memoir push     ') + chalk.gray('— back up your AI memory') + '\n' +
-    chalk.cyan('  memoir restore  ') + chalk.gray('— restore on a new machine') + '\n' +
-    chalk.cyan('  memoir status   ') + chalk.gray('— see detected AI tools') + '\n\n' +
+    chalk.cyan('  memoir init      ') + chalk.gray('— first-time setup') + '\n' +
+    chalk.cyan('  memoir push      ') + chalk.gray('— back up your AI memory') + '\n' +
+    chalk.cyan('  memoir restore   ') + chalk.gray('— restore on a new machine') + '\n' +
+    chalk.cyan('  memoir snapshot  ') + chalk.gray('— capture your current session') + '\n' +
+    chalk.cyan('  memoir resume    ') + chalk.gray('— pick up where you left off') + '\n' +
+    chalk.cyan('  memoir status    ') + chalk.gray('— see detected AI tools') + '\n\n' +
+    chalk.gray('  Tip: use --only claude,gemini to sync specific tools') + '\n\n' +
     chalk.gray(`v${VERSION}`),
     { padding: 1, borderStyle: 'round', borderColor: 'cyan', dimBorder: true }
   ) + '\n');
@@ -58,9 +63,10 @@ program
   .command('push')
   .alias('remember')
   .description('Back up your AI memory to the cloud')
-  .action(async () => {
+  .option('--only <tools>', 'Only sync specific tools (comma-separated: claude,gemini,codex,cursor,copilot,windsurf,aider)')
+  .action(async (options) => {
     try {
-      await pushCommand();
+      await pushCommand(options);
     } catch (err) {
       console.error(chalk.red('\n✖ Error during sync:'), err.message);
       process.exit(1);
@@ -71,9 +77,10 @@ program
   .command('restore')
   .alias('pull')
   .description('Restore your AI memory on this machine')
-  .action(async () => {
+  .option('--only <tools>', 'Only restore specific tools (comma-separated: claude,gemini,codex,cursor,copilot,windsurf,aider)')
+  .action(async (options) => {
     try {
-      await restoreCommand();
+      await restoreCommand(options);
     } catch (err) {
       console.error(chalk.red('\n✖ Error during restore:'), err.message);
       process.exit(1);
@@ -105,6 +112,35 @@ program
     }
   });
 
+program
+  .command('snapshot')
+  .alias('handoff')
+  .description('Capture your current coding session for handoff')
+  .option('--smart', 'Use AI to generate a better summary (requires Gemini API key)')
+  .option('--goal <goal>', 'What you want to do next (goal-directed handoff)')
+  .action(async (options) => {
+    try {
+      await snapshotCommand(options);
+    } catch (err) {
+      console.error(chalk.red('\n✖ Error during snapshot:'), err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('resume')
+  .description('Pick up where you left off on another machine')
+  .option('--inject', 'Write the handoff where your AI tool will read it')
+  .option('--to <tool>', 'Target tool for injection (claude, gemini, cursor, codex)')
+  .action(async (options) => {
+    try {
+      await resumeCommand(options);
+    } catch (err) {
+      console.error(chalk.red('\n✖ Error during resume:'), err.message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('migrate')
   .description('Translate memory between AI tools (Claude, Gemini, Codex, Cursor, etc.)')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memoir-cli",
-  "version": "1.5.1",
-  "description": "Sync and translate AI memory across devices and tools. Back up Claude, Gemini, Codex, Cursor, Copilot, Windsurf, and Aider configs. Migrate instructions between AI coding assistants with one command.",
+  "version": "2.0.0",
+  "description": "Sync AI memory across devices. Back up and restore Claude, Gemini, Codex, Cursor, Copilot, Windsurf configs. Snapshot coding sessions and resume on another machine. Migrate instructions between AI assistants.",
   "main": "src/index.js",
   "type": "module",
   "bin": {
@@ -44,7 +44,10 @@
     "openai",
     "ai-assistant",
     "coding-assistant",
-    "context-sync"
+    "context-sync",
+    "session-handoff",
+    "snapshot",
+    "resume"
   ],
   "author": "camgitt",
   "license": "MIT",
@@ -55,7 +58,6 @@
     "fs-extra": "^11.2.0",
     "gradient-string": "^3.0.0",
     "inquirer": "^9.2.15",
-
     "open": "^11.0.0",
     "ora": "^7.0.1"
   }

package/src/adapters/index.js

@@ -171,11 +171,17 @@ function formatSize(bytes) {
   return `${(bytes / (1024 * 1024)).toFixed(1)}mb`;
 }
 
-export async function extractMemories(stagingDir, spinner) {
+export async function extractMemories(stagingDir, spinner, onlyFilter = null) {
   let foundAny = false;
   const results = [];
 
   for (const adapter of adapters) {
+    // Skip if --only filter is set and this adapter doesn't match
+    if (onlyFilter) {
+      const adapterKey = adapter.name.toLowerCase().replace(/ /g, '-').replace('cli', '').replace('openai-', '').trim().replace(/-$/, '');
+      const matches = onlyFilter.some(f => adapter.name.toLowerCase().includes(f) || adapterKey.includes(f));
+      if (!matches) continue;
+    }
     if (adapter.customExtract) {
       const dest = path.join(stagingDir, adapter.name.toLowerCase().replace(/ /g, '-'));
       let foundFile = false;

package/src/adapters/restore.js

@@ -56,11 +56,17 @@ async function syncFiles(src, dest, changes) {
   }
 }
 
-export async function restoreMemories(sourceDir, spinner) {
+export async function restoreMemories(sourceDir, spinner, onlyFilter = null) {
   let restoredAny = false;
   const allResults = [];
 
   for (const adapter of adapters) {
+    // Skip if --only filter is set and this adapter doesn't match
+    if (onlyFilter) {
+      const matches = onlyFilter.some(f => adapter.name.toLowerCase().includes(f));
+      if (!matches) continue;
+    }
+
     const backupDir = path.join(sourceDir, adapter.name.toLowerCase().replace(/ /g, '-'));
 
     if (await fs.pathExists(backupDir)) {
@@ -125,20 +131,24 @@ export async function restoreMemories(sourceDir, spinner) {
         // Show summary of changes
         spinner.stop();
         const totalChanged = changes.added.length + changes.updated.length;
+        const relPath = (f) => path.relative(adapter.source, f);
         if (totalChanged > 0) {
           console.log(chalk.green.bold(`\n  ${adapter.icon} ${adapter.name} — ${totalChanged} file(s) restored to ${chalk.underline(adapter.source)}`));
           for (const f of changes.added) {
-            console.log(chalk.green(`    + ${path.basename(f)}`) + chalk.gray(` (new)`));
+            console.log(chalk.green(`    + ${relPath(f)}`) + chalk.gray(` (new)`));
           }
           for (const f of changes.updated) {
-            console.log(chalk.yellow(`    ↻ ${path.basename(f)}`) + chalk.gray(` (updated)`));
+            console.log(chalk.yellow(`    ↻ ${relPath(f)}`) + chalk.gray(` (updated)`));
           }
         }
         if (changes.skipped.length > 0) {
-          console.log(chalk.gray(`  ⏭ ${changes.skipped.length} file(s) already up to date`));
+          console.log(chalk.gray(`  ⏭ ${changes.skipped.length} file(s) already up to date:`));
+          for (const f of changes.skipped) {
+            console.log(chalk.gray(`    = ${relPath(f)}`));
+          }
         }
-        if (totalChanged === 0) {
-          console.log(chalk.gray(`  ✔ ${adapter.name} — already up to date`));
+        if (totalChanged === 0 && changes.skipped.length === 0) {
+          console.log(chalk.gray(`  ✔ ${adapter.name} — nothing to restore`));
         }
         spinner.start();
 

package/src/commands/push.js

@@ -9,7 +9,7 @@ import { getConfig } from '../config.js';
 import { extractMemories, adapters } from '../adapters/index.js';
 import { syncToLocal, syncToGit } from '../providers/index.js';
 
-export async function pushCommand() {
+export async function pushCommand(options = {}) {
   const config = await getConfig();
 
   if (!config) {
@@ -28,7 +28,8 @@ export async function pushCommand() {
   await fs.ensureDir(stagingDir);
 
   try {
-    const foundAny = await extractMemories(stagingDir, spinner);
+    const onlyFilter = options.only ? options.only.split(',').map(t => t.trim().toLowerCase()) : null;
+    const foundAny = await extractMemories(stagingDir, spinner, onlyFilter);
 
     if (!foundAny) {
       spinner.stop();

package/src/commands/restore.js

@@ -8,7 +8,7 @@ import gradient from 'gradient-string';
 import { getConfig } from '../config.js';
 import { fetchFromLocal, fetchFromGit } from '../providers/restore.js';
 
-export async function restoreCommand() {
+export async function restoreCommand(options = {}) {
   const config = await getConfig();
 
   if (!config) {
@@ -29,10 +29,12 @@ export async function restoreCommand() {
   try {
     let restored = false;
 
+    const onlyFilter = options.only ? options.only.split(',').map(t => t.trim().toLowerCase()) : null;
+
     if (config.provider === 'local' || config.provider.includes('local')) {
-      restored = await fetchFromLocal(config, stagingDir, spinner);
+      restored = await fetchFromLocal(config, stagingDir, spinner, onlyFilter);
     } else if (config.provider === 'git' || config.provider.includes('git')) {
-      restored = await fetchFromGit(config, stagingDir, spinner);
+      restored = await fetchFromGit(config, stagingDir, spinner, onlyFilter);
     } else {
       spinner.fail(chalk.red(`Unknown provider: ${config.provider}`));
       return;

package/src/commands/resume.js

@@ -0,0 +1,166 @@
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import ora from 'ora';
+import boxen from 'boxen';
+import gradient from 'gradient-string';
+import { getConfig } from '../config.js';
+import { execFileSync } from 'child_process';
+
+const home = os.homedir();
+
+// Fetch latest handoff from git backup
+async function fetchLatestHandoff(config, spinner) {
+  const tmpDir = path.join(os.tmpdir(), `memoir-resume-${Date.now()}`);
+  await fs.ensureDir(tmpDir);
+
+  try {
+    if (config.provider === 'git' || config.provider.includes('git')) {
+      spinner.text = chalk.gray('Pulling latest handoff from GitHub...');
+      execFileSync('git', ['clone', '--depth', '1', config.gitRepo, '.'], { cwd: tmpDir, stdio: 'ignore' });
+    } else if (config.provider === 'local' || config.provider.includes('local')) {
+      const resolvedSource = config.localPath.replace(/^~/, home);
+      spinner.text = chalk.gray('Fetching handoff from local backup...');
+      await fs.copy(resolvedSource, tmpDir);
+    }
+
+    const handoffDir = path.join(tmpDir, 'handoffs');
+    if (!await fs.pathExists(handoffDir)) {
+      return null;
+    }
+
+    // Find the newest handoff file
+    const files = (await fs.readdir(handoffDir))
+      .filter(f => f.endsWith('.md') && f !== 'latest.md')
+      .sort()
+      .reverse();
+
+    if (files.length === 0) return null;
+
+    const content = await fs.readFile(path.join(handoffDir, files[0]), 'utf8');
+    return { filename: files[0], content };
+  } finally {
+    await fs.remove(tmpDir);
+  }
+}
+
+// Inject handoff into a tool's context location
+async function injectHandoff(content, tool) {
+  const targets = {
+    claude: () => {
+      // Write to Claude's project memory dir so it's auto-loaded
+      const cwd = process.cwd();
+      const cwdKey = '-' + cwd.replace(/^\//, '').replace(/\\/g, '-').replace(/\//g, '-').replace(/:/g, '');
+      const memDir = path.join(home, '.claude', 'projects', cwdKey, 'memory');
+      return path.join(memDir, 'handoff.md');
+    },
+    gemini: () => {
+      return path.join(process.cwd(), 'GEMINI.md');
+    },
+    cursor: () => {
+      return path.join(process.cwd(), '.cursor', 'rules', 'handoff.mdc');
+    },
+    codex: () => {
+      return path.join(process.cwd(), 'AGENTS.md');
+    }
+  };
+
+  const getTarget = targets[tool];
+  if (!getTarget) {
+    throw new Error(`Unknown tool: ${tool}. Supported: claude, gemini, cursor, codex`);
+  }
+
+  const targetPath = getTarget();
+  await fs.ensureDir(path.dirname(targetPath));
+
+  if (tool === 'gemini' && await fs.pathExists(targetPath)) {
+    // Append to existing GEMINI.md
+    const existing = await fs.readFile(targetPath, 'utf8');
+    if (!existing.includes('# Session Handoff')) {
+      await fs.writeFile(targetPath, existing + '\n\n' + content);
+    } else {
+      // Replace existing handoff section
+      const before = existing.split('# Session Handoff')[0];
+      await fs.writeFile(targetPath, before + content);
+    }
+  } else {
+    await fs.writeFile(targetPath, content);
+  }
+
+  return targetPath;
+}
+
+export async function resumeCommand(options = {}) {
+  const config = await getConfig();
+
+  if (!config) {
+    console.log('\n' + boxen(
+      chalk.red('Not configured yet\n\n') +
+      chalk.white('Run ') + chalk.cyan.bold('memoir init') + chalk.white(' to get started.'),
+      { padding: 1, borderStyle: 'round', borderColor: 'red' }
+    ) + '\n');
+    return;
+  }
+
+  console.log();
+  const spinner = ora({ text: chalk.gray('Fetching latest handoff...'), spinner: 'dots' }).start();
+
+  // First check local cache
+  const localLatest = path.join(home, '.config', 'memoir', 'handoffs', 'latest.md');
+  let handoff;
+
+  // Try remote first
+  try {
+    handoff = await fetchLatestHandoff(config, spinner);
+  } catch (err) {
+    spinner.warn(chalk.yellow(`Remote fetch failed: ${err.message}`));
+    spinner.start();
+  }
+
+  // Fallback to local cache
+  if (!handoff && await fs.pathExists(localLatest)) {
+    handoff = { filename: 'latest.md', content: await fs.readFile(localLatest, 'utf8') };
+  }
+
+  if (!handoff) {
+    spinner.fail(chalk.red('No handoffs found.'));
+    console.log(chalk.gray('\n  Run ') + chalk.cyan('memoir snapshot') + chalk.gray(' on another machine first.\n'));
+    return;
+  }
+
+  // Save locally
+  const localHandoffDir = path.join(home, '.config', 'memoir', 'handoffs');
+  await fs.ensureDir(localHandoffDir);
+  await fs.writeFile(path.join(localHandoffDir, 'latest.md'), handoff.content);
+
+  spinner.stop();
+
+  // Display the handoff
+  console.log(boxen(
+    gradient.pastel('  Session Handoff  ') + '\n\n' +
+    handoff.content
+      .replace(/^---[\s\S]*?---\n/, '') // Strip YAML frontmatter for display
+      .trim(),
+    { padding: 1, borderStyle: 'round', borderColor: 'cyan', dimBorder: true }
+  ));
+
+  // Inject if requested
+  if (options.inject) {
+    const tool = options.to || 'claude';
+    spinner.start(chalk.gray(`Injecting handoff for ${tool}...`));
+    try {
+      const targetPath = await injectHandoff(handoff.content, tool);
+      spinner.stop();
+      console.log('\n' + chalk.green(`  Injected handoff → ${targetPath}`));
+      console.log(chalk.gray(`  ${tool.charAt(0).toUpperCase() + tool.slice(1)} will read this on next session.\n`));
+    } catch (err) {
+      spinner.fail(chalk.red(`Inject failed: ${err.message}`));
+    }
+  } else {
+    console.log('\n' + chalk.gray('  To inject into your AI tool:'));
+    console.log(chalk.cyan('    memoir resume --inject') + chalk.gray(' (Claude)'));
+    console.log(chalk.cyan('    memoir resume --inject --to gemini'));
+    console.log(chalk.cyan('    memoir resume --inject --to cursor') + '\n');
+  }
+}

package/src/commands/snapshot.js

@@ -0,0 +1,382 @@
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import ora from 'ora';
+import boxen from 'boxen';
+import gradient from 'gradient-string';
+import { getConfig, getGeminiApiKey } from '../config.js';
+import { syncToLocal, syncToGit } from '../providers/index.js';
+
+const home = os.homedir();
+
+// Find all Claude session files, sorted newest first
+function findClaudeSessions() {
+  const projectsDir = path.join(home, '.claude', 'projects');
+  if (!fs.existsSync(projectsDir)) return [];
+
+  const sessions = [];
+  const scanDir = (dir) => {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        scanDir(full);
+      } else if (entry.name.endsWith('.jsonl') && !entry.name.includes('subagent')) {
+        const stat = fs.statSync(full);
+        sessions.push({ path: full, mtime: stat.mtimeMs, size: stat.size });
+      }
+    }
+  };
+  scanDir(projectsDir);
+  sessions.sort((a, b) => b.mtime - a.mtime);
+  return sessions;
+}
+
+// Parse a Claude .jsonl session file
+function parseClaudeSession(sessionPath) {
+  const raw = fs.readFileSync(sessionPath, 'utf8').trim();
+  const lines = raw.split('\n');
+
+  const result = {
+    sessionId: null,
+    slug: null,
+    gitBranch: null,
+    cwd: null,
+    firstTimestamp: null,
+    lastTimestamp: null,
+    model: null,
+    userMessages: [],
+    filesWritten: new Set(),
+    filesRead: new Set(),
+    bashCommands: [],
+    errors: [],
+  };
+
+  for (const line of lines) {
+    let obj;
+    try { obj = JSON.parse(line); } catch { continue; }
+
+    if (!result.sessionId && obj.sessionId) result.sessionId = obj.sessionId;
+    if (!result.slug && obj.slug) result.slug = obj.slug;
+    if (!result.gitBranch && obj.gitBranch) result.gitBranch = obj.gitBranch;
+    if (!result.cwd && obj.cwd) result.cwd = obj.cwd;
+    if (!result.firstTimestamp && obj.timestamp) result.firstTimestamp = obj.timestamp;
+    if (obj.timestamp) result.lastTimestamp = obj.timestamp;
+
+    // User messages (skip system/task notifications)
+    if (obj.type === 'user' && obj.message?.content) {
+      const content = typeof obj.message.content === 'string' ? obj.message.content : '';
+      if (content.length > 3 && !content.startsWith('<task-notification>')) {
+        result.userMessages.push(content);
+      }
+    }
+
+    // Tool uses from assistant messages
+    if (obj.type === 'assistant' && Array.isArray(obj.message?.content)) {
+      for (const block of obj.message.content) {
+        if (block.type !== 'tool_use') continue;
+        const name = block.name;
+        const input = block.input || {};
+
+        if (name === 'Write' || name === 'Edit') {
+          const fp = input.file_path || '';
+          if (fp && !fp.startsWith('/tmp/') && !fp.startsWith('/private/tmp/')) {
+            result.filesWritten.add(fp);
+          }
+        } else if (name === 'Read') {
+          const fp = input.file_path || '';
+          if (fp && !fp.startsWith('/tmp/') && !fp.startsWith('/private/tmp/')) {
+            result.filesRead.add(fp);
+          }
+        } else if (name === 'Bash') {
+          const cmd = (input.command || '').trim();
+          if (cmd && !cmd.startsWith('sleep') && !cmd.startsWith('cat /private/tmp')) {
+            result.bashCommands.push(cmd.length > 120 ? cmd.slice(0, 120) + '...' : cmd);
+          }
+        }
+      }
+    }
+
+    // Capture errors from tool results
+    if (obj.type === 'tool_result' && obj.message?.content) {
+      const content = typeof obj.message.content === 'string' ? obj.message.content : '';
+      if (content.includes('Error') || content.includes('error') || content.includes('FAIL')) {
+        const errorLine = content.split('\n').find(l => /error|fail/i.test(l));
+        if (errorLine && errorLine.length < 200) {
+          result.errors.push(errorLine.trim());
+        }
+      }
+    }
+  }
+
+  // Convert sets to arrays
+  result.filesWritten = [...result.filesWritten];
+  result.filesRead = [...result.filesRead];
+  // Deduplicate errors
+  result.errors = [...new Set(result.errors)].slice(0, 10);
+
+  return result;
+}
+
+// Shorten file paths relative to cwd for readability
+function shortenPath(filePath, cwd) {
+  if (filePath.startsWith(cwd + '/')) {
+    return filePath.slice(cwd.length + 1);
+  }
+  if (filePath.startsWith(home + '/')) {
+    return '~/' + filePath.slice(home.length + 1);
+  }
+  return filePath;
+}
+
+// Format duration between two ISO timestamps
+function formatDuration(start, end) {
+  const ms = new Date(end) - new Date(start);
+  const mins = Math.floor(ms / 60000);
+  if (mins < 60) return `${mins}m`;
+  const hours = Math.floor(mins / 60);
+  const remaining = mins % 60;
+  return `${hours}h ${remaining}m`;
+}
+
+// Generate handoff markdown from parsed session
+function generateHandoff(parsed, options = {}) {
+  const now = new Date();
+  const dateStr = now.toISOString().split('T')[0];
+  const timeStr = now.toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit' });
+  const hostname = os.hostname();
+  const platform = process.platform === 'darwin' ? 'macOS' : process.platform === 'win32' ? 'Windows' : 'Linux';
+  const duration = formatDuration(parsed.firstTimestamp, parsed.lastTimestamp);
+  const cwd = parsed.cwd || home;
+
+  // Build user message summary (filter noise, keep substance)
+  const meaningfulMessages = parsed.userMessages
+    .filter(m => m.length > 10 && !m.startsWith('ok') && !m.startsWith('yes'))
+    .map(m => m.length > 200 ? m.slice(0, 200) + '...' : m);
+
+  // YAML frontmatter
+  let md = `---
+memoir_version: "2.0"
+source_tool: claude
+session_id: ${parsed.sessionId || 'unknown'}
+session_name: ${parsed.slug || 'unknown'}
+timestamp: ${now.toISOString()}
+machine: ${hostname} (${platform})
+project: ${cwd}
+branch: ${parsed.gitBranch || 'unknown'}
+duration: ${duration}
+files_modified: ${parsed.filesWritten.length}
+files_read: ${parsed.filesRead.length}
+---
+
+# Session Handoff
+
+**From:** ${hostname} (${platform})
+**When:** ${dateStr} ${timeStr}
+**Tool:** Claude Code
+**Branch:** ${parsed.gitBranch || 'unknown'}
+**Duration:** ${duration}
+**Project:** ${cwd}
+
+## What was discussed
+${meaningfulMessages.map(m => `- ${m}`).join('\n')}
+
+## Files modified
+${parsed.filesWritten.length > 0
+    ? parsed.filesWritten.map(f => `- \`${shortenPath(f, cwd)}\``).join('\n')
+    : '_None_'}
+
+## Files referenced
+${parsed.filesRead.length > 0
+    ? parsed.filesRead.map(f => `- \`${shortenPath(f, cwd)}\``).join('\n')
+    : '_None_'}
+
+## Commands run
+${parsed.bashCommands.length > 0
+    ? parsed.bashCommands.slice(0, 20).map(c => `- \`${c}\``).join('\n')
+    : '_None_'}
+`;
+
+  if (parsed.errors.length > 0) {
+    md += `\n## Errors encountered\n${parsed.errors.map(e => `- ${e}`).join('\n')}\n`;
+  }
+
+  if (options.goal) {
+    md += `\n## Goal for next session\n${options.goal}\n`;
+  }
+
+  md += `\n## Context for next session\nThis handoff was captured from a Claude Code session on ${platform}. `;
+  md += `The session touched ${parsed.filesWritten.length} files and ran ${parsed.bashCommands.length} commands. `;
+  if (parsed.filesWritten.length > 0) {
+    md += `Key files to review: ${parsed.filesWritten.slice(0, 5).map(f => '`' + shortenPath(f, cwd) + '`').join(', ')}.`;
+  }
+  md += '\n';
+
+  return md;
+}
+
+// Use Gemini API to create a smart summary
+async function smartSummarize(parsed, apiKey) {
+  const prompt = `You are summarizing a coding session for handoff to another machine. Be concise and actionable.
+
+Session info:
+- Duration: ${formatDuration(parsed.firstTimestamp, parsed.lastTimestamp)}
+- Branch: ${parsed.gitBranch || 'unknown'}
+- Project dir: ${parsed.cwd || 'unknown'}
+
+User messages (what they asked for):
+${parsed.userMessages.filter(m => m.length > 10).map(m => `- ${m.slice(0, 200)}`).join('\n')}
+
+Files modified:
+${parsed.filesWritten.map(f => `- ${f}`).join('\n')}
+
+Write a structured summary with these exact sections:
+## Summary
+(2-3 sentences of what was accomplished)
+
+## Key decisions
+(Bullet list of important decisions made)
+
+## Current state
+(What's done, what's in progress, what's left)
+
+## Next steps
+(What should be done next to continue this work)
+
+Keep it under 300 words total. Be specific about file names and features.`;
+
+  const response = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=${apiKey}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      contents: [{ parts: [{ text: prompt }] }],
+      generationConfig: { maxOutputTokens: 1000, temperature: 0.3 }
+    })
+  });
+
+  if (!response.ok) {
+    throw new Error(`Gemini API error: ${response.status}`);
+  }
+
+  const data = await response.json();
+  return data.candidates?.[0]?.content?.parts?.[0]?.text || null;
+}
+
+export async function snapshotCommand(options = {}) {
+  const config = await getConfig();
+
+  console.log();
+  const spinner = ora({ text: chalk.gray('Finding latest session...'), spinner: 'dots' }).start();
+
+  // Find sessions
+  const sessions = findClaudeSessions();
+  if (sessions.length === 0) {
+    spinner.fail(chalk.red('No Claude Code sessions found.'));
+    return;
+  }
+
+  const latest = sessions[0];
+  spinner.text = chalk.gray('Parsing session...');
+
+  // Parse the session
+  const parsed = parseClaudeSession(latest.path);
+
+  if (parsed.userMessages.length === 0) {
+    spinner.fail(chalk.red('Session has no user messages.'));
+    return;
+  }
+
+  spinner.text = chalk.gray('Generating handoff...');
+
+  // Generate handoff markdown
+  let handoff;
+
+  if (options.smart) {
+    const apiKey = await getGeminiApiKey();
+    if (!apiKey) {
+      spinner.warn(chalk.yellow('No Gemini API key found. Using local extraction.'));
+      spinner.start();
+      handoff = generateHandoff(parsed, options);
+    } else {
+      spinner.text = chalk.gray('Generating AI-powered summary...');
+      try {
+        const smartSummary = await smartSummarize(parsed, apiKey);
+        // Generate base handoff then inject smart summary
+        handoff = generateHandoff(parsed, options);
+        if (smartSummary) {
+          // Insert smart summary after the frontmatter header
+          const insertPoint = handoff.indexOf('## What was discussed');
+          handoff = handoff.slice(0, insertPoint) +
+            '## AI Summary\n' + smartSummary + '\n\n' +
+            handoff.slice(insertPoint);
+        }
+      } catch (err) {
+        spinner.warn(chalk.yellow(`AI summary failed: ${err.message}. Using local extraction.`));
+        spinner.start();
+        handoff = generateHandoff(parsed, options);
+      }
+    }
+  } else {
+    handoff = generateHandoff(parsed, options);
+  }
+
+  // Save handoff
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const filename = `${timestamp}-claude.md`;
+
+  // If config exists, push to backup
+  if (config) {
+    const stagingDir = path.join(os.tmpdir(), `memoir-handoff-${Date.now()}`);
+    await fs.ensureDir(path.join(stagingDir, 'handoffs'));
+    await fs.writeFile(path.join(stagingDir, 'handoffs', filename), handoff);
+
+    spinner.text = chalk.gray('Pushing handoff to backup...');
+
+    try {
+      if (config.provider === 'local' || config.provider.includes('local')) {
+        await syncToLocal(config, stagingDir, spinner);
+      } else if (config.provider === 'git' || config.provider.includes('git')) {
+        await syncToGit(config, stagingDir, spinner);
+      }
+    } catch (err) {
+      spinner.warn(chalk.yellow(`Push failed: ${err.message}. Saved locally.`));
+    }
+
+    await fs.remove(stagingDir);
+  }
+
+  // Also save locally for immediate access
+  const localHandoffDir = path.join(home, '.config', 'memoir', 'handoffs');
+  await fs.ensureDir(localHandoffDir);
+  await fs.writeFile(path.join(localHandoffDir, filename), handoff);
+
+  // Also save as "latest" for easy access
+  await fs.writeFile(path.join(localHandoffDir, 'latest.md'), handoff);
+
+  spinner.stop();
+
+  // Display summary
+  const duration = formatDuration(parsed.firstTimestamp, parsed.lastTimestamp);
+  console.log('\n' + boxen(
+    gradient.pastel('  Snapshot captured  ') + '\n\n' +
+    chalk.white(`Session: ${parsed.slug || 'unnamed'}`) + '\n' +
+    chalk.gray(`Duration: ${duration} | Branch: ${parsed.gitBranch || '?'} | ${parsed.filesWritten.length} files changed`) + '\n\n' +
+    chalk.white.bold('Files modified:') + '\n' +
+    (parsed.filesWritten.length > 0
+      ? parsed.filesWritten.slice(0, 8).map(f => chalk.cyan(`  ${shortenPath(f, parsed.cwd || home)}`)).join('\n')
+      : chalk.gray('  None')) +
+    (parsed.filesWritten.length > 8 ? chalk.gray(`\n  ...and ${parsed.filesWritten.length - 8} more`) : '') + '\n\n' +
+    chalk.white.bold('User requests:') + '\n' +
+    parsed.userMessages
+      .filter(m => m.length > 10 && !m.startsWith('ok') && !m.startsWith('yes'))
+      .slice(0, 5)
+      .map(m => chalk.gray(`  "${m.slice(0, 80)}${m.length > 80 ? '...' : ''}"`))
+      .join('\n') + '\n\n' +
+    chalk.gray(`Saved to: ${localHandoffDir}/${filename}`) +
+    (config ? '\n' + chalk.gray(`Pushed to: ${config.provider === 'git' ? config.gitRepo : config.localPath}`) : ''),
+    { padding: 1, borderStyle: 'round', borderColor: 'green', dimBorder: true }
+  ) + '\n');
+
+  console.log(chalk.gray('  Restore on another machine with: ') + chalk.cyan('memoir resume') + '\n');
+}

package/src/providers/restore.js

@@ -5,7 +5,7 @@ import os from 'os';
 import { execFileSync } from 'child_process';
 import { restoreMemories } from '../adapters/restore.js';
 
-export async function fetchFromLocal(config, stagingDir, spinner) {
+export async function fetchFromLocal(config, stagingDir, spinner, onlyFilter = null) {
   const sourceDir = config.localPath;
   if (!sourceDir) throw new Error('Local path is not configured.');
 
@@ -18,10 +18,10 @@ export async function fetchFromLocal(config, stagingDir, spinner) {
   spinner.text = `Fetching data from local directory: ${chalk.cyan(resolvedSource)}`;
   await fs.copy(resolvedSource, stagingDir);
 
-  return await restoreMemories(stagingDir, spinner);
+  return await restoreMemories(stagingDir, spinner, onlyFilter);
 }
 
-export async function fetchFromGit(config, stagingDir, spinner) {
+export async function fetchFromGit(config, stagingDir, spinner, onlyFilter = null) {
   const repoUrl = config.gitRepo;
   if (!repoUrl) throw new Error('Git repository is not configured.');
 
@@ -33,5 +33,5 @@ export async function fetchFromGit(config, stagingDir, spinner) {
     throw new Error('Failed to pull from git repository. Ensure your SSH keys are configured and the repository is accessible.');
   }
 
-  return await restoreMemories(stagingDir, spinner);
+  return await restoreMemories(stagingDir, spinner, onlyFilter);
 }