# Project Memory Manager

## Persistent Project Memory System for Claude Code

The Project Memory Manager provides Claude Code with long-term memory capabilities, enabling it to remember solutions, learn from experiences, and maintain context across sessions.

### Memory Architecture for Claude Code Integration

#### Memory Structure
```yaml
project_memory:
  session_memory:
    current_context:
      - active_decisions: "Decisions made in current session"
      - working_artifacts: "Files being actively worked on"
      - active_personas: "Currently engaged AI personas"
      - current_goals: "Session objectives and priorities"
      - claude_code_state: "Tool usage history and file states"
      
    conversation_history:
      - message_threads: "Inter-persona communications"
      - decision_points: "Critical decision moments"
      - conflict_resolutions: "How conflicts were resolved"
      - claude_commands: "History of Claude Code tool usage"
      
  long_term_memory:
    decisions_made:
      - decision_id: "{uuid}"
        context: "When: project phase, why: rationale, who: decision maker"
        decision_text: "Chosen approach or technology"
        alternatives_considered: ["option1", "option2", "option3"]
        outcome: "Success|Failure|Partial"
        success_metrics: "Quantifiable measures of success"
        lessons_learned: "What we learned from this decision"
        
    solutions_implemented:
      - solution_id: "{uuid}"
        problem: "Detailed problem description"
        context: "Project circumstances when problem occurred"
        approach: "How the problem was solved"
        code_patterns: "Specific code patterns used"
        tools_used: ["Read", "Write", "Edit", "Bash", "Grep"]
        effectiveness: "Success rate and metrics"
        reusability: "How applicable to other situations"
        file_locations: "Where solution was implemented"
        
    errors_encountered:
      - error_id: "{uuid}"
        description: "What went wrong"
        context: "Circumstances leading to error"
        root_cause: "Fundamental cause analysis"
        prevention: "How to avoid in future"
        detection_patterns: "How to recognize early"
        recovery_steps: "How to fix when it happens"
        tools_involved: "Which Claude Code tools were involved"
        
    pattern_library:
      - pattern_id: "{uuid}"
        pattern_name: "Descriptive name"
        pattern_type: "architectural|code|workflow|communication"
        success_contexts: "Where this pattern worked well"
        failure_contexts: "Where this pattern failed"
        adaptation_notes: "How to adapt for different contexts"
        related_patterns: "Complementary or alternative patterns"
```

### Memory Operations for Claude Code

#### Memory Storage with Claude Code Integration
```python
async def store_memory_with_claude_context(memory_item, claude_context):
    """
    Store memory with full Claude Code context integration
    """
    # Enrich memory with Claude Code context
    enriched_memory = {
        **memory_item,
        'claude_code_context': {
            'files_involved': claude_context.get('active_files', []),
            'tools_used': claude_context.get('recent_tools', []),
            'git_state': await get_git_context(),
            'project_structure': await analyze_project_structure(),
            'session_id': claude_context.get('session_id')
        },
        'timestamp': datetime.utcnow().isoformat(),
        'memory_type': classify_memory_type(memory_item)
    }
    
    # Store in structured format for easy retrieval
    memory_storage_path = determine_storage_path(enriched_memory)
    await store_memory_item(enriched_memory, memory_storage_path)
    
    # Create searchable index
    await index_memory_for_search(enriched_memory)
    
    # Link to related memories
    await create_memory_relationships(enriched_memory)
    
    return {
        'memory_id': enriched_memory['id'],
        'storage_path': memory_storage_path,
        'indexed': True,
        'relationships_created': True
    }

async def store_solution_memory(problem, solution, outcome, claude_tools_used):
    """
    Store a successful solution with Claude Code tool context
    """
    solution_memory = {
        'id': generate_uuid(),
        'type': 'solution',
        'problem': {
            'description': problem['description'],
            'context': problem['context'],
            'constraints': problem.get('constraints', []),
            'complexity_level': assess_complexity(problem)
        },
        'solution': {
            'approach': solution['approach'],
            'implementation_steps': solution['steps'],
            'code_changes': solution.get('code_changes', []),
            'configuration_changes': solution.get('config_changes', []),
            'tools_sequence': claude_tools_used
        },
        'outcome': {
            'success_level': outcome['success_level'],
            'metrics': outcome.get('metrics', {}),
            'user_satisfaction': outcome.get('satisfaction'),
            'performance_impact': outcome.get('performance'),
            'maintainability_impact': outcome.get('maintainability')
        },
        'reusability': {
            'applicable_contexts': identify_applicable_contexts(problem, solution),
            'adaptation_guide': create_adaptation_guide(solution),
            'prerequisites': solution.get('prerequisites', []),
            'known_variations': []
        }
    }
    
    # Store with Claude Code context
    current_claude_context = await get_current_claude_context()
    return await store_memory_with_claude_context(
        solution_memory, 
        current_claude_context
    )

async def store_error_memory(error_details, recovery_actions, claude_context):
    """
    Store error experience for future prevention
    """
    error_memory = {
        'id': generate_uuid(),
        'type': 'error',
        'error': {
            'description': error_details['description'],
            'error_type': classify_error_type(error_details),
            'symptoms': error_details['symptoms'],
            'context': error_details['context'],
            'impact': error_details['impact']
        },
        'analysis': {
            'root_cause': error_details['root_cause'],
            'contributing_factors': error_details.get('contributing_factors', []),
            'detection_difficulty': error_details.get('detection_difficulty'),
            'prevention_difficulty': error_details.get('prevention_difficulty')
        },
        'recovery': {
            'steps_taken': recovery_actions['steps'],
            'tools_used': recovery_actions['tools'],
            'time_to_recovery': recovery_actions.get('duration'),
            'effectiveness': recovery_actions['effectiveness']
        },
        'prevention': {
            'early_warning_signs': identify_warning_signs(error_details),
            'prevention_strategies': create_prevention_strategies(error_details),
            'detection_rules': create_detection_rules(error_details),
            'automated_checks': suggest_automated_checks(error_details)
        }
    }
    
    return await store_memory_with_claude_context(error_memory, claude_context)
```

