23 KiB

Raw Blame History

BMAD Memory Architecture Implementation Guide

Overview

This guide provides step-by-step instructions for implementing the BMAD Memory Architecture methodology within your IDE environment. The methodology is designed to work across Claude Code, Cursor AI, V0, Roocode, JetBrains, and other AI-enhanced development environments.

Quick Start Guide

1. Choose Your Implementation Path

Select the implementation approach that matches your IDE environment:

Claude Code Implementation - File-based memory with conversation integration
Cursor AI Implementation - Workspace-integrated memory with extension APIs
V0 Implementation - Browser-based memory with component integration
JetBrains Implementation - Plugin-based memory with IDE integration
Universal Implementation - Platform-agnostic approach

2. Implementation Phases

All implementations follow these phases:

Foundation Setup (1-2 hours)
Basic Memory Operations (2-4 hours)
Integration & Enhancement (4-8 hours)
Optimization & Monitoring (2-4 hours)

3. Prerequisites

Before starting, ensure you have:

Access to your chosen IDE environment
Basic understanding of your IDE's extension/plugin system
Familiarity with the BMAD Method personas you'll be using
Understanding of your project's data privacy requirements

Phase 1: Foundation Setup

Step 1: Create Memory Directory Structure

Create the following directory structure in your project:

. your-project/ .bmad-memory/ config/ memory-config.json retention-policies.json storage/ working/ short-term/ episodic/ semantic/ procedural/ long-term/ indices/ id-index.json type-index.json temporal-index.json logs/ memory-operations.log \.

Step 2: Initialize Memory Configuration

Create memory-config.json:

.json { "version": "1.0.0", "ide_environment": "your-ide-name", "memory_types": { "working": { "enabled": true, "storage_type": "session", "max_size_mb": 50, "retention_hours": 24 }, "short_term": { "enabled": true, "storage_type": "file", "max_size_mb": 200, "retention_days": 7 }, "episodic": { "enabled": true, "storage_type": "file", "max_size_mb": 500, "retention_months": 3 }, "semantic": { "enabled": true, "storage_type": "file", "max_size_mb": 1000, "retention_policy": "importance_based" }, "procedural": { "enabled": true, "storage_type": "file", "max_size_mb": 300, "retention_policy": "usage_based" }, "long_term": { "enabled": true, "storage_type": "file", "max_size_mb": 2000, "retention_policy": "permanent" } }, "security": { "encryption_enabled": true, "access_control": "user_based", "privacy_level": "private" }, "performance": { "cache_enabled": true, "cache_size_mb": 100, "indexing_enabled": true } } \.

Step 3: Create Retention Policies

Create retention-policies.json:

.json { "policies": { "importance_based": { "critical": "permanent", "important": "1_year", "useful": "6_months", "reference": "3_months" }, "usage_based": { "frequent": "1_year", "occasional": "6_months", "rare": "3_months", "never": "1_month" }, "privacy_based": { "public": "standard_retention", "shared": "group_retention", "private": "user_controlled", "sensitive": "strict_retention" } }, "cleanup_schedule": { "daily": ["working", "temporary"], "weekly": ["short_term"], "monthly": ["episodic", "low_importance"], "quarterly": ["full_cleanup"] } } \.

Phase 2: Basic Memory Operations

Step 1: Implement Memory Entity Structure

Create a basic memory entity template:

.json { "id": "mem_{{timestamp}}_{{random}}", "type": "semantic|episodic|procedural|working|short_term|long_term", "created": "2024-01-15T10:30:00Z", "last_accessed": "2024-01-15T10:30:00Z", "access_count": 1, "importance": 0.5, "metadata": { "source": "user_input|system_generated|imported", "owner": "user_id", "project": "project_name", "tags": ["tag1", "tag2"], "privacy": "private|shared|public", "retention_policy": "policy_name" }, "content": { "title": "Memory Title", "summary": "Brief summary of the memory", "details": "Detailed content", "format": "text|json|markdown|code", "embeddings": null }, "relationships": [ { "target_id": "mem_other_id", "type": "related|supports|contradicts|follows", "strength": 0.8, "created": "2024-01-15T10:30:00Z" } ] } \.

