@stackmemoryai/stackmemory 0.8.0 → 1.0.0

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

@@ -1,245 +0,0 @@
-#!/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 { 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 (err: unknown) {
-      console.error(
-        '\n❌ Demo failed:',
-        err instanceof Error ? err.message : err
-      );
-      throw err;
-    } 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('===========================');
-
-    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 (err: unknown) {
-      console.log(
-        `⚠️  Recovery simulation: ${err instanceof Error ? err.message : err}`
-      );
-    }
-  }
-
-  /**
-   * 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 (err: unknown) {
-    console.error('Demo failed:', err instanceof Error ? err.message : err);
-    if (process.env.DEBUG && err instanceof Error) {
-      console.error(err.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

@@ -1,200 +0,0 @@
-#!/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,
-  enableVerboseTracing,
-  createTracedDatabase,
-  traceStep,
-} from './index.js';
-
-// Example class with tracing
-// @TraceClass() - decorators not enabled in tsconfig
-class ExampleService {
-  private data: Map<string, unknown> = new Map();
-
-  async fetchData(id: string): Promise<Record<string, unknown>> {
-    // Simulate API call
-    await this.delay(50);
-
-    if (id === 'error') {
-      throw new Error('Simulated API error');
-    }
-
-    return { id, value: Math.random() };
-  }
-
-  async processData(
-    data: Record<string, unknown>
-  ): Promise<Record<string, unknown>> {
-    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: unknown): 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 {
-        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

@@ -1,171 +0,0 @@
-/**
- * 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

@@ -1,79 +0,0 @@
-/**
- * Test the trace detection integration with MCP server
- */
-
-import LocalStackMemoryMCP from './server';
-
-// Type for accessing private members in tests
-interface MCPTestInstance {
-  traceDetector: {
-    addToolCall: (call: {
-      id: string;
-      tool: string;
-      timestamp: number;
-      arguments: Record<string, unknown>;
-    }) => void;
-    flush: () => void;
-  };
-  handleGetTraceStatistics: (
-    args: Record<string, unknown>
-  ) => Promise<{ content: Array<{ text: string }> }>;
-  handleGetTraces: (args: {
-    limit: number;
-  }) => Promise<{ content: Array<{ text: string }> }>;
-}
-
-async function testTraceIntegration() {
-  console.log('🧪 Testing Trace Detection in MCP Server\n');
-
-  // Access the private methods through prototype
-  const MCPClass = LocalStackMemoryMCP as unknown as new () => MCPTestInstance;
-  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);