Reflexion Framework Usage Guide

Overview

The Reflexion framework enables MCP ADR Analysis Server tools to learn from mistakes through linguistic feedback and self-reflection. This guide demonstrates how to integrate Reflexion capabilities into tools and configure learning parameters for continuous improvement.

Quick Start

Basic Reflexion Integration

import { executeWithReflexion } from '../utils/reflexion-framework.js';

// Execute a task with reflexion learning
const reflexionResult = await executeWithReflexion(
  originalPrompt,
  {
    memoryEnabled: true,
    reflectionDepth: 'detailed',
    evaluationCriteria: ['task-success', 'quality', 'efficiency'],
    learningRate: 0.7
  }
);

// Use the enhanced prompt with memory context
const enhancedPrompt = reflexionResult.enhancedPrompt;

Tool Integration Example

// Example: Reflexion-enhanced ADR suggestion tool
export async function suggestAdrsWithReflexion(context: any) {
  // Step 1: Create base prompt
  const basePrompt = createAdrSuggestionPrompt(context);
  
  // Step 2: Apply Reflexion learning
  const reflexionResult = await executeWithReflexion(
    basePrompt,
    {
      memoryEnabled: true,
      maxMemoryEntries: 50,
      reflectionDepth: 'comprehensive',
      evaluationCriteria: ['task-success', 'relevance', 'clarity', 'completeness'],
      learningRate: 0.8,
      memoryRetention: 90 // days
    }
  );
  
  // Step 3: Return enhanced prompt for AI execution
  return {
    content: [{
      type: 'text',
      text: reflexionResult.enhancedPrompt.prompt
    }],
    metadata: {
      reflexionLearning: {
        memoriesUsed: reflexionResult.taskAttempt.relatedMemories.length,
        learningOutcome: reflexionResult.learningOutcome,
        improvementAchieved: reflexionResult.learningOutcome.improvementAchieved
      }
    }
  };
}

Configuration Options

Reflexion Configuration

interface ReflexionConfig {
  memoryEnabled: boolean;           // Enable memory system
  maxMemoryEntries: number;         // Maximum memories per type (1-1000)
  reflectionDepth: 'basic' | 'detailed' | 'comprehensive';
  evaluationCriteria: EvaluationCriterion[];
  learningRate: number;             // How quickly to adapt (0-1)
  memoryRetention: number;          // How long to keep memories (days)
  feedbackIntegration: boolean;     // Enable external feedback
  autoCleanup: boolean;             // Automatic memory cleanup
  relevanceThreshold: number;       // Minimum relevance for memory retrieval (0-1)
  confidenceThreshold: number;      // Minimum confidence for lesson application (0-1)
}

Evaluation Criteria Options

type EvaluationCriterion =
  | 'task-success'      // Did the task succeed?
  | 'quality'          // How well was it executed?
  | 'efficiency'       // Was the approach optimal?
  | 'accuracy'         // How accurate were the results?
  | 'completeness'     // Was the task fully completed?
  | 'relevance'        // How relevant was the output?
  | 'clarity'          // How clear was the communication?
  | 'innovation';      // Was the approach creative/novel?

Reflection Depth Options

type ReflectionDepth = 
  | 'basic'            // Simple success/failure analysis
  | 'detailed'         // Comprehensive lesson extraction
  | 'comprehensive';   // Deep analysis with meta-learning

Tool-Specific Configurations

ADR Generation Tools

const adrReflexionConfig: ReflexionConfig = {
  memoryEnabled: true,
  maxMemoryEntries: 100,
  reflectionDepth: 'comprehensive',
  evaluationCriteria: ['task-success', 'relevance', 'clarity', 'completeness'],
  learningRate: 0.8,
  memoryRetention: 90,
  feedbackIntegration: true,
  autoCleanup: true,
  relevanceThreshold: 0.6,
  confidenceThreshold: 0.7
};

Analysis Tools