#### Memory Retrieval with Context Awareness
```python
async def retrieve_relevant_memories(current_context, query_type='all'):
    """
    Retrieve memories relevant to current Claude Code context
    """
    # Analyze current context for retrieval cues
    context_cues = extract_context_cues(current_context)
    
    # Search strategies based on context
    search_strategies = {
        'file_based': search_by_file_patterns(context_cues.file_patterns),
        'technology_based': search_by_technology_stack(context_cues.tech_stack),
        'problem_based': search_by_problem_similarity(context_cues.current_problem),
        'tool_based': search_by_tool_usage(context_cues.tools_being_used)
    }
    
    # Execute parallel searches
    search_results = await asyncio.gather(*[
        strategy() for strategy in search_strategies.values()
    ])
    
    # Combine and rank results
    combined_results = combine_search_results(search_results)
    ranked_memories = rank_by_relevance(combined_results, current_context)
    
    # Filter by query type
    if query_type != 'all':
        ranked_memories = filter_by_type(ranked_memories, query_type)
    
    return {
        'relevant_memories': ranked_memories[:10],  # Top 10 most relevant
        'search_metadata': {
            'total_found': len(combined_results),
            'context_cues': context_cues,
            'search_strategies_used': list(search_strategies.keys())
        }
    }

async def get_solution_recommendations(current_problem, claude_context):
    """
    Get solution recommendations based on historical memory
    """
    # Find similar problems from memory
    similar_problems = await search_similar_problems(
        current_problem,
        claude_context
    )
    
    recommendations = []
    for similar_case in similar_problems:
        # Extract applicable solutions
        applicable_solutions = extract_applicable_solutions(
            similar_case,
            current_problem,
            claude_context
        )
        
        for solution in applicable_solutions:
            # Adapt solution to current context
            adapted_solution = await adapt_solution_to_context(
                solution,
                current_problem,
                claude_context
            )
            
            # Calculate confidence score
            confidence = calculate_solution_confidence(
                solution['historical_success'],
                adapted_solution['adaptation_complexity'],
                context_similarity(similar_case['context'], claude_context)
            )
            
            recommendation = {
                'solution': adapted_solution,
                'confidence': confidence,
                'historical_case': similar_case['id'],
                'adaptation_notes': adapted_solution['adaptation_notes'],
                'expected_effort': estimate_implementation_effort(adapted_solution),
                'risk_factors': identify_risk_factors(adapted_solution, current_problem)
            }
            
            recommendations.append(recommendation)
    
    # Sort by confidence and return top recommendations
    return sorted(recommendations, key=lambda x: x['confidence'], reverse=True)[:5]

async def get_error_prevention_guidance(current_activity, claude_context):
    """
    Provide error prevention guidance based on memory
    """
    # Identify potential risks in current activity
    risk_indicators = identify_risk_indicators(current_activity, claude_context)
    
    # Search for similar past errors
    similar_errors = await search_similar_error_contexts(risk_indicators)
    
    prevention_guidance = []
    for error_case in similar_errors:
        # Extract prevention strategies
        prevention_strategies = error_case['prevention']['prevention_strategies']
        
        # Adapt to current context
        adapted_strategies = adapt_prevention_strategies(
            prevention_strategies,
            current_activity,
            claude_context
        )
        
        guidance = {
            'risk_type': error_case['error']['error_type'],
            'warning_signs': error_case['prevention']['early_warning_signs'],
            'prevention_actions': adapted_strategies,
            'detection_rules': error_case['prevention']['detection_rules'],
            'historical_case': error_case['id'],
            'severity': error_case['error']['impact']
        }
        
        prevention_guidance.append(guidance)
    
    return {
        'high_priority_guidance': [g for g in prevention_guidance if g['severity'] == 'high'],
        'medium_priority_guidance': [g for g in prevention_guidance if g['severity'] == 'medium'],
        'all_guidance': prevention_guidance
    }
```

### Memory Lifecycle Management

