@stackmemoryai/stackmemory 0.5.57 → 0.5.59

package/scripts/demos/ralph-integration-demo.ts

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * Ralph-StackMemory Integration Demonstration
+ * Shows how the integration works with a working example
+ */
+
+import { RalphStackMemoryBridge } from './bridge/ralph-stackmemory-bridge.js';
+import { logger } from '../../core/monitoring/logger.js';
+import { RalphStackMemoryConfig } from './types.js';
+
+class RalphIntegrationDemo {
+  private bridge: RalphStackMemoryBridge;
+
+  constructor() {
+    // Configure the bridge for demo
+    const config: Partial<RalphStackMemoryConfig> = {
+      contextBudget: {
+        maxTokens: 2000, // Smaller budget for demo
+        compressionEnabled: true,
+        adaptiveBudgeting: true,
+      },
+      performance: {
+        asyncSaves: true,
+        batchSize: 5,
+        compressionLevel: 1,
+        cacheEnabled: true,
+      },
+      lifecycle: {
+        checkpoints: {
+          enabled: true,
+          frequency: 3, // Checkpoint every 3 iterations
+          retentionDays: 1, // Short retention for demo
+        },
+      },
+    };
+
+    this.bridge = new RalphStackMemoryBridge({
+      config,
+      debug: true,
+    });
+  }
+
+  /**
+   * Run the integration demo
+   */
+  async run(): Promise<void> {
+    console.log('\n🤖 Ralph-StackMemory Integration Demo\n');
+
+    try {
+      // Phase 1: Initialize
+      await this.demonstrateInitialization();
+
+      // Phase 2: Run iterations
+      await this.demonstrateIterations();
+
+      // Phase 3: Show recovery
+      await this.demonstrateRecovery();
+
+      // Phase 4: Show metrics
+      await this.demonstrateMetrics();
+
+      console.log('\n✅ Demo completed successfully!\n');
+    } catch (error: any) {
+      console.error('\n❌ Demo failed:', error.message);
+      throw error;
+    } finally {
+      await this.cleanup();
+    }
+  }
+
+  /**
+   * Demonstrate initialization
+   */
+  private async demonstrateInitialization(): Promise<void> {
+    console.log('📋 Phase 1: Initialization');
+    console.log('==========================');
+
+    // Initialize the bridge
+    await this.bridge.initialize();
+
+    // Create a new loop
+    const task = 'Implement user authentication system with JWT';
+    const criteria = [
+      '- User registration endpoint working',
+      '- Login endpoint returns JWT token',
+      '- Protected routes validate JWT',
+      '- Password hashing implemented',
+      '- Tests pass with >80% coverage',
+    ].join('\n');
+
+    const loopState = await this.bridge.createNewLoop(task, criteria);
+
+    console.log(`✓ Created Ralph loop: ${loopState.loopId}`);
+    console.log(`✓ Task: ${task.substring(0, 50)}...`);
+    console.log(`✓ Status: ${loopState.status}`);
+    console.log(`✓ Iteration: ${loopState.iteration}`);
+    console.log();
+  }
+
+  /**
+   * Demonstrate iterations with context management
+   */
+  private async demonstrateIterations(): Promise<void> {
+    console.log('🔄 Phase 2: Iteration Management');
+    console.log('=================================');
+
+    const maxIterations = 5;
+
+    for (let i = 0; i < maxIterations; i++) {
+      console.log(`\n--- Iteration ${i + 1} ---`);
+
+      // Run worker iteration
+      console.log('🔧 Running worker iteration...');
+      const iteration = await this.bridge.runWorkerIteration();
+
+      console.log(
+        `✓ Analysis: ${iteration.analysis.filesCount} files, tests ${iteration.analysis.testsPass ? 'pass' : 'fail'}`
+      );
+      console.log(`✓ Plan: ${iteration.plan.summary}`);
+      console.log(`✓ Changes: ${iteration.changes.length} modifications`);
+      console.log(
+        `✓ Validation: ${iteration.validation.testsPass ? 'pass' : 'fail'}`
+      );
+
+      // Run reviewer iteration
+      console.log('👀 Running reviewer iteration...');
+      const review = await this.bridge.runReviewerIteration();
+
+      if (review.complete) {
+        console.log('🎉 Task completed!');
+        break;
+      } else {
+        console.log(`📝 Feedback: ${review.feedback?.substring(0, 100)}...`);
+      }
+
+      // Show context budget usage
+      const usage = this.bridge.getPerformanceMetrics();
+      console.log(
+        `📊 Token usage: ${usage.tokenCount} / Context load: ${usage.contextLoadTime}ms`
+      );
+
+      // Create checkpoint every few iterations
+      if ((i + 1) % 3 === 0) {
+        console.log('💾 Creating checkpoint...');
+        const checkpoint = await this.bridge.createCheckpoint();
+        console.log(`✓ Checkpoint: ${checkpoint.id}`);
+      }
+
+      // Small delay for demo
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+  }
+
+  /**
+   * Demonstrate crash recovery
+   */
+  private async demonstrateRecovery(): Promise<void> {
+    console.log('\n🚑 Phase 3: Crash Recovery');
+    console.log('===========================');
+
+    // Simulate getting session ID
+    const sessionId = 'demo-session-123';
+
+    try {
+      console.log('🔄 Simulating session rehydration...');
+
+      // This would normally rehydrate from a real StackMemory session
+      // For demo, we'll show the concept
+      console.log('✓ Loading context from StackMemory...');
+      console.log('✓ Reconciling state from git, files, and memory...');
+      console.log('✓ Applying context budget constraints...');
+      console.log('✓ Resuming from last iteration...');
+
+      // Show recovery metrics
+      console.log('📈 Recovery successful!');
+      console.log('  - Context loaded: 2.1s');
+      console.log('  - State reconciled: 0.3s');
+      console.log('  - Memory usage: 45MB');
+      console.log('  - Cache hit rate: 78%');
+    } catch (error: any) {
+      console.log(`⚠️  Recovery simulation: ${error.message}`);
+    }
+  }
+
+  /**
+   * Demonstrate performance metrics
+   */
+  private async demonstrateMetrics(): Promise<void> {
+    console.log('\n📊 Phase 4: Performance Metrics');
+    console.log('================================');
+
+    const metrics = this.bridge.getPerformanceMetrics();
+
+    console.log('Performance Summary:');
+    console.log(`  Iteration Time: ${metrics.iterationTime}ms avg`);
+    console.log(`  Context Load Time: ${metrics.contextLoadTime}ms avg`);
+    console.log(`  State Save Time: ${metrics.stateSaveTime}ms avg`);
+    console.log(
+      `  Memory Usage: ${Math.round(metrics.memoryUsage / 1024 / 1024)}MB`
+    );
+    console.log(`  Token Count: ${metrics.tokenCount}`);
+    console.log(`  Cache Hit Rate: ${Math.round(metrics.cacheHitRate * 100)}%`);
+
+    console.log('\nOptimization Features:');
+    console.log('  ✓ Async frame saves with batching');
+    console.log('  ✓ Context compression and budget management');
+    console.log('  ✓ State reconciliation with conflict resolution');
+    console.log('  ✓ Lifecycle hooks for clean integration');
+    console.log('  ✓ Checkpoint-based recovery');
+  }
+
+  /**
+   * Cleanup resources
+   */
+  private async cleanup(): Promise<void> {
+    console.log('\n🧹 Cleaning up...');
+    await this.bridge.cleanup();
+    console.log('✓ Resources cleaned up');
+  }
+}
+
+/**
+ * CLI interface
+ */
+async function main() {
+  const demo = new RalphIntegrationDemo();
+
+  try {
+    await demo.run();
+  } catch (error: any) {
+    console.error('Demo failed:', error.message);
+    if (process.env.DEBUG) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Run if called directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(console.error);
+}
+
+export { RalphIntegrationDemo };

package/scripts/demos/trace-demo.ts

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * Trace Demo - Shows how the debug tracing works
+ * Run with: DEBUG_TRACE=true npx tsx src/core/trace/trace-demo.ts
+ */
+
+import {
+  trace,
+  Trace,
+  TraceClass,
+  enableVerboseTracing,
+  createTracedDatabase,
+  traceStep,
+} from './index.js';
+import { logger } from '../monitoring/logger.js';
+// Type-safe environment variable access
+function getEnv(key: string, defaultValue?: string): string {
+  const value = process.env[key];
+  if (value === undefined) {
+    if (defaultValue !== undefined) return defaultValue;
+    throw new Error(`Environment variable ${key} is required`);
+  }
+  return value;
+}
+
+function getOptionalEnv(key: string): string | undefined {
+  return process.env[key];
+}
+
+// Example class with tracing
+// @TraceClass() - decorators not enabled in tsconfig
+class ExampleService {
+  private data: Map<string, any> = new Map();
+
+  async fetchData(id: string): Promise<any> {
+    // Simulate API call
+    await this.delay(50);
+
+    if (id === 'error') {
+      throw new Error('Simulated API error');
+    }
+
+    return { id, value: Math.random() };
+  }
+
+  async processData(data: any): Promise<any> {
+    return traceStep('Data validation', async () => {
+      await this.delay(20);
+
+      if (!data.id) {
+        throw new Error('Invalid data: missing ID');
+      }
+
+      return traceStep('Data transformation', async () => {
+        await this.delay(30);
+        return {
+          ...data,
+          processed: true,
+          timestamp: Date.now(),
+        };
+      });
+    });
+  }
+
+  cacheData(key: string, value: any): void {
+    trace.traceSync('function', 'cacheData', { key, value }, () => {
+      this.data.set(key, value);
+    });
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+// Example with database operations
+async function databaseExample() {
+  return trace.step('Database operations example', async () => {
+    const db = createTracedDatabase(':memory:');
+
+    // Create table
+    db.exec(`
+      CREATE TABLE users (
+        id INTEGER PRIMARY KEY,
+        name TEXT NOT NULL,
+        email TEXT UNIQUE,
+        created_at INTEGER DEFAULT (strftime('%s', 'now'))
+      )
+    `);
+
+    // Insert data
+    const insert = db.prepare('INSERT INTO users (name, email) VALUES (?, ?)');
+    insert.run('Alice', 'alice@example.com');
+    insert.run('Bob', 'bob@example.com');
+
+    // Query data
+    const select = db.prepare('SELECT * FROM users WHERE name = ?');
+    const user = select.get('Alice');
+
+    // Complex query (will trigger slow query warning if threshold is low)
+    const complex = db.prepare(`
+      SELECT 
+        name,
+        COUNT(*) as count,
+        MAX(created_at) as latest
+      FROM users
+      GROUP BY name
+      HAVING COUNT(*) > 0
+    `);
+    const results = complex.all();
+
+    db.close();
+
+    return { user, results };
+  });
+}
+
+// Main demo function
+async function runDemo() {
+  console.log('\n' + '='.repeat(80));
+  console.log('STACKMEMORY DEBUG TRACE DEMO');
+  console.log('='.repeat(80) + '\n');
+
+  // Enable verbose tracing for the demo
+  if (process.env['DEBUG_TRACE'] !== 'true') {
+    console.log('Enabling verbose tracing for this demo...\n');
+    enableVerboseTracing();
+  }
+
+  try {
+    // Example 1: Service operations
+    await trace.command('demo:service', { example: 'service' }, async () => {
+      const service = new ExampleService();
+
+      console.log('\n--- Example 1: Service Operations ---\n');
+
+      // Successful operation
+      const data = await service.fetchData('test-1');
+      const processed = await service.processData(data);
+      service.cacheData('test-1', processed);
+
+      console.log('Service operation completed\n');
+    });
+
+    // Example 2: Database operations
+    await trace.command('demo:database', { example: 'database' }, async () => {
+      console.log('\n--- Example 2: Database Operations ---\n');
+
+      const results = await databaseExample();
+
+      console.log('Database operations completed');
+      console.log('   Found user:', results.user);
+      console.log('   Query results:', results.results);
+    });
+
+    // Example 3: Error handling
+    await trace.command('demo:errors', { example: 'errors' }, async () => {
+      console.log('\n--- Example 3: Error Handling ---\n');
+
+      const service = new ExampleService();
+
+      try {
+        await service.fetchData('error');
+      } catch (error: unknown) {
+        console.log('Error properly traced and handled\n');
+      }
+    });
+
+    // Example 4: Performance tracking
+    await trace.command(
+      'demo:performance',
+      { example: 'performance' },
+      async () => {
+        console.log('\n--- Example 4: Performance Tracking ---\n');
+
+        // Simulate slow operation
+        await trace.step('Slow operation', async () => {
+          await new Promise((resolve) => setTimeout(resolve, 150));
+        });
+
+        // Simulate fast operations
+        for (let i = 0; i < 3; i++) {
+          await trace.step(`Fast operation ${i + 1}`, async () => {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+          });
+        }
+
+        console.log('Performance tracking completed\n');
+      }
+    );
+  } catch (error: unknown) {
+    console.error('Demo failed:', error);
+  }
+
+  // Show execution summary
+  console.log('\n' + trace.getExecutionSummary());
+
+  // Export traces for analysis
+  const traces = trace.exportTraces();
+  console.log(`\nTotal traces collected: ${traces.length}`);
+
+  // Show example trace entry
+  if (traces.length > 0) {
+    console.log('\nExample trace entry:');
+    console.log(JSON.stringify(traces[0], null, 2));
+  }
+}
+
+// Run the demo
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runDemo().catch(console.error);
+}
+
+export { runDemo };

package/scripts/demos/trace-detector.demo.ts

@@ -0,0 +1,171 @@
+/**
+ * Demo script to showcase Trace Detection functionality
+ */
+
+import { TraceDetector } from './trace-detector.js';
+import { ToolCall } from './types.js';
+import { v4 as uuidv4 } from 'uuid';
+
+// Create a new trace detector
+const detector = new TraceDetector();
+
+console.log('Trace Detection Demo\n');
+console.log('='.repeat(50));
+
+// Simulate a search-driven modification trace
+console.log('\n📋 Simulating Search-Driven Modification:');
+const baseTime = Date.now();
+
+const searchDrivenTools: ToolCall[] = [
+  {
+    id: uuidv4(),
+    tool: 'search',
+    timestamp: baseTime,
+    arguments: { query: 'authentication bug' },
+  },
+  {
+    id: uuidv4(),
+    tool: 'grep',
+    timestamp: baseTime + 1000,
+    arguments: { pattern: 'auth.*error' },
+  },
+  {
+    id: uuidv4(),
+    tool: 'read',
+    timestamp: baseTime + 2000,
+    filesAffected: ['/src/auth/login.ts'],
+  },
+  {
+    id: uuidv4(),
+    tool: 'edit',
+    timestamp: baseTime + 3000,
+    filesAffected: ['/src/auth/login.ts'],
+  },
+];
+
+searchDrivenTools.forEach((tool) => {
+  detector.addToolCall(tool);
+  console.log(`  Added: ${tool.tool}`);
+});
+
+// Simulate an error recovery trace (separate due to time gap)
+console.log('\nSimulating Error Recovery:');
+const errorTime = baseTime + 40000; // 40 seconds later
+
+const errorRecoveryTools: ToolCall[] = [
+  {
+    id: uuidv4(),
+    tool: 'bash',
+    timestamp: errorTime,
+    arguments: { command: 'npm test' },
+    error: 'Test failed: TypeError',
+  },
+  {
+    id: uuidv4(),
+    tool: 'edit',
+    timestamp: errorTime + 1000,
+    filesAffected: ['/src/utils/validator.ts'],
+  },
+  {
+    id: uuidv4(),
+    tool: 'bash',
+    timestamp: errorTime + 2000,
+    arguments: { command: 'npm test' },
+    result: 'All tests passing',
+  },
+];
+
+errorRecoveryTools.forEach((tool) => {
+  detector.addToolCall(tool);
+  console.log(`  Added: ${tool.tool}${tool.error ? ' (with error)' : ''}`);
+});
+
+// Simulate a feature implementation trace
+console.log('\n✨ Simulating Feature Implementation:');
+const featureTime = baseTime + 80000; // 80 seconds later
+
+const featureTools: ToolCall[] = [
+  {
+    id: uuidv4(),
+    tool: 'write',
+    timestamp: featureTime,
+    filesAffected: ['/src/components/Dashboard.tsx'],
+  },
+  {
+    id: uuidv4(),
+    tool: 'edit',
+    timestamp: featureTime + 1000,
+    filesAffected: ['/src/components/Dashboard.tsx'],
+  },
+  {
+    id: uuidv4(),
+    tool: 'test',
+    timestamp: featureTime + 2000,
+    arguments: { file: 'Dashboard.test.tsx' },
+  },
+];
+
+featureTools.forEach((tool) => {
+  detector.addToolCall(tool);
+  console.log(`  Added: ${tool.tool}`);
+});
+
+// Flush any pending traces
+detector.flush();
+
+// Get statistics
+console.log('\nTrace Statistics:');
+console.log('='.repeat(50));
+const stats = detector.getStatistics();
+console.log(`Total Traces: ${stats.totalTraces}`);
+console.log(`Average Score: ${stats.averageScore.toFixed(2)}`);
+console.log(`Average Length: ${stats.averageLength.toFixed(1)} tools`);
+console.log(`High Importance (>0.7): ${stats.highImportanceCount}`);
+
+console.log('\nTrace Types:');
+Object.entries(stats.tracesByType).forEach(([type, count]) => {
+  console.log(`  ${type}: ${count}`);
+});
+
+// Display all traces
+console.log('\nDetected Traces:');
+console.log('='.repeat(50));
+const traces = detector.getTraces();
+traces.forEach((trace, index) => {
+  console.log(`\nTrace ${index + 1}:`);
+  console.log(`  Type: ${trace.type}`);
+  console.log(`  Score: ${trace.score.toFixed(2)}`);
+  console.log(`  Tools: ${trace.tools.map((t) => t.tool).join(' → ')}`);
+  console.log(`  Summary: ${trace.summary}`);
+  console.log(
+    `  Duration: ${((trace.metadata.endTime - trace.metadata.startTime) / 1000).toFixed(1)}s`
+  );
+
+  if (trace.metadata.filesModified.length > 0) {
+    console.log(`  Files Modified: ${trace.metadata.filesModified.join(', ')}`);
+  }
+
+  if (trace.metadata.errorsEncountered.length > 0) {
+    console.log(`  Errors: ${trace.metadata.errorsEncountered.join(', ')}`);
+  }
+
+  if (trace.metadata.causalChain) {
+    console.log(`  ✓ Causal Chain Detected (error→fix→verify)`);
+  }
+});
+
+// Test high-importance trace filtering
+console.log('\n⭐ High Importance Traces (score > 0.3):');
+const highImportance = detector.getHighImportanceTraces(0.3);
+highImportance.forEach((trace) => {
+  console.log(
+    `  [${trace.type}] Score: ${trace.score.toFixed(2)} - ${trace.summary}`
+  );
+});
+
+// Export traces as JSON
+console.log('\n💾 Exporting traces to JSON...');
+const exported = detector.exportTraces();
+console.log(`Exported ${exported.length} characters of JSON data`);
+
+console.log('\nDemo complete!');

package/scripts/demos/trace-test.ts

@@ -0,0 +1,67 @@
+/**
+ * Test the trace detection integration with MCP server
+ */
+
+import LocalStackMemoryMCP from './server';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+async function testTraceIntegration() {
+  console.log('🧪 Testing Trace Detection in MCP Server\n');
+
+  // Mock minimal server setup
+  const mockServer = {
+    setRequestHandler: () => {},
+    connect: () => Promise.resolve(),
+  } as any;
+
+  // Access the private methods through prototype
+  const MCPClass = LocalStackMemoryMCP as any;
+  const mcp = new MCPClass();
+
+  // Simulate tool calls directly on the trace detector
+  console.log('📋 Simulating tool calls:');
+
+  // Simulate a search-driven trace
+  const baseTime = Date.now();
+  mcp.traceDetector.addToolCall({
+    id: '1',
+    tool: 'get_context',
+    timestamp: baseTime,
+    arguments: { query: 'authentication' },
+  });
+  console.log('  ✓ Added get_context');
+
+  mcp.traceDetector.addToolCall({
+    id: '2',
+    tool: 'add_decision',
+    timestamp: baseTime + 1000,
+    arguments: { content: 'Use JWT tokens', type: 'decision' },
+  });
+  console.log('  ✓ Added add_decision');
+
+  mcp.traceDetector.addToolCall({
+    id: '3',
+    tool: 'start_frame',
+    timestamp: baseTime + 2000,
+    arguments: { name: 'implement-auth' },
+  });
+  console.log('  ✓ Added start_frame');
+
+  // Flush traces
+  mcp.traceDetector.flush();
+
+  // Get statistics
+  const stats = await mcp.handleGetTraceStatistics({});
+  console.log('\n📊 Trace Statistics:');
+  console.log(stats.content[0].text);
+
+  // Get traces
+  const traces = await mcp.handleGetTraces({ limit: 10 });
+  console.log('\n📝 Detected Traces:');
+  console.log(traces.content[0].text);
+
+  console.log('\n✅ MCP Trace Integration Test Complete!');
+}
+
+// Run the test
+testTraceIntegration().catch(console.error);