const analysisReflexionConfig: ReflexionConfig = {
  memoryEnabled: true,
  maxMemoryEntries: 75,
  reflectionDepth: 'detailed',
  evaluationCriteria: ['accuracy', 'completeness', 'efficiency'],
  learningRate: 0.7,
  memoryRetention: 60,
  feedbackIntegration: true,
  autoCleanup: true,
  relevanceThreshold: 0.5,
  confidenceThreshold: 0.6
};

Research Tools

const researchReflexionConfig: ReflexionConfig = {
  memoryEnabled: true,
  maxMemoryEntries: 60,
  reflectionDepth: 'detailed',
  evaluationCriteria: ['quality', 'relevance', 'innovation'],
  learningRate: 0.75,
  memoryRetention: 120,
  feedbackIntegration: true,
  autoCleanup: true,
  relevanceThreshold: 0.55,
  confidenceThreshold: 0.65
};

Usage Patterns

Pattern 1: Continuous Learning

// For tools that should learn and improve over time
const continuousLearningConfig: ReflexionConfig = {
  memoryEnabled: true,
  maxMemoryEntries: 200,
  reflectionDepth: 'comprehensive',
  evaluationCriteria: ['task-success', 'quality', 'efficiency', 'innovation'],
  learningRate: 0.8,
  memoryRetention: 180,
  feedbackIntegration: true,
  autoCleanup: true
};

Pattern 2: Quick Adaptation

// For tools that need rapid learning from immediate feedback
const quickAdaptationConfig: ReflexionConfig = {
  memoryEnabled: true,
  maxMemoryEntries: 50,
  reflectionDepth: 'detailed',
  evaluationCriteria: ['task-success', 'efficiency'],
  learningRate: 0.9,
  memoryRetention: 30,
  feedbackIntegration: true,
  autoCleanup: true
};

Pattern 3: Conservative Learning

// For tools where stability is more important than rapid adaptation
const conservativeLearningConfig: ReflexionConfig = {
  memoryEnabled: true,
  maxMemoryEntries: 100,
  reflectionDepth: 'basic',
  evaluationCriteria: ['task-success', 'quality'],
  learningRate: 0.5,
  memoryRetention: 365,
  feedbackIntegration: false,
  autoCleanup: false
};

Memory Management

Memory Types and Usage

// Retrieve specific types of memories
const episodicMemories = await retrieveMemories({
  memoryTypes: ['episodic'],
  taskType: 'adr-suggestion',
  maxResults: 10
});

const semanticMemories = await retrieveMemories({
  memoryTypes: ['semantic'],
  keywords: ['microservices', 'scalability'],
  relevanceThreshold: 0.7
});

const proceduralMemories = await retrieveMemories({
  memoryTypes: ['procedural'],
  context: { domain: 'web-applications' },
  maxResults: 5
});

Memory Persistence

// Manually persist important memories
const importantMemory: ReflexionMemory = {
  memoryId: 'critical_lesson_001',
  memoryType: 'semantic',
  content: {
    summary: 'Always validate ADR assumptions with stakeholders',
    lessons: ['Stakeholder validation prevents misaligned decisions'],
    applicableScenarios: ['adr-generation', 'decision-making']
  },
  relevanceScore: 0.95,
  tags: ['stakeholder-alignment', 'validation', 'critical']
};

await persistReflexionMemory(importantMemory);

Learning Progress Tracking

Monitor Learning Effectiveness

// Get learning progress for a specific task type
const progress = await getLearningProgress('adr-suggestion');
console.log('Learning Progress:', {
  successRate: progress.successRate,
  improvementTrend: progress.improvementTrend,
  keyLessons: progress.keyLessons,
  persistentIssues: progress.persistentIssues
});

Detect Learning Plateaus

// Check if learning has plateaued and needs intervention
const plateauAnalysis = progress.plateauDetection;
if (plateauAnalysis.isOnPlateau) {
  console.log('Learning plateau detected:', {
    duration: plateauAnalysis.plateauDuration,
    suggestedInterventions: plateauAnalysis.suggestedInterventions
  });
}

Integration Examples

Example 1: ADR Suggestion with Reflexion

