@stackmemoryai/stackmemory 1.6.0 → 1.6.2

package/scripts/gepa/README.md

@@ -1,275 +0,0 @@
-# Prompt Forge (GEPA)
-
-**Genetic Eval-driven Prompt Algorithm**
-
-Automatically evolve and optimize your `CLAUDE.md` system prompts using AI-powered evolutionary algorithms.
-
-## Auto-Optimize on Save
-
-```bash
-# Start watcher - auto-optimizes when CLAUDE.md changes
-node scripts/gepa/hooks/auto-optimize.js watch ./CLAUDE.md
-```
-
-Output shows before/after comparison:
-```
-╔════════════════════════════════════════════════════════════╗
-║  BEFORE / AFTER COMPARISON                                  ║
-╠════════════════════════════════════════════════════════════╣
-║  Metric              Before      After       Change         ║
-╠════════════════════════════════════════════════════════════╣
-║  Lines                  125        142    +17 (+14%)        ║
-║  Est. Tokens            873        920    +47 (+5%)         ║
-║  MUST rules               1          3     +2 (+200%)       ║
-║  NEVER rules              3          5     +2 (+67%)        ║
-╚════════════════════════════════════════════════════════════╝
-
-Section Changes:
-  Added:
-    + Error Handling
-    + Performance Guidelines
-
-Summary:
-  Token budget: +47 tokens
-  Rule density: +4 explicit rules
-```
-
-## How It Works
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                         GEPA Loop                                │
-│                                                                  │
-│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐  │
-│  │  Seed    │───►│  Mutate  │───►│   Eval   │───►│  Select  │  │
-│  │ Prompt   │    │ (AI gen) │    │ (Claude) │    │  (best)  │  │
-│  └──────────┘    └──────────┘    └──────────┘    └────┬─────┘  │
-│       ▲                                               │        │
-│       │              ┌──────────┐                     │        │
-│       └──────────────┤ Reflect  │◄────────────────────┘        │
-│                      │(insights)│                              │
-│                      └──────────┘                              │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Quick Start
-
-```bash
-# 1. Initialize with your current CLAUDE.md
-node scripts/gepa/optimize.js init ./CLAUDE.md
-
-# 2. Run full optimization (10 generations)
-node scripts/gepa/optimize.js run
-
-# 3. Apply the best result
-cp scripts/gepa/generations/current ./CLAUDE.md
-```
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `init [path]` | Initialize with a CLAUDE.md file |
-| `mutate` | Generate new prompt variants |
-| `eval [variant]` | Run evals on a specific variant |
-| `score` | Score all variants and select best |
-| `run [N]` | Full optimization loop for N generations |
-| `status` | Show current optimization status |
-| `diff [a] [b]` | Compare two variants |
-
-## Mutation Strategies
-
-GEPA uses 6 mutation strategies, cycling through them:
-
-1. **rephrase** - Reword for clarity without changing meaning
-2. **add_examples** - Add concrete examples where abstract
-3. **remove_redundancy** - DRY up repetitive instructions
-4. **restructure** - Reorganize for better flow
-5. **add_constraints** - Add guardrails for failure modes
-6. **simplify** - Break down complex rules
-
-## Reflection (Key Innovation)
-
-Unlike random mutations, GEPA analyzes **why** prompts fail:
-
-```bash
-# Analyze session patterns
-node scripts/gepa/hooks/reflect.js analyze
-
-# Generate targeted improvements
-node scripts/gepa/hooks/reflect.js reflect
-```
-
-The reflection engine examines:
-- Common error patterns
-- Tool call success rates
-- User feedback (thumbs up/down)
-- Performance by variant
-
-Then generates **targeted** mutation suggestions.
-
-## Hook Integration
-
-To track real usage for evals, add to `~/.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "postToolCall": [
-      {
-        "command": "node ~/.claude/gepa/hooks/eval-tracker.js track-tool"
-      }
-    ],
-    "postSession": [
-      {
-        "command": "node ~/.claude/gepa/hooks/eval-tracker.js save"
-      }
-    ]
-  }
-}
-```
-
-Or use the StackMemory daemon integration:
-
-```bash
-# Add to your .env
-GEPA_ENABLED=true
-GEPA_DIR=~/.claude/gepa
-```
-
-## Configuration
-
-Edit `config.json`:
-
-```json
-{
-  "evolution": {
-    "populationSize": 4,      // Variants per generation
-    "generations": 10,        // Max generations
-    "selectionRate": 0.5      // Top 50% survive
-  },
-  "evals": {
-    "minSamplesPerVariant": 5,  // Evals per variant
-    "timeout": 120000            // 2 min per eval
-  },
-  "scoring": {
-    "threshold": 0.8           // Stop when 80% success
-  }
-}
-```
-
-## Writing Good Evals
-
-Evals live in `evals/*.jsonl`:
-
-```json
-{
-  "id": "eval-001",
-  "name": "simple_function",
-  "prompt": "Write a function that checks if a string is a palindrome",
-  "expected": {
-    "has_function": true,
-    "handles_edge_cases": true
-  },
-  "weight": 1.0
-}
-```
-
-### Expected Checks
-
-| Check | What It Looks For |
-|-------|-------------------|
-| `has_function` | Function definition in output |
-| `handles_edge_cases` | Null/empty/edge case handling |
-| `uses_async` | async/await usage |
-| `bug_fixed` | Fix-related language |
-| `explains_fix` | Explanation of changes |
-| Custom key | Looks for key as substring |
-
-## Directory Structure
-
-```
-scripts/gepa/
-├── config.json           # Settings
-├── state.json            # Current state
-├── optimize.js           # Main optimizer
-├── hooks/
-│   ├── eval-tracker.js   # Session tracking hook
-│   └── reflect.js        # Reflection engine
-├── evals/
-│   └── coding-tasks.jsonl
-├── generations/
-│   ├── gen-000/
-│   │   └── baseline.md
-│   ├── gen-001/
-│   │   ├── variant-a.md
-│   │   ├── variant-b.md
-│   │   └── baseline.md
-│   └── current -> gen-001/variant-a.md
-└── results/
-    ├── scores.jsonl
-    └── sessions/
-```
-
-## Best Practices
-
-1. **Start with good evals** - Garbage in, garbage out
-2. **Run multiple generations** - Improvements compound
-3. **Review diffs** - Understand what changed
-4. **Keep baseline** - Always compare against original
-5. **Monitor for drift** - Watch for unintended changes
-
-## Example Output
-
-```
-$ node optimize.js run 3
-
-============================================================
-GENERATION 1/3
-============================================================
-
-Generating 4 variants for generation 1...
-  Creating variant-a using strategy: rephrase
-  Creating variant-b using strategy: add_examples
-  Creating variant-c using strategy: remove_redundancy
-  Creating variant-d using strategy: restructure
-
-Scoring 5 variants in generation 1...
-  Running evals on baseline... Score: 65.0%
-  Running evals on variant-a... Score: 72.0%
-  Running evals on variant-b... Score: 78.0%
-  Running evals on variant-c... Score: 70.0%
-  Running evals on variant-d... Score: 68.0%
-
-Results:
-  1. variant-b: 78.0% <-- BEST
-  2. variant-a: 72.0%
-  3. variant-c: 70.0%
-  4. variant-d: 68.0%
-  5. baseline: 65.0%
-
-New best: variant-b (78.0%)
-
-============================================================
-OPTIMIZATION COMPLETE
-============================================================
-Best variant: variant-b
-Best score: 85.2%
-Generations: 3
-
-To apply: cp generations/current /path/to/your/CLAUDE.md
-```
-
-## Troubleshooting
-
-**"claude CLI not found"**
-Set `ANTHROPIC_API_KEY` for API fallback.
-
-**Slow evals**
-Reduce `minSamplesPerVariant` in config.
-
-**Poor results**
-Add more diverse evals covering failure modes.
-
-**Drift from original intent**
-Add evals that test for desired behaviors explicitly.

