claude-memory-agent 2.1.0 → 2.2.1

package/bin/cli.js

@@ -247,7 +247,17 @@ function main() {
     switch (command) {
         case 'install':
         case 'setup':
-            runPython('install.py', args.slice(1));
+            // Run the onboarding wizard
+            try {
+                const { main: runOnboarding } = require('./onboarding');
+                runOnboarding().catch(err => {
+                    console.error('Setup error:', err.message);
+                    process.exit(1);
+                });
+            } catch (e) {
+                // Fallback to Python installer if onboarding deps missing
+                runPython('install.py', args.slice(1));
+            }
             break;
 
         case 'start':

package/bin/lib/banner.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const chalk = require('chalk');
+const gradient = require('gradient-string');
+
+const BANNER = `
+  ██████╗██╗      █████╗ ██╗   ██╗██████╗ ███████╗
+ ██╔════╝██║     ██╔══██╗██║   ██║██╔══██╗██╔════╝
+ ██║     ██║     ███████║██║   ██║██║  ██║█████╗
+ ██║     ██║     ██╔══██║██║   ██║██║  ██║██╔══╝
+ ╚██████╗███████╗██║  ██║╚██████╔╝██████╔╝███████╗
+  ╚═════╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝
+ ███╗   ███╗███████╗███╗   ███╗ ██████╗ ██████╗ ██╗   ██╗
+ ████╗ ████║██╔════╝████╗ ████║██╔═══██╗██╔══██╗╚██╗ ██╔╝
+ ██╔████╔██║█████╗  ██╔████╔██║██║   ██║██████╔╝ ╚████╔╝
+ ██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║██║   ██║██╔══██╗  ╚██╔╝
+ ██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║╚██████╔╝██║  ██║   ██║
+ ╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═╝   ╚═╝`;
+
+const VERSION = 'v2.1.0';
+
+/**
+ * Print the Claude Memory Agent ASCII art banner with gradient coloring.
+ * Uses a cool blue-to-purple gradient (mind -> cristal).
+ */
+function printBanner() {
+    const coolGradient = gradient(['#0575E6', '#7B68EE', '#A855F7', '#6C63FF']);
+    console.log(coolGradient(BANNER));
+
+    // Center the version string beneath the banner
+    const bannerWidth = 56; // approximate width of the widest banner line
+    const padding = Math.max(0, Math.floor((bannerWidth - VERSION.length) / 2));
+    const centeredVersion = ' '.repeat(padding) + VERSION;
+    console.log('');
+    console.log(chalk.dim(centeredVersion));
+    console.log('');
+}
+
+module.exports = { printBanner };

package/bin/lib/environment.js

@@ -0,0 +1,166 @@
+'use strict';
+
+const os = require('os');
+const http = require('http');
+const { execSync } = require('child_process');
+const chalk = require('chalk');
+
+/**
+ * Try running a command and return its stdout, or null on failure.
+ * @param {string} cmd - Command to execute
+ * @returns {string|null}
+ */
+function tryExec(cmd) {
+    try {
+        return execSync(cmd, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5000,
+        }).trim();
+    } catch (_) {
+        return null;
+    }
+}
+
+/**
+ * Detect the Python interpreter available on this system.
+ * Tries python3, python, py in order. Returns { found, version, cmd }.
+ * @returns {{ found: boolean, version: string|null, cmd: string|null }}
+ */
+function detectPython() {
+    const commands = ['python3', 'python', 'py'];
+    for (const cmd of commands) {
+        const output = tryExec(`${cmd} --version`);
+        if (output && output.includes('Python 3')) {
+            const match = output.match(/Python\s+([\d.]+)/);
+            return { found: true, version: match ? match[1] : output, cmd };
+        }
+    }
+    return { found: false, version: null, cmd: null };
+}
+
+/**
+ * Detect whether Claude Code CLI is installed.
+ * @returns {{ found: boolean, version: string|null }}
+ */
+function detectClaude() {
+    const commands = process.platform === 'win32'
+        ? ['claude', 'claude.cmd', 'claude-code', 'claude-code.cmd']
+        : ['claude', 'claude-code'];
+
+    for (const cmd of commands) {
+        const output = tryExec(`${cmd} --version`);
+        if (output) {
+            const firstLine = output.split('\n')[0].trim();
+            return { found: true, version: firstLine };
+        }
+    }
+    return { found: false, version: null };
+}
+
+/**
+ * Check whether Ollama is running and list available models.
+ * Makes an HTTP GET to localhost:11434/api/tags with a 2-second timeout.
+ * @returns {Promise<{ running: boolean, models: string[] }>}
+ */
+function detectOllama() {
+    return new Promise((resolve) => {
+        const req = http.get('http://localhost:11434/api/tags', { timeout: 2000 }, (res) => {
+            let data = '';
+            res.on('data', (chunk) => { data += chunk; });
+            res.on('end', () => {
+                try {
+                    const json = JSON.parse(data);
+                    const models = (json.models || []).map((m) => {
+                        const name = m.name || '';
+                        return name.includes(':') ? name.split(':')[0] : name;
+                    });
+                    resolve({ running: true, models });
+                } catch (_) {
+                    resolve({ running: false, models: [] });
+                }
+            });
+        });
+
+        req.on('error', () => resolve({ running: false, models: [] }));
+        req.on('timeout', () => {
+            req.destroy();
+            resolve({ running: false, models: [] });
+        });
+    });
+}
+
+/**
+ * Detect the full environment: OS, Node, Python, Claude Code, and Ollama.
+ * @returns {Promise<Object>} Environment information object
+ */
+async function detectEnvironment() {
+    const python = detectPython();
+    const claude = detectClaude();
+    const ollama = await detectOllama();
+
+    return {
+        os: {
+            platform: os.platform(),
+            arch: os.arch(),
+            release: os.release(),
+        },
+        node: {
+            version: process.version,
+            path: process.execPath,
+        },
+        python,
+        claude,
+        ollama,
+    };
+}
+
+/**
+ * Print the environment detection results in a formatted, colored layout.
+ * @param {Object} env - Environment object from detectEnvironment()
+ */
+function printEnvironment(env) {
+    const ok = chalk.green('\u2713');
+    const warn = chalk.yellow('!');
+
+    console.log('');
+    console.log(chalk.bold('  Environment Detection'));
+    console.log(chalk.dim('  ' + '\u2500'.repeat(40)));
+
+    // OS
+    console.log(`  ${ok} ${chalk.bold('OS')}         ${env.os.platform} ${env.os.arch} (${env.os.release})`);
+
+    // Node
+    console.log(`  ${ok} ${chalk.bold('Node.js')}    ${env.node.version}`);
+
+    // Python
+    if (env.python.found) {
+        console.log(`  ${ok} ${chalk.bold('Python')}     ${env.python.version} ${chalk.dim('(' + env.python.cmd + ')')}`);
+    } else {
+        console.log(`  ${warn} ${chalk.bold('Python')}     ${chalk.yellow('not found')} ${chalk.dim('(install Python 3.9+)')}`);
+    }
+
+    // Claude Code
+    if (env.claude.found) {
+        console.log(`  ${ok} ${chalk.bold('Claude')}     ${env.claude.version}`);
+    } else {
+        console.log(`  ${warn} ${chalk.bold('Claude')}     ${chalk.yellow('not found')} ${chalk.dim('(npm i -g @anthropic-ai/claude-code)')}`);
+    }
+
+    // Ollama
+    if (env.ollama.running) {
+        console.log(`  ${ok} ${chalk.bold('Ollama')}     running`);
+        if (env.ollama.models.length > 0) {
+            const modelList = env.ollama.models.join(', ');
+            console.log(`             ${chalk.dim('models: ' + modelList)}`);
+        } else {
+            console.log(`             ${chalk.dim('no models pulled')}`);
+        }
+    } else {
+        console.log(`  ${warn} ${chalk.bold('Ollama')}     ${chalk.yellow('not running')} ${chalk.dim('(optional - for ollama provider)')}`);
+    }
+
+    console.log('');
+}
+
+module.exports = { detectEnvironment, printEnvironment };

package/bin/lib/installer.js

@@ -0,0 +1,291 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync, spawn } = require('child_process');
+const ora = require('ora');
+
+/**
+ * Detect which Python command is available (python3, python, or py).
+ * @returns {string|null} The command string, or null if none found
+ */
+function detectPythonCmd() {
+    const commands = ['python3', 'python', 'py'];
+    for (const cmd of commands) {
+        try {
+            const output = execSync(`${cmd} --version`, {
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 5000,
+            });
+            if (output && output.includes('Python 3')) {
+                return cmd;
+            }
+        } catch (_) {
+            // try next
+        }
+    }
+    return null;
+}
+
+/**
+ * Run a command synchronously with shell on Windows.
+ * @param {string} cmd - Command to execute
+ * @param {string} cwd - Working directory
+ * @returns {{ success: boolean, output: string }}
+ */
+function runSync(cmd, cwd) {
+    try {
+        const output = execSync(cmd, {
+            encoding: 'utf8',
+            cwd: cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 300000, // 5 minutes for pip installs
+            shell: true,
+        });
+        return { success: true, output: output || '' };
+    } catch (err) {
+        const stderr = err.stderr ? err.stderr.toString() : err.message;
+        return { success: false, output: stderr };
+    }
+}
+
+/**
+ * Build the .env file content string from the config object.
+ * @param {Object} config - Wizard configuration selections
+ * @param {string} agentDir - Path to the agent directory
+ * @returns {string} .env file contents
+ */
+function buildEnvContent(config, agentDir) {
+    const timestamp = new Date().toISOString();
+    const dbPath = config.dbPath || path.join(agentDir, 'memories.db').replace(/\\/g, '/');
+    const memoryUrl = 'http://' + (config.host === '0.0.0.0' ? 'localhost' : config.host) + ':' + config.port;
+
+    const lines = [
+        '# Claude Memory Agent Configuration',
+        '# Generated by onboarding wizard',
+        '# Date: ' + timestamp,
+        '',
+        '# Server Configuration',
+        'HOST=' + config.host,
+        'PORT=' + config.port,
+        'MEMORY_AGENT_URL=' + memoryUrl,
+        '',
+        '# Embedding Configuration',
+        'EMBEDDING_PROVIDER=' + config.provider,
+        'EMBEDDING_MODEL=' + config.model,
+        '',
+        '# Ollama Configuration (only needed if EMBEDDING_PROVIDER=ollama)',
+        'OLLAMA_HOST=http://localhost:11434',
+        '',
+        '# Database Configuration',
+        'DATABASE_PATH=' + dbPath,
+        'USE_VECTOR_INDEX=true',
+        'DB_POOL_SIZE=5',
+        'DB_TIMEOUT=30.0',
+        '',
+        '# Logging',
+        'LOG_LEVEL=' + config.logLevel,
+        '',
+        '# Authentication',
+        'AUTH_ENABLED=' + (config.authEnabled ? 'true' : 'false'),
+        '',
+        '# Memory Tiers',
+        'TIER_HOT_MAX_AGE_DAYS=' + config.hotTierDays,
+        'TIER_WARM_MAX_AGE_DAYS=' + config.warmTierDays,
+    ];
+
+    return lines.join('\n') + '\n';
+}
+
+/**
+ * Build the argument array for install.py based on wizard config.
+ * @param {Object} config - Wizard configuration selections
+ * @returns {string[]} Arguments for install.py
+ */
+function buildInstallArgs(config) {
+    const args = ['--auto', '--skip-env', '--skip-deps', '--skip-claude-check'];
+
+    if (config.scope === 'project') {
+        args.push('--scope', 'project', '--project-path', config.projectPath);
+    } else if (config.scope === 'global') {
+        args.push('--scope', 'global');
+    } else if (config.scope === 'both') {
+        args.push('--scope', 'both', '--project-path', config.projectPath);
+    }
+
+    if (!config.autoStart) {
+        args.push('--no-start');
+    }
+
+    return args;
+}
+
+/**
+ * Run the full installer sequence, bridging from the Node wizard to install.py.
+ *
+ * Steps:
+ *   1. Write .env file from config
+ *   2. Check Python dependencies
+ *   3. Install Python packages
+ *   4. Creating configuration (already done)
+ *   5. Configure Claude Code MCP via install.py
+ *   6. Install hooks (handled by install.py)
+ *   7. Start Memory Agent (handled by install.py if autoStart)
+ *
+ * @param {Object} config - All wizard selections
+ * @param {string} agentDir - Absolute path to the memory-agent directory
+ * @returns {Promise<{ success: boolean, errors: string[] }>}
+ */
+async function runInstaller(config, agentDir) {
+    const errors = [];
+
+    // Detect Python
+    const pythonCmd = detectPythonCmd();
+    if (!pythonCmd) {
+        return { success: false, errors: ['Python 3 is required but was not found on this system.'] };
+    }
+
+    // --- Step 1: Write .env file ---
+    const spinnerEnv = ora('Writing configuration file (.env)').start();
+    try {
+        const envContent = buildEnvContent(config, agentDir);
+        const envPath = path.join(agentDir, '.env');
+        fs.writeFileSync(envPath, envContent, 'utf8');
+        spinnerEnv.succeed('Configuration file written (.env)');
+    } catch (err) {
+        spinnerEnv.fail('Failed to write .env file');
+        errors.push('Failed to write .env: ' + err.message);
+        return { success: false, errors };
+    }
+
+    // --- Step 2: Check Python dependencies ---
+    const spinnerCheck = ora('Checking Python dependencies').start();
+    const checkResult = runSync(pythonCmd + ' -m pip check', agentDir);
+    if (checkResult.success) {
+        spinnerCheck.succeed('Python dependencies verified');
+    } else {
+        spinnerCheck.warn('Dependency check had warnings (will attempt install)');
+    }
+
+    // --- Step 3: Install Python packages ---
+    const spinnerPip = ora('Installing Python packages').start();
+    const requirementsPath = path.join(agentDir, 'requirements.txt');
+    if (fs.existsSync(requirementsPath)) {
+        const pipResult = runSync(
+            pythonCmd + ' -m pip install -r requirements.txt -q --disable-pip-version-check',
+            agentDir
+        );
+        if (pipResult.success) {
+            spinnerPip.succeed('Python packages installed');
+        } else {
+            spinnerPip.fail('Failed to install Python packages');
+            errors.push('pip install failed: ' + pipResult.output);
+        }
+    } else {
+        spinnerPip.warn('requirements.txt not found, skipping');
+    }
+
+    // --- Step 4: Configuration already created ---
+    const spinnerConfig = ora('Creating configuration').start();
+    spinnerConfig.succeed('Configuration created (.env written in step 1)');
+
+    // --- Step 5: Configure Claude Code MCP ---
+    const spinnerMcp = ora('Configuring Claude Code MCP').start();
+    const installPyPath = path.join(agentDir, 'install.py');
+    if (fs.existsSync(installPyPath)) {
+        const installArgs = buildInstallArgs(config);
+        const mcpResult = runSync(
+            pythonCmd + ' ' + JSON.stringify(installPyPath) + ' ' + installArgs.join(' '),
+            agentDir
+        );
+        if (mcpResult.success) {
+            spinnerMcp.succeed('Claude Code MCP configured');
+        } else {
+            spinnerMcp.fail('MCP configuration had issues');
+            errors.push('install.py: ' + mcpResult.output);
+        }
+    } else {
+        spinnerMcp.warn('install.py not found, skipping MCP configuration');
+    }
+
+    // --- Step 6: Hooks ---
+    const spinnerHooks = ora('Installing hooks').start();
+    if (Array.isArray(config.hooks) && config.hooks.length > 0) {
+        spinnerHooks.succeed('Hooks configured (' + config.hooks.length + ' selected)');
+    } else {
+        spinnerHooks.succeed('No hooks selected (handled by install.py)');
+    }
+
+    // --- Step 7: Start agent ---
+    if (config.autoStart) {
+        const spinnerStart = ora('Starting Memory Agent').start();
+        const startScript = path.join(agentDir, 'main.py');
+        if (fs.existsSync(startScript)) {
+            try {
+                const child = spawn(pythonCmd, [startScript], {
+                    cwd: agentDir,
+                    detached: true,
+                    stdio: 'ignore',
+                    shell: process.platform === 'win32',
+                });
+                child.unref();
+                // Give it a moment to start
+                await new Promise((resolve) => setTimeout(resolve, 2000));
+                spinnerStart.succeed('Memory Agent started (background)');
+            } catch (err) {
+                spinnerStart.fail('Failed to start Memory Agent');
+                errors.push('Start failed: ' + err.message);
+            }
+        } else {
+            spinnerStart.warn('main.py not found, skipping auto-start');
+        }
+    }
+
+    return { success: errors.length === 0, errors };
+}
+
+/**
+ * Basic setup fallback when onboarding wizard dependencies are not available.
+ * Writes a default .env file and attempts Python dependency installation.
+ * @param {string} agentDir - Path to the agent directory
+ */
+async function basicSetup(agentDir) {
+    const config = {
+        scope: 'global',
+        projectPath: null,
+        provider: 'sentence-transformers',
+        model: 'BAAI/bge-base-en-v1.5',
+        port: 8102,
+        host: '127.0.0.1',
+        autoStart: false,
+        logLevel: 'INFO',
+        dbPath: null,
+        authEnabled: false,
+        hotTierDays: 14,
+        warmTierDays: 90,
+        hooks: ['session_start', 'grounding', 'session_end'],
+    };
+
+    // Write .env
+    const envContent = buildEnvContent(config, agentDir);
+    const envPath = path.join(agentDir, '.env');
+    if (!fs.existsSync(envPath)) {
+        fs.writeFileSync(envPath, envContent, 'utf8');
+        console.log('Created default .env configuration');
+    }
+
+    // Install Python deps
+    const pythonCmd = detectPythonCmd();
+    if (pythonCmd) {
+        const reqPath = path.join(agentDir, 'requirements.txt');
+        if (fs.existsSync(reqPath)) {
+            runSync(pythonCmd + ' -m pip install -r requirements.txt -q --disable-pip-version-check', agentDir);
+            console.log('Python dependencies installed');
+        }
+    }
+
+    console.log('Basic setup complete. Run "claude-memory-agent install" for full configuration.');
+}
+
+module.exports = { runInstaller, basicSetup };

