469 lines
15 KiB
Markdown
469 lines
15 KiB
Markdown
# Memory System Architecture
|
|
<!-- Comprehensive architectural blueprint for memory system implementation -->
|
|
<!-- For executable memory operations, see tasks/memory-operations-task.md -->
|
|
|
|
> **Note**: This is an architectural guide for memory system implementation, not an executable task. For the executable memory orchestration task, see `bmad-agent/tasks/memory-operations-task.md`.
|
|
|
|
## Purpose
|
|
This guide provides comprehensive instructions for integrating memory capabilities into the BMAD orchestrator and personas. It serves as a reference for developers implementing or extending memory functionality.
|
|
|
|
## Memory Categories & Schemas
|
|
|
|
### 1. Decision Memories
|
|
**Schema**: `decision:{project}:{persona}:{timestamp}`
|
|
**Purpose**: Track architectural and strategic choices with outcomes
|
|
**Content Structure**:
|
|
```json
|
|
{
|
|
"type": "decision",
|
|
"project": "project-name",
|
|
"persona": "architect|pm|dev|design-architect|po|sm|analyst",
|
|
"decision": "chose-nextjs-over-react",
|
|
"rationale": "better ssr support for seo requirements",
|
|
"alternatives_considered": ["react+vite", "vue", "svelte"],
|
|
"constraints": ["team-familiarity", "timeline", "seo-critical"],
|
|
"outcome": "successful|problematic|unknown|in-progress",
|
|
"lessons": "nextjs learning curve was steeper than expected",
|
|
"context_tags": ["frontend", "framework", "ssr", "seo"],
|
|
"follow_up_needed": false,
|
|
"confidence_level": 85,
|
|
"implementation_notes": "migration took 2 extra days due to routing complexity"
|
|
}
|
|
```
|
|
|
|
### 2. Pattern Memories
|
|
**Schema**: `pattern:{workflow-type}:{success-indicator}`
|
|
**Purpose**: Capture successful workflow sequences and anti-patterns
|
|
**Content Structure**:
|
|
```json
|
|
{
|
|
"type": "workflow-pattern",
|
|
"workflow": "new-project-mvp",
|
|
"sequence": ["analyst", "pm", "architect", "design-architect", "po", "sm", "dev"],
|
|
"decision_points": [
|
|
{
|
|
"stage": "pm-to-architect",
|
|
"common_questions": ["monorepo vs polyrepo", "database choice"],
|
|
"success_factors": ["clear-requirements", "defined-constraints"],
|
|
"failure_indicators": ["rushed-handoff", "unclear-scope"]
|
|
}
|
|
],
|
|
"success_indicators": {
|
|
"time_to_first_code": "< 3 days",
|
|
"architecture_stability": "no major changes after dev start",
|
|
"user_satisfaction": "high",
|
|
"technical_debt": "low"
|
|
},
|
|
"anti_patterns": ["skipping-po-validation", "architecture-without-prd"],
|
|
"context_requirements": ["clear-goals", "defined-constraints", "user-research"],
|
|
"optimization_opportunities": ["parallel-work", "early-validation"]
|
|
}
|
|
```
|
|
|
|
### 3. Consultation Memories
|
|
**Schema**: `consultation:{type}:{participants}:{outcome}`
|
|
**Purpose**: Learn from multi-persona collaboration patterns
|
|
**Content Structure**:
|
|
```json
|
|
{
|
|
"type": "consultation",
|
|
"consultation_type": "design-review",
|
|
"participants": ["pm", "architect", "design-architect"],
|
|
"problem": "database scaling for real-time features",
|
|
"perspectives": {
|
|
"pm": "user-experience priority, cost concerns",
|
|
"architect": "technical feasibility, performance requirements",
|
|
"design-architect": "ui responsiveness, loading states"
|
|
},
|
|
"consensus": "implement caching layer with websockets",
|
|
"minority_opinions": ["architect preferred event-sourcing approach"],
|
|
"implementation_success": true,
|
|
"follow_up_needed": false,
|
|
"reusable_insights": ["caching-before-scaling", "websocket-ui-patterns"],
|
|
"time_to_resolution": "40 minutes",
|
|
"satisfaction_score": 8.5
|
|
}
|
|
```
|
|
|
|
### 4. User Preference Memories
|
|
**Schema**: `user-preference:{category}:{pattern}`
|
|
**Purpose**: Learn individual working style and optimize recommendations
|
|
**Content Structure**:
|
|
```json
|
|
{
|
|
"type": "user-preference",
|
|
"category": "workflow-style",
|
|
"pattern": "prefers-detailed-planning",
|
|
"evidence": [
|
|
"always runs PO checklist before development",
|
|
"requests comprehensive architecture before coding",
|
|
"frequently uses doc-sharding for organization"
|
|
],
|
|
"confidence": 0.85,
|
|
"exceptions": ["emergency-fixes", "prototype-development"],
|
|
"optimization_suggestions": [
|
|
"auto-suggest-checklist-runs",
|
|
"proactive-architecture-review"
|
|
],
|
|
"last_validated": "2024-01-15T10:30:00Z"
|
|
}
|
|
```
|
|
|
|
### 5. Problem-Solution Memories
|
|
**Schema**: `problem-solution:{domain}:{solution-type}`
|
|
**Purpose**: Track effective solutions for recurring problems
|
|
**Content Structure**:
|
|
```json
|
|
{
|
|
"type": "problem-solution",
|
|
"domain": "frontend-performance",
|
|
"problem": "slow initial page load with large component tree",
|
|
"solution": "implemented code splitting with React.lazy",
|
|
"implementation_details": {
|
|
"approach": "route-based splitting + component-level lazy loading",
|
|
"libraries": ["react", "react-router-dom"],
|
|
"complexity": "medium",
|
|
"time_investment": "2 days"
|
|
},
|
|
"outcome": {
|
|
"performance_improvement": "60% faster initial load",
|
|
"maintenance_impact": "minimal",
|
|
"user_satisfaction": "high"
|
|
},
|
|
"reusability": "high",
|
|
"prerequisites": ["react-16.6+", "proper-bundler-config"],
|
|
"related_problems": ["component-tree-depth", "bundle-size"]
|
|
}
|
|
```
|
|
|
|
## Memory Operations Integration
|
|
|
|
### Context Restoration with Memory Search
|
|
```python
|
|
def restore_enhanced_context(target_persona, current_session_state):
|
|
# Layer 1: Immediate session context
|
|
immediate_context = load_session_state()
|
|
|
|
# Layer 2: Historical memory search
|
|
memory_queries = [
|
|
f"decisions involving {target_persona} and {extract_key_terms(current_task)}",
|
|
f"successful patterns for {current_project_state.phase} with {current_project_state.tech_stack}",
|
|
f"user preferences for {target_persona} workflows",
|
|
f"problem solutions for {current_project_state.domain}"
|
|
]
|
|
|
|
historical_insights = []
|
|
for query in memory_queries:
|
|
memories = search_memory(query, limit=3, threshold=0.7)
|
|
historical_insights.extend(memories)
|
|
|
|
# Layer 3: Proactive intelligence
|
|
proactive_queries = [
|
|
f"lessons learned from {similar_projects}",
|
|
f"common mistakes in {current_project_state.phase}",
|
|
f"optimization opportunities for {current_workflow}"
|
|
]
|
|
|
|
proactive_insights = search_memory_aggregated(proactive_queries)
|
|
|
|
# Synthesize and present
|
|
return synthesize_context_briefing(
|
|
immediate_context,
|
|
historical_insights,
|
|
proactive_insights,
|
|
target_persona
|
|
)
|
|
```
|
|
|
|
### Auto-Memory Creation Triggers
|
|
**Major Decision Points**:
|
|
```python
|
|
def auto_create_decision_memory(decision_context):
|
|
if is_major_decision(decision_context):
|
|
memory_content = {
|
|
"type": "decision",
|
|
"project": get_current_project(),
|
|
"persona": decision_context.active_persona,
|
|
"decision": decision_context.choice_made,
|
|
"rationale": decision_context.reasoning,
|
|
"alternatives_considered": decision_context.other_options,
|
|
"constraints": extract_constraints(decision_context),
|
|
"timestamp": now(),
|
|
"confidence_level": assess_confidence(decision_context)
|
|
}
|
|
|
|
add_memories(
|
|
content=json.dumps(memory_content),
|
|
tags=generate_decision_tags(memory_content),
|
|
metadata={"type": "decision", "auto_created": True}
|
|
)
|
|
```
|
|
|
|
**Successful Workflow Completions**:
|
|
```python
|
|
def auto_create_pattern_memory(workflow_completion):
|
|
pattern_memory = {
|
|
"type": "workflow-pattern",
|
|
"workflow": workflow_completion.workflow_type,
|
|
"sequence": workflow_completion.persona_sequence,
|
|
"success_indicators": extract_success_metrics(workflow_completion),
|
|
"duration": workflow_completion.total_time,
|
|
"efficiency_score": calculate_efficiency(workflow_completion),
|
|
"user_satisfaction": workflow_completion.satisfaction_rating
|
|
}
|
|
|
|
add_memories(
|
|
content=json.dumps(pattern_memory),
|
|
tags=generate_pattern_tags(pattern_memory),
|
|
metadata={"type": "pattern", "reusability": "high"}
|
|
)
|
|
```
|
|
|
|
**Problem Resolution Outcomes**:
|
|
```python
|
|
def auto_create_solution_memory(problem_resolution):
|
|
solution_memory = {
|
|
"type": "problem-solution",
|
|
"domain": problem_resolution.domain,
|
|
"problem": problem_resolution.problem_description,
|
|
"solution": problem_resolution.solution_implemented,
|
|
"outcome": problem_resolution.measured_results,
|
|
"reusability": assess_reusability(problem_resolution),
|
|
"complexity": problem_resolution.implementation_complexity
|
|
}
|
|
|
|
add_memories(
|
|
content=json.dumps(solution_memory),
|
|
tags=generate_solution_tags(solution_memory),
|
|
metadata={"type": "solution", "effectiveness": solution_memory.outcome.success_rate}
|
|
)
|
|
```
|
|
|
|
## Proactive Intelligence System
|
|
|
|
### Pattern Recognition Engine
|
|
```python
|
|
def recognize_emerging_patterns():
|
|
recent_memories = search_memory(
|
|
"decision outcome pattern",
|
|
time_filter="last_30_days",
|
|
limit=50
|
|
)
|
|
|
|
patterns = {
|
|
"successful_approaches": identify_success_patterns(recent_memories),
|
|
"emerging_anti_patterns": identify_failure_patterns(recent_memories),
|
|
"efficiency_trends": analyze_efficiency_trends(recent_memories),
|
|
"user_adaptation": track_user_behavior_changes(recent_memories)
|
|
}
|
|
|
|
return patterns
|
|
```
|
|
|
|
### Proactive Warning System
|
|
```python
|
|
def generate_proactive_warnings(current_context):
|
|
# Search for similar contexts that led to problems
|
|
problem_memories = search_memory(
|
|
f"problem {current_context.phase} {current_context.persona} {current_context.task_type}",
|
|
limit=5,
|
|
threshold=0.7
|
|
)
|
|
|
|
warnings = []
|
|
for memory in problem_memories:
|
|
if similarity_score(current_context, memory.context) > 0.8:
|
|
warnings.append({
|
|
"warning": memory.problem_description,
|
|
"prevention": memory.prevention_strategy,
|
|
"early_indicators": memory.warning_signs,
|
|
"confidence": calculate_warning_confidence(memory, current_context)
|
|
})
|
|
|
|
return warnings
|
|
```
|
|
|
|
### Intelligent Suggestion Engine
|
|
```python
|
|
def generate_intelligent_suggestions(current_state):
|
|
# Multi-factor suggestion generation
|
|
suggestions = []
|
|
|
|
# Historical success patterns
|
|
success_patterns = search_memory(
|
|
f"successful {current_state.phase} {current_state.project_type}",
|
|
limit=5,
|
|
threshold=0.8
|
|
)
|
|
|
|
for pattern in success_patterns:
|
|
if is_applicable(pattern, current_state):
|
|
suggestions.append({
|
|
"type": "success_pattern",
|
|
"suggestion": pattern.approach,
|
|
"confidence": pattern.success_rate,
|
|
"rationale": pattern.why_it_worked
|
|
})
|
|
|
|
# User preference patterns
|
|
user_prefs = search_memory(
|
|
f"user-preference {current_state.active_persona}",
|
|
limit=3,
|
|
threshold=0.9
|
|
)
|
|
|
|
for pref in user_prefs:
|
|
suggestions.append({
|
|
"type": "personalized",
|
|
"suggestion": pref.preferred_approach,
|
|
"confidence": pref.confidence,
|
|
"rationale": f"Based on your working style: {pref.pattern}"
|
|
})
|
|
|
|
# Optimization opportunities
|
|
optimizations = search_memory(
|
|
f"optimization {current_state.workflow_type}",
|
|
limit=3,
|
|
threshold=0.7
|
|
)
|
|
|
|
for opt in optimizations:
|
|
suggestions.append({
|
|
"type": "optimization",
|
|
"suggestion": opt.improvement,
|
|
"confidence": opt.effectiveness,
|
|
"rationale": f"Could save: {opt.time_savings}"
|
|
})
|
|
|
|
return rank_suggestions(suggestions)
|
|
```
|
|
|
|
## Memory Quality Management
|
|
|
|
### Memory Validation & Cleanup
|
|
```python
|
|
def validate_memory_quality():
|
|
# Find outdated memories
|
|
outdated = search_memory(
|
|
"decision outcome",
|
|
time_filter="older_than_90_days",
|
|
limit=100
|
|
)
|
|
|
|
for memory in outdated:
|
|
# Validate if still relevant
|
|
if not is_still_relevant(memory):
|
|
archive_memory(memory)
|
|
elif needs_update(memory):
|
|
update_memory_with_new_insights(memory)
|
|
|
|
# Identify conflicting memories
|
|
conflicts = detect_memory_conflicts()
|
|
for conflict in conflicts:
|
|
resolve_memory_conflict(conflict)
|
|
```
|
|
|
|
### Memory Consolidation
|
|
```python
|
|
def consolidate_memories():
|
|
# Weekly consolidation process
|
|
related_memories = group_related_memories()
|
|
|
|
for group in related_memories:
|
|
if should_consolidate(group):
|
|
consolidated = create_consolidated_memory(group)
|
|
replace_memories(group, consolidated)
|
|
```
|
|
|
|
## Integration with BMAD Operations
|
|
|
|
### Enhanced Persona Briefings
|
|
```markdown
|
|
# 🧠 Memory-Enhanced Briefing for {Persona}
|
|
|
|
## Relevant Experience
|
|
**From Similar Situations**:
|
|
- {relevant_memory_1.summary}
|
|
- {relevant_memory_2.summary}
|
|
|
|
**What Usually Works**:
|
|
- {success_pattern_1}
|
|
- {success_pattern_2}
|
|
|
|
**What to Avoid**:
|
|
- {anti_pattern_1}
|
|
- {anti_pattern_2}
|
|
|
|
## Your Working Style
|
|
**Based on past interactions**:
|
|
- You typically prefer: {user_preference_1}
|
|
- You're most effective when: {optimal_conditions}
|
|
- Watch out for: {personal_pitfall_patterns}
|
|
|
|
## Proactive Insights
|
|
⚠️ **Potential Issues**: {proactive_warnings}
|
|
💡 **Optimization Opportunities**: {efficiency_suggestions}
|
|
🎯 **Success Factors**: {recommended_approaches}
|
|
```
|
|
|
|
### Memory-Enhanced Decision Support
|
|
```markdown
|
|
# 🤔 Memory-Enhanced Decision Support
|
|
|
|
## Similar Past Decisions
|
|
**{Similar Decision 1}** (Confidence: {similarity}%)
|
|
- **Chosen**: {past_choice}
|
|
- **Outcome**: {past_outcome}
|
|
- **Lesson**: {key_learning}
|
|
|
|
## Pattern Analysis
|
|
**Success Rate by Option**:
|
|
- Option A: {success_rate}% (based on {n} cases)
|
|
- Option B: {success_rate}% (based on {n} cases)
|
|
|
|
## Recommendation
|
|
**Suggested**: {memory_based_recommendation}
|
|
**Confidence**: {confidence_level}%
|
|
**Rationale**: {evidence_from_memory}
|
|
```
|
|
|
|
## Memory Commands Integration
|
|
|
|
### Available Memory Commands
|
|
```bash
|
|
# Core memory operations
|
|
/remember <content> # Manually add important memories
|
|
/recall <query> # Search memories with natural language
|
|
/insights # Get proactive insights for current context
|
|
/patterns # Show recognized patterns in working style
|
|
|
|
# Analysis and optimization
|
|
/memory-analyze # Analyze memory patterns and quality
|
|
/learn # Process recent outcomes and update intelligence
|
|
/consolidate # Run memory consolidation process
|
|
/cleanup # Archive outdated memories
|
|
|
|
# Specific memory types
|
|
/remember-decision <details> # Log a specific decision with context
|
|
/remember-lesson <content> # Log a lesson learned
|
|
/remember-preference <pref> # Update user preference memory
|
|
/remember-solution <sol> # Log a successful problem solution
|
|
```
|
|
|
|
### Memory Command Implementations
|
|
```python
|
|
def handle_memory_commands(command, args, current_context):
|
|
if command == "/remember":
|
|
return manual_memory_creation(args, current_context)
|
|
elif command == "/recall":
|
|
return memory_search_interface(args)
|
|
elif command == "/insights":
|
|
return generate_proactive_insights(current_context)
|
|
elif command == "/patterns":
|
|
return analyze_user_patterns(current_context.user_id)
|
|
elif command == "/learn":
|
|
return run_learning_cycle()
|
|
# ... implement other commands
|
|
```
|
|
|
|
This memory orchestration system transforms BMAD from a stateless process into an intelligent, learning development companion that accumulates wisdom and provides increasingly sophisticated guidance over time. |