package/scripts/gepa/config.json

@@ -1,59 +0,0 @@
-{
-  "name": "GEPA - Genetic Eval-driven Prompt Algorithm",
-  "version": "1.0.0",
-
-  "target": {
-    "file": "CLAUDE.md",
-    "scope": "project",
-    "backup": true
-  },
-
-  "evolution": {
-    "populationSize": 4,
-    "generations": 10,
-    "selectionRate": 0.5,
-    "mutationStrategies": [
-      "rephrase",
-      "add_examples",
-      "remove_redundancy",
-      "restructure",
-      "add_constraints",
-      "simplify"
-    ]
-  },
-
-  "evals": {
-    "directory": "./evals",
-    "minSamplesPerVariant": 8,
-    "timeout": 120000,
-    "metrics": [
-      "task_completion",
-      "code_quality",
-      "instruction_following",
-      "efficiency"
-    ]
-  },
-
-  "judge": {
-    "model": "claude-haiku-4-5-20251001",
-    "maxOutputTokens": 2000,
-    "timeoutMs": 30000
-  },
-
-  "scoring": {
-    "weights": {
-      "task_completion": 0.4,
-      "code_quality": 0.25,
-      "instruction_following": 0.25,
-      "efficiency": 0.1
-    },
-    "threshold": 0.7
-  },
-
-  "hooks": {
-    "trackToolCalls": true,
-    "trackTokenUsage": true,
-    "trackErrors": true,
-    "trackUserFeedback": true
-  }
-}