package/bin/lib/models.js

@@ -0,0 +1,95 @@
+'use strict';
+
+const chalk = require('chalk');
+
+/**
+ * Embedding models available through the Ollama provider.
+ */
+const OLLAMA_MODELS = [
+    { name: 'all-minilm', tier: 'Light', dim: 384, size: '~46MB', speed: 5, desc: 'Quick searches, low resources' },
+    { name: 'nomic-embed-text', tier: 'Standard', dim: 768, size: '~274MB', speed: 4, desc: 'General purpose (recommended)', recommended: true },
+    { name: 'mxbai-embed-large', tier: 'Pro', dim: 1024, size: '~670MB', speed: 3, desc: 'High-precision recall' },
+    { name: 'snowflake-arctic-embed', tier: 'Pro', dim: 1024, size: '~670MB', speed: 3, desc: 'Multilingual projects' },
+    { name: 'bge-m3', tier: 'Pro', dim: 1024, size: '~1.2GB', speed: 2, desc: 'Dense retrieval, research' },
+];
+
+/**
+ * Embedding models for the sentence-transformers (standalone) provider.
+ */
+const STANDALONE_MODELS = [
+    { name: 'all-MiniLM-L6-v2', tier: 'Light', dim: 384, size: '~80MB', speed: 5, desc: 'Fastest, minimal resources' },
+    { name: 'BAAI/bge-base-en-v1.5', tier: 'Standard', dim: 768, size: '~440MB', speed: 4, desc: 'Good balance (recommended)', recommended: true },
+    { name: 'Alibaba-NLP/gte-large-en-v1.5', tier: 'Pro', dim: 1024, size: '~1.5GB', speed: 3, desc: 'Best quality English' },
+];
+
+/**
+ * Return the model list for a given provider.
+ * @param {'ollama'|'sentence-transformers'} provider
+ * @returns {Array<Object>}
+ */
+function getModelsByProvider(provider) {
+    if (provider === 'ollama') {
+        return OLLAMA_MODELS;
+    }
+    return STANDALONE_MODELS;
+}
+
+/**
+ * Build a star rating string: filled stars followed by empty stars, colored yellow.
+ * @param {number} count - Number of filled stars (out of 5)
+ * @returns {string}
+ */
+function starsString(count) {
+    const filled = '\u2605'.repeat(count);
+    const empty = '\u2606'.repeat(5 - count);
+    return chalk.yellow(filled + empty);
+}
+
+/**
+ * Format a model object into a display string suitable for inquirer choices.
+ *
+ * Example output:
+ *   [Light]  all-minilm         384d  ~46MB   *****  Quick searches [installed]
+ *
+ * @param {Object} model - Model object with name, tier, dim, size, speed, desc
+ * @param {string[]} installedModels - Array of model names currently installed
+ * @returns {string}
+ */
+function formatModelChoice(model, installedModels) {
+    const tierLabel = chalk.cyan('[' + model.tier + ']');
+    const tierPad = 10 - model.tier.length - 2; // account for brackets
+    const tierSpacing = ' '.repeat(Math.max(tierPad, 1));
+
+    const namePad = 26 - model.name.length;
+    const nameSpacing = ' '.repeat(Math.max(namePad, 1));
+
+    const dimStr = chalk.dim(model.dim + 'd');
+    const dimPad = 6 - String(model.dim).length;
+    const dimSpacing = ' '.repeat(Math.max(dimPad, 1));
+
+    const sizeStr = chalk.dim(model.size);
+    const sizePad = 8 - model.size.length;
+    const sizeSpacing = ' '.repeat(Math.max(sizePad, 1));
+
+    const rating = starsString(model.speed);
+
+    const isInstalled = Array.isArray(installedModels) && installedModels.includes(model.name);
+    const installedBadge = isInstalled ? chalk.green(' [installed]') : '';
+
+    return (
+        tierLabel + tierSpacing +
+        model.name + nameSpacing +
+        dimStr + dimSpacing +
+        sizeStr + sizeSpacing +
+        rating + '  ' +
+        model.desc +
+        installedBadge
+    );
+}
+
+module.exports = {
+    OLLAMA_MODELS,
+    STANDALONE_MODELS,
+    getModelsByProvider,
+    formatModelChoice,
+};