memoir-cli 2.4.0 → 2.5.1

package/README.md

@@ -1,88 +1,129 @@
 <div align="center">
 
 # memoir
-**Your AI Remembers Everything. Sync It Everywhere.**
 
-[![npm version](https://img.shields.io/npm/v/memoir-cli.svg?style=flat-square)](https://npmjs.org/package/memoir-cli)
+**Sync your AI memory across every device and every tool.**
+
+[![npm version](https://img.shields.io/npm/v/memoir-cli.svg?style=flat-square&color=7c6ef0)](https://npmjs.org/package/memoir-cli)
+[![npm downloads](https://img.shields.io/npm/dm/memoir-cli.svg?style=flat-square&color=7c6ef0)](https://npmjs.org/package/memoir-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)](https://nodejs.org)
+
+Your AI tools forget you on every new machine. memoir fixes that.
 
-*Never lose your AI's context again. Sync and translate your AI memory across every device and tool.*
+[Website](https://memoir.sh) &bull; [npm](https://npmjs.org/package/memoir-cli) &bull; [Blog](https://memoir.sh/blog)
+
+<br />
 
 ![memoir demo](demo.gif)
 
 </div>
 
----
+## Why memoir
 
-## The Problem
+You spend weeks teaching your AI tools how you code. Your CLAUDE.md is dialed in. Your .cursorrules are perfect. Your ChatGPT custom instructions know your stack.
 
-You spend weeks teaching your AI tools how you code — your preferred patterns, project context, coding standards.
+Then you get a new laptop. **Everything is gone.**
 
-Then you switch laptops. Or try a new AI tool. Or want your team on the same page.
+memoir backs up, restores, and **translates** your AI memory across any machine and any tool. One command to save. One command to restore.
 
-All that context is trapped in hidden dotfiles on one machine.
+```bash
+npm install -g memoir-cli
+```
 
-## The Solution
+## Supported Tools (11)
+
+| Tool | What gets synced |
+|------|-----------------|
+| **ChatGPT** | CHATGPT.md custom instructions |
+| **Claude Code** | ~/.claude/ settings, memory, CLAUDE.md files |
+| **Gemini CLI** | ~/.gemini/ config, GEMINI.md files |
+| **OpenAI Codex** | ~/.codex/ config, AGENTS.md, codex.md |
+| **Cursor** | Settings, keybindings, .cursorrules |
+| **GitHub Copilot** | Config, copilot-instructions.md |
+| **Windsurf** | Settings, keybindings, .windsurfrules |
+| **Zed** | Settings, keymap, tasks |
+| **Cline** | Settings, .clinerules |
+| **Continue.dev** | Config, .continuerules |
+| **Aider** | .aider.conf.yml, system prompt |
 
-`memoir` extracts, backs up, restores, and **translates** your AI memory across any computer and any tool. One command to save. One command to restore. One command to translate between tools.
+Plus **per-project configs** — memoir scans your filesystem for CLAUDE.md, GEMINI.md, CHATGPT.md, .cursorrules, and AGENTS.md across all your projects.
+
+## Quick Start
 
 ```bash
+# Install
 npm install -g memoir-cli
+
+# First-time setup (GitHub repo or local)
+memoir init
+
+# Back up all your AI configs
+memoir push
+
+# Restore on a new machine
+memoir restore
 ```
 
-### Supported Tools (11)
-| Tool | Config synced |
-|------|--------------|
-| **ChatGPT** | `CHATGPT.md` — custom instructions, preferences |
-| **Claude Code** | `~/.claude/` — settings, projects, memory files |
-| **Gemini CLI** | `~/.gemini/` — settings, GEMINI.md |
-| **OpenAI Codex** | `~/.codex/` — config, instructions |
-| **Cursor** | Settings, keybindings, rules |
-| **GitHub Copilot** | Config, settings |
-| **Windsurf** | Settings, keybindings, rules |
-| **Zed** | Settings, keymap, tasks |
-| **Cline** | Settings, rules |
-| **Continue.dev** | Config, rules |
-| **Aider** | `.aider.conf.yml`, system prompt |
+That's it. Every AI tool gets its memory back.
 
-Plus **per-project configs**: automatically finds `CLAUDE.md`, `GEMINI.md`, `CHATGPT.md`, `.cursorrules`, `AGENTS.md` across all your projects.
+## Key Features
 
----
+### Translate between AI tools
+```bash
+memoir migrate --from chatgpt --to claude
+# AI-powered — rewrites conventions, not copy-paste
+```
 
-## Quick Start
+Works between any combination: ChatGPT, Claude, Gemini, Cursor, Copilot, Codex, Windsurf, Aider, and more. Translate to one tool or all at once:
 
-### 1. Initialize
 ```bash
-memoir init
-# Walks you through setup — GitHub repo or local folder
-# Auto-creates a private repo if you have gh CLI
+memoir migrate --from chatgpt --to all
 ```
 
-### 2. Back up your memory
+### Session handoff
 ```bash
-memoir push
+# Laptop dying? Capture your session
+memoir snapshot
+
+# Pick up on another machine
+memoir resume --inject --to claude
 ```
 
-### 3. Restore on a new machine
+### Profiles (personal / work)
 ```bash
-memoir restore
+memoir profile create work
+memoir push --profile work
+memoir profile switch personal
 ```
 
-### 4. Translate between tools
+Each profile has its own repo and tool filters. Work configs never mix with personal.
+
+### Cloud sync (Pro)
 ```bash
-memoir migrate --from claude --to gemini
-# AI-powered translation — not copy-paste, real rewriting
+memoir login
+memoir cloud push      # encrypted cloud backup
+memoir cloud restore   # restore from any version
+memoir history         # view all backup versions
 ```
 
----
+Free tier: 3 cloud backups. Pro ($5/mo): unlimited + version history.
+
+### Security
+```bash
+memoir doctor
+# Scans for secrets, API keys, .env files before pushing
+```
+
+memoir **never** syncs credentials, API keys, .env files, or auth tokens.
 
 ## All Commands
 
 | Command | What it does |
 |---------|-------------|
-| `memoir init` | Setup wizard — GitHub or local, upload or download |
+| `memoir init` | Setup wizard — GitHub or local storage |
 | `memoir push` | Back up all AI configs |
-| `memoir restore` | Restore on a new machine (non-destructive) |
+| `memoir restore` | Restore on a new machine |
 | `memoir status` | Show detected AI tools |
 | `memoir doctor` | Diagnose issues, scan for secrets |
 | `memoir view` | Preview what's in your backup |
@@ -91,28 +132,27 @@ memoir migrate --from claude --to gemini
 | `memoir snapshot` | Capture current coding session |
 | `memoir resume` | Pick up where you left off |
 | `memoir profile` | Manage profiles (personal/work) |
+| `memoir cloud push` | Back up to memoir cloud |
+| `memoir cloud restore` | Restore from memoir cloud |
+| `memoir history` | View cloud backup versions |
+| `memoir login` | Sign in to memoir cloud |
 | `memoir update` | Self-update to latest version |
 
----
-
-## Profiles
+## How memoir compares
 
-Separate personal and work configs — different repos, different tools.
+| Feature | memoir | skillshare | ai-rulez | memories.sh |
+|---------|--------|-----------|----------|-------------|
+| Cross-device sync | **Yes** | Yes (git) | No | Yes |
+| AI-powered translation | **Yes** | No | No | No |
+| Tools supported | **11** | 40+ | 18 | 3 |
+| Cloud backup | **Yes** | No | No | Yes ($15/mo) |
+| Version history | **Yes** | No | No | No |
+| Session handoff | **Yes** | No | No | No |
+| Profiles | **Yes** | No | No | No |
+| Secret scanning | **Yes** | Yes | No | No |
+| Free & open source | **Yes** | Yes | Yes | No |
 
-```bash
-memoir profile create work      # set up work profile with its own repo
-memoir profile create personal  # personal side projects
-
-memoir push --profile work      # sync only work configs
-memoir restore --profile personal
-
-memoir profile list             # see all profiles
-memoir profile switch work      # change default
-```
-
-Each profile can filter which tools to sync, so your personal side project memory never mixes with work.
-
----
+memoir is free and open source. Cloud sync starts at $0 (3 backups free).
 
 ## Common Workflows
 
@@ -122,46 +162,36 @@ Each profile can filter which tools to sync, so your personal side project memor
 memoir push
 
 # New machine
-memoir init    # → Download → same GitHub repo
-memoir restore # All configs restored in seconds
+npm install -g memoir-cli
+memoir init      # connect to same repo
+memoir restore   # all configs restored in seconds
 ```
 
-### Translate between tools
+### Switching from ChatGPT to Claude
 ```bash
 memoir migrate --from chatgpt --to claude
-# Your ChatGPT custom instructions become a proper CLAUDE.md
+# Your custom instructions become a proper CLAUDE.md
 ```
 
-### Fan out to every tool
+### Daily sync between machines
 ```bash
-memoir migrate --from chatgpt --to all
-# One source of truth, every tool gets its own format
+memoir push      # end of day on laptop
+memoir restore   # next morning on desktop
 ```
 
-### Daily sync
+### Cross-platform (Mac ↔ Windows ↔ Linux)
 ```bash
-memoir push      # end of day
-memoir restore   # next morning, different machine
-```
-
----
-
-## Security
-
-Memoir **only** syncs config files, instructions, and memory markdown. It never touches credentials, API keys, `.env` files, or auth tokens.
-
-Run `memoir doctor` to see exactly what would be synced and scan for accidental secrets before pushing.
-
----
+# Push from Mac
+memoir push
 
-## Roadmap
+# Restore on Windows — paths remap automatically
+memoir restore
+```
 
-- **Universal format** — write one `MEMOIR.md`, generate all tool-specific configs
-- **Cloud sync** — no GitHub needed, encrypted backups
-- **Teams** — shared coding standards across your whole team
-- **Templates** — community-shared AI tool configs
+## Requirements
 
----
+- Node.js >= 18
+- Works on macOS, Windows, Linux
 
 ## Contributing
 
@@ -172,6 +202,13 @@ Contributions welcome — especially new tool adapters and migration improvement
 3. Commit and push
 4. Open a PR
 
+## Links
+
+- **Website:** [memoir.sh](https://memoir.sh)
+- **npm:** [memoir-cli](https://npmjs.org/package/memoir-cli)
+- **Blog:** [memoir.sh/blog](https://memoir.sh/blog)
+- **Issues:** [GitHub Issues](https://github.com/camgitt/memoir/issues)
+
 ## License
 
 MIT

package/bin/memoir.js

@@ -14,6 +14,9 @@ import { migrateCommand } from '../src/commands/migrate.js';
 import { snapshotCommand } from '../src/commands/snapshot.js';
 import { resumeCommand } from '../src/commands/resume.js';
 import { profileListCommand, profileCreateCommand, profileSwitchCommand, profileDeleteCommand } from '../src/commands/profile.js';
+import { loginCommand, logoutCommand } from '../src/commands/login.js';
+import { cloudPushCommand, cloudRestoreCommand } from '../src/commands/cloud.js';
+import { historyCommand } from '../src/commands/history.js';
 import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
@@ -60,6 +63,11 @@ if (process.argv.length <= 2) {
     chalk.cyan('  memoir status    ') + chalk.gray('— see detected AI tools') + '\n' +
     chalk.cyan('  memoir profile   ') + chalk.gray('— manage profiles (personal/work)') + '\n' +
     chalk.cyan('  memoir update    ') + chalk.gray('— update to latest version') + '\n\n' +
+    chalk.white.bold('Cloud (Pro):') + '\n' +
+    chalk.cyan('  memoir login         ') + chalk.gray('— sign in to memoir cloud') + '\n' +
+    chalk.cyan('  memoir cloud push    ') + chalk.gray('— back up to the cloud') + '\n' +
+    chalk.cyan('  memoir cloud restore ') + chalk.gray('— restore from cloud') + '\n' +
+    chalk.cyan('  memoir history       ') + chalk.gray('— view backup versions') + '\n\n' +
     chalk.gray('  Tip: use --profile work to sync a specific profile') + '\n\n' +
     chalk.gray(`v${VERSION}`),
     { padding: 1, borderStyle: 'round', borderColor: 'cyan', dimBorder: true }
@@ -263,6 +271,74 @@ program
     }
   });
 
+// Cloud auth
+program
+  .command('login')
+  .description('Sign in to memoir cloud')
+  .action(async () => {
+    try {
+      await loginCommand();
+    } catch (err) {
+      console.error(chalk.red('\n✖ Error:'), err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('logout')
+  .description('Sign out of memoir cloud')
+  .action(async () => {
+    try {
+      await logoutCommand();
+    } catch (err) {
+      console.error(chalk.red('\n✖ Error:'), err.message);
+      process.exit(1);
+    }
+  });
+
+// Cloud sync
+const cloud = program.command('cloud').description('Cloud backup and restore (Pro)');
+
+cloud
+  .command('push')
+  .description('Back up your AI memory to the cloud')
+  .option('--only <tools>', 'Only sync specific tools (comma-separated)')
+  .action(async (options) => {
+    try {
+      await cloudPushCommand(options);
+    } catch (err) {
+      console.error(chalk.red('\n✖ Error:'), err.message);
+      process.exit(1);
+    }
+  });
+
+cloud
+  .command('restore')
+  .description('Restore your AI memory from the cloud')
+  .option('--only <tools>', 'Only restore specific tools (comma-separated)')
+  .option('-y, --yes', 'Skip confirmation prompts')
+  .option('--version <number>', 'Restore a specific version')
+  .action(async (options) => {
+    try {
+      await cloudRestoreCommand(options);
+    } catch (err) {
+      console.error(chalk.red('\n✖ Error:'), err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('history')
+  .description('View your cloud backup history')
+  .action(async () => {
+    try {
+      await historyCommand();
+    } catch (err) {
+      console.error(chalk.red('\n✖ Error:'), err.message);
+      process.exit(1);
+    }
+  });
+
 // Profile management
 const profile = program.command('profile').description('Manage profiles (personal, work, etc.)');
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memoir-cli",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "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",

package/src/adapters/restore.js

@@ -70,18 +70,36 @@ function remapProjectPaths(backupDir, adapterSource) {
 
   // Step 3: Identify foreign home keys in the backup
   // A "home key" is a dir that: has memory/, OR is a prefix of other dirs, AND is not a sub-project
+  // Also detect alternate local encodings (e.g. -C-Users-X and C--Users-X are the same machine)
   const foreignHomeKeys = new Set();
+  const localAltKeys = new Set(); // alternate encodings of local home dir
+
+  // Detect alternate local encodings by checking if a dir resolves to the same homedir
+  const home = os.homedir();
+  const homeNormalized = home.toLowerCase().replace(/[\\/:]/g, '');
 
   for (const entry of backupEntries) {
-    // Skip dirs that already belong to this machine
+    // Skip dirs that already match the primary local key
     if (entry === localHomeKey || entry.startsWith(localHomeKey + '-')) continue;
 
+    // Check if this entry is an alternate encoding of the local home dir
+    const entryNormalized = entry.replace(/^[-]/, '').toLowerCase().replace(/[-]/g, '');
+    if (entryNormalized === homeNormalized || homeNormalized.endsWith(entryNormalized) || entryNormalized.endsWith(homeNormalized)) {
+      // This is an alternate encoding of the local home — treat as local, not foreign
+      localAltKeys.add(entry);
+      continue;
+    }
+
     // Is this a sub-project of another backup dir? Then skip — its parent handles it
     const isSubProject = backupEntries.some(other =>
       other !== entry && entry.startsWith(other + '-')
     );
     if (isSubProject) continue;
 
+    // Is this a sub-project of an alternate local key? Skip too
+    const isAltSubProject = [...localAltKeys].some(alt => entry.startsWith(alt + '-'));
+    if (isAltSubProject) continue;
+
     // Has memory/ subfolder = definitely a home key
     const hasMemory = fs.existsSync(path.join(projectsDir, entry, 'memory'));
     // Is a prefix of other dirs = likely a home key
@@ -116,6 +134,33 @@ function remapProjectPaths(backupDir, adapterSource) {
   return remaps;
 }
 
+// Merge memory dirs from a foreign machine — copies files that don't exist locally,
+// and for files that exist on both, keeps the newer version.
+async function mergeMemoryDirs(src, dest) {
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      await fs.ensureDir(destPath);
+      await mergeMemoryDirs(srcPath, destPath);
+    } else {
+      if (await fs.pathExists(destPath)) {
+        // Both machines have this file — keep the newer one
+        const srcStat = await fs.stat(srcPath);
+        const destStat = await fs.stat(destPath);
+        if (srcStat.mtimeMs > destStat.mtimeMs) {
+          await fs.copy(srcPath, destPath);
+        }
+      } else {
+        // File only exists on foreign machine — always copy it
+        await fs.copy(srcPath, destPath);
+      }
+    }
+  }
+}
+
 async function syncFiles(src, dest, changes) {
   const entries = await fs.readdir(src, { withFileTypes: true });
   for (const entry of entries) {
@@ -194,8 +239,8 @@ export async function restoreMemories(sourceDir, spinner, onlyFilter = null, aut
               const newDir = path.join(backupDir, 'projects', remap.newName);
               if (await fs.pathExists(oldDir)) {
                 if (await fs.pathExists(newDir)) {
-                  // Merge into existing directory
-                  await syncFiles(oldDir, newDir, { added: [], updated: [], skipped: [] });
+                  // Merge into existing directory — force-copy new files from foreign machine
+                  await mergeMemoryDirs(oldDir, newDir);
                   await fs.remove(oldDir);
                 } else {
                   await fs.move(oldDir, newDir);

package/src/cloud/auth.js

@@ -0,0 +1,112 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { SUPABASE_URL, SUPABASE_ANON_KEY } from './constants.js';
+
+const isWin = process.platform === 'win32';
+const configDir = isWin
+  ? path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'memoir')
+  : path.join(os.homedir(), '.config', 'memoir');
+const AUTH_FILE = path.join(configDir, 'auth.json');
+
+async function supaFetch(endpoint, options = {}) {
+  const url = `${SUPABASE_URL}${endpoint}`;
+  const res = await fetch(url, {
+    ...options,
+    headers: {
+      'apikey': SUPABASE_ANON_KEY,
+      'Content-Type': 'application/json',
+      ...options.headers,
+    },
+  });
+  return res;
+}
+
+export async function signUp(email, password) {
+  const res = await supaFetch('/auth/v1/signup', {
+    method: 'POST',
+    body: JSON.stringify({ email, password }),
+  });
+  const data = await res.json();
+  if (!res.ok) throw new Error(data.error_description || data.msg || 'Sign up failed');
+  return data;
+}
+
+export async function signIn(email, password) {
+  const res = await supaFetch('/auth/v1/token?grant_type=password', {
+    method: 'POST',
+    body: JSON.stringify({ email, password }),
+  });
+  const data = await res.json();
+  if (!res.ok) throw new Error(data.error_description || data.msg || 'Sign in failed');
+  return data;
+}
+
+export async function refreshSession(refreshToken) {
+  const res = await supaFetch('/auth/v1/token?grant_type=refresh_token', {
+    method: 'POST',
+    body: JSON.stringify({ refresh_token: refreshToken }),
+  });
+  const data = await res.json();
+  if (!res.ok) throw new Error(data.error_description || data.msg || 'Token refresh failed');
+  return data;
+}
+
+export async function saveSession(session) {
+  await fs.ensureDir(configDir);
+  const payload = {
+    access_token: session.access_token,
+    refresh_token: session.refresh_token,
+    expires_at: Date.now() + (session.expires_in * 1000),
+    user: {
+      id: session.user.id,
+      email: session.user.email,
+    },
+  };
+  await fs.writeFile(AUTH_FILE, JSON.stringify(payload, null, 2), { mode: 0o600 });
+  return payload;
+}
+
+export async function getSession() {
+  if (!await fs.pathExists(AUTH_FILE)) return null;
+
+  const stored = await fs.readJson(AUTH_FILE);
+
+  // If token expires within 60 seconds, refresh
+  if (stored.expires_at < Date.now() + 60000) {
+    try {
+      const refreshed = await refreshSession(stored.refresh_token);
+      return await saveSession(refreshed);
+    } catch {
+      // Refresh failed — session is dead
+      await fs.remove(AUTH_FILE);
+      return null;
+    }
+  }
+
+  return stored;
+}
+
+export async function logout() {
+  if (await fs.pathExists(AUTH_FILE)) {
+    await fs.remove(AUTH_FILE);
+  }
+}
+
+export async function isLoggedIn() {
+  const session = await getSession();
+  return !!session;
+}
+
+export async function getSubscription(session) {
+  const res = await supaFetch('/rest/v1/subscriptions?select=*&user_id=eq.' + session.user.id, {
+    headers: {
+      'Authorization': `Bearer ${session.access_token}`,
+    },
+  });
+  const data = await res.json();
+  if (!res.ok || !data.length) return { status: 'free' };
+  return data[0];
+}
+
+export { AUTH_FILE, supaFetch };

package/src/cloud/constants.js

@@ -0,0 +1,5 @@
+export const SUPABASE_URL = 'https://oqrkxytbahfwjhcbyzrx.supabase.co';
+export const SUPABASE_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Im9xcmt4eXRiYWhmd2poY2J5enJ4Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzMyMTQ4MzMsImV4cCI6MjA4ODc5MDgzM30.jOKOi73OJgIgi1zj0VOIQkGp0xqS3ee4gfCjpdqCnvM';
+export const STORAGE_BUCKET = 'memoir-backups';
+export const MAX_BACKUPS_FREE = 3;
+export const MAX_BACKUPS_PRO = 50;

package/src/cloud/storage.js

@@ -0,0 +1,212 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { createGzip, createGunzip } from 'zlib';
+import { pipeline } from 'stream/promises';
+import { Readable, Writable } from 'stream';
+import { SUPABASE_URL, SUPABASE_ANON_KEY, STORAGE_BUCKET, MAX_BACKUPS_FREE, MAX_BACKUPS_PRO } from './constants.js';
+
+// Bundle a directory into a JSON manifest + gzip
+async function bundleDir(dir) {
+  const files = [];
+
+  async function walk(currentDir, prefix = '') {
+    const entries = await fs.readdir(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await walk(fullPath, relPath);
+      } else {
+        const content = await fs.readFile(fullPath);
+        files.push({
+          path: relPath,
+          content: content.toString('base64'),
+        });
+      }
+    }
+  }
+
+  await walk(dir);
+  const json = JSON.stringify(files);
+  const buffer = Buffer.from(json, 'utf-8');
+
+  // Gzip
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    const gzip = createGzip({ level: 9 });
+    gzip.on('data', chunk => chunks.push(chunk));
+    gzip.on('end', () => resolve(Buffer.concat(chunks)));
+    gzip.on('error', reject);
+    gzip.end(buffer);
+  });
+}
+
+// Unbundle gzipped JSON back to a directory
+async function unbundleToDir(gzipped, destDir) {
+  const decompressed = await new Promise((resolve, reject) => {
+    const chunks = [];
+    const gunzip = createGunzip();
+    gunzip.on('data', chunk => chunks.push(chunk));
+    gunzip.on('end', () => resolve(Buffer.concat(chunks)));
+    gunzip.on('error', reject);
+    gunzip.end(gzipped);
+  });
+
+  const files = JSON.parse(decompressed.toString('utf-8'));
+
+  for (const file of files) {
+    const fullPath = path.join(destDir, file.path);
+    await fs.ensureDir(path.dirname(fullPath));
+    await fs.writeFile(fullPath, Buffer.from(file.content, 'base64'));
+  }
+
+  return files.length;
+}
+
+// Upload backup to Supabase Storage + insert metadata
+export async function uploadBackup(stagingDir, session, toolResults) {
+  const gzipped = await bundleDir(stagingDir);
+
+  const backupId = crypto.randomUUID();
+  const storagePath = `${session.user.id}/${backupId}.gz`;
+
+  // Upload to Storage
+  const uploadRes = await fetch(`${SUPABASE_URL}/storage/v1/object/${STORAGE_BUCKET}/${storagePath}`, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${session.access_token}`,
+      'apikey': SUPABASE_ANON_KEY,
+      'Content-Type': 'application/octet-stream',
+    },
+    body: gzipped,
+  });
+
+  if (!uploadRes.ok) {
+    const err = await uploadRes.text();
+    throw new Error(`Upload failed: ${err}`);
+  }
+
+  // Get next version number
+  const versionRes = await fetch(
+    `${SUPABASE_URL}/rest/v1/backups?select=version&user_id=eq.${session.user.id}&order=version.desc&limit=1`,
+    {
+      headers: {
+        'Authorization': `Bearer ${session.access_token}`,
+        'apikey': SUPABASE_ANON_KEY,
+      },
+    }
+  );
+  const versionData = await versionRes.json();
+  const nextVersion = (versionData.length > 0 ? versionData[0].version : 0) + 1;
+
+  // Count files in staging dir
+  let fileCount = 0;
+  const countFiles = async (dir) => {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+      if (e.isDirectory()) await countFiles(path.join(dir, e.name));
+      else fileCount++;
+    }
+  };
+  await countFiles(stagingDir);
+
+  // Insert metadata
+  const tools = toolResults.map(r => r.adapter.name);
+  const metaRes = await fetch(`${SUPABASE_URL}/rest/v1/backups`, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${session.access_token}`,
+      'apikey': SUPABASE_ANON_KEY,
+      'Content-Type': 'application/json',
+      'Prefer': 'return=representation',
+    },
+    body: JSON.stringify({
+      user_id: session.user.id,
+      tool_count: tools.length,
+      file_count: fileCount,
+      size_bytes: gzipped.length,
+      tools,
+      storage_path: storagePath,
+      machine_name: os.hostname(),
+      version: nextVersion,
+    }),
+  });
+
+  if (!metaRes.ok) {
+    const err = await metaRes.text();
+    throw new Error(`Failed to save backup metadata: ${err}`);
+  }
+
+  const backup = (await metaRes.json())[0];
+  return { ...backup, sizeBytes: gzipped.length };
+}
+
+// Download a specific backup
+export async function downloadBackup(backup, destDir, session) {
+  const res = await fetch(`${SUPABASE_URL}/storage/v1/object/${STORAGE_BUCKET}/${backup.storage_path}`, {
+    headers: {
+      'Authorization': `Bearer ${session.access_token}`,
+      'apikey': SUPABASE_ANON_KEY,
+    },
+  });
+
+  if (!res.ok) throw new Error(`Download failed: ${await res.text()}`);
+
+  const gzipped = Buffer.from(await res.arrayBuffer());
+  const fileCount = await unbundleToDir(gzipped, destDir);
+  return fileCount;
+}
+
+// List backups for user
+export async function listBackups(session) {
+  const res = await fetch(
+    `${SUPABASE_URL}/rest/v1/backups?select=*&user_id=eq.${session.user.id}&order=created_at.desc`,
+    {
+      headers: {
+        'Authorization': `Bearer ${session.access_token}`,
+        'apikey': SUPABASE_ANON_KEY,
+      },
+    }
+  );
+
+  if (!res.ok) throw new Error('Failed to fetch backup history');
+  return res.json();
+}
+
+// Delete old backups beyond the limit
+export async function cleanupOldBackups(session, isPro) {
+  const maxBackups = isPro ? MAX_BACKUPS_PRO : MAX_BACKUPS_FREE;
+  const backups = await listBackups(session);
+
+  if (backups.length <= maxBackups) return 0;
+
+  const toDelete = backups.slice(maxBackups);
+  let deleted = 0;
+
+  for (const backup of toDelete) {
+    // Delete from storage
+    await fetch(`${SUPABASE_URL}/storage/v1/object/${STORAGE_BUCKET}/${backup.storage_path}`, {
+      method: 'DELETE',
+      headers: {
+        'Authorization': `Bearer ${session.access_token}`,
+        'apikey': SUPABASE_ANON_KEY,
+      },
+    });
+
+    // Delete metadata row
+    await fetch(`${SUPABASE_URL}/rest/v1/backups?id=eq.${backup.id}`, {
+      method: 'DELETE',
+      headers: {
+        'Authorization': `Bearer ${session.access_token}`,
+        'apikey': SUPABASE_ANON_KEY,
+      },
+    });
+
+    deleted++;
+  }
+
+  return deleted;
+}
+
+export { bundleDir, unbundleToDir };

package/src/commands/cloud.js

@@ -0,0 +1,173 @@
+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 { getSession, getSubscription } from '../cloud/auth.js';
+import { uploadBackup, downloadBackup, listBackups, cleanupOldBackups } from '../cloud/storage.js';
+import { extractMemories } from '../adapters/index.js';
+import { MAX_BACKUPS_FREE } from '../cloud/constants.js';
+
+export async function cloudPushCommand(options = {}) {
+  const session = await getSession();
+  if (!session) {
+    console.log('\n' + boxen(
+      chalk.red('✖ Not logged in') + '\n\n' +
+      chalk.white('Run ') + chalk.cyan('memoir login') + chalk.white(' first.'),
+      { padding: 1, borderStyle: 'round', borderColor: 'red' }
+    ) + '\n');
+    return;
+  }
+
+  const sub = await getSubscription(session);
+  const isPro = sub.status === 'pro';
+
+  // Check backup count for free users
+  if (!isPro) {
+    const existing = await listBackups(session);
+    if (existing.length >= MAX_BACKUPS_FREE) {
+      console.log('\n' + boxen(
+        chalk.yellow('Free plan limit reached') + '\n\n' +
+        chalk.white(`You have ${existing.length}/${MAX_BACKUPS_FREE} backups.`) + '\n' +
+        chalk.white('Oldest backup will be replaced.') + '\n\n' +
+        chalk.gray('Upgrade to Pro for 50 backups + version history.'),
+        { padding: 1, borderStyle: 'round', borderColor: 'yellow' }
+      ) + '\n');
+    }
+  }
+
+  console.log();
+  const spinner = ora({ text: chalk.gray('Scanning AI tools...'), spinner: 'dots' }).start();
+
+  const stagingDir = path.join(os.tmpdir(), `memoir-cloud-${Date.now()}`);
+  await fs.ensureDir(stagingDir);
+
+  try {
+    const onlyFilter = options.only ? options.only.split(',').map(t => t.trim().toLowerCase()) : null;
+    const foundAny = await extractMemories(stagingDir, spinner, onlyFilter);
+
+    if (!foundAny) {
+      spinner.fail(chalk.yellow('No AI tools found to back up.'));
+      return;
+    }
+
+    // Collect tool results for metadata
+    const toolResults = [];
+    const entries = await fs.readdir(stagingDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        toolResults.push({ adapter: { name: entry.name } });
+      }
+    }
+
+    spinner.start(chalk.gray('Uploading to memoir cloud...'));
+
+    const backup = await uploadBackup(stagingDir, session, toolResults);
+
+    // Cleanup old backups
+    const deleted = await cleanupOldBackups(session, isPro);
+
+    spinner.stop();
+
+    const sizeStr = backup.sizeBytes < 1024
+      ? `${backup.sizeBytes}B`
+      : backup.sizeBytes < 1024 * 1024
+        ? `${(backup.sizeBytes / 1024).toFixed(1)}KB`
+        : `${(backup.sizeBytes / (1024 * 1024)).toFixed(1)}MB`;
+
+    console.log(boxen(
+      gradient.pastel('  Backed up to cloud  ') + '\n\n' +
+      chalk.green('✔ ') + chalk.white(`Version ${backup.version}`) + '\n' +
+      chalk.gray(`  ${backup.file_count} files, ${sizeStr}`) + '\n' +
+      chalk.gray(`  from ${os.hostname()}`) +
+      (deleted > 0 ? '\n' + chalk.gray(`  ${deleted} old backup${deleted > 1 ? 's' : ''} cleaned up`) : '') + '\n\n' +
+      chalk.gray('Restore with: ') + chalk.cyan('memoir cloud restore'),
+      { padding: 1, borderStyle: 'round', borderColor: 'green', dimBorder: true }
+    ) + '\n');
+
+  } catch (error) {
+    spinner.fail(chalk.red('Cloud push failed: ') + error.message);
+  } finally {
+    await fs.remove(stagingDir);
+  }
+}
+
+export async function cloudRestoreCommand(options = {}) {
+  const session = await getSession();
+  if (!session) {
+    console.log('\n' + boxen(
+      chalk.red('✖ Not logged in') + '\n\n' +
+      chalk.white('Run ') + chalk.cyan('memoir login') + chalk.white(' first.'),
+      { padding: 1, borderStyle: 'round', borderColor: 'red' }
+    ) + '\n');
+    return;
+  }
+
+  console.log();
+  const spinner = ora({ text: chalk.gray('Fetching from memoir cloud...'), spinner: 'dots' }).start();
+
+  try {
+    const backups = await listBackups(session);
+
+    if (backups.length === 0) {
+      spinner.fail(chalk.yellow('No backups found in the cloud.'));
+      console.log(chalk.gray('\n  Run ') + chalk.cyan('memoir cloud push') + chalk.gray(' to create your first backup.\n'));
+      return;
+    }
+
+    // Use specified version or latest
+    let backup;
+    if (options.version) {
+      backup = backups.find(b => b.version === parseInt(options.version));
+      if (!backup) {
+        spinner.fail(chalk.red(`Version ${options.version} not found.`));
+        console.log(chalk.gray('\n  Run ') + chalk.cyan('memoir history') + chalk.gray(' to see available versions.\n'));
+        return;
+      }
+    } else {
+      backup = backups[0]; // Latest
+    }
+
+    spinner.text = chalk.gray(`Downloading version ${backup.version}...`);
+
+    const stagingDir = path.join(os.tmpdir(), `memoir-cloud-restore-${Date.now()}`);
+    await fs.ensureDir(stagingDir);
+
+    const fileCount = await downloadBackup(backup, stagingDir, session);
+
+    spinner.text = chalk.gray('Restoring files...');
+
+    // Use the existing restore logic
+    const { restoreMemories } = await import('../adapters/restore.js');
+    const onlyFilter = options.only ? options.only.split(',').map(t => t.trim().toLowerCase()) : null;
+    const autoYes = options.yes || false;
+
+    const restored = await restoreMemories(stagingDir, spinner, onlyFilter, autoYes);
+
+    spinner.stop();
+
+    if (restored) {
+      const date = new Date(backup.created_at).toLocaleDateString();
+      console.log(boxen(
+        gradient.pastel('  Restored from cloud  ') + '\n\n' +
+        chalk.green('✔ ') + chalk.white(`Version ${backup.version}`) + chalk.gray(` from ${date}`) + '\n' +
+        chalk.gray(`  ${backup.tools.join(', ')}`) + '\n' +
+        (backup.machine_name ? chalk.gray(`  Originally from ${backup.machine_name}`) + '\n' : '') + '\n' +
+        chalk.gray('Restart your AI tools to pick up the changes.'),
+        { padding: 1, borderStyle: 'round', borderColor: 'green', dimBorder: true }
+      ) + '\n');
+    } else {
+      console.log('\n' + boxen(
+        chalk.yellow('Nothing was restored.'),
+        { padding: 1, borderStyle: 'round', borderColor: 'yellow' }
+      ) + '\n');
+    }
+
+    await fs.remove(stagingDir);
+
+  } catch (error) {
+    spinner.fail(chalk.red('Cloud restore failed: ') + error.message);
+  }
+}

package/src/commands/history.js

@@ -0,0 +1,65 @@
+import chalk from 'chalk';
+import boxen from 'boxen';
+import gradient from 'gradient-string';
+import { getSession } from '../cloud/auth.js';
+import { listBackups } from '../cloud/storage.js';
+
+export async function historyCommand() {
+  const session = await getSession();
+  if (!session) {
+    console.log('\n' + boxen(
+      chalk.red('✖ Not logged in') + '\n\n' +
+      chalk.white('Run ') + chalk.cyan('memoir login') + chalk.white(' first.'),
+      { padding: 1, borderStyle: 'round', borderColor: 'red' }
+    ) + '\n');
+    return;
+  }
+
+  try {
+    const backups = await listBackups(session);
+
+    if (backups.length === 0) {
+      console.log('\n' + boxen(
+        chalk.yellow('No backups yet.') + '\n\n' +
+        chalk.gray('Run ') + chalk.cyan('memoir cloud push') + chalk.gray(' to create your first backup.'),
+        { padding: 1, borderStyle: 'round', borderColor: 'yellow' }
+      ) + '\n');
+      return;
+    }
+
+    console.log();
+
+    const lines = backups.map((b, i) => {
+      const date = new Date(b.created_at);
+      const dateStr = date.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
+      const timeStr = date.toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit' });
+
+      const sizeStr = b.size_bytes < 1024
+        ? `${b.size_bytes}B`
+        : b.size_bytes < 1024 * 1024
+          ? `${(b.size_bytes / 1024).toFixed(1)}KB`
+          : `${(b.size_bytes / (1024 * 1024)).toFixed(1)}MB`;
+
+      const latest = i === 0 ? chalk.green(' ← latest') : '';
+      const machine = b.machine_name ? chalk.gray(` from ${b.machine_name}`) : '';
+
+      return (
+        chalk.white.bold(`  v${b.version}`) + `  ${dateStr} ${timeStr}` + latest + '\n' +
+        chalk.gray(`      ${b.file_count} files, ${sizeStr}`) + machine + '\n' +
+        chalk.gray(`      ${b.tools.join(', ')}`)
+      );
+    });
+
+    console.log(boxen(
+      gradient.pastel('  memoir history  ') + '\n\n' +
+      chalk.gray(`${session.user.email} — ${backups.length} backup${backups.length !== 1 ? 's' : ''}`) + '\n\n' +
+      lines.join('\n\n') + '\n\n' +
+      chalk.gray('─'.repeat(36)) + '\n' +
+      chalk.gray('Restore a version: ') + chalk.cyan('memoir cloud restore --version 3'),
+      { padding: 1, borderStyle: 'round', borderColor: 'cyan', dimBorder: true }
+    ) + '\n');
+
+  } catch (error) {
+    console.log('\n' + chalk.red('Error: ') + error.message + '\n');
+  }
+}

package/src/commands/login.js

@@ -0,0 +1,93 @@
+import chalk from 'chalk';
+import boxen from 'boxen';
+import gradient from 'gradient-string';
+import inquirer from 'inquirer';
+import { signIn, signUp, saveSession, getSession, logout, getSubscription } from '../cloud/auth.js';
+
+export async function loginCommand() {
+  // Check if already logged in
+  const existing = await getSession();
+  if (existing) {
+    const sub = await getSubscription(existing);
+    console.log('\n' + boxen(
+      gradient.pastel('  memoir cloud  ') + '\n\n' +
+      chalk.green('✔ Already logged in as ') + chalk.cyan(existing.user.email) + '\n' +
+      chalk.gray('Plan: ') + (sub.status === 'pro' ? chalk.green('Pro') : chalk.yellow('Free')),
+      { padding: 1, borderStyle: 'round', borderColor: 'green', dimBorder: true }
+    ) + '\n');
+    return;
+  }
+
+  console.log();
+
+  const { action } = await inquirer.prompt([{
+    type: 'list',
+    name: 'action',
+    message: 'Sign in or create account?',
+    choices: [
+      { name: 'Sign in (existing account)', value: 'signin' },
+      { name: 'Create account', value: 'signup' },
+    ],
+  }]);
+
+  const { email } = await inquirer.prompt([{
+    type: 'input',
+    name: 'email',
+    message: 'Email:',
+    validate: v => v.includes('@') ? true : 'Enter a valid email',
+  }]);
+
+  const { password } = await inquirer.prompt([{
+    type: 'password',
+    name: 'password',
+    message: 'Password:',
+    mask: '*',
+    validate: v => v.length >= 6 ? true : 'Password must be at least 6 characters',
+  }]);
+
+  try {
+    let session;
+
+    if (action === 'signup') {
+      const result = await signUp(email, password);
+      if (result.access_token) {
+        session = await saveSession(result);
+      } else {
+        // Email confirmation required
+        console.log('\n' + boxen(
+          chalk.green('✔ Account created!') + '\n\n' +
+          chalk.white('Check your email to confirm, then run ') + chalk.cyan('memoir login') + chalk.white(' again.'),
+          { padding: 1, borderStyle: 'round', borderColor: 'green' }
+        ) + '\n');
+        return;
+      }
+    } else {
+      const result = await signIn(email, password);
+      session = await saveSession(result);
+    }
+
+    const sub = await getSubscription(session);
+
+    console.log('\n' + boxen(
+      gradient.pastel('  memoir cloud  ') + '\n\n' +
+      chalk.green('✔ Logged in as ') + chalk.cyan(session.user.email) + '\n' +
+      chalk.gray('Plan: ') + (sub.status === 'pro' ? chalk.green('Pro') : chalk.yellow('Free')) + '\n\n' +
+      chalk.gray('Try: ') + chalk.cyan('memoir cloud push') + chalk.gray(' to back up to the cloud'),
+      { padding: 1, borderStyle: 'round', borderColor: 'green', dimBorder: true }
+    ) + '\n');
+
+  } catch (error) {
+    console.log('\n' + boxen(
+      chalk.red('✖ ' + error.message),
+      { padding: 1, borderStyle: 'round', borderColor: 'red' }
+    ) + '\n');
+  }
+}
+
+export async function logoutCommand() {
+  await logout();
+  console.log('\n' + boxen(
+    chalk.green('✔ Logged out'),
+    { padding: 1, borderStyle: 'round', borderColor: 'green', dimBorder: true }
+  ) + '\n');
+}