package/scripts/gepa/evals/coding-tasks.jsonl

@@ -1,5 +0,0 @@
-{"id": "eval-001", "name": "simple_function", "prompt": "Write a function that checks if a string is a palindrome", "expected": {"has_function": true, "handles_edge_cases": true, "is_tested": false}, "weight": 1.0}
-{"id": "eval-002", "name": "refactor_code", "prompt": "Refactor this code to use async/await instead of callbacks", "input_file": "fixtures/callback-hell.js", "expected": {"uses_async": true, "preserves_behavior": true, "no_nested_callbacks": true}, "weight": 1.5}
-{"id": "eval-003", "name": "fix_bug", "prompt": "Fix the off-by-one error in this loop", "input_file": "fixtures/buggy-loop.js", "expected": {"bug_fixed": true, "no_new_bugs": true, "explains_fix": true}, "weight": 1.2}
-{"id": "eval-004", "name": "add_feature", "prompt": "Add pagination to this API endpoint", "input_file": "fixtures/api-endpoint.ts", "expected": {"has_pagination": true, "has_limit": true, "has_offset": true, "backwards_compatible": true}, "weight": 1.5}
-{"id": "eval-005", "name": "code_review", "prompt": "Review this PR and identify issues", "input_file": "fixtures/pr-diff.txt", "expected": {"identifies_security_issue": true, "identifies_performance_issue": true, "actionable_feedback": true}, "weight": 1.3}

package/scripts/gepa/evals/fixtures/api-endpoint.ts

@@ -1,31 +0,0 @@
-// Simple API endpoint that needs pagination added
-import express from 'express';
-
-const router = express.Router();
-
-interface User {
-  id: number;
-  name: string;
-  email: string;
-}
-
-// In-memory store
-const users: User[] = Array.from({ length: 100 }, (_, i) => ({
-  id: i + 1,
-  name: `User ${i + 1}`,
-  email: `user${i + 1}@example.com`,
-}));
-
-// GET /users - returns ALL users (no pagination)
-router.get('/users', (req, res) => {
-  res.json(users);
-});
-
-// GET /users/:id
-router.get('/users/:id', (req, res) => {
-  const user = users.find((u) => u.id === parseInt(req.params.id));
-  if (!user) return res.status(404).json({ error: 'Not found' });
-  res.json(user);
-});
-
-export default router;

package/scripts/gepa/evals/fixtures/brittle-integration.ts

@@ -1,38 +0,0 @@
-// Integration handler that crashes on external API failure
-// Needs graceful degradation following the DiffMem/Greptile pattern
-
-interface MCPResponse {
-  content: Array<{ type: string; text: string }>;
-  metadata?: Record<string, unknown>;
-}
-
-// This handler crashes the entire MCP server when the API is unreachable.
-// Refactor to degrade gracefully.
-async function handleExternalLookup(args: {
-  query: string;
-  limit?: number;
-}): Promise<MCPResponse> {
-  const response = await fetch('https://api.external-service.com/search', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ query: args.query, limit: args.limit || 10 }),
-  });
-
-  // BUG: No error handling — fetch failures (ECONNREFUSED, DNS, timeout)
-  // will throw and crash the MCP server process.
-  // BUG: 4xx errors (bad request, auth failed) should not be retried.
-  // BUG: Logs at error level, flooding logs when service is down.
-
-  if (!response.ok) {
-    throw new Error(`API error: ${response.status}`);
-  }
-
-  const data = await response.json();
-
-  return {
-    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
-    metadata: { tool: 'external_lookup', resultCount: data.results?.length },
-  };
-}
-
-export { handleExternalLookup };

package/scripts/gepa/evals/fixtures/buggy-loop.js

