@stackmemoryai/stackmemory 0.5.59 → 0.5.61

package/README.md

@@ -1,6 +1,6 @@
 # StackMemory
 
-**Lossless, project-scoped memory for AI tools** • v0.5.51
+**Lossless, project-scoped memory for AI tools** • v0.5.59
 
 StackMemory is a **production-ready memory runtime** for AI coding tools that preserves full project context across sessions:
 
@@ -36,6 +36,110 @@ StackMemory solves this by:
 
 ---
 
+## Features
+
+StackMemory includes powerful features to enhance your AI coding workflow. Enable/disable with `claude-sm config setup`.
+
+### Predictive Edit
+
+Anticipates your next edit and displays suggestions as a status bar overlay. Powered by llama-server and Claude Code's PostToolUse hooks.
+
+```bash
+claude-sm --sweep          # Enable (default: on)
+claude-sm --no-sweep       # Disable
+```
+
+- **How it works**: Analyzes tool outputs and predicts likely follow-up edits
+- **Interface**: Tab to accept, Esc to dismiss
+- **Requirement**: Installs `node-pty` on first use
+
+### Code Review
+
+AI-powered code review using Greptile's codebase-aware analysis. Automatically registers the Greptile MCP server for deep repository understanding.
+
+```bash
+claude-sm --greptile       # Enable (default: on)
+claude-sm --no-greptile    # Disable
+```
+
+- **Tools provided**: `index_repository`, `query_repository`, `get_repository_info`
+- **Requirement**: `GREPTILE_API_KEY` in `.env`
+
+### Prompt Forge
+
+Genetic Eval-driven Prompt Algorithm (GEPA) for automatic system prompt optimization. Evolves your `CLAUDE.md` through mutation, evaluation, and selection.
+
+```bash
+claude-sm --gepa           # Enable
+claude-sm --no-gepa        # Disable (default)
+```
+
+- **Auto-optimize**: Watches `CLAUDE.md` and runs optimization on changes
+- **Strategies**: rephrase, add_examples, remove_redundancy, restructure, add_constraints, simplify
+- **Output**: Before/after comparison with metrics (lines, tokens, rules)
+
+### Model Switcher
+
+Dynamic model routing based on task complexity. Automatically selects the optimal model (Haiku/Sonnet/Opus) for each request.
+
+```bash
+claude-sm --model-routing  # Enable
+claude-sm --no-model-routing  # Disable (default)
+```
+
+- **Cost optimization**: Uses cheaper models for simple tasks
+- **Quality preservation**: Routes complex tasks to more capable models
+
+### Safe Branch
+
+Git worktree isolation for experimental changes. Each session operates in an isolated branch, preventing accidental commits to main.
+
+```bash
+claude-sm --worktree       # Enable
+claude-sm --no-worktree    # Disable (default)
+```
+
+- **Isolation**: Changes happen in a separate worktree
+- **Safety**: Main branch remains untouched until explicit merge
+
+### Mobile Sync
+
+WhatsApp notifications for session updates and task completion. Stay informed even when away from your terminal.
+
+```bash
+claude-sm --whatsapp       # Enable
+claude-sm --no-whatsapp    # Disable (default)
+```
+
+- **Notifications**: Session start, task completion, errors
+- **Interactive**: Reply to trigger actions remotely
+
+### Session Insights
+
+Detailed tracing of session activity for debugging and optimization. Tracks tool calls, timing, and decision paths.
+
+```bash
+claude-sm --tracing        # Enable
+claude-sm --no-tracing     # Disable (default)
+```
+
+- **Visibility**: Full execution trace
+- **Analytics**: Performance metrics and patterns
+
+### Task Alert
+
+Desktop/terminal notifications when long-running tasks complete. Never miss a completed build or test run.
+
+```bash
+claude-sm --notify-on-done # Enable (default: on)
+claude-sm --no-notify-on-done  # Disable
+```
+
+- **Platforms**: macOS notifications, terminal bell
+- **Smart**: Only notifies for tasks taking >10 seconds
+
+---
+
 ## Core concepts (quick mental model)
 
 | Concept        | Meaning                                           |

package/dist/src/cli/claude-sm.js