Step 2: Implement Basic CRUD Operations

Create Memory Operation

.```javascript // Example implementation pattern function createMemory(content, type, metadata = {}) { const memory = { id: generateMemoryId(), type: type, created: new Date().toISOString(), last_accessed: new Date().toISOString(), access_count: 1, importance: calculateInitialImportance(content, metadata), metadata: { source: 'user_input', owner: getCurrentUser(), project: getCurrentProject(), tags: extractTags(content), privacy: metadata.privacy || 'private', retention_policy: determineRetentionPolicy(type, metadata), ...metadata }, content: { title: extractTitle(content), summary: generateSummary(content), details: content, format: detectFormat(content), embeddings: null // Will be generated asynchronously }, relationships: [] };

return storeMemory(memory); } .```

Read Memory Operation

.```javascript function retrieveMemory(memoryId) { const memory = loadMemoryFromStorage(memoryId); if (memory) { memory.last_accessed = new Date().toISOString(); memory.access_count += 1; updateMemoryInStorage(memory); return memory; } return null; }

function searchMemories(query, options = {}) { const searchStrategy = determineSearchStrategy(query); const results = executeSearch(query, searchStrategy, options); return rankAndFilterResults(results, options); } .```

Update Memory Operation

.```javascript function updateMemory(memoryId, updates) { const memory = loadMemoryFromStorage(memoryId); if (!memory) return null;

// Merge updates const updatedMemory = { ...memory, ...updates, last_modified: new Date().toISOString(), version: (memory.version || 1) + 1 };

// Update indices updateIndices(updatedMemory);

return storeMemory(updatedMemory); } .```

Delete Memory Operation

.```javascript function deleteMemory(memoryId) { const memory = loadMemoryFromStorage(memoryId); if (!memory) return false;

// Clean up relationships cleanupRelationships(memoryId);

// Remove from indices removeFromIndices(memoryId);

// Secure deletion secureDeleteFromStorage(memoryId);

// Log deletion logMemoryOperation('delete', memoryId);

return true; } .```

Step 3: Implement Basic Search

.```javascript function implementBasicSearch() { // Direct ID lookup function findById(id) { return loadMemoryFromStorage(id); }

// Keyword search function searchByKeywords(keywords) { const results = []; const allMemories = loadAllMemories();

for (const memory of allMemories) {
  const score = calculateKeywordScore(memory, keywords);
  if (score > 0.3) {
    results.push({ memory, score });
  }
}

return results.sort((a, b) => b.score - a.score);

}

// Type-based search function searchByType(type) { return loadMemoriesByType(type); }

// Temporal search function searchByTimeRange(startDate, endDate) { return loadMemoriesByTimeRange(startDate, endDate); } } .```

Phase 3: Integration & Enhancement

Step 1: IDE-Specific Integration

Claude Code Integration

.```markdown

Claude Code Memory Integration

Setup Instructions

Create memory management prompts:

.``` You are now equipped with a memory system. When I share information that should be remembered:

Identify the memory type (working, episodic, semantic, procedural, long-term)
Extract key information and create a memory entry
Store it in the appropriate .bmad-memory/ directory
Update relevant indices

When I ask questions, search your memory first before responding. .```

Create memory integration workflow:

.``` For each conversation:

Check for relevant memories at the start
Create new memories for important insights
Update existing memories with new information
Maintain conversation context using memory . \.

Cursor AI Integration

.```typescript // Cursor AI Extension Integration class CursorMemoryExtension { constructor() { this.memorySystem = new MemorySystem(); this.setupEventListeners(); }

setupEventListeners() { // Listen for file changes vscode.workspace.onDidChangeTextDocument((event) => { this.handleFileChange(event); });

// Listen for cursor position changes
vscode.window.onDidChangeTextEditorSelection((event) => {
  this.handleCursorChange(event);
});

}

handleFileChange(event) { // Extract context and create memory const context = this.extractContext(event); this.memorySystem.createMemory(context, 'working'); }

provideCompletionItems(document, position) { // Use memory to enhance completions const context = this.getContext(document, position); const relevantMemories = this.memorySystem.search(context); return this.enhanceCompletions(relevantMemories); } } .```