@@ -1,18 +0,0 @@
-// Bug: Off-by-one error - processes one too many items
-function processItems(items) {
-  const results = [];
-
-  // BUG: should be i < items.length, not i <= items.length
-  for (let i = 0; i <= items.length; i++) {
-    const item = items[i];
-    results.push(item.toUpperCase()); // Will crash on undefined
-  }
-
-  return results;
-}
-
-// Test
-const items = ['apple', 'banana', 'cherry'];
-console.log(processItems(items)); // Crashes!
-
-module.exports = { processItems };

package/scripts/gepa/evals/fixtures/callback-hell.js

@@ -1,53 +0,0 @@
-// Callback hell example - needs refactoring to async/await
-function fetchUserData(userId, callback) {
-  getUser(userId, function (err, user) {
-    if (err) {
-      callback(err);
-      return;
-    }
-
-    getPosts(user.id, function (err, posts) {
-      if (err) {
-        callback(err);
-        return;
-      }
-
-      getComments(posts[0].id, function (err, comments) {
-        if (err) {
-          callback(err);
-          return;
-        }
-
-        getLikes(comments[0].id, function (err, likes) {
-          if (err) {
-            callback(err);
-            return;
-          }
-
-          callback(null, {
-            user: user,
-            posts: posts,
-            comments: comments,
-            likes: likes,
-          });
-        });
-      });
-    });
-  });
-}
-
-// Mock functions
-function getUser(id, cb) {
-  cb(null, { id, name: 'Test' });
-}
-function getPosts(userId, cb) {
-  cb(null, [{ id: 1, title: 'Post' }]);
-}
-function getComments(postId, cb) {
-  cb(null, [{ id: 1, text: 'Comment' }]);
-}
-function getLikes(commentId, cb) {
-  cb(null, [{ id: 1 }]);
-}
-
-module.exports = { fetchUserData };

package/scripts/gepa/evals/fixtures/fts5-triggers.sql

@@ -1,23 +0,0 @@
--- FTS5 external content table for full-text search on frames
-CREATE VIRTUAL TABLE IF NOT EXISTS frames_fts USING fts5(
-  name, digest_text, inputs, outputs,
-  content='frames', content_rowid='rowid'
-);
-
--- Sync trigger: INSERT
-CREATE TRIGGER IF NOT EXISTS frames_ai AFTER INSERT ON frames BEGIN
-  INSERT INTO frames_fts(rowid, name, digest_text, inputs, outputs)
-  VALUES (new.rowid, new.name, new.digest_text, new.inputs, new.outputs);
-END;
-
--- Sync trigger: UPDATE
-CREATE TRIGGER IF NOT EXISTS frames_au AFTER UPDATE ON frames BEGIN
-  INSERT INTO frames_fts(frames_fts, rowid, name, digest_text, inputs, outputs)
-  VALUES ('delete', old.rowid, old.name, old.digest_text, old.inputs, old.outputs);
-  INSERT INTO frames_fts(rowid, name, digest_text, inputs, outputs)
-  VALUES (new.rowid, new.name, new.digest_text, new.inputs, new.outputs);
-END;
-
--- BUG: Missing DELETE trigger!
--- When a frame is deleted, the FTS index still contains stale data.
--- Add the missing AFTER DELETE trigger below.

package/scripts/gepa/evals/fixtures/leaky-service.ts

@@ -1,70 +0,0 @@
-// Daemon service with timer leak bug
-interface ServiceConfig {
-  enabled: boolean;
-  interval: number; // minutes
-}
-
-interface ServiceState {
-  isRunning: boolean;
-  intervalMs: number;
-  lastRunTime: number;
-  errorCount: number;
-}
-
-class MonitorService {
-  private config: ServiceConfig;
-  private intervalId?: NodeJS.Timeout;
-  private isRunning = false;
-  private lastRunTime = 0;
-  private errorCount = 0;
-
-  constructor(config: ServiceConfig) {
-    this.config = config;
-  }
-
-  // BUG: No guard against double-start — calling start() twice
-  // creates two intervals but only stores the second one.
-  // The first interval leaks and keeps running forever.
-  start(): void {
-    this.isRunning = true;
-    const intervalMs = this.config.interval * 60 * 1000;
-
-    this.doWork(); // initial run
-
-    this.intervalId = setInterval(() => {
-      this.doWork();
-    }, intervalMs);
-  }
-
-  stop(): void {
-    if (this.intervalId) {
-      clearInterval(this.intervalId);
-      this.intervalId = undefined;
-    }
-    this.isRunning = false;
-  }
-
-  // BUG: Calls stop() then start() but start() doesn't check
-  // if already running, so if stop() fails to clear the interval
-  // (e.g., intervalId is undefined), we leak.
-  updateConfig(config: Partial<ServiceConfig>): void {
-    const wasRunning = this.isRunning;
-    if (wasRunning) this.stop();
-    this.config = { ...this.config, ...config };
-    if (wasRunning && this.config.enabled) this.start();
-  }
-
-  // TODO: Add getState() method returning ServiceState
-
-  private doWork(): void {
-    try {
-      // Simulate work
-      console.log('Running monitor check...');
-      this.lastRunTime = Date.now();
-    } catch (err) {
-      this.errorCount++;
-    }
-  }
-}
-
-export { MonitorService, ServiceConfig, ServiceState };

