BMAD-METHOD/bmad-core/tasks/memory-synthesis.md

Memory Synthesis Task

Purpose

Extract and synthesize learnings from development work into persistent project memory for future reference and continuous improvement.

When to Use

This task should be executed:

• At the completion of every story implementation
• When manually triggered via *mem-synth orchestrator command
• When adding specific memories via *mem-add orchestrator command

Process

Section 1: Memory Synthesizer Activation

1. Activate Memory Synthesizer Persona:
   • Switch to "Memory Synthesizer" role for objective analysis
   • Focus on extracting generalizable learnings rather than specific implementation details

Section 2: Knowledge Extraction (Two-Pass Analysis)

2. First Pass - Explicit Learnings:

   • Scan all Dev Notes sections in the story file
   • Look for explicit lessons learned, patterns discovered, or insights documented
   • Extract formal review summaries and their conclusions
   • Identify documented anti-patterns or best practices

3. Second Pass - Implicit Learnings:

   • Analyze implementation decisions and their outcomes
   • Identify patterns in complexity assessments and review failures
   • Extract insights from dependency analysis and version considerations
   • Note architectural decisions and their rationale

Section 3: Memory Validation & Synthesis

4. Memory Candidate Generation:

   • Transform specific learnings into generalizable principles
   • Focus on actionable insights that apply beyond the current story
   • Ensure memories are concise but comprehensive
   • Format as clear, actionable statements

5. Conflict Detection & Validation:

   • Load existing project memory from .bmad-core/data/bmad-project-memory.md
   • Check each memory candidate against existing memories
   • Identify potential conflicts or contradictions
   • Resolve conflicts by:
     • Updating existing memory with new insights
     • Creating more nuanced memory that encompasses both perspectives
     • Flagging genuine contradictions for user review

6. Memory Quality Assessment:

   • Ensure memories are:
     • Specific enough to be actionable
     • General enough to apply to future work
     • Clear and unambiguous in their guidance
     • Non-contradictory with existing project knowledge

Section 4: Memory Integration

7. Memory File Update:

   • Append validated new memories to the project memory file
   • Maintain chronological order with clear attribution
   • Use consistent formatting for easy parsing
   • Preserve existing memory structure and organization

8. Integration Verification:

   • Verify the updated memory file is well-formed
   • Ensure no duplicate or contradictory entries exist
   • Confirm all new memories are properly integrated

Memory Quality Standards

Good Memory Examples

• "Authentication logic should be centralized in the auth service; direct token manipulation is an anti-pattern in this codebase"
• "Always validate user inputs before database queries to prevent SQL injection vulnerabilities"
• "Complex UI components (Fibonacci 5+) should include unit tests for state management logic"

Poor Memory Examples (Too Specific)

• "The login button should be blue" (too specific to one implementation)
• "Use React 18.2.0 for this project" (version-specific, not generalizable)
• "File UserService.ts needs refactoring" (specific file reference)

Memory Conflict Resolution

Duplicate Detection:

• Identify memories that convey the same principle
• Merge similar memories into more comprehensive statements
• Preserve the most actionable version

Contradiction Handling:

• Flag genuine contradictions for user review
• Provide context for conflicting approaches
• Suggest resolution strategies when possible

Memory Evolution:

• Update existing memories with new insights
• Refine general principles based on specific experiences
• Maintain memory relevance and accuracy

Output Format

Memory File Structure

# Project Memory

## Development Patterns
- [Memory about coding patterns and practices]

## Architecture Decisions  
- [Memory about architectural choices and rationale]

## Quality Standards
- [Memory about testing, review, and quality practices]

## Technology Insights
- [Memory about specific technologies, libraries, and tools]

## Process Learnings
- [Memory about development process and workflow insights]

Memory Entry Format

- **[Category]**: [Actionable memory statement] (Source: Story [ID], [Date])

Error Handling

Memory Validation Failures

• Duplicate: "I've already got this noted, great minds think alike!"
• Contradiction: "Hmm, this conflicts with what I learned in Story X. Want to discuss which approach is better?"
• Invalid: "This seems too specific to generalize. Could you rephrase it as a broader principle?"
• Success: "Great insight! I've added this to our project memory."

File Access Issues

• Gracefully handle missing memory file (create new one)
• Handle file permission issues with clear error messages
• Provide fallback options when file operations fail

Dependencies

• Access to story file with Dev Notes sections
• Read/write access to .bmad-core/data/bmad-project-memory.md
• Understanding of project context and patterns
• Ability to perform semantic analysis of development notes