V0 Integration

.```javascript // V0 Memory Integration class V0MemorySystem { constructor() { this.storage = new BrowserMemoryStorage(); this.setupComponentMemory(); }

setupComponentMemory() { // Hook into component generation this.onComponentGenerated = (component) => { this.storeComponentMemory(component); };

// Hook into design decisions
this.onDesignDecision = (decision) => {
  this.storeDesignMemory(decision);
};

}

storeComponentMemory(component) { const memory = { type: 'procedural', content: { title: Component: ${component.name}, details: component.code, metadata: { framework: component.framework, props: component.props, usage: component.usage } } };

this.storage.store(memory);

}

enhanceGeneration(prompt) { // Search for relevant component memories const relevantMemories = this.storage.search(prompt); return this.incorporateMemories(prompt, relevantMemories); } } .```

JetBrains Integration

.```kotlin // JetBrains Plugin Integration class JetBrainsMemoryPlugin : ApplicationComponent { private val memorySystem = MemorySystem()

override fun initComponent() {
    setupProjectListeners()
    setupEditorListeners()
}

private fun setupProjectListeners() {
    ProjectManager.getInstance().addProjectManagerListener(object : ProjectManagerListener {
        override fun projectOpened(project: Project) {
            memorySystem.loadProjectMemories(project)
        }
        
        override fun projectClosed(project: Project) {
            memorySystem.saveProjectMemories(project)
        }
    })
}

private fun setupEditorListeners() {
    EditorFactory.getInstance().addEditorFactoryListener(object : EditorFactoryListener {
        override fun editorCreated(event: EditorFactoryEvent) {
            val editor = event.editor
            setupMemoryIntegration(editor)
        }
    })
}

private fun setupMemoryIntegration(editor: Editor) {
    // Add memory-enhanced code completion
    // Add memory-based code suggestions
    // Track coding patterns for memory storage
}

} .```

Step 2: Persona Integration

.```javascript // Persona-Memory Integration class PersonaMemoryIntegration { constructor(memorySystem) { this.memorySystem = memorySystem; this.setupPersonaSpecificMemory(); }

setupPersonaSpecificMemory() { // Architect persona memory specialization this.architectMemory = { storeArchitecturalDecision: (decision) => { return this.memorySystem.createMemory({ type: 'semantic', content: decision, metadata: { persona: 'architect', category: 'architectural_decision', impact: 'high' } }); },

  getArchitecturalPatterns: (context) => {
    return this.memorySystem.search({
      query: context,
      filters: {
        persona: 'architect',
        category: 'pattern'
      }
    });
  }
};

// Product Manager persona memory specialization
this.pmMemory = {
  storeRequirement: (requirement) => {
    return this.memorySystem.createMemory({
      type: 'episodic',
      content: requirement,
      metadata: {
        persona: 'product_manager',
        category: 'requirement',
        stakeholder: requirement.stakeholder
      }
    });
  },
  
  getStakeholderFeedback: (stakeholder) => {
    return this.memorySystem.search({
      filters: {
        persona: 'product_manager',
        stakeholder: stakeholder
      }
    });
  }
};

// V0 UX/UI Architect persona memory specialization
this.uxMemory = {
  storeDesignPattern: (pattern) => {
    return this.memorySystem.createMemory({
      type: 'procedural',
      content: pattern,
      metadata: {
        persona: 'ux_ui_architect',
        category: 'design_pattern',
        component_type: pattern.type
      }
    });
  },
  
  getDesignPatterns: (componentType) => {
    return this.memorySystem.search({
      filters: {
        persona: 'ux_ui_architect',
        component_type: componentType
      }
    });
  }
};

} } .```

Step 3: Workflow Integration