@@ -37,7 +37,8 @@ const DEFAULT_SM_CONFIG = {
   defaultWhatsApp: false,
   defaultModelRouting: false,
   defaultSweep: true,
-  defaultGreptile: true
+  defaultGreptile: true,
+  defaultGEPA: false
 };
 function getConfigPath() {
   return path.join(os.homedir(), ".stackmemory", "claude-sm.json");
@@ -84,7 +85,8 @@ class ClaudeSM {
       useModelRouting: this.smConfig.defaultModelRouting,
       useThinkingMode: false,
       useSweep: this.smConfig.defaultSweep,
-      useGreptile: this.smConfig.defaultGreptile
+      useGreptile: this.smConfig.defaultGreptile,
+      useGEPA: this.smConfig.defaultGEPA
     };
     this.stackmemoryPath = this.findStackMemory();
     this.worktreeScriptPath = path.join(
@@ -154,6 +156,67 @@ class ClaudeSM {
     }
     return null;
   }
+  gepaProcess = null;
+  startGEPAWatcher() {
+    const claudeMdPath = fs.existsSync(path.join(process.cwd(), "CLAUDE.md")) ? path.join(process.cwd(), "CLAUDE.md") : null;
+    if (!claudeMdPath) {
+      console.log(chalk.gray("   Prompt Forge: disabled (no CLAUDE.md found)"));
+      return;
+    }
+    const gepaPaths = [
+      // From dist/src/cli -> scripts/gepa (3 levels up)
+      path.join(__dirname, "../../../scripts/gepa/hooks/auto-optimize.js"),
+      // From src/cli -> scripts/gepa (2 levels up, for dev mode)
+      path.join(__dirname, "../../scripts/gepa/hooks/auto-optimize.js"),
+      // Global install location
+      path.join(
+        os.homedir(),
+        ".stackmemory",
+        "scripts",
+        "gepa",
+        "hooks",
+        "auto-optimize.js"
+      ),
+      // npm global install
+      path.join(
+        __dirname,
+        "..",
+        "..",
+        "scripts",
+        "gepa",
+        "hooks",
+        "auto-optimize.js"
+      )
+    ];
+    const gepaScript = gepaPaths.find((p) => fs.existsSync(p));
+    if (!gepaScript) {
+      console.log(chalk.gray("   Prompt Forge: disabled (scripts not found)"));
+      return;
+    }
+    this.gepaProcess = spawn("node", [gepaScript, "watch", claudeMdPath], {
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, GEPA_SILENT: "1" }
+    });
+    this.gepaProcess.unref();
+    this.gepaProcess.stdout?.on("data", (data) => {
+      const output = data.toString().trim();
+      if (output && !output.includes("Watching")) {
+        console.log(chalk.magenta(`[GEPA] ${output}`));
+      }
+    });
+    console.log(
+      chalk.cyan(
+        `   Prompt Forge: watching ${path.basename(claudeMdPath)} for optimization`
+      )
+    );
+  }
+  stopGEPAWatcher() {
+    if (this.gepaProcess) {
+      this.gepaProcess.kill("SIGTERM");
+      this.gepaProcess = null;
+    }
+  }
   ensureGreptileMcp() {
     const apiKey = process.env["GREPTILE_API_KEY"];
     const ghToken = process.env["GITHUB_TOKEN"];
@@ -582,6 +645,12 @@ class ClaudeSM {
         case "--no-greptile":
           this.config.useGreptile = false;
           break;
+        case "--gepa":
+          this.config.useGEPA = true;
+          break;
+        case "--no-gepa":
+          this.config.useGEPA = false;
+          break;
         default:
           claudeArgs.push(arg);
       }
@@ -727,6 +796,9 @@ class ClaudeSM {
     if (this.config.useGreptile) {
       this.ensureGreptileMcp();
     }
+    if (this.config.useGEPA) {
+      this.startGEPAWatcher();
+    }
     if (this.config.useWhatsApp) {
       console.log(
         chalk.cyan("\u{1F4F1} WhatsApp mode: notifications + webhook enabled")
@@ -817,6 +889,7 @@ class ClaudeSM {
       process.exit(1);
     });
     claude.on("exit", async (code) => {
+      this.stopGEPAWatcher();
       const status = fallbackMonitor.getStatus();
       if (status.inFallback) {
         console.log(
@@ -870,38 +943,24 @@ const configCmd = program.command("config").description("Manage claude-sm defaul
 configCmd.command("show").description("Show current default settings").action(() => {
   const config = loadSMConfig();
   console.log(chalk.blue("claude-sm defaults:"));
-  console.log(
-    `  defaultWorktree: ${config.defaultWorktree ? chalk.green("true") : chalk.gray("false")}`
-  );
-  console.log(
-    `  defaultSandbox:  ${config.defaultSandbox ? chalk.green("true") : chalk.gray("false")}`
-  );
-  console.log(
-    `  defaultChrome:   ${config.defaultChrome ? chalk.green("true") : chalk.gray("false")}`
-  );
-  console.log(
-    `  defaultTracing:  ${config.defaultTracing ? chalk.green("true") : chalk.gray("false")}`
-  );
-  console.log(
-    `  defaultRemote:   ${config.defaultRemote ? chalk.green("true") : chalk.gray("false")}`
-  );
-  console.log(
-    `  defaultNotifyOnDone: ${config.defaultNotifyOnDone ? chalk.green("true") : chalk.gray("false")}`
-  );
-  console.log(
-    `  defaultWhatsApp: ${config.defaultWhatsApp ? chalk.green("true") : chalk.gray("false")}`
-  );
-  console.log(
-    `  defaultModelRouting: ${config.defaultModelRouting ? chalk.green("true") : chalk.gray("false")}`
-  );
-  console.log(
-    `  defaultSweep:        ${config.defaultSweep ? chalk.green("true") : chalk.gray("false")}`
-  );
-  console.log(
-    `  defaultGreptile:     ${config.defaultGreptile ? chalk.green("true") : chalk.gray("false")}`
-  );
+  const on = chalk.green("ON ");
+  const off = chalk.gray("OFF");
+  console.log(chalk.cyan("\n  Feature           Status"));
+  console.log(chalk.gray("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  console.log(`  Predictive Edit   ${config.defaultSweep ? on : off}`);
+  console.log(`  Code Review       ${config.defaultGreptile ? on : off}`);
+  console.log(`  Prompt Forge      ${config.defaultGEPA ? on : off}`);
+  console.log(`  Model Switcher    ${config.defaultModelRouting ? on : off}`);
+  console.log(`  Safe Branch       ${config.defaultWorktree ? on : off}`);
+  console.log(`  Mobile Sync       ${config.defaultWhatsApp ? on : off}`);
+  console.log(`  Session Insights  ${config.defaultTracing ? on : off}`);
+  console.log(`  Task Alert        ${config.defaultNotifyOnDone ? on : off}`);
+  console.log(chalk.gray("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  console.log(`  Sandbox           ${config.defaultSandbox ? on : off}`);
+  console.log(`  Chrome            ${config.defaultChrome ? on : off}`);
+  console.log(`  Remote            ${config.defaultRemote ? on : off}`);
   console.log(chalk.gray(`
-Config: ${getConfigPath()}`));
+  Config: ${getConfigPath()}`));
 });
 configCmd.command("set <key> <value>").description("Set a default (e.g., set worktree true)").action((key, value) => {
   const config = loadSMConfig();
@@ -918,14 +977,15 @@ configCmd.command("set <key> <value>").description("Set a default (e.g., set wor
     "model-routing": "defaultModelRouting",
     modelrouting: "defaultModelRouting",
     sweep: "defaultSweep",
-    greptile: "defaultGreptile"
+    greptile: "defaultGreptile",
+    gepa: "defaultGEPA"
   };
   const configKey = keyMap[key];
   if (!configKey) {
     console.log(chalk.red(`Unknown key: ${key}`));
     console.log(
       chalk.gray(
-        "Valid keys: worktree, sandbox, chrome, tracing, remote, notify-done, whatsapp, sweep, greptile"
+        "Valid keys: worktree, sandbox, chrome, tracing, remote, notify-done, whatsapp, sweep, greptile, gepa"
       )
     );
     process.exit(1);
@@ -1016,6 +1076,21 @@ configCmd.command("greptile-off").description("Disable Greptile AI code review b
   saveSMConfig(config);
   console.log(chalk.green("Greptile disabled by default"));
 });
+configCmd.command("gepa-on").description("Enable GEPA auto-optimization of CLAUDE.md on changes").action(() => {
+  const config = loadSMConfig();
+  config.defaultGEPA = true;
+  saveSMConfig(config);
+  console.log(chalk.green("GEPA auto-optimization enabled by default"));
+  console.log(
+    chalk.gray("CLAUDE.md changes will trigger evolutionary optimization")
+  );
+});
+configCmd.command("gepa-off").description("Disable GEPA auto-optimization").action(() => {
+  const config = loadSMConfig();
+  config.defaultGEPA = false;
+  saveSMConfig(config);
+  console.log(chalk.green("GEPA auto-optimization disabled by default"));
+});
 configCmd.command("setup").description("Interactive feature setup wizard").action(async () => {
   const inquirer = await import("inquirer");
   const ora = (await import("ora")).default;
@@ -1024,38 +1099,43 @@ configCmd.command("setup").description("Interactive feature setup wizard").actio
   const features = [
     {
       key: "defaultSweep",
-      name: "Sweep",
-      desc: "Next-edit predictions via PTY wrapper (installs node-pty)"
+      name: "Predictive Edit",
+      desc: "AI-powered next-edit suggestions in real-time"
     },
     {
       key: "defaultGreptile",
-      name: "Greptile",
-      desc: "AI code review MCP server (requires GREPTILE_API_KEY)"
+      name: "Code Review",
+      desc: "Automated code review with deep codebase intelligence"
+    },
+    {
+      key: "defaultGEPA",
+      name: "Prompt Forge",
+      desc: "Evolutionary optimization of system prompts"
     },
     {
       key: "defaultModelRouting",
-      name: "Model Routing",
-      desc: "Route tasks to Qwen/other providers"
+      name: "Model Switcher",
+      desc: "Smart routing across Claude, Qwen, and other models"
     },
     {
       key: "defaultWorktree",
-      name: "Worktree",
-      desc: "Git worktree isolation per instance"
+      name: "Safe Branch",
+      desc: "Isolated git worktrees for conflict-free parallel work"
     },
     {
       key: "defaultWhatsApp",
-      name: "WhatsApp",
-      desc: "Notifications and remote control"
+      name: "Mobile Sync",
+      desc: "Remote control and notifications via WhatsApp"
     },
     {
       key: "defaultTracing",
-      name: "Tracing",
-      desc: "Debug trace logging"
+      name: "Session Insights",
+      desc: "Deep execution tracing and performance analytics"
     },
     {
       key: "defaultNotifyOnDone",
-      name: "Notify on Done",
-      desc: "Notification when session ends"
+      name: "Task Alert",
+      desc: "Instant notification when sessions complete"
     }
   ];
   const choices = features.map((f) => ({
@@ -1147,7 +1227,7 @@ Saved to ${getConfigPath()}`));
 program.option("-w, --worktree", "Create isolated worktree for this instance").option("-W, --no-worktree", "Disable worktree (override default)").option("-r, --remote", "Enable remote mode (WhatsApp for all questions)").option("--no-remote", "Disable remote mode (override default)").option("-n, --notify-done", "Send WhatsApp notification when session ends").option("--no-notify-done", "Disable notification when session ends").option(
   "--whatsapp",
   "Enable WhatsApp mode (auto-start webhook + ngrok + notifications)"
-).option("--no-whatsapp", "Disable WhatsApp mode (override default)").option("-s, --sandbox", "Enable sandbox mode (file/network restrictions)").option("-c, --chrome", "Enable Chrome automation").option("-a, --auto", "Automatically detect and apply best settings").option("-b, --branch <name>", "Specify branch name for worktree").option("-t, --task <desc>", "Task description for context").option("--claude-bin <path>", "Path to claude CLI (or use CLAUDE_BIN)").option("--no-context", "Disable StackMemory context integration").option("--no-trace", "Disable debug tracing (enabled by default)").option("--verbose-trace", "Enable verbose debug tracing with full details").option("--think", "Enable thinking mode with Qwen (deep reasoning)").option("--think-hard", "Alias for --think").option("--ultrathink", "Alias for --think").option("--qwen", "Force Qwen provider for this session").option("--openai", "Force OpenAI provider for this session").option("--ollama", "Force Ollama provider for this session").option("--model-routing", "Enable model routing").option("--no-model-routing", "Disable model routing").option("--sweep", "Enable Sweep next-edit predictions (PTY wrapper)").option("--no-sweep", "Disable Sweep predictions").option("--greptile", "Enable Greptile AI code review (MCP server)").option("--no-greptile", "Disable Greptile integration").helpOption("-h, --help", "Display help").allowUnknownOption(true).action(async (_options) => {
+).option("--no-whatsapp", "Disable WhatsApp mode (override default)").option("-s, --sandbox", "Enable sandbox mode (file/network restrictions)").option("-c, --chrome", "Enable Chrome automation").option("-a, --auto", "Automatically detect and apply best settings").option("-b, --branch <name>", "Specify branch name for worktree").option("-t, --task <desc>", "Task description for context").option("--claude-bin <path>", "Path to claude CLI (or use CLAUDE_BIN)").option("--no-context", "Disable StackMemory context integration").option("--no-trace", "Disable debug tracing (enabled by default)").option("--verbose-trace", "Enable verbose debug tracing with full details").option("--think", "Enable thinking mode with Qwen (deep reasoning)").option("--think-hard", "Alias for --think").option("--ultrathink", "Alias for --think").option("--qwen", "Force Qwen provider for this session").option("--openai", "Force OpenAI provider for this session").option("--ollama", "Force Ollama provider for this session").option("--model-routing", "Enable model routing").option("--no-model-routing", "Disable model routing").option("--sweep", "Enable Sweep next-edit predictions (PTY wrapper)").option("--no-sweep", "Disable Sweep predictions").option("--greptile", "Enable Greptile AI code review (MCP server)").option("--no-greptile", "Disable Greptile integration").option("--gepa", "Enable GEPA auto-optimization of CLAUDE.md").option("--no-gepa", "Disable GEPA auto-optimization").helpOption("-h, --help", "Display help").allowUnknownOption(true).action(async (_options) => {
   const claudeSM = new ClaudeSM();
   const args = process.argv.slice(2);
   await claudeSM.run(args);