export async function suggestAdrsWithReflexion(context: any) {
  // Step 1: Retrieve relevant memories
  const memories = await retrieveRelevantMemories('adr-suggestion', context);
  
  // Step 2: Create memory-enhanced prompt
  const basePrompt = createAdrSuggestionPrompt(context);
  const enhancedPrompt = await enhancePromptWithMemories(basePrompt, memories);
  
  // Step 3: Execute with reflexion tracking
  const result = await executeWithReflexion(enhancedPrompt, {
    memoryEnabled: true,
    reflectionDepth: 'comprehensive',
    evaluationCriteria: ['task-success', 'relevance', 'clarity'],
    learningRate: 0.8
  });
  
  // Step 4: Return enhanced prompt for AI execution
  return {
    content: [{ type: 'text', text: result.enhancedPrompt.prompt }],
    metadata: {
      reflexionData: {
        memoriesUsed: result.taskAttempt.relatedMemories,
        learningOutcome: result.learningOutcome,
        recommendations: result.recommendations
      }
    }
  };
}

Example 2: Project Analysis with Learning

export async function analyzeProjectWithReflexion(projectPath: string) {
  const basePrompt = createProjectAnalysisPrompt(projectPath);
  
  const result = await executeWithReflexion(basePrompt, {
    memoryEnabled: true,
    reflectionDepth: 'detailed',
    evaluationCriteria: ['accuracy', 'completeness', 'efficiency'],
    learningRate: 0.7,
    memoryRetention: 60
  });
  
  return {
    content: [{ type: 'text', text: result.enhancedPrompt.prompt }],
    metadata: {
      learningMetrics: {
        improvementAchieved: result.learningOutcome.improvementAchieved,
        lessonsLearned: result.learningOutcome.lessonsLearned,
        memoriesCreated: result.learningOutcome.memoriesCreated
      }
    }
  };
}

Performance Considerations

Memory Optimization

// Configure memory limits for performance
const performanceOptimizedConfig: ReflexionConfig = {
  maxMemoryEntries: 50,        // Limit memory storage
  relevanceThreshold: 0.7,     // Only high-relevance memories
  autoCleanup: true,           // Automatic cleanup
  memoryRetention: 30          // Shorter retention for performance
};

Learning Efficiency

// Balance learning speed with stability
const balancedConfig: ReflexionConfig = {
  learningRate: 0.6,           // Moderate learning rate
  confidenceThreshold: 0.7,    // High confidence requirement
  reflectionDepth: 'detailed', // Balanced reflection depth
  feedbackIntegration: true    // Use external feedback
};

Error Handling and Fallbacks

Graceful Degradation

async function executeWithReflexionSafely(
  prompt: PromptObject,
  config: ReflexionConfig
): Promise<PromptObject> {
  try {
    const result = await executeWithReflexion(prompt, config);
    return result.enhancedPrompt;
  } catch (error) {
    console.warn('Reflexion failed, using original prompt:', error);
    return prompt; // Fallback to original
  }
}

Memory Recovery

// Handle memory corruption or loss
async function recoverFromMemoryIssues(taskType: string) {
  try {
    await validateMemoryIntegrity(taskType);
  } catch (error) {
    console.warn('Memory issues detected, rebuilding from backups');
    await rebuildMemoryFromBackups(taskType);
  }
}

Best Practices

1. Configuration Selection

• High-stakes tools: Use comprehensive reflection with conservative learning
• Experimental tools: Use detailed reflection with higher learning rates
• Stable tools: Use basic reflection with low learning rates

2. Memory Management

• Set appropriate memory limits based on tool usage patterns
• Use relevant memory types for different learning objectives
• Implement regular memory cleanup and validation

3. Learning Optimization

• Monitor learning progress and adjust configurations
• Use external feedback when available
• Balance learning speed with stability requirements

4. Performance Monitoring

• Track memory usage and retrieval performance
• Monitor learning effectiveness and plateau detection
• Adjust configurations based on performance metrics

This usage guide provides comprehensive guidance for integrating Reflexion learning capabilities into MCP tools while maintaining the 100% prompt-driven architecture and ensuring effective continuous improvement.