specmem-hardwicksoftware 3.7.35 → 3.7.38

package/bin/specmem-cli.cjs

@@ -44,6 +44,20 @@ const SPECMEM_PKG = path.dirname(__dirname);
 const MODELS_DIR = path.join(SPECMEM_PKG, 'models');
 const OPTIMIZED_DIR = path.join(MODELS_DIR, 'optimized');
 
+// Helper: Get compaction proxy port if running
+function getProxyEnv() {
+  try {
+    const portFile = path.join(os.homedir(), '.claude', '.compaction-proxy-port');
+    if (fs.existsSync(portFile)) {
+      const port = parseInt(fs.readFileSync(portFile, 'utf8').trim(), 10);
+      if (port) {
+        return { ANTHROPIC_BASE_URL: `http://127.0.0.1:${port}` };
+      }
+    }
+  } catch (e) {}
+  return {};
+}
+
 const args = process.argv.slice(2);
 const command = args[0] || 'help';
 const subArgs = args.slice(1);
@@ -237,6 +251,20 @@ switch (command) {
   case 'proxy':
     manageProxy(subArgs);
     break;
+  case 'embed':
+    manageEmbed(subArgs);
+    break;
+  case 'config':
+    manageConfig(subArgs);
+    break;
+  case 'minicot':
+  case 'minicott':
+    manageMinicot(subArgs);
+    break;
+  case 'quickstart':
+    // Minimal init without database setup
+    runQuickstart();
+    break;
   case '--version':
   case '-v':
   case 'version':
@@ -570,11 +598,11 @@ ${CYAN}What's configured:${RESET}
       } catch {
         console.log(`${YELLOW}⚠${RESET} Could not install screen, launching  directly...`);
         console.log(`${DIM}Run: claude${RESET}\n`);
-        // Launch  directly without screen
+        // Launch  directly without screen (add proxy env)
         const child = spawn('claude', [], {
           cwd: projectDir,
           stdio: 'inherit',
-          env: { ...process.env, SPECMEM_PROJECT_PATH: projectDir }
+          env: { ...process.env, SPECMEM_PROJECT_PATH: projectDir, ...getProxyEnv() }
         });
         return;
       }
@@ -601,10 +629,12 @@ ${CYAN}What's configured:${RESET}
     console.log(`${DIM}───────────────────────────────────────────────${RESET}`);
 
     // Use -S to create named session, no -d so it attaches immediately
+    // Include proxy env to route through compaction proxy
+    const proxyEnv = getProxyEnv();
     const result = spawnSync('screen', ['-S', screenName, 'claude'], {
       cwd: projectDir,
       stdio: 'inherit',
-      env: { ...process.env, SPECMEM_PROJECT_PATH: projectDir }
+      env: { ...process.env, SPECMEM_PROJECT_PATH: projectDir, ...proxyEnv }
     });
 
     // User has detached or  exited
@@ -909,24 +939,1060 @@ ${BOLD}Aliases:${RESET}
   }
 }
 
