Reflexion Framework Usage Guide

What is Reflexion? Reflexion is a self-improvement framework where the system learns from prior attempts and feedback, then applies those lessons to improve future outputs.

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.