package/scripts/gepa/evals/fixtures/mcp-dispatch-stub.ts

@@ -1,39 +0,0 @@
-// Existing MCP server dispatch pattern — add get_frame_summary handler
-import { z } from 'zod';
-
-interface Frame {
-  id: string;
-  name: string;
-  status: 'open' | 'closed';
-  events: Array<{ id: string; type: string }>;
-}
-
-// Simulated frame store
-const frames = new Map<string, Frame>();
-
-// Existing tool dispatch (add your handler here)
-async function handleToolCall(name: string, args: unknown) {
-  switch (name) {
-    case 'start_frame': {
-      const input = z.object({ name: z.string().min(1) }).parse(args);
-      const id = `frame-${Date.now()}`;
-      frames.set(id, { id, name: input.name, status: 'open', events: [] });
-      return { frameId: id, status: 'opened' };
-    }
-
-    case 'close_frame': {
-      const input = z.object({ frameId: z.string() }).parse(args);
-      const frame = frames.get(input.frameId);
-      if (!frame) throw new Error(`Frame not found: ${input.frameId}`);
-      frame.status = 'closed';
-      return { frameId: frame.id, status: 'closed' };
-    }
-
-    // TODO: Add get_frame_summary handler here
-
-    default:
-      throw new Error(`Unknown tool: ${name}`);
-  }
-}
-
-export { handleToolCall };

package/scripts/gepa/evals/fixtures/pr-diff.txt

@@ -1,24 +0,0 @@
-diff --git a/src/auth/login.ts b/src/auth/login.ts
-index 1a2b3c4..5d6e7f8 100644
---- a/src/auth/login.ts
-+++ b/src/auth/login.ts
-@@ -12,8 +12,15 @@ export async function handleLogin(req: Request, res: Response) {
-   const { email, password } = req.body;
-
--  const user = await db.query('SELECT * FROM users WHERE email = $1', [email]);
-+  // Quick fix: direct string interpolation for faster queries
-+  const user = await db.query(`SELECT * FROM users WHERE email = '${email}'`);
-   if (!user) return res.status(401).json({ error: 'Invalid credentials' });
-
--  const valid = await bcrypt.compare(password, user.passwordHash);
-+  const valid = password === user.passwordHash;
-   if (!valid) return res.status(401).json({ error: 'Invalid credentials' });
-
-+  // Store session
-+  const token = email + ':' + Date.now();
-+  res.cookie('session', token);
-+
-+  // Log for debugging
-+  console.log(`Login: ${email} / ${password}`);
-+
-   return res.json({ success: true, user: { id: user.id, email: user.email } });

package/scripts/gepa/evals/fixtures/unsafe-webhook.ts

@@ -1,34 +0,0 @@
-// Webhook handler with validation vulnerabilities
-interface WebhookPayload {
-  action: string;
-  type: string;
-  data: {
-    id: string;
-    title?: string;
-    description?: string;
-    [key: string]: unknown;
-  };
-}
-
-// VULNERABLE: No prototype pollution protection, no length limits,
-// no action validation. Fix this function.
-function validateWebhookPayload(payload: unknown): WebhookPayload | null {
-  if (!payload || typeof payload !== 'object') return null;
-
-  const p = payload as Record<string, unknown>;
-
-  if (!p.action || typeof p.action !== 'string') return null;
-  if (!p.type || typeof p.type !== 'string') return null;
-  if (!p.data || typeof p.data !== 'object') return null;
-
-  const data = p.data as Record<string, unknown>;
-  if (!data.id || typeof data.id !== 'string') return null;
-
-  // No sanitization — title and description can be any length
-  // No action validation — accepts any string
-  // No prototype pollution check — __proto__ passes through
-
-  return p as unknown as WebhookPayload;
-}
-
-export { validateWebhookPayload, WebhookPayload };