.```javascript // Workflow-Memory Integration class WorkflowMemoryIntegration { constructor(memorySystem) { this.memorySystem = memorySystem; this.setupWorkflowHooks(); }

setupWorkflowHooks() { // Hook into workflow start this.onWorkflowStart = (workflow) => { const context = this.loadWorkflowContext(workflow); this.memorySystem.setWorkingContext(context); };

// Hook into workflow steps
this.onWorkflowStep = (step, result) => {
  this.memorySystem.createMemory({
    type: 'episodic',
    content: {
      title: `Workflow Step: ${step.name}`,
      details: result,
      workflow: step.workflow,
      timestamp: new Date().toISOString()
    }
  });
};

// Hook into workflow completion
this.onWorkflowComplete = (workflow, outcome) => {
  this.memorySystem.createMemory({
    type: 'semantic',
    content: {
      title: `Workflow Outcome: ${workflow.name}`,
      details: outcome,
      lessons_learned: this.extractLessons(workflow),
      success_factors: this.identifySuccessFactors(workflow)
    }
  });
};

}

enhanceWorkflowWithMemory(workflow) { // Get relevant memories for workflow const relevantMemories = this.memorySystem.search({ query: workflow.description, filters: { type: ['semantic', 'procedural'] } });

// Enhance workflow steps with memory insights
return this.incorporateMemoryInsights(workflow, relevantMemories);

} } .```

Phase 4: Optimization & Monitoring

Step 1: Performance Monitoring Setup

.```javascript // Performance Monitoring class MemoryPerformanceMonitor { constructor(memorySystem) { this.memorySystem = memorySystem; this.metrics = new PerformanceMetrics(); this.setupMonitoring(); }

setupMonitoring() { // Monitor operation latency this.memorySystem.onOperation = (operation, duration) => { this.metrics.recordLatency(operation, duration); };

// Monitor memory usage
setInterval(() => {
  this.metrics.recordMemoryUsage(this.getMemoryUsage());
}, 60000); // Every minute

// Monitor cache performance
this.memorySystem.cache.onHit = () => this.metrics.recordCacheHit();
this.memorySystem.cache.onMiss = () => this.metrics.recordCacheMiss();

}

generatePerformanceReport() { return { latency: this.metrics.getLatencyStats(), throughput: this.metrics.getThroughputStats(), memory_usage: this.metrics.getMemoryUsageStats(), cache_performance: this.metrics.getCacheStats(), recommendations: this.generateRecommendations() }; } } .```

Step 2: Quality Monitoring

.```javascript // Quality Monitoring class MemoryQualityMonitor { constructor(memorySystem) { this.memorySystem = memorySystem; this.setupQualityChecks(); }

setupQualityChecks() { // Monitor data quality setInterval(() => { this.checkDataQuality(); }, 3600000); // Every hour

// Monitor relationship integrity
setInterval(() => {
  this.checkRelationshipIntegrity();
}, 86400000); // Daily

}

checkDataQuality() { const memories = this.memorySystem.getAllMemories(); const qualityReport = { completeness: this.assessCompleteness(memories), accuracy: this.assessAccuracy(memories), consistency: this.assessConsistency(memories), freshness: this.assessFreshness(memories) };

this.reportQualityIssues(qualityReport);
return qualityReport;

} } .```

Step 3: Automated Maintenance

.```javascript // Automated Maintenance class MemoryMaintenanceSystem { constructor(memorySystem) { this.memorySystem = memorySystem; this.setupMaintenanceTasks(); }

setupMaintenanceTasks() { // Daily maintenance this.scheduleTask('daily', () => { this.cleanupWorkingMemory(); this.updateAccessStatistics(); this.optimizeIndices(); });

// Weekly maintenance
this.scheduleTask('weekly', () => {
  this.consolidateMemories();
  this.updateImportanceScores();
  this.cleanupExpiredMemories();
});

// Monthly maintenance
this.scheduleTask('monthly', () => {
  this.archiveOldMemories();
  this.optimizeStorage();
  this.generateMaintenanceReport();
});

}

scheduleTask(frequency, task) { // Implementation depends on your environment // Could use cron jobs, setTimeout, or IDE-specific scheduling } } .```

Testing Your Implementation

Step 1: Basic Functionality Tests

