memoir-cli 1.0.0

package/README.md

@@ -0,0 +1,103 @@
+<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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+*Never lose your AI's context again. Sync Gemini CLI, Claude Code, and more across all your devices instantly.*
+
+</div>
+
+---
+
+## 💡 The Problem
+
+You spend weeks teaching your local AI CLI exactly how you like your code formatted, your preferred architectural patterns, and your project's unique context.
+
+Then, you switch laptops. Or you want to share that setup with your team.
+
+Suddenly, you're starting from scratch. Your AI's "memory" is trapped in hidden `.gemini` or `.claude` folders on a single machine.
+
+## 🚀 The Solution
+
+`memoir` is a zero-friction CLI tool that seamlessly extracts, backs up, and restores your AI's memory across any computer. You bring your own storage (a private GitHub repo or an iCloud/Dropbox folder), and `memoir` handles the rest safely and securely.
+
+No locked-in SaaS, no lost context, no complex shell scripts.
+
+### Supported Integrations
+- [x] **Gemini CLI**
+- [x] **Claude CLI**
+- [ ] *Cursor (Coming Soon)*
+- [ ] *GitHub Copilot (Coming Soon)*
+
+---
+
+## 🛠️ Installation
+
+Install globally via npm so you can use it anywhere on your machine:
+
+```bash
+npm install -g memoir-cli
+```
+
+## ⚡ Quick Start
+
+### 1. Initialize
+Run the setup wizard. We'll help you securely link a private GitHub repository or a local sync folder.
+
+```bash
+memoir init
+```
+
+### 2. Backup Your Memory
+Just had a great session? Save your AI's learned context to the cloud:
+
+```bash
+memoir push
+# or simply use the alias:
+memoir remember
+```
+
+### 3. Restore Anywhere
+Got a new machine? Pull your brain down instantly:
+
+```bash
+memoir restore
+# or:
+memoir pull
+```
+
+---
+
+## 🔒 Security First
+
+Your AI memory files often sit right next to sensitive API keys and OAuth tokens. **`memoir` is designed to be paranoid.**
+
+Our specialized adapters intelligently filter your directories. We **only** sync configuration files, custom prompts, and markdown memory (`GEMINI.md`, `CLAUDE.md`). We will never touch, copy, or push `.env` files, `.key` files, or credential caches.
+
+---
+
+## 🗺️ Roadmap: The Future of Data Portability
+
+We believe developers shouldn't be locked into a single AI ecosystem.
+
+**Coming in v2.0: The Migration Engine**
+Currently, `memoir` backs up your files exactly as they are. Soon, you will be able to run `memoir migrate --from claude --to gemini`. The CLI will automatically translate your Claude Code instructions into Gemini CLI facts, allowing you to fluidly swap AI providers without losing a drop of context.
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Whether it's adding an adapter for a new AI CLI, improving the UI, or helping build the Migration Engine.
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## 📄 License
+
+Distributed under the MIT License. See `LICENSE` for more information.