+// ============================================================================
+// EMBED COMMAND - Embedding Server Management
+// ============================================================================
+function manageEmbed(args) {
+  const sub = (args[0] || 'status').toLowerCase();
+  const projectPath = process.cwd();
+
+  // Get project-specific paths
+  const specmemDir = path.join(projectPath, 'specmem');
+  const socketDir = path.join(specmemDir, 'run');
+  const socketPath = path.join(socketDir, 'embed.sock');
+  const pidFilePath = path.join(socketDir, 'embedding.pid');
+
+  switch (sub) {
+    case 'start': {
+      // Ensure directories exist
+      if (!fs.existsSync(socketDir)) {
+        fs.mkdirSync(socketDir, { recursive: true });
+      }
+
+      // Check if already running
+      if (fs.existsSync(pidFilePath)) {
+        const pidData = fs.readFileSync(pidFilePath, 'utf8').trim();
+        const [pid] = pidData.split(':');
+        try {
+          process.kill(pid, 0); // Check if process exists
+          console.log(`${YELLOW}Embedding server already running (PID: ${pid})${RESET}`);
+          process.exit(0);
+        } catch (e) {
+          // PID file stale, remove it
+          fs.unlinkSync(pidFilePath);
+        }
+      }
+
+      // Start the embedding server
+      console.log(`${CYAN}Starting embedding server...${RESET}`);
+      const embedScript = path.join(SPECMEM_PKG, 'embedding-sandbox', 'frankenstein-embeddings.py');
+
+      if (!fs.existsSync(embedScript)) {
+        console.log(`${RED}Embedding script not found: ${embedScript}${RESET}`);
+        process.exit(1);
+      }
+
+      const env = {
+        ...process.env,
+        SPECMEM_PROJECT_PATH: projectPath,
+        SPECMEM_EMBEDDING_SOCKET: socketPath,
+      };
+
+      const child = spawn('python3', [embedScript], {
+        cwd: projectPath,
+        env,
+        detached: true,
+        stdio: 'ignore',
+      });
+
+      child.unref();
+
+      // Write PID file
+      fs.writeFileSync(pidFilePath, `${child.pid}:${Date.now()}`, { mode: 0o644 });
+
+      console.log(`${GREEN}Embedding server started (PID: ${child.pid})${RESET}`);
+      console.log(`${DIM}Socket: ${socketPath}${RESET}`);
+      break;
+    }
+
+    case 'stop': {
+      if (!fs.existsSync(pidFilePath)) {
+        console.log(`${YELLOW}No PID file found - server may not be running${RESET}`);
+        process.exit(1);
+      }
+
+      const pidData = fs.readFileSync(pidFilePath, 'utf8').trim();
+      const [pid, timestamp] = pidData.split(':');
+
+      try {
+        process.kill(parseInt(pid), 'SIGTERM');
+        console.log(`${GREEN}Sent SIGTERM to embedding server (PID: ${pid})${RESET}`);
+
+        // Wait a bit then force kill if still alive
+        setTimeout(() => {
+          try {
+            process.kill(parseInt(pid), 0);
+            process.kill(parseInt(pid), 'SIGKILL');
+            console.log(`${YELLOW}Force killed server${RESET}`);
+          } catch (e) {
+            // Process already dead
+          }
+        }, 3000);
+
+        // Remove PID file
+        fs.unlinkSync(pidFilePath);
+        console.log(`${GREEN}Embedding server stopped${RESET}`);
+      } catch (e) {
+        console.log(`${RED}Failed to stop server: ${e.message}${RESET}`);
+        fs.unlinkSync(pidFilePath);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'restart': {
+      // First try to stop
+      if (fs.existsSync(pidFilePath)) {
+        const pidData = fs.readFileSync(pidFilePath, 'utf8').trim();
+        const [pid] = pidData.split(':');
+        try {
+          process.kill(parseInt(pid), 'SIGTERM');
+        } catch (e) {
+          // Already dead
+        }
+        fs.unlinkSync(pidFilePath);
+      }
+
+      // Small delay then start
+      setTimeout(() => {
+        // Recursive call to start
+        manageEmbed(['start']);
+      }, 1000);
+      break;
+    }
+
+    case 'force-restart': {
+      // Force kill regardless of state
+      if (fs.existsSync(pidFilePath)) {
+        const pidData = fs.readFileSync(pidFilePath, 'utf8').trim();
+        const [pid] = pidData.split(':');
+        try {
+          process.kill(parseInt(pid), 'SIGKILL');
+        } catch (e) {
+          // Already dead
+        }
+        fs.unlinkSync(pidFilePath);
+      }
+
+      // Also try to kill any process using the socket
+      try {
+        execSync(`lsof -t ${socketPath} 2>/dev/null | xargs -r kill -9 2>/dev/null || true`, { stdio: 'pipe' });
+      } catch (e) {}
+
+      // Start fresh
+      setTimeout(() => {
+        manageEmbed(['start']);
+      }, 500);
+      break;
+    }
+
+    case 'status': {
+      console.log(`${CYAN}═══ Embedding Server Status ═══${RESET}\n`);
+
+      if (!fs.existsSync(socketDir)) {
+        console.log(`${YELLOW}Project not initialized - no specmem directory${RESET}`);
+        console.log(`${DIM}Run 'specmem init' or 'specmem quickstart' first${RESET}`);
+        process.exit(1);
+      }
+
+      // Check PID file
+      if (fs.existsSync(pidFilePath)) {
+        const pidData = fs.readFileSync(pidFilePath, 'utf8').trim();
+        const [pid, timestamp] = pidData.split(':');
+        console.log(`  PID File: ${GREEN}exists${RESET} (PID: ${pid})`);
+        console.log(`  Started:  ${new Date(parseInt(timestamp)).toLocaleString()}`);
+
+        // Check if process is alive
+        try {
+          process.kill(parseInt(pid), 0);
+          console.log(`  Process:  ${GREEN}running${RESET}`);
+        } catch (e) {
+          console.log(`  Process:  ${RED}dead (stale PID file)${RESET}`);
+        }
+      } else {
+        console.log(`  PID File: ${YELLOW}not found${RESET}`);
+      }
+
+      // Check socket
+      console.log(`\n  Socket:   ${socketPath}`);
+      if (fs.existsSync(socketPath)) {
+        console.log(`            ${GREEN}exists${RESET}`);
+      } else {
+        console.log(`            ${YELLOW}not found${RESET}`);
+      }
+
+      // Check for stopped flag
+      const stoppedFlag = path.join(socketDir, 'embedding.stopped');
+      if (fs.existsSync(stoppedFlag)) {
+        console.log(`\n  ${YELLOW}Server was manually stopped by user${RESET}`);
+        console.log(`  ${DIM}Use 'specmem embed start' to restart${RESET}`);
+      }
+      break;
+    }
+
+    case 'list': {
+      console.log(`${CYAN}═══ All Embedding Servers ═══${RESET}\n`);
+
+      // Find all PID files in common locations
+      const searchPaths = [
+        path.join(os.homedir(), '.specmem'),
+        path.join(projectPath, 'specmem'),
+        path.join(projectPath, '.specmem'),
+      ];
+
+      let found = false;
+      for (const sp of searchPaths) {
+        if (!fs.existsSync(sp)) continue;
+
+        try {
+          const pidFiles = execSync(`find ${sp} -name "embedding.pid" 2>/dev/null`, { encoding: 'utf8' })
+            .trim()
+            .split('\n')
+            .filter(Boolean);
+
+          for (const pf of pidFiles) {
+            const dir = path.dirname(pf);
+            const socketPath = path.join(dir, 'embed.sock');
+
+            if (fs.existsSync(pf)) {
+              const pidData = fs.readFileSync(pf, 'utf8').trim();
+              const [pid, timestamp] = pidData.split(':');
+              const projName = path.basename(path.dirname(path.dirname(dir)));
+
+              let status = `${RED}dead${RESET}`;
+              try {
+                process.kill(parseInt(pid), 0);
+                status = `${GREEN}running${RESET}`;
+              } catch (e) {}
+
+              console.log(`  Project: ${projName}`);
+              console.log(`    PID:     ${pid} (${status})`);
+              console.log(`    Socket:  ${socketPath}`);
+              console.log(`    Started: ${new Date(parseInt(timestamp)).toLocaleString()}`);
+              console.log('');
+              found = true;
+            }
+          }
+        } catch (e) {}
+      }
+
+      if (!found) {
+        console.log(`  ${DIM}No embedding servers found${RESET}`);
+      }
+      break;
+    }
+
+    case 'diagnose': {
+      console.log(`${CYAN}═══ Embedding Server Diagnostics ═══${RESET}\n`);
+
+      console.log(`Project: ${projectPath}`);
+      console.log(`SpecMem Dir: ${specmemDir}`);
+      console.log(`Socket Dir: ${socketDir}`);
+      console.log(`Socket Path: ${socketPath}`);
+      console.log(`PID File: ${pidFilePath}`);
+
+      // Check if directories exist
+      console.log(`\n${CYAN}Directory Status:${RESET}`);
+      console.log(`  specmem/ exists: ${fs.existsSync(specmemDir) ? GREEN + 'yes' + RESET : YELLOW + 'no' + RESET}`);
+      console.log(`  run/ exists: ${fs.existsSync(socketDir) ? GREEN + 'yes' + RESET : YELLOW + 'no' + RESET}`);
+      console.log(`  socket exists: ${fs.existsSync(socketPath) ? GREEN + 'yes' + RESET : YELLOW + 'no' + RESET}`);
+      console.log(`  PID file exists: ${fs.existsSync(pidFilePath) ? GREEN + 'yes' + RESET : YELLOW + 'no' + RESET}`);
+
+      // Check process
+      if (fs.existsSync(pidFilePath)) {
+        const pidData = fs.readFileSync(pidFilePath, 'utf8').trim();
+        const [pid] = pidData.split(':');
+
+        console.log(`\n${CYAN}Process Info:${RESET}`);
+        console.log(`  PID: ${pid}`);
+
+        try {
+          const procPath = `/proc/${pid}`;
+          if (fs.existsSync(procPath)) {
+            const cmdline = fs.readFileSync(path.join(procPath, 'cmdline'), 'utf8').replace(/\0/g, ' ');
+            console.log(`  Command: ${cmdline.slice(0, 100)}`);
+
+            // Check env
+            try {
+              const envPath = path.join(procPath, 'environ');
+              const envData = fs.readFileSync(envPath);
+              const envStr = envData.toString('utf8');
+              const specmemEnv = envStr.split('\0').find(e => e.startsWith('SPECMEM'));
+              if (specmemEnv) {
+                console.log(`  Env: ${specmemEnv.slice(0, 80)}`);
+              }
+            } catch (e) {}
+          } else {
+            console.log(`  ${RED}Process does not exist (stale PID)${RESET}`);
+          }
+        } catch (e) {
+          console.log(`  ${RED}Error reading process: ${e.message}${RESET}`);
+        }
+      }
+
+      // Check socket ownership
+      if (fs.existsSync(socketPath)) {
+        console.log(`\n${CYAN}Socket Status:${RESET}`);
+        try {
+          const stats = fs.statSync(socketPath);
+          console.log(`  Created: ${stats.birthtime}`);
+          console.log(`  Size: ${stats.size} bytes`);
+        } catch (e) {
+          console.log(`  Error: ${e.message}`);
+        }
+      }
+      break;
+    }
+
+    case 'cleanup': {
+      console.log(`${CYAN}Cleaning up stale embedding server files...${RESET}`);
+
+      let cleaned = 0;
+
+      // Clean stale PID files
+      const searchPaths = [
+        path.join(os.homedir(), '.specmem'),
+        path.join(projectPath, 'specmem'),
+        path.join(projectPath, '.specmem'),
+      ];
+
+      for (const sp of searchPaths) {
+        if (!fs.existsSync(sp)) continue;
+
+        try {
+          const pidFiles = execSync(`find ${sp} -name "embedding.pid" 2>/dev/null`, { encoding: 'utf8' })
+            .trim()
+            .split('\n')
+            .filter(Boolean);
+
+          for (const pf of pidFiles) {
+            try {
+              const pidData = fs.readFileSync(pf, 'utf8').trim();
+              const [pid] = pidData.split(':');
+              try {
+                process.kill(parseInt(pid), 0);
+                // Process still alive, skip
+              } catch (e) {
+                // Process dead, remove PID file
+                fs.unlinkSync(pf);
+                console.log(`  Removed stale PID file: ${pf}`);
+                cleaned++;
+              }
+            } catch (e) {}
+          }
+        } catch (e) {}
+      }
+
+      console.log(`${GREEN}Cleaned ${cleaned} stale PID files${RESET}`);
+      break;
+    }
+
+    default:
+      console.log(`${BOLD}Usage:${RESET} specmem embed <command>
+
+${BOLD}Commands:${RESET}
+  ${CYAN}start${RESET}         Start embedding server
+  ${CYAN}stop${RESET}          Stop embedding server
+  ${CYAN}restart${RESET}       Restart embedding server
+  ${CYAN}force-restart${RESET} Force restart (kill and start fresh)
+  ${CYAN}status${RESET}        Show embedding server status
+  ${CYAN}list${RESET}          List all embedding servers
+  ${CYAN}diagnose${RESET}      Full diagnostic info
+  ${CYAN}cleanup${RESET}       Clean up stale PID files
+`);
+  }
+}
+
+// ============================================================================
+// CONFIG COMMAND - Configuration Management
+// ============================================================================
+function manageConfig(args) {
+  const sub = (args[0] || 'list').toLowerCase();
+  const key = args[1];
+  const value = args[2];
+
+  const configDir = path.join(os.homedir(), '.specmem');
+  const configFile = path.join(configDir, 'config.json');
+
+  // Default config values
+  const defaults = {
+    SPECMEM_SEARCH_LIMIT: '5',
+    SPECMEM_THRESHOLD: '0.30',
+    SPECMEM_MAX_CONTENT: '200',
+    SPECMEM_DB_HOST: 'localhost',
+    SPECMEM_DB_PORT: '5432',
+    SPECMEM_EMBEDDING_MODEL: 'BAAI/bge-small-en-v1.5',
+    SPECMEM_EMBEDDING_BATCH_SIZE: '100',
+    SPECMEM_AUTO_CONSOLIDATE: 'true',
+  };
+
+  // Load existing config
+  let config = {};
+  if (fs.existsSync(configFile)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+    } catch (e) {}
+  }
+
+  // Helper to save config
+  const saveConfig = () => {
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+    fs.writeFileSync(configFile, JSON.stringify(config, null, 2), { mode: 0o644 });
+  };
+
+  // Helper to get value (config > env > default)
+  const getValue = (k) => {
+    if (config[k] !== undefined) return config[k];
+    if (process.env[k] !== undefined) return process.env[k];
+    return defaults[k];
+  };
+
+  switch (sub) {
+    case 'list': {
+      console.log(`${CYAN}═══ SpecMem Configuration ═══${RESET}\n`);
+
+      // Show source
+      if (fs.existsSync(configFile)) {
+        console.log(`${GREEN}Config file:${RESET} ${configFile}`);
+      } else {
+        console.log(`${YELLOW}Config file:${RESET} not found (using defaults)`);
+      }
+      console.log('');
+
+      // List all settings
+      const allKeys = [...new Set([...Object.keys(defaults), ...Object.keys(config)])];
+      for (const k of allKeys.sort()) {
+        const val = getValue(k);
+        const def = defaults[k];
+        const isDefault = val === def;
+        const isEnvOverride = process.env[k] !== undefined && config[k] === undefined;
+
+        let source = '';
+        if (isEnvOverride) {
+          source = ` ${DIM}(env override)${RESET}`;
+        } else if (!isDefault) {
+          source = ` ${CYAN}(custom)${RESET}`;
+        } else {
+          source = ` ${DIM}(default)${RESET}`;
+        }
+
+        console.log(`  ${k}: ${val}${source}`);
+      }
+      break;
+    }
+
+    case 'get': {
+      if (!key) {
+        console.log(`${RED}Error: Please specify a key to get${RESET}`);
+        console.log(`Usage: specmem config get <key>`);
+        process.exit(1);
+      }
+
+      const val = getValue(key);
+      console.log(`${key}=${val}`);
+      break;
+    }
+
+    case 'set': {
+      if (!key || value === undefined) {
+        console.log(`${RED}Error: Please specify key and value${RESET}`);
+        console.log(`Usage: specmem config set <key> <value>`);
+        process.exit(1);
+      }
+
+      config[key] = value;
+      saveConfig();
+      console.log(`${GREEN}Set ${key}=${value}${RESET}`);
+      console.log(`${DIM}This will override environment variable ${key}${RESET}`);
+      console.log(`${DIM}To apply, restart your Claude session or set the env var manually${RESET}`);
+      break;
+    }
+
+    case 'unset': {
+      if (!key) {
+        console.log(`${RED}Error: Please specify a key to unset${RESET}`);
+        console.log(`Usage: specmem config unset <key>`);
+        process.exit(1);
+      }
+
+      if (config[key] !== undefined) {
+        delete config[key];
+        saveConfig();
+        console.log(`${GREEN}Unset ${key}${RESET}`);
+        console.log(`${DIM}Now using default: ${defaults[key] || '(none)'}${RESET}`);
+      } else {
+        console.log(`${YELLOW}${key} was not set in config (using default)${RESET}`);
+      }
+      break;
+    }
+
+    case 'reset': {
+      if (fs.existsSync(configFile)) {
+        fs.unlinkSync(configFile);
+        console.log(`${GREEN}Reset config to defaults${RESET}`);
+      } else {
+        console.log(`${YELLOW}No config file to reset${RESET}`);
+      }
+      break;
+    }
+
+    case 'edit': {
+      // Open config file in editor
+      if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+      }
+      if (!fs.existsSync(configFile)) {
+        saveConfig();
+      }
+
+      const editor = process.env.EDITOR || 'nano';
+      try {
+        execSync(`${editor} "${configFile}"`, { stdio: 'inherit' });
+        console.log(`${GREEN}Config file saved${RESET}`);
+      } catch (e) {
+        console.log(`${RED}Failed to open editor: ${e.message}${RESET}`);
+        console.log(`Edit manually: ${configFile}`);
+      }
+      break;
+    }
+
+    default:
+      console.log(`${BOLD}Usage:${RESET} specmem config <command>
+
+${BOLD}Commands:${RESET}
+  ${CYAN}list${RESET}        List all settings with current values
+  ${CYAN}get <key>${RESET}   Get value of specific setting
+  ${CYAN}set <key> <val>${RESET} Set value (persists to config file)
+  ${CYAN}unset <key>${RESET} Remove custom value (use default)
+  ${CYAN}reset${RESET}      Reset all config to defaults
+  ${CYAN}edit${RESET}       Open config file in editor
+
+${BOLD}Configurable Settings:${RESET}
+  SPECMEM_SEARCH_LIMIT        Memory search limit (default: 5)
+  SPECMEM_THRESHOLD           Similarity threshold (default: 0.30)
+  SPECMEM_MAX_CONTENT         Max content length (default: 200)
+  SPECMEM_DB_HOST             Database host
+  SPECMEM_DB_PORT             Database port
+  SPECMEM_EMBEDDING_MODEL     Embedding model name
+  SPECMEM_EMBEDDING_BATCH_SIZE Batch size (default: 100)
+  SPECMEM_AUTO_CONSOLIDATE    Auto consolidation toggle
+`);
+  }
+}
+
+// ============================================================================
+// MINICOT COMMAND - Mini COT (Pythia) Server Management
+// ============================================================================
+function manageMinicot(args) {
+  const sub = (args[0] || 'status').toLowerCase();
+  const projectPath = process.cwd();
+
+  // Get project-specific paths - prefer sockets/, fallback to run/
+  const specmemDir = path.join(projectPath, 'specmem');
+  const socketDir = path.join(specmemDir, 'sockets');
+  const runDir = path.join(specmemDir, 'run');
+  const socketPath = path.join(socketDir, 'minicot.sock');
+  const runSocketPath = path.join(runDir, 'minicot.sock');
+  const pidFilePath = path.join(socketDir, 'minicot.pid');
+  const runPidFilePath = path.join(runDir, 'minicot.pid');
+  const stoppedFlag = path.join(socketDir, 'minicot.stopped');
+  const runStoppedFlag = path.join(runDir, 'minicot.stopped');
+
+  // Helper to find the actual paths in use
+  const getActivePaths = () => {
+    if (fs.existsSync(pidFilePath) || fs.existsSync(socketPath)) {
+      return { socketDir, socketPath, pidFilePath, stoppedFlag };
+    }
+    if (fs.existsSync(runPidFilePath) || fs.existsSync(runSocketPath)) {
+      return { socketDir: runDir, socketPath: runSocketPath, pidFilePath: runPidFilePath, stoppedFlag: runStoppedFlag };
+    }
+    return { socketDir, socketPath, pidFilePath, stoppedFlag };
+  };
+
+  // Helper to get minicot script path
+  const getMinicotScript = () => {
+    const candidates = [
+      path.join(projectPath, 'mini-cot-service.py'),
+      path.join(SPECMEM_PKG, 'mini-cot-service.py'),
+      path.join(projectPath, 'node_modules', 'specmem-hardwicksoftware', 'mini-cot-service.py'),
+      path.join(dirname(process.execPath), 'lib', 'node_modules', 'specmem-hardwicksoftware', 'mini-cot-service.py'),
+    ];
+    for (const c of candidates) {
+      if (fs.existsSync(c)) return c;
+    }
+    return candidates[0]; // Return first candidate anyway for error message
+  };
+
+  switch (sub) {
+    case 'start': {
+      // Ensure directories exist - prefer sockets/, create run/ as fallback
+      if (!fs.existsSync(socketDir)) {
+        fs.mkdirSync(socketDir, { recursive: true });
+      }
+
+      // Check if already running
+      const activePaths = getActivePaths();
+      if (fs.existsSync(activePaths.pidFilePath)) {
+        const pidData = fs.readFileSync(activePaths.pidFilePath, 'utf8').trim();
+        const [pid] = pidData.split(':');
+        try {
+          process.kill(pid, 0);
+          console.log(`${YELLOW}Mini COT server already running (PID: ${pid})${RESET}`);
+          process.exit(0);
+        } catch (e) {
+          fs.unlinkSync(activePaths.pidFilePath);
+        }
+      }
+
+      // Start the minicot server
+      console.log(`${CYAN}Starting Mini COT server...${RESET}`);
+      const minicotScript = getMinicotScript();
+
+      if (!fs.existsSync(minicotScript)) {
+        console.log(`${RED}Mini COT script not found: ${minicotScript}${RESET}`);
+        process.exit(1);
+      }
+
+      const env = {
+        ...process.env,
+        SPECMEM_PROJECT_PATH: projectPath,
+        SPECMEM_MINICOT_SOCKET: socketPath,
+        SPECMEM_MINICOT_MODEL: process.env.SPECMEM_MINICOT_MODEL || 'EleutherAI/pythia-410m',
+      };
+
+      const child = spawn('python3', [minicotScript, '--socket', socketPath], {
+        cwd: projectPath,
+        env,
+        detached: true,
+        stdio: 'ignore',
+      });
+
+      child.unref();
+
+      // Write PID file
+      fs.writeFileSync(pidFilePath, `${child.pid}:${Date.now()}`, { mode: 0o644 });
+
+      console.log(`${GREEN}Mini COT server started (PID: ${child.pid})${RESET}`);
+      console.log(`${DIM}Socket: ${socketPath}${RESET}`);
+      console.log(`${DIM}Model: ${env.SPECMEM_MINICOT_MODEL}${RESET}`);
+      break;
+    }
+
+    case 'stop': {
+      const activePaths = getActivePaths();
+      if (!fs.existsSync(activePaths.pidFilePath)) {
+        console.log(`${YELLOW}No PID file found - server may not be running${RESET}`);
+        process.exit(1);
+      }
+
+      const pidData = fs.readFileSync(activePaths.pidFilePath, 'utf8').trim();
+      const [pid, timestamp] = pidData.split(':');
+
+      try {
+        process.kill(parseInt(pid), 'SIGTERM');
+        console.log(`${GREEN}Sent SIGTERM to Mini COT server (PID: ${pid})${RESET}`);
+
+        setTimeout(() => {
+          try {
+            process.kill(parseInt(pid), 0);
+            process.kill(parseInt(pid), 'SIGKILL');
+            console.log(`${YELLOW}Force killed server${RESET}`);
+          } catch (e) {}
+        }, 3000);
+
+        fs.unlinkSync(activePaths.pidFilePath);
+        console.log(`${GREEN}Mini COT server stopped${RESET}`);
+      } catch (e) {
+        console.log(`${RED}Failed to stop server: ${e.message}${RESET}`);
+        fs.unlinkSync(activePaths.pidFilePath);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'restart': {
+      const activePaths = getActivePaths();
+      if (fs.existsSync(activePaths.pidFilePath)) {
+        const pidData = fs.readFileSync(activePaths.pidFilePath, 'utf8').trim();
+        const [pid] = pidData.split(':');
+        try {
+          process.kill(parseInt(pid), 'SIGTERM');
+        } catch (e) {}
+        fs.unlinkSync(activePaths.pidFilePath);
+      }
+
+      setTimeout(() => {
+        manageMinicot(['start']);
+      }, 1000);
+      break;
+    }
+
+    case 'force-restart': {
+      let activePaths;
+      try {
+        activePaths = getActivePaths();
+      } catch (e) {
+        activePaths = { socketDir, socketPath, pidFilePath, stoppedFlag };
+      }
+
+      if (fs.existsSync(pidFilePath)) {
+        const pidData = fs.readFileSync(pidFilePath, 'utf8').trim();
+        const [pid] = pidData.split(':');
+        try {
+          process.kill(parseInt(pid), 'SIGKILL');
+        } catch (e) {}
+        fs.unlinkSync(pidFilePath);
+      }
+      if (fs.existsSync(runPidFilePath)) {
+        const pidData = fs.readFileSync(runPidFilePath, 'utf8').trim();
+        const [pid] = pidData.split(':');
+        try {
+          process.kill(parseInt(pid), 'SIGKILL');
+        } catch (e) {}
+        fs.unlinkSync(runPidFilePath);
+      }
+
+      // Also try to kill any process using the socket
+      try {
+        execSync(`lsof -t ${socketPath} 2>/dev/null | xargs -r kill -9 2>/dev/null || true`, { stdio: 'pipe' });
+        execSync(`lsof -t ${runSocketPath} 2>/dev/null | xargs -r kill -9 2>/dev/null || true`, { stdio: 'pipe' });
+      } catch (e) {}
+
+      setTimeout(() => {
+        manageMinicot(['start']);
+      }, 500);
+      break;
+    }
+
+    case 'status': {
+      console.log(`${CYAN}═══ Mini COT Server Status ═══${RESET}\n`);
+
+      const activePaths = getActivePaths();
+
+      if (!fs.existsSync(socketDir) && !fs.existsSync(runDir)) {
+        console.log(`${YELLOW}Project not initialized - no specmem directory${RESET}`);
+        console.log(`${DIM}Run 'specmem init' or 'specmem quickstart' first${RESET}`);
+        process.exit(1);
+      }
+
+      // Check PID file
+      if (fs.existsSync(activePaths.pidFilePath)) {
+        const pidData = fs.readFileSync(activePaths.pidFilePath, 'utf8').trim();
+        const [pid, timestamp] = pidData.split(':');
+        console.log(`  PID File: ${GREEN}exists${RESET} (PID: ${pid})`);
+        console.log(`  Started:  ${new Date(parseInt(timestamp)).toLocaleString()}`);
+
+        try {
+          process.kill(parseInt(pid), 0);
+          console.log(`  Process:  ${GREEN}running${RESET}`);
+        } catch (e) {
+          console.log(`  Process:  ${RED}dead (stale PID file)${RESET}`);
+        }
+      } else {
+        console.log(`  PID File: ${YELLOW}not found${RESET}`);
+      }
+
+      // Check socket
+      console.log(`\n  Socket:   ${activePaths.socketPath}`);
+      if (fs.existsSync(activePaths.socketPath)) {
+        console.log(`            ${GREEN}exists${RESET}`);
+      } else {
+        console.log(`            ${YELLOW}not found${RESET}`);
+      }
+
+      // Check stopped flag
+      if (fs.existsSync(stoppedFlag) || fs.existsSync(runStoppedFlag)) {
+        console.log(`\n  ${YELLOW}Server was manually stopped by user${RESET}`);
+        console.log(`  ${DIM}Use 'specmem minicot start' to restart${RESET}`);
+      }
+
+      // Show model info
+      console.log(`\n  Model:    ${process.env.SPECMEM_MINICOT_MODEL || 'EleutherAI/pythia-410m'}${RESET}`);
+      break;
+    }
+
+    case 'list': {
+      console.log(`${CYAN}═══ All Mini COT Servers ═══${RESET}\n`);
+
+      const searchPaths = [
+        path.join(os.homedir(), '.specmem'),
+      ];
+
+      // Add all specmem dirs we can find
+      try {
+        const projDirs = execSync(`find ${os.homedir()} -maxdepth 3 -type d -name "specmem" 2>/dev/null | head -20`, { encoding: 'utf8' })
+          .trim()
+          .split('\n')
+          .filter(Boolean);
+        for (const d of projDirs) {
+          if (!searchPaths.includes(d)) searchPaths.push(d);
+        }
+      } catch (e) {}
+
+      let found = false;
+      for (const sp of searchPaths) {
+        if (!fs.existsSync(sp)) continue;
+
+        for (const subdir of ['sockets', 'run']) {
+          const dir = path.join(sp, subdir);
+          if (!fs.existsSync(dir)) continue;
+
+          const pf = path.join(dir, 'minicot.pid');
+          if (!fs.existsSync(pf)) continue;
+
+          const pidData = fs.readFileSync(pf, 'utf8').trim();
+          const [pid, timestamp] = pidData.split(':');
+          const projName = path.basename(path.dirname(path.dirname(dir)));
+
+          let status = `${RED}dead${RESET}`;
+          try {
+            process.kill(parseInt(pid), 0);
+            status = `${GREEN}running${RESET}`;
+          } catch (e) {}
+
+          console.log(`  Project: ${projName}`);
+          console.log(`    PID:     ${pid} (${status})`);
+          console.log(`    Socket:  ${path.join(dir, 'minicot.sock')}`);
+          console.log(`    Started: ${new Date(parseInt(timestamp)).toLocaleString()}`);
+          console.log('');
+          found = true;
+        }
+      }
+
+      if (!found) {
+        console.log(`  ${DIM}No Mini COT servers found${RESET}`);
+      }
+      break;
+    }
+
+    case 'diagnose': {
+      console.log(`${CYAN}═══ Mini COT Server Diagnostics ═══${RESET}\n`);
+
+      const activePaths = getActivePaths();
+
+      console.log(`Project: ${projectPath}`);
+      console.log(`SpecMem Dir: ${specmemDir}`);
+      console.log(`Socket Dir: ${activePaths.socketDir}`);
+      console.log(`Socket Path: ${activePaths.socketPath}`);
+      console.log(`PID File: ${activePaths.pidFilePath}`);
+
+      // Check if directories exist
+      console.log(`\n${CYAN}Directory Status:${RESET}`);
+      console.log(`  specmem/ exists: ${fs.existsSync(specmemDir) ? GREEN + 'yes' + RESET : YELLOW + 'no' + RESET}`);
+      console.log(`  sockets/ exists: ${fs.existsSync(socketDir) ? GREEN + 'yes' + RESET : YELLOW + 'no' + RESET}`);
+      console.log(`  run/ exists: ${fs.existsSync(runDir) ? GREEN + 'yes' + RESET : YELLOW + 'no' + RESET}`);
+      console.log(`  socket exists: ${fs.existsSync(activePaths.socketPath) ? GREEN + 'yes' + RESET : YELLOW + 'no' + RESET}`);
+      console.log(`  PID file exists: ${fs.existsSync(activePaths.pidFilePath) ? GREEN + 'yes' + RESET : YELLOW + 'no' + RESET}`);
+
+      // Check process
+      if (fs.existsSync(activePaths.pidFilePath)) {
+        const pidData = fs.readFileSync(activePaths.pidFilePath, 'utf8').trim();
+        const [pid] = pidData.split(':');
+
+        console.log(`\n${CYAN}Process Info:${RESET}`);
+        console.log(`  PID: ${pid}`);
+
+        try {
+          const procPath = `/proc/${pid}`;
+          if (fs.existsSync(procPath)) {
+            const cmdline = fs.readFileSync(path.join(procPath, 'cmdline'), 'utf8').replace(/\0/g, ' ');
+            console.log(`  Command: ${cmdline.slice(0, 100)}`);
+
+            try {
+              const envPath = path.join(procPath, 'environ');
+              const envData = fs.readFileSync(envPath);
+              const envStr = envData.toString('utf8');
+              const minicotEnv = envStr.split('\0').find(e => e.startsWith('SPECMEM_MINICOT'));
+              if (minicotEnv) {
+                console.log(`  Env: ${minicotEnv.slice(0, 80)}`);
+              }
+            } catch (e) {}
+          } else {
+            console.log(`  ${RED}Process does not exist (stale PID)${RESET}`);
+          }
+        } catch (e) {
+          console.log(`  ${RED}Error reading process: ${e.message}${RESET}`);
+        }
+      }
+
+      // Check for running minicot processes
+      console.log(`\n${CYAN}Running Python Processes:${RESET}`);
+      try {
+        const procs = execSync(`pgrep -af "mini-cot-service.py" 2>/dev/null || echo ""`, { encoding: 'utf8' }).trim();
+        if (procs) {
+          console.log(procs.split('\n').map(l => `  ${l}`).join('\n'));
+        } else {
+          console.log(`  ${DIM}None found${RESET}`);
+        }
+      } catch (e) {
+        console.log(`  ${DIM}Could not search processes${RESET}`);
+      }
+      break;
+    }
+
+    case 'cleanup': {
+      console.log(`${CYAN}Cleaning up stale Mini COT server files...${RESET}`);
+
+      let cleaned = 0;
+
+      const searchPaths = [
+        path.join(os.homedir(), '.specmem'),
+      ];
+
+      // Find all specmem dirs
+      try {
+        const projDirs = execSync(`find ${os.homedir()} -maxdepth 3 -type d -name "specmem" 2>/dev/null | head -20`, { encoding: 'utf8' })
+          .trim()
+          .split('\n')
+          .filter(Boolean);
+        for (const d of projDirs) {
+          if (!searchPaths.includes(d)) searchPaths.push(d);
+        }
+      } catch (e) {}
+
+      for (const sp of searchPaths) {
+        if (!fs.existsSync(sp)) continue;
+
+        for (const subdir of ['sockets', 'run']) {
+          const dir = path.join(sp, subdir);
+          if (!fs.existsSync(dir)) continue;
+
+          const pf = path.join(dir, 'minicot.pid');
+          if (!fs.existsSync(pf)) continue;
+
+          try {
+            const pidData = fs.readFileSync(pf, 'utf8').trim();
+            const [pid] = pidData.split(':');
+            try {
+              process.kill(parseInt(pid), 0);
+            } catch (e) {
+              fs.unlinkSync(pf);
+              console.log(`  Removed stale PID file: ${pf}`);
+              cleaned++;
+            }
+          } catch (e) {}
+        }
+      }
+
+      console.log(`${GREEN}Cleaned ${cleaned} stale PID files${RESET}`);
+      break;
+    }
+
+    default:
+      console.log(`${BOLD}Usage:${RESET} specmem minicot <command>
+
+${BOLD}Commands:${RESET}
+  ${CYAN}start${RESET}         Start Mini COT server (Pythia-410M)
+  ${CYAN}stop${RESET}          Stop Mini COT server
+  ${CYAN}restart${RESET}       Restart Mini COT server
+  ${CYAN}force-restart${RESET} Force restart (kill and start fresh)
+  ${CYAN}status${RESET}        Show Mini COT server status
+  ${CYAN}list${RESET}          List all Mini COT servers
+  ${CYAN}diagnose${RESET}      Full diagnostic info
+  ${CYAN}cleanup${RESET}       Clean up stale PID files
+`);
+  }
+}
+
+// ============================================================================
+// QUICKSTART - Minimal init without database
+// ============================================================================
+function runQuickstart() {
+  showBanner();
+  console.log(`${CYAN}${BOLD}═══ SpecMem Quickstart ═══${RESET}\n`);
+  console.log(`${DIM}Setting up minimal SpecMem configuration...${RESET}\n`);
+
+  const projectPath = process.cwd();
+  const specmemDir = path.join(projectPath, 'specmem');
+  const configDir = path.join(os.homedir(), '.specmem');
+
+  // Create project directories
+  console.log(`${CYAN}→${RESET} Creating project directories...`);
+  const dirs = ['run', 'sockets', 'logs', 'data'];
+  for (const dir of dirs) {
+    const dirPath = path.join(specmemDir, dir);
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
+  }
+  console.log(`${GREEN}✓${RESET} Created ${specmemDir}/*`);
+
+  // Create global config if needed
+  console.log(`${CYAN}→${RESET} Setting up global config...`);
+  const configFile = path.join(configDir, 'config.json');
+  if (!fs.existsSync(configFile)) {
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+    const defaultConfig = {
+      SPECMEM_SEARCH_LIMIT: '5',
+      SPECMEM_THRESHOLD: '0.30',
+      SPECMEM_MAX_CONTENT: '200',
+      SPECMEM_AUTO_CONSOLIDATE: 'true',
+    };
+    fs.writeFileSync(configFile, JSON.stringify(defaultConfig, null, 2), { mode: 0o644 });
+    console.log(`${GREEN}✓${RESET} Created default config`);
+  } else {
+    console.log(`${DIM}  Config already exists${RESET}`);
+  }
+
+  // Create .env file if needed
+  const envFile = path.join(projectPath, '.env');
+  if (!fs.existsSync(envFile)) {
+    const envContent = `# SpecMem Configuration
+# Database (optional - will use defaults if not set)
+# SPECMEM_DB_HOST=localhost
+# SPECMEM_DB_PORT=5432
+# SPECMEM_DB_NAME=specmem
+
+# Embedding settings
+# SPECMEM_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
+
+# Memory settings
+# SPECMEM_SEARCH_LIMIT=5
+# SPECMEM_THRESHOLD=0.30
+`;
+    fs.writeFileSync(envFile, envContent, { mode: 0o644 });
+    console.log(`${GREEN}✓${RESET} Created .env template`);
+  } else {
+    console.log(`${DIM}  .env already exists${RESET}`);
+  }
+
+  console.log(`
+${GREEN}${BOLD}✓ Quickstart complete!${RESET}
+
+${CYAN}Next steps:${RESET}
+  • Run ${CYAN}specmem embed start${RESET} to start embedding server
+  • Or run ${CYAN}claude${RESET} - SpecMem will auto-start services
+
+${YELLOW}Note:${RESET} Database not configured. Run ${CYAN}specmem init${RESET} for full setup.
+`);
+}
+
 // Show help
 function showHelp() {
   showBanner();
   console.log(`${BOLD}Usage:${RESET} specmem <command>
 
 ${BOLD}Commands:${RESET}
-  ${CYAN}setup${RESET}     First-run setup (download + optimize embedding models)
-  ${CYAN}init${RESET}      Initialize SpecMem for current project
-  ${CYAN}status${RESET}    Check SpecMem status and model info
-  ${CYAN}proxy${RESET}     Manage compaction proxy (enable/disable/status)
+  ${CYAN}setup${RESET}      First-run setup (download + optimize embedding models)
+  ${CYAN}init${RESET}       Initialize SpecMem for current project
+  ${CYAN}quickstart${RESET} Quick setup without database
+  ${CYAN}status${RESET}     Check SpecMem status and model info
+  ${CYAN}proxy${RESET}      Manage compaction proxy (enable/disable/status)
+  ${CYAN}embed${RESET}       Manage embedding server (start/stop/status)
+  ${CYAN}minicot${RESET}    Manage Mini COT server (Pythia-410M)
+  ${CYAN}config${RESET}      Manage configuration settings
   ${CYAN}dashboard${RESET}  Launch the AEGIS dashboard (alias: dash)
-  ${CYAN}doctor${RESET}    Check system requirements
+  ${CYAN}doctor${RESET}     Check system requirements
 
 ${BOLD}Quick Start:${RESET}
-  ${DIM}$${RESET} specmem init    ${DIM}# First time only - optimizes models${RESET}
+  ${DIM}$${RESET} specmem init      ${DIM}# First time only - optimizes models${RESET}
   ${DIM}$${RESET} cd your-project
-  ${DIM}$${RESET} specmem init     ${DIM}# Initialize project${RESET}
-  ${DIM}$${RESET} claude           ${DIM}# Services auto-start with !${RESET}
+  ${DIM}$${RESET} specmem init       ${DIM}# Initialize project${RESET}
+  ${DIM}$${RESET} claude             ${DIM}# Services auto-start with !${RESET}
 
 ${BOLD}What It Does:${RESET}
   SpecMem provides semantic memory for  Code sessions.