BMAD-METHOD/bmad-agent/memory/context-persistence-engine.md

620 lines
26 KiB
Markdown

# BMAD Context Persistence Engine Methodology
## Overview
The Context Persistence Engine provides a comprehensive methodology for maintaining conversation context and project information across sessions within the BMAD Method framework. This engine ensures seamless continuity for users working on long-term projects while maintaining data integrity, privacy, and performance.
## Methodology Framework Clarification
**Important:** This Context Persistence Engine is a **methodology framework**, not an application. The BMAD Method provides:
1. **Conceptual Framework**: How to think about context persistence across AI agent sessions
2. **Implementation Patterns**: Reusable patterns that can be adapted to any AI platform
3. **Configuration Templates**: Methodology for configuring persistence in different environments
4. **Quality Standards**: Validation criteria for any implementation
### How This Works as Methodology
#### For AI Agent Users
- **Thinking Framework**: How to conceptualize context persistence in your AI interactions
- **Organization Patterns**: Systematic approaches to organizing and maintaining context
- **Quality Guidelines**: Standards for evaluating context persistence effectiveness
- **Application Methods**: How to apply these concepts in your specific AI environment
#### For Teams and Organizations
- **Standards Framework**: Adopt these methodologies as organizational standards
- **Training Materials**: Use these patterns to train teams on context persistence
- **Governance Framework**: Apply these quality standards across AI implementations
## Core Architecture Methodology
### Context Persistence Framework
#### Context Entity Lifecycle Methodology
```yaml
context_lifecycle_methodology:
creation_phase:
principles:
- "Identify significant context moments during AI interactions"
- "Capture context while information is fresh and complete"
- "Establish relationships between related context elements"
- "Apply consistent metadata standards for future retrieval"
application_methods:
- "Document decisions immediately after they are made"
- "Record rationale and alternatives considered"
- "Note stakeholders and impact assessments"
- "Create searchable tags and categories"
active_management_phase:
principles:
- "Maintain context accuracy through regular updates"
- "Strengthen relationships between related contexts"
- "Monitor context usage and effectiveness"
- "Apply quality standards consistently"
application_methods:
- "Review and update context during project milestones"
- "Link new decisions to historical context"
- "Track which contexts are most valuable"
- "Validate context accuracy with stakeholders"
persistence_phase:
principles:
- "Organize context for long-term accessibility"
- "Apply appropriate retention policies"
- "Ensure context integrity over time"
- "Optimize for future retrieval needs"
application_methods:
- "Categorize context by importance and frequency of access"
- "Create summary documents for complex contexts"
- "Establish archival procedures for outdated context"
- "Maintain backup copies of critical context"
restoration_phase:
principles:
- "Quickly locate relevant historical context"
- "Reconstruct complete context pictures"
- "Validate context relevance to current needs"
- "Integrate historical context with current work"
application_methods:
- "Use systematic search strategies"
- "Cross-reference related context elements"
- "Verify context accuracy before application"
- "Adapt historical context to current circumstances"
```
#### Context Persistence Layers Methodology
```yaml
persistence_layers_methodology:
session_layer:
purpose: "Manage active conversation and task context"
methodology: "Maintain awareness of current session state and immediate history"
application: "Keep track of current conversation flow and immediate decisions"
retention_approach: "Maintain for duration of active work session"
project_layer:
purpose: "Maintain project-specific context and decisions"
methodology: "Build comprehensive project knowledge over time"
application: "Connect current work to overall project objectives and history"
retention_approach: "Maintain throughout project lifecycle"
user_layer:
purpose: "Capture user preferences and working patterns"
methodology: "Learn and adapt to individual user needs and styles"
application: "Customize AI interactions based on user preferences"
retention_approach: "Maintain based on user-defined preferences"
organizational_layer:
purpose: "Apply organizational knowledge and standards"
methodology: "Ensure consistency with organizational practices"
application: "Apply organizational standards and best practices"
retention_approach: "Maintain according to organizational policies"
```
### Context Organization Methodology
#### Organization Strategy Framework
```yaml
organization_strategies:
structured_organization:
approach: "Systematic categorization using predefined schemas"
advantages:
- "Consistent organization across all contexts"
- "Easy validation against standards"
- "Cross-platform compatibility"
- "Version control friendly"
application_methods:
- "Define standard categories for your domain"
- "Create templates for common context types"
- "Establish tagging conventions"
- "Implement quality checklists"
flexible_organization:
approach: "Adaptive organization based on context characteristics"
advantages:
- "Optimized for specific use cases"
- "Flexible implementation options"
- "Balanced effectiveness"
- "Maintainable structure"
application_methods:
- "Analyze context characteristics before organizing"
- "Choose organization method based on context type"
- "Adapt organization as context evolves"
- "Balance structure with flexibility"
```
#### Context Organization Implementation Methodology
Instead of code, here's the thinking framework:
**Context Organization Decision Process:**
1. **Analyze Context Characteristics**: Determine context type, complexity, and relationships
2. **Select Organization Strategy**: Choose structured or flexible approach based on analysis
3. **Apply Organization Method**: Use selected strategy to organize context systematically
4. **Validate Organization Quality**: Ensure organization meets quality standards
5. **Document Organization Rationale**: Record why specific organization choices were made
**Context Preparation Methodology:**
1. **Create Working Copy**: Ensure original context remains unchanged during organization
2. **Resolve Relationships**: Identify and document connections to other contexts
3. **Normalize Information**: Ensure consistent format and terminology
4. **Apply Privacy Guidelines**: Remove or protect sensitive information as needed
5. **Optimize for Access**: Structure context for efficient future retrieval
### Context Storage Methodology
#### Multi-Tier Organization Architecture
```yaml
organization_architecture:
frequently_accessed_context:
description: "Context needed regularly in current work"
characteristics:
- access_frequency: "daily_or_weekly"
- importance: "high_for_current_work"
- organization: "easily_accessible_format"
- maintenance: "regular_updates_needed"
application_methods:
- "Keep in primary workspace or notebook"
- "Use quick-reference formats"
- "Update regularly during work sessions"
- "Organize for immediate access"
occasionally_accessed_context:
description: "Context needed periodically for reference"
characteristics:
- access_frequency: "monthly_or_quarterly"
- importance: "moderate_for_ongoing_work"
- organization: "structured_reference_format"
- maintenance: "periodic_review_and_update"
application_methods:
- "Organize in reference documentation"
- "Create searchable summaries"
- "Review during project milestones"
- "Maintain clear categorization"
archived_context:
description: "Historical context for long-term reference"
characteristics:
- access_frequency: "rarely_but_valuable"
- importance: "historical_reference_value"
- organization: "compressed_summary_format"
- maintenance: "minimal_ongoing_maintenance"
application_methods:
- "Create comprehensive summaries"
- "Organize by time period or project phase"
- "Maintain minimal but complete records"
- "Focus on lessons learned and key decisions"
```
#### Organization Selection Methodology
Instead of algorithmic code, here's the decision framework:
**Organization Tier Selection Process:**
1. **Assess Context Characteristics**: Analyze context importance, complexity, and relationships
2. **Evaluate Access Patterns**: Determine how frequently context will be needed
3. **Consider Maintenance Requirements**: Assess ongoing update and maintenance needs
4. **Apply Selection Criteria**: Use established criteria to choose appropriate tier
5. **Validate Selection**: Ensure chosen tier meets current and future needs
**Selection Criteria Framework:**
- **High-frequency access + Current relevance** = Frequently accessed tier
- **Moderate frequency + Ongoing relevance** = Occasionally accessed tier
- **Low frequency + Historical value** = Archived tier
- **No ongoing value** = Consider for removal
### Context Restoration Methodology
#### Restoration Process Framework
```yaml
restoration_methodology:
context_location_phase:
principles:
- "Use systematic search strategies"
- "Apply multiple search approaches"
- "Verify context completeness"
- "Check access appropriateness"
application_methods:
- "Start with most likely locations"
- "Use keyword and tag-based searches"
- "Cross-reference related contexts"
- "Validate context relevance to current needs"
context_reconstruction_phase:
principles:
- "Rebuild complete context picture"
- "Validate information accuracy"
- "Reconstruct decision rationale"
- "Identify missing elements"
application_methods:
- "Gather all related context elements"
- "Verify information currency and accuracy"
- "Reconstruct timeline and decision flow"
- "Identify and fill information gaps"
relationship_restoration_phase:
principles:
- "Identify context relationships"
- "Rebuild connection understanding"
- "Validate relationship accuracy"
- "Update relationship understanding"
application_methods:
- "Map connections between context elements"
- "Verify relationship relevance"
- "Update relationships based on new information"
- "Document relationship rationale"
context_validation_phase:
principles:
- "Verify context completeness"
- "Check information consistency"
- "Validate against current standards"
- "Ensure appropriate access"
application_methods:
- "Compare against quality checklists"
- "Cross-check with other sources"
- "Validate with stakeholders if needed"
- "Confirm context appropriateness"
context_activation_phase:
principles:
- "Integrate with current work"
- "Update access records"
- "Monitor context usage"
- "Document restoration success"
application_methods:
- "Apply context to current decisions"
- "Note when context was accessed"
- "Track context effectiveness"
- "Record restoration lessons learned"
```
#### Restoration Implementation Methodology
Instead of code implementation, here's the thinking framework:
**Context Restoration Decision Process:**
1. **Define Restoration Needs**: Clearly identify what context is needed and why
2. **Locate Context Sources**: Systematically search available context repositories
3. **Validate Context Quality**: Ensure located context meets current needs
4. **Reconstruct Complete Picture**: Assemble all relevant context elements
5. **Apply to Current Work**: Integrate restored context into current activities
**Relationship Reconstruction Methodology:**
1. **Identify Relationship References**: Find connections mentioned in context
2. **Locate Related Contexts**: Search for contexts referenced in relationships
3. **Validate Relationship Relevance**: Ensure relationships are still meaningful
4. **Rebuild Understanding**: Reconstruct how contexts relate to each other
5. **Document Relationship Value**: Record why relationships are important
### Context Expiration and Cleanup Methodology
#### Expiration Policy Framework
```yaml
expiration_methodologies:
time_based_expiration:
absolute_expiration:
description: "Context expires at specific time or project phase"
application: "Set clear expiration dates for temporary contexts"
methodology: "Compare current date/phase to expiration criteria"
relative_expiration:
description: "Context expires after period of non-use"
application: "Remove contexts that haven't been accessed recently"
methodology: "Track access patterns and apply sliding window criteria"
hybrid_expiration:
description: "Combination of time and usage-based expiration"
application: "Apply multiple criteria for complex context lifecycle"
methodology: "Evaluate against multiple expiration criteria"
value_based_expiration:
relevance_assessment:
description: "Expire based on ongoing relevance to work"
criteria: "Regular assessment of context value and applicability"
usage_patterns:
description: "Expire based on actual usage and access patterns"
criteria: "Monitor how frequently context is accessed and applied"
stakeholder_preferences:
description: "Expire based on user or organizational preferences"
criteria: "Apply user-defined or organizational retention policies"
```
#### Cleanup Process Methodology
Instead of code, here's the systematic approach:
**Context Cleanup Decision Process:**
1. **Initialize Cleanup Session**: Define cleanup scope and criteria
2. **Identify Expiration Candidates**: Apply expiration policies to identify contexts
3. **Categorize Cleanup Actions**: Determine appropriate action for each context
4. **Execute Cleanup Actions**: Apply chosen actions systematically
5. **Document Cleanup Results**: Record what was done and why
**Cleanup Action Categories:**
- **Archive**: Move to long-term storage for historical reference
- **Summarize**: Create condensed version retaining key information
- **Update**: Refresh context with current information
- **Remove**: Delete contexts with no ongoing value
- **Migrate**: Move to different organization tier
## Cross-Session Continuity Methodology
### Session State Management Methodology
#### Session Context Preservation Framework
```yaml
session_preservation_methodology:
session_snapshot_approach:
components_to_capture:
- "Current conversation state and flow"
- "Active decisions and their rationale"
- "Work progress and next steps"
- "Temporary insights and observations"
- "Session-specific preferences and settings"
snapshot_creation_triggers:
systematic_triggers:
- "End of significant work sessions"
- "Completion of major decisions or milestones"
- "Before switching to different work contexts"
- "At regular intervals during long sessions"
snapshot_organization_approach:
organization_method: "Structured documentation in accessible format"
content_format: "Clear, searchable text with consistent structure"
security_approach: "Apply appropriate privacy protection"
retention_method: "Maintain according to established retention policies"
```
#### Session Restoration Methodology
Instead of code, here's the restoration thinking framework:
**Session Context Restoration Process:**
1. **Identify Target Session**: Determine which previous session context is needed
2. **Locate Session Information**: Find documentation from target session
3. **Validate Session Relevance**: Ensure session context applies to current work
4. **Reconstruct Session State**: Rebuild understanding of previous session
5. **Integrate with Current Work**: Apply session context to current activities
**Session Context Integration Methodology:**
1. **Assess Current State**: Understand current work context and needs
2. **Identify Relevant History**: Find applicable elements from previous sessions
3. **Merge Contexts**: Combine historical and current context appropriately
4. **Validate Integration**: Ensure merged context is coherent and useful
5. **Activate Integrated Context**: Apply combined context to current work
### Context Sharing Methodology
#### Cross-Platform Context Sharing Framework
```yaml
cross_platform_sharing_methodology:
synchronization_approaches:
real_time_coordination:
description: "Immediate coordination across platforms and team members"
methodology: "Establish shared documentation and communication protocols"
application: "Use for collaborative work and multi-platform workflows"
periodic_coordination:
description: "Regular coordination at defined intervals"
methodology: "Schedule regular context sharing and synchronization sessions"
application: "Use for background coordination and resource optimization"
on_demand_coordination:
description: "User-initiated coordination when needed"
methodology: "Provide clear procedures for manual context sharing"
application: "Use for controlled coordination and privacy-focused sharing"
conflict_resolution_approaches:
priority_based_resolution:
description: "Most recent or highest priority change takes precedence"
methodology: "Establish clear priority criteria and apply consistently"
collaborative_resolution:
description: "Intelligent merging of different context versions"
methodology: "Use systematic approaches to combine conflicting contexts"
stakeholder_resolution:
description: "User-guided resolution of context conflicts"
methodology: "Provide clear procedures for resolving context conflicts"
```
## Privacy and Security Methodology
### Privacy-Preserving Context Management
#### Data Minimization Methodology
```yaml
data_minimization_approach:
collection_principles:
- "Capture only context necessary for work objectives"
- "Minimize personal and sensitive information in context"
- "Apply anonymization where possible and appropriate"
- "Provide user control over context collection scope"
organization_optimization:
- "Remove redundant and duplicate context information"
- "Identify and consolidate common patterns"
- "Archive inactive context according to retention policies"
- "Remove expired context according to established criteria"
access_limitation:
- "Apply need-to-know principles for context access"
- "Provide time-limited access where appropriate"
- "Monitor and audit context access patterns"
- "Remove unnecessary access permissions regularly"
```
#### Security and Privacy Framework
Instead of encryption code, here's the security methodology:
**Context Security Decision Process:**
1. **Assess Context Sensitivity**: Determine security requirements for context
2. **Select Protection Strategy**: Choose appropriate protection methods
3. **Apply Protection Measures**: Implement chosen security approaches
4. **Validate Protection Effectiveness**: Ensure security measures are working
5. **Maintain Security Standards**: Keep protection measures current and effective
**Protection Strategy Selection:**
- **Public Context**: Standard organization and access controls
- **Sensitive Context**: Enhanced protection and limited access
- **Confidential Context**: Maximum protection and audit trails
- **Personal Context**: User-controlled access and retention
## Performance Optimization Methodology
### Context Management Performance Framework
#### Performance Measurement Methodology
```yaml
performance_metrics_framework:
context_management_metrics:
- "Time required to create and organize context"
- "Speed of context location and retrieval"
- "Effectiveness of context organization systems"
- "Efficiency of context compression and summarization"
context_usage_metrics:
- "Time required to locate relevant context"
- "Accuracy of context retrieval results"
- "Speed of context reconstruction and application"
- "Overall time savings from context reuse"
system_effectiveness_metrics:
- "Context organization consistency and quality"
- "Context access and retrieval success rates"
- "User satisfaction with context management"
- "Error rates in context application"
```
#### Performance Optimization Methodology
Instead of optimization code, here's the improvement framework:
**Context Performance Optimization Process:**
1. **Analyze Current Performance**: Measure current context management effectiveness
2. **Identify Improvement Opportunities**: Find areas where performance can be enhanced
3. **Select Optimization Strategies**: Choose appropriate improvement approaches
4. **Apply Optimization Methods**: Implement selected performance improvements
5. **Measure Optimization Impact**: Assess effectiveness of optimization efforts
**Optimization Strategy Selection:**
- **Organization Optimization**: Improve context categorization and structure
- **Access Optimization**: Enhance context search and retrieval methods
- **Quality Optimization**: Improve context accuracy and completeness
- **Process Optimization**: Streamline context management workflows
## Integration Methodology
### Orchestrator Integration Framework
#### Context Management Events Methodology
```yaml
context_management_events:
context_creation_events:
description: "Significant context creation moments"
information_captured: "Context metadata and creation rationale"
stakeholder_notification: "Inform relevant team members and systems"
context_update_events:
description: "Important context modifications"
information_captured: "Update details and modification rationale"
stakeholder_notification: "Notify affected team members and processes"
context_access_events:
description: "Context retrieval and application"
information_captured: "Access details and application context"
stakeholder_notification: "Update usage tracking and analytics"
context_expiration_events:
description: "Context reaching end of useful life"
information_captured: "Expiration details and cleanup actions"
stakeholder_notification: "Inform cleanup and archival processes"
```
### Memory Architecture Integration Methodology
#### Memory-Context Coordination Framework
Instead of coordination code, here's the integration methodology:
**Memory-Context Integration Process:**
1. **Analyze Integration Needs**: Determine how memory and context should work together
2. **Design Coordination Strategy**: Plan how memory and context will be coordinated
3. **Implement Coordination Approach**: Apply chosen integration strategy
4. **Validate Integration Effectiveness**: Ensure memory and context work well together
5. **Optimize Integration Performance**: Improve coordination based on experience
**Coordination Strategy Options:**
- **Immediate Integration**: Memory and context updated together in real-time
- **Deferred Integration**: Memory and context synchronized at regular intervals
- **Independent Operation**: Memory and context managed separately with manual coordination
## Quality Assurance Methodology
### Context Integrity Validation Framework
#### Integrity Assessment Methodology
```yaml
integrity_assessment_framework:
information_integrity:
- "Verify context accuracy and completeness"
- "Ensure consistent terminology and format"
- "Validate information currency and relevance"
- "Check relationship accuracy and completeness"
logical_integrity:
- "Ensure context aligns with business rules and standards"
- "Verify workflow state consistency"
- "Check temporal consistency and logical flow"
- "Validate access control compliance"
system_integrity:
- "Assess context organization system health"
- "Verify backup and recovery system status"
- "Check security measure effectiveness"
- "Ensure performance standard compliance"
```
#### Validation Implementation Methodology
Instead of validation code, here's the quality assurance framework:
**Context Quality Validation Process:**
1. **Define Validation Scope**: Determine what aspects of context to validate
2. **Apply Validation Criteria**: Use established quality standards for assessment
3. **Identify Quality Issues**: Find areas where context doesn't meet standards
4. **Develop Improvement Plan**: Create plan to address identified quality issues
5. **Implement Quality Improvements**: Apply improvements and validate effectiveness
**Quality Assessment Areas:**
- **Content Quality**: Accuracy, completeness, and relevance of context information
- **Organization Quality**: Effectiveness of context categorization and structure
- **Access Quality**: Ease and accuracy of context retrieval and application
- **Maintenance Quality**: Effectiveness of context updates and lifecycle management
This Context Persistence Engine methodology provides a comprehensive framework for implementing context persistence across sessions while maintaining data integrity, privacy, and performance within the BMAD Method framework - all through systematic approaches and thinking frameworks rather than specific technical implementations.