#### Automatic Memory Capture
```python
async def automatic_memory_capture():
    """
    Automatically capture memory from Claude Code sessions
    """
    # Monitor Claude Code tool usage
    tool_monitor = ToolUsageMonitor()
    
    # Monitor file changes
    file_monitor = FileChangeMonitor()
    
    # Monitor conversation flow
    conversation_monitor = ConversationMonitor()
    
    async def capture_loop():
        while True:
            # Check for significant events
            significant_events = await detect_significant_events([
                tool_monitor,
                file_monitor,
                conversation_monitor
            ])
            
            for event in significant_events:
                if event.type == 'problem_solved':
                    await capture_solution_memory(event)
                elif event.type == 'error_occurred':
                    await capture_error_memory(event)
                elif event.type == 'decision_made':
                    await capture_decision_memory(event)
                elif event.type == 'pattern_discovered':
                    await capture_pattern_memory(event)
            
            await asyncio.sleep(1)  # Check every second
    
    # Start monitoring
    await capture_loop()

async def capture_solution_memory(solution_event):
    """
    Automatically capture solution memory from successful problem resolution
    """
    # Extract problem context
    problem_context = {
        'description': solution_event.problem_description,
        'files_involved': solution_event.files_modified,
        'tools_used': solution_event.claude_tools_sequence,
        'context': solution_event.project_context
    }
    
    # Extract solution details
    solution_details = {
        'approach': solution_event.solution_approach,
        'steps': solution_event.implementation_steps,
        'code_changes': solution_event.code_modifications,
        'validation_steps': solution_event.validation_performed
    }
    
    # Measure outcome
    outcome_metrics = await measure_solution_outcome(solution_event)
    
    # Store solution memory
    return await store_solution_memory(
        problem_context,
        solution_details,
        outcome_metrics,
        solution_event.claude_tools_sequence
    )
```

### Memory-Enhanced Claude Code Commands

#### Intelligent Command Enhancement
```python
async def memory_enhanced_read(file_path, current_context):
    """
    Enhance Read command with memory-based insights
    """
    # Standard read operation
    file_content = await claude_code_read(file_path)
    
    # Get relevant memories about this file
    file_memories = await get_file_related_memories(file_path)
    
    # Generate insights based on memory
    insights = {
        'previous_modifications': extract_modification_patterns(file_memories),
        'common_issues': extract_common_issues(file_memories),
        'successful_patterns': extract_successful_patterns(file_memories),
        'related_decisions': extract_related_decisions(file_memories)
    }
    
    return {
        'content': file_content,
        'memory_insights': insights,
        'recommendations': generate_memory_based_recommendations(
            file_path, 
            file_content, 
            insights,
            current_context
        )
    }

async def memory_enhanced_write(file_path, content, current_context):
    """
    Enhance Write command with memory-based validation
    """
    # Pre-write memory check
    memory_check = await check_write_against_memory(
        file_path,
        content,
        current_context
    )
    
    if memory_check.has_warnings:
        # Present warnings based on memory
        warnings = memory_check.warnings
        user_confirmation = await request_user_confirmation(warnings)
        
        if not user_confirmation:
            return {'status': 'cancelled', 'reason': 'user_cancelled_due_to_warnings'}
    
    # Execute write with memory tracking
    write_result = await claude_code_write(file_path, content)
    
    # Store write action in memory
    await store_write_action_memory(
        file_path,
        content,
        write_result,
        current_context
    )
    
    return write_result

async def memory_enhanced_bash(command, current_context):
    """
    Enhance Bash command with memory-based error prevention
    """
    # Check command against error memory
    error_prevention = await check_command_against_error_memory(
        command,
        current_context
    )
    
    if error_prevention.has_risks:
        # Suggest safer alternatives based on memory
        safer_alternatives = error_prevention.safer_alternatives
        
        enhanced_command = await suggest_command_enhancement(
            command,
            safer_alternatives,
            current_context
        )
        
        if enhanced_command:
            command = enhanced_command
    
    # Execute command with monitoring
    execution_result = await claude_code_bash(command)
    
    # Learn from execution outcome
    await learn_from_command_execution(
        command,
        execution_result,
        current_context
    )
    
    return execution_result
```

### Claude Code Integration Commands

```bash
# Memory management commands
bmad memory search --problem "authentication-issues" --context "nodejs"
bmad memory recall --solution-for "database-connection-pooling"
bmad memory store --solution "api-caching-strategy" --success-metrics "response-time-improved-40%"

# Memory-enhanced development commands
bmad develop --with-memory "implement-feature" --learn-from-similar
bmad analyze --file "src/auth.ts" --show-memory-insights
bmad prevent-errors --activity "database-migration" --based-on-memory

# Memory insights and learning
bmad memory insights --project-patterns
bmad memory learn --from-session --extract-patterns
bmad memory optimize --remove-obsolete --consolidate-similar
```

This Project Memory Manager transforms Claude Code into a learning system that remembers what works, learns from mistakes, and provides increasingly intelligent assistance based on accumulated experience across projects and sessions.