package/bin/memoir.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import chalk from 'chalk';
+import boxen from 'boxen';
+import gradient from 'gradient-string';
+import { initCommand } from '../src/commands/init.js';
+import { pushCommand } from '../src/commands/push.js';
+import { restoreCommand } from '../src/commands/restore.js';
+
+const VERSION = '1.0.0';
+
+program
+  .name('memoir')
+  .description('Your AI remembers everything. Sync it everywhere.')
+  .version(VERSION);
+
+program
+  .command('init')
+  .description('Initialize and configure memoir storage preferences')
+  .action(async () => {
+    try {
+      await initCommand();
+    } catch (err) {
+      console.error(chalk.red('\n✖ Error during initialization:'), err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('push')
+  .alias('remember')
+  .description('Sync your AI memory to your configured storage')
+  .action(async () => {
+    try {
+      await pushCommand();
+    } catch (err) {
+      console.error(chalk.red('\n✖ Error during sync:'), err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('restore')
+  .alias('pull')
+  .description('Restore your AI memory from your configured storage')
+  .action(async () => {
+    try {
+      await restoreCommand();
+    } catch (err) {
+      console.error(chalk.red('\n✖ Error during restore:'), err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('migrate')
+  .description('Migrate memory/context from one AI bot to another (e.g. Claude to Gemini)')
+  .action(() => {
+    console.log('\n' + boxen(
+      gradient.pastel('memoir migrate (Coming Soon)') + '\n\n' +
+      chalk.white('We are actively developing the ability to instantly translate') + '\n' +
+      chalk.white('and swap your context/memories between different AI providers.') + '\n\n' +
+      chalk.cyan('Stay tuned for updates!'),
+      { padding: 1, borderStyle: 'round', borderColor: 'yellow', align: 'center' }
+    ) + '\n');
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "memoir-cli",
+  "version": "1.0.0",
+  "description": "Your AI remembers everything. Sync it everywhere.",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "memoir": "bin/memoir.js"
+  },
+  "scripts": {
+    "start": "node bin/memoir.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "ai",
+    "cli",
+    "sync",
+    "memory",
+    "memoir",
+    "gemini",
+    "claude",
+    "backup",
+    "restore"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "boxen": "^7.1.1",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "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

@@ -0,0 +1,42 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import chalk from 'chalk';
+
+const home = os.homedir();
+
+export const adapters = [
+  {
+    name: 'Gemini CLI',
+    source: path.join(home, '.gemini'),
+    filter: (src) => {
+      const basename = path.basename(src);
+      const ignored = ['.git', 'oauth_creds.json', 'google_accounts.json', 'tmp', 'history'];
+      return !ignored.includes(basename);
+    }
+  },
+  {
+    name: 'Claude CLI',
+    source: path.join(home, '.claude'),
+    filter: (src) => {
+      const basename = path.basename(src);
+      return !basename.endsWith('.key') && basename !== '.env';
+    }
+  }
+];
+
+export async function extractMemories(stagingDir, spinner) {
+  let foundAny = false;
+  
+  for (const adapter of adapters) {
+    if (await fs.pathExists(adapter.source)) {
+      spinner.text = `Found ${chalk.cyan(adapter.name)} memory... copying to staging`;
+      const dest = path.join(stagingDir, adapter.name.toLowerCase().replace(' ', '-'));
+      await fs.ensureDir(dest);
+      await fs.copy(adapter.source, dest, { filter: adapter.filter });
+      foundAny = true;
+    }
+  }
+  
+  return foundAny;
+}

package/src/adapters/restore.js

@@ -0,0 +1,43 @@
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import inquirer from 'inquirer';
+import { adapters } from '../adapters/index.js';
+
+export async function restoreMemories(sourceDir, spinner) {
+  let restoredAny = false;
+
+  for (const adapter of adapters) {
+    const backupDir = path.join(sourceDir, adapter.name.toLowerCase().replace(' ', '-'));
+    
+    if (await fs.pathExists(backupDir)) {
+      spinner.stop();
+      
+      console.log('\\n' + chalk.yellow(`⚠ Found backup for ${chalk.bold(adapter.name)}.`));
+      const { confirm } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'confirm',
+          message: `Restore ${adapter.name} memory? This will overwrite existing configuration files!`,
+          default: false
+        }
+      ]);
+
+      spinner.start();
+      
+      if (confirm) {
+        spinner.text = `Restoring ${chalk.cyan(adapter.name)} memory to ${adapter.source}...`;
+        await fs.ensureDir(adapter.source);
+        // Copy files from backup to the real source directory
+        await fs.copy(backupDir, adapter.source, { overwrite: true });
+        restoredAny = true;
+      } else {
+        spinner.info(chalk.gray(`Skipped restoring ${adapter.name}.`));
+        spinner.start();
+      }
+    }
+  }
+
+  return restoredAny;
+}

package/src/commands/init.js

@@ -0,0 +1,81 @@
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import open from 'open';
+import boxen from 'boxen';
+import gradient from 'gradient-string';
+import { saveConfig } from '../config.js';
+
+export async function initCommand() {
+  const title = gradient.pastel.multiline('memoir \\nYour AI Remembers Everything');
+  console.log('\\n' + boxen(title, { 
+    padding: 1, 
+    margin: 1, 
+    borderStyle: 'round', 
+    borderColor: 'cyan',
+    align: 'center'
+  }));
+
+  console.log(chalk.gray("Let's configure where your AI knowledge will be safely stored.\\n"));
+
+  const answers = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'provider',
+      message: 'Choose your storage provider:',
+      choices: [
+        { name: '☁️  Git Repository ' + chalk.gray('(GitHub, GitLab - Best for syncing across computers)'), value: 'git' },
+        { name: '📂 Local Directory ' + chalk.gray('(Dropbox, iCloud - Best for local backups)'), value: 'local' }
+      ]
+    },
+    {
+      type: 'input',
+      name: 'localPath',
+      message: 'Enter the full path to your sync directory ' + chalk.gray('(e.g., ~/Dropbox/memoir):'),
+      when: (answers) => answers.provider === 'local',
+      validate: (input) => input.trim() !== '' ? true : chalk.red('✖ Path is required')
+    },
+    {
+      type: 'confirm',
+      name: 'openBrowser',
+      message: 'Need to create an empty GitHub repository right now?',
+      when: (answers) => answers.provider === 'git',
+      default: false
+    }
+  ]);
+
+  if (answers.openBrowser) {
+    console.log(chalk.cyan('\\n↗ Opening GitHub... Create an empty private repository, then return here.\\n'));
+    await open('https://github.com/new');
+  }
+
+  const finalAnswers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'gitRepo',
+      message: 'Repository URL ' + chalk.gray('(e.g., git@github.com:username/ai-memory.git):'),
+      when: () => answers.provider === 'git',
+      validate: (input) => {
+        if (input.trim() === '') return chalk.red('✖ Repo URL is required');
+        if (!input.includes('github.com') && !input.includes('gitlab.com')) {
+          return chalk.yellow('⚠ Warning: This does not look like a standard GitHub/GitLab URL. Please verify.');
+        }
+        return true;
+      }
+    }
+  ]);
+
+  const config = {
+    provider: answers.provider,
+    localPath: answers.localPath,
+    gitRepo: finalAnswers.gitRepo
+  };
+
+  await saveConfig(config);
+
+  console.log('\\n' + boxen(
+    chalk.green('✔ Configuration saved successfully!') + '\\n\\n' +
+    chalk.white('To backup your memory, run:') + '\\n' +
+    chalk.cyan.bold('memoir push'),
+    { padding: 1, borderStyle: 'single', borderColor: 'green' }
+  ) + '\\n');
+}

package/src/commands/push.js

@@ -0,0 +1,50 @@
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import ora from 'ora';
+import { getConfig } from '../config.js';
+import { extractMemories } from '../adapters/index.js';
+import { syncToLocal, syncToGit } from '../providers/index.js';
+
+export async function pushCommand() {
+  const config = await getConfig();
+  
+  if (!config) {
+    console.log('\\n' + chalk.red('✖ memoir is not configured.'));
+    console.log(`Run ${chalk.cyan('memoir init')} to set up your storage provider.\\n`);
+    return;
+  }
+
+  console.log();
+  const spinner = ora('Initializing AI memory sync...').start();
+
+  // Create a temporary staging directory
+  const stagingDir = path.join(os.tmpdir(), `memoir-staging-${Date.now()}`);
+  await fs.ensureDir(stagingDir);
+
+  try {
+    spinner.text = 'Scanning system for AI configurations...';
+    
+    // Pass spinner so adapter can update it
+    const foundAny = await extractMemories(stagingDir, spinner);
+    
+    if (!foundAny) {
+      spinner.warn(chalk.yellow('No supported AI memory folders found on this system.'));
+      return;
+    }
+
+    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);
+    } else {
+      spinner.fail(chalk.red(`Unknown provider: ${config.provider}`));
+    }
+  } catch (error) {
+    spinner.fail(chalk.red('Sync failed: ') + error.message);
+  } finally {
+    // Clean up staging directory
+    await fs.remove(stagingDir);
+  }
+}

package/src/commands/restore.js

@@ -0,0 +1,49 @@
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import ora from 'ora';
+import { getConfig } from '../config.js';
+import { fetchFromLocal, fetchFromGit } from '../providers/restore.js';
+
+export async function restoreCommand() {
+  const config = await getConfig();
+  
+  if (!config) {
+    console.log('\\n' + chalk.red('✖ memoir is not configured.'));
+    console.log(`Run ${chalk.cyan('memoir init')} to set up your storage provider and fetch your files.\\n`);
+    return;
+  }
+
+  console.log();
+  const spinner = ora('Initializing AI memory restore...').start();
+
+  // Create a temporary staging directory to hold the downloaded files
+  const stagingDir = path.join(os.tmpdir(), `memoir-restore-${Date.now()}`);
+  await fs.ensureDir(stagingDir);
+
+  try {
+    let restored = false;
+
+    if (config.provider === 'local' || config.provider.includes('local')) {
+      restored = await fetchFromLocal(config, stagingDir, spinner);
+    } else if (config.provider === 'git' || config.provider.includes('git')) {
+      restored = await fetchFromGit(config, stagingDir, spinner);
+    } else {
+      spinner.fail(chalk.red(`Unknown provider: ${config.provider}`));
+      return;
+    }
+
+    if (restored) {
+      spinner.succeed(chalk.green('Restore complete! Your AI bots have their memories back.'));
+    } else {
+      spinner.info(chalk.yellow('No memories were restored.'));
+    }
+
+  } catch (error) {
+    spinner.fail(chalk.red('Restore failed: ') + error.message);
+  } finally {
+    // Clean up staging directory
+    await fs.remove(stagingDir);
+  }
+}

package/src/config.js

@@ -0,0 +1,18 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+
+const CONFIG_DIR = path.join(os.homedir(), '.config', 'memoir');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+export async function getConfig() {
+  if (await fs.pathExists(CONFIG_FILE)) {
+    return fs.readJson(CONFIG_FILE);
+  }
+  return null;
+}
+
+export async function saveConfig(config) {
+  await fs.ensureDir(CONFIG_DIR);
+  await fs.writeJson(CONFIG_FILE, config, { spaces: 2 });
+}

package/src/index.js

@@ -0,0 +1,4 @@
+// Entry point for the memoir library, if used programmatically
+export { getConfig, saveConfig } from './config.js';
+export { extractMemories } from './adapters/index.js';
+export { syncToLocal, syncToGit } from './providers/index.js';

package/src/providers/index.js

@@ -0,0 +1,42 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import chalk from 'chalk';
+import { execSync } from 'child_process';
+
+export async function syncToLocal(config, stagingDir, spinner) {
+  const destDir = config.localPath;
+  if (!destDir) throw new Error('Local path is not configured.');
+  
+  // Expand tilde if user used it
+  const resolvedDest = destDir.replace(/^~/, os.homedir());
+  
+  spinner.text = `Syncing files to local directory: ${chalk.cyan(resolvedDest)}`;
+  await fs.ensureDir(resolvedDest);
+  
+  await fs.copy(stagingDir, resolvedDest);
+  spinner.succeed(chalk.green('Sync complete! ') + chalk.gray(`(Saved to ${resolvedDest})`));
+}
+
+export async function syncToGit(config, stagingDir, spinner) {
+  const repoUrl = config.gitRepo;
+  if (!repoUrl) throw new Error('Git repository is not configured.');
+  
+  spinner.text = `Authenticating and syncing with Git remote: ${chalk.cyan(repoUrl)}`;
+  
+  try {
+    execSync('git init', { cwd: stagingDir, stdio: 'ignore' });
+    execSync('git branch -m main', { cwd: stagingDir, stdio: 'ignore' });
+    execSync('git add .', { cwd: stagingDir, stdio: 'ignore' });
+    execSync('git config user.name "memoir" && git config user.email "bot@memoir.dev"', { cwd: stagingDir, stdio: 'ignore' });
+    execSync('git commit -m "chore: memoir backup"', { cwd: stagingDir, stdio: 'ignore' });
+    
+    spinner.text = `Pushing data to ${chalk.cyan(repoUrl)}...`;
+    // We ignore stdio to prevent spam, but if it fails it will throw
+    execSync(`git push --force ${repoUrl} main`, { cwd: stagingDir, stdio: 'ignore' });
+    
+    spinner.succeed(chalk.green('Sync complete! ') + chalk.gray('(Uploaded securely to GitHub)'));
+  } catch (err) {
+    throw new Error('Failed to push to git repository. Ensure your SSH keys are configured and the repository exists.');
+  }
+}

package/src/providers/restore.js

@@ -0,0 +1,38 @@
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { execSync } from 'child_process';
+import { restoreMemories } from '../adapters/restore.js';
+
+export async function fetchFromLocal(config, stagingDir, spinner) {
+  const sourceDir = config.localPath;
+  if (!sourceDir) throw new Error('Local path is not configured.');
+  
+  const resolvedSource = sourceDir.replace(/^~/, os.homedir());
+  
+  if (!(await fs.pathExists(resolvedSource))) {
+    throw new Error(`The backup directory does not exist: ${resolvedSource}`);
+  }
+
+  spinner.text = `Fetching data from local directory: ${chalk.cyan(resolvedSource)}`;
+  await fs.copy(resolvedSource, stagingDir);
+  
+  return await restoreMemories(stagingDir, spinner);
+}
+
+export async function fetchFromGit(config, stagingDir, spinner) {
+  const repoUrl = config.gitRepo;
+  if (!repoUrl) throw new Error('Git repository is not configured.');
+  
+  spinner.text = `Cloning memory from Git remote: ${chalk.cyan(repoUrl)}`;
+  
+  try {
+    // Clone depth 1 to make it fast
+    execSync(`git clone --depth 1 ${repoUrl} .`, { cwd: stagingDir, stdio: 'ignore' });
+  } catch (err) {
+    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);
+}