.```javascript // Basic Tests function runBasicTests() { console.log('Running basic memory system tests...');

// Test memory creation const memory = createMemory('Test content', 'working'); assert(memory.id, 'Memory should have an ID');

// Test memory retrieval const retrieved = retrieveMemory(memory.id); assert(retrieved.content.details === 'Test content', 'Content should match');

// Test memory search const results = searchMemories('Test'); assert(results.length > 0, 'Search should return results');

// Test memory update const updated = updateMemory(memory.id, { importance: 0.8 }); assert(updated.importance === 0.8, 'Importance should be updated');

// Test memory deletion const deleted = deleteMemory(memory.id); assert(deleted === true, 'Memory should be deleted');

console.log('Basic tests passed!'); } .```

Step 2: Integration Tests

.```javascript // Integration Tests function runIntegrationTests() { console.log('Running integration tests...');

// Test persona integration testPersonaIntegration();

// Test workflow integration testWorkflowIntegration();

// Test IDE-specific features testIDEIntegration();

console.log('Integration tests passed!'); } .```

Step 3: Performance Tests

.```javascript // Performance Tests function runPerformanceTests() { console.log('Running performance tests...');

// Test operation latency const startTime = Date.now(); for (let i = 0; i < 1000; i++) { createMemory(Test content ${i}, 'working'); } const createTime = Date.now() - startTime; console.log(Created 1000 memories in ${createTime}ms);

// Test search performance const searchStart = Date.now(); const results = searchMemories('Test'); const searchTime = Date.now() - searchStart; console.log(Search completed in ${searchTime}ms);

console.log('Performance tests completed!'); } .```

Troubleshooting Guide

Common Issues and Solutions

Issue: Memory operations are slow

Solution:

Check if indexing is enabled
Optimize cache settings
Consider storage type (file vs. memory)
Review retention policies

Issue: Search results are not relevant

Solution:

Improve content summarization
Add more specific tags
Enhance relationship mapping
Tune similarity thresholds

Issue: Memory usage is too high

Solution:

Implement aggressive cleanup policies
Compress old memories
Archive infrequently accessed data
Optimize data structures

Issue: IDE integration not working

Solution:

Check IDE-specific API compatibility
Verify extension/plugin permissions
Review event listener setup
Test with minimal implementation

Next Steps

After completing the basic implementation:

Customize for Your Use Case: Adapt the memory types and retention policies to your specific needs
Enhance Search: Implement semantic search using embeddings
Add Analytics: Set up detailed performance and usage analytics
Scale Up: Implement distributed memory for team collaboration
Security Hardening: Add encryption and advanced access controls

Support and Resources

Memory Architecture Methodology: /bmad-agent/memory/memory-architecture.md
Data Structures Guide: /bmad-agent/memory/memory-data-structures.md
Performance Optimization: /bmad-agent/memory/memory-performance-monitoring.md
Security Implementation: /bmad-agent/memory/memory-security-privacy.md
Testing Framework: /bmad-agent/memory/memory-testing-validation.md

For additional support, refer to the IDE-specific implementation guides in the following sections.

23 KiB Raw Blame History

BMAD Memory Architecture Implementation Guide

Overview

Quick Start Guide

1. Choose Your Implementation Path

2. Implementation Phases

3. Prerequisites

Phase 1: Foundation Setup

Step 1: Create Memory Directory Structure

Step 2: Initialize Memory Configuration

Step 3: Create Retention Policies

Phase 2: Basic Memory Operations

Step 1: Implement Memory Entity Structure

Step 2: Implement Basic CRUD Operations

Create Memory Operation

Read Memory Operation

Update Memory Operation

Delete Memory Operation

Step 3: Implement Basic Search

Phase 3: Integration & Enhancement

Step 1: IDE-Specific Integration

Claude Code Integration

Claude Code Memory Integration

Setup Instructions

Cursor AI Integration

V0 Integration

JetBrains Integration

Step 2: Persona Integration

Step 3: Workflow Integration

Phase 4: Optimization & Monitoring

Step 1: Performance Monitoring Setup

Step 2: Quality Monitoring

Step 3: Automated Maintenance

Testing Your Implementation

Step 1: Basic Functionality Tests

Step 2: Integration Tests

Step 3: Performance Tests

Troubleshooting Guide

Common Issues and Solutions

Issue: Memory operations are slow

Issue: Search results are not relevant

Issue: Memory usage is too high

Issue: IDE integration not working

Next Steps

Support and Resources

23 KiB

Raw Blame History