MCP Memory Service

# Natural Memory Triggers v7.1.0 - Performance Optimization Guide This guide provides comprehensive strategies for optimizing Natural Memory Triggers performance to achieve the best balance of speed, accuracy, and resource usage for your specific workflow. ## Performance Overview Natural Memory Triggers uses a sophisticated multi-tier architecture designed for optimal performance: ### Performance Tiers | Tier | Target Latency | Processing | Accuracy | Use Case | |------|---------------|------------|-----------|----------| | **Instant** | < 50ms | Pattern matching, cache checks | 85% | Common memory-seeking patterns | | **Fast** | < 150ms | Lightweight semantic analysis | 90% | Topic shifts, question patterns | | **Intensive** | < 500ms | Deep semantic understanding | 95% | Complex context analysis | ### Real-World Benchmarks **Production Performance Metrics:** - ✅ **85%+ trigger accuracy** across all processing tiers - ✅ **<50ms instant analysis** for cached and pattern-matched queries - ✅ **<150ms fast analysis** for semantic topic detection - ✅ **<5ms cache performance** with LRU management - ✅ **Zero user-facing latency** with background processing ## Performance Profiles Choose the right profile based on your current workflow needs: ### 🏃 Speed Focused Profile Optimized for minimal latency with basic memory awareness. ```bash node memory-mode-controller.js profile speed_focused ``` **Configuration:** - **Max Latency**: 100ms - **Enabled Tiers**: Instant only - **Background Processing**: Disabled - **Cache Aggressiveness**: High **Best For:** - Quick coding sessions - Pair programming - Time-sensitive development work - Performance-critical environments **Trade-offs:** - Minimal memory awareness - Only pattern-based detection - No semantic analysis - Reduced context accuracy **Optimization Tips:** ```bash # Increase cache size for better hit rates node memory-mode-controller.js config set performance.cacheSize 100 # Reduce cooldown for faster triggers node memory-mode-controller.js config set naturalTriggers.cooldownPeriod 15000 # Lower memory limit for faster responses node memory-mode-controller.js config set naturalTriggers.maxMemoriesPerTrigger 3 ``` ### ⚖️ Balanced Profile (Recommended) Optimal balance of speed and context awareness for general development. ```bash node memory-mode-controller.js profile balanced ``` **Configuration:** - **Max Latency**: 200ms - **Enabled Tiers**: Instant + Fast - **Background Processing**: Enabled - **Degradation Threshold**: 400ms **Best For:** - Daily development work - General coding sessions - Code reviews and debugging - Most productive for regular use **Optimization Tips:** ```bash # Fine-tune sensitivity for your preference node memory-mode-controller.js sensitivity 0.6 # Monitor performance regularly node memory-mode-controller.js metrics # Adjust based on user satisfaction node memory-mode-controller.js config set performance.autoAdjust true ``` ### 🧠 Memory Aware Profile Maximum context awareness with acceptable higher latency. ```bash node memory-mode-controller.js profile memory_aware ``` **Configuration:** - **Max Latency**: 500ms - **Enabled Tiers**: All (Instant + Fast + Intensive) - **Background Processing**: Enabled - **Context Analysis**: Deep semantic understanding **Best For:** - Architectural decision sessions - Complex problem solving - Research and exploration work - When context quality is paramount **Optimization Tips:** ```bash # Enable all analysis features node memory-mode-controller.js config set performance.enableFullAnalysis true # Increase memory retrieval for better context node memory-mode-controller.js config set naturalTriggers.maxMemoriesPerTrigger 8 # Enable conversation context tracking node memory-mode-controller.js config set performance.trackConversationContext true ``` ### 🤖 Adaptive Profile Machine learning-based optimization that learns your preferences. ```bash node memory-mode-controller.js profile adaptive ``` **Configuration:** - **Max Latency**: Auto-adjusting (100ms - 800ms) - **Enabled Tiers**: Dynamic based on usage patterns - **User Feedback**: Tracks satisfaction and adjusts - **Learning Rate**: 0.05 (configurable) **Optimization Process:** 1. **Learning Phase** (first 50 interactions): Collects usage data 2. **Adjustment Phase** (ongoing): Optimizes based on patterns 3. **Feedback Integration**: Incorporates user satisfaction signals 4. **Performance Tuning**: Adjusts tiers and thresholds automatically **Monitoring Adaptive Learning:** ```bash # Check learning progress node memory-mode-controller.js metrics --learning # View adaptation history node memory-mode-controller.js config get performance.adaptationHistory # Reset learning data if needed node memory-mode-controller.js config set performance.resetLearning true ``` ## Performance Monitoring ### Real-Time Metrics Monitor system performance in real-time: ```bash # Basic performance overview node memory-mode-controller.js status # Detailed performance metrics node memory-mode-controller.js metrics # Continuous monitoring (updates every 5 seconds) watch -n 5 "node ~/.claude/hooks/memory-mode-controller.js metrics" ``` **Key Metrics to Monitor:** #### Response Time Metrics - **Average Latency**: Overall response time across all tiers - **Tier-Specific Latency**: Performance breakdown by processing tier - **Cache Hit Rate**: Percentage of requests served from cache - **Memory Service Latency**: Backend response times #### Accuracy Metrics - **Trigger Accuracy**: Percentage of relevant memory retrievals - **False Positive Rate**: Percentage of irrelevant triggers - **User Satisfaction**: Adaptive feedback scoring - **Success Rate**: Overall system effectiveness #### Resource Usage Metrics - **Cache Size**: Current semantic cache utilization - **Memory Usage**: Node.js heap and memory consumption - **CPU Usage**: Processing overhead (available with `--system` flag) - **Network I/O**: Memory service communication overhead ### Performance Alerts Set up automated performance monitoring: ```bash # Create performance monitoring script cat > ~/nmt-monitor.sh << 'EOF' #!/bin/bash METRICS=$(node ~/.claude/hooks/memory-mode-controller.js metrics --json) AVG_LATENCY=$(echo $METRICS | jq '.performance.avgLatency') if [ $AVG_LATENCY -gt 300 ]; then echo "⚠️ High latency detected: ${AVG_LATENCY}ms" # Could trigger notifications, logging, or automatic optimization fi EOF chmod +x ~/nmt-monitor.sh # Add to crontab for regular monitoring (crontab -l ; echo "*/5 * * * * ~/nmt-monitor.sh") | crontab - ``` ## Cache Optimization The semantic cache is crucial for performance. Optimize it based on your usage patterns: ### Cache Configuration ```bash # View current cache statistics node memory-mode-controller.js cache stats # Adjust cache size based on memory availability node memory-mode-controller.js config set performance.cacheSize 75 # entries # Configure cache cleanup behavior node memory-mode-controller.js config set performance.cacheCleanupThreshold 0.8 ``` ### Cache Performance Analysis ```bash # Analyze cache effectiveness node memory-mode-controller.js cache analyze # Example output: Cache Performance Analysis: Hit Rate: 42% (ideal: >30%) Average Hit Time: 3.2ms Average Miss Time: 147ms Most Valuable Cached Patterns: - "what did we decide": 15 hits, 180ms saved - "how did we implement": 12 hits, 134ms saved - "similar to what we": 8 hits, 98ms saved ``` ### Cache Optimization Strategies #### High Hit Rate Strategy ```bash # Increase cache size for better retention node memory-mode-controller.js config set performance.cacheSize 100 # Increase pattern retention time node memory-mode-controller.js config set performance.cacheRetentionTime 3600000 # 1 hour ``` #### Memory-Conscious Strategy ```bash # Reduce cache size for lower memory usage node memory-mode-controller.js config set performance.cacheSize 25 # More aggressive cleanup node memory-mode-controller.js config set performance.cacheCleanupThreshold 0.6 ``` ## Memory Service Optimization Optimize communication with the MCP Memory Service: ### Connection Configuration ```bash # Adjust timeout settings for your environment node memory-mode-controller.js config set memoryService.timeout 5000 # Configure connection pooling (if available) node memory-mode-controller.js config set memoryService.connectionPool.maxConnections 3 # Enable keep-alive for persistent connections node memory-mode-controller.js config set memoryService.keepAlive true ``` ### Backend-Specific Optimization #### SQLite-vec Backend ```bash # Optimize for local performance node memory-mode-controller.js config set memoryService.localOptimizations true node memory-mode-controller.js config set memoryService.timeout 3000 ``` #### Cloudflare Backend ```bash # Optimize for network latency node memory-mode-controller.js config set memoryService.timeout 8000 node memory-mode-controller.js config set memoryService.retryAttempts 2 ``` #### ChromaDB Backend ```bash # Optimize for multi-client access node memory-mode-controller.js config set memoryService.timeout 6000 node memory-mode-controller.js config set memoryService.batchRequests true ``` ## Git Integration Optimization Optimize Git-aware context analysis for better performance: ### Repository Analysis Configuration ```bash # Limit commit analysis scope for performance node memory-mode-controller.js config set gitAnalysis.commitLookback 7 # days node memory-mode-controller.js config set gitAnalysis.maxCommits 10 # Cache git analysis results node memory-mode-controller.js config set gitAnalysis.cacheResults true node memory-mode-controller.js config set gitAnalysis.cacheExpiry 1800 # 30 minutes ``` ### Large Repository Optimization For repositories with extensive history: ```bash # Reduce analysis depth node memory-mode-controller.js config set gitAnalysis.maxCommits 5 node memory-mode-controller.js config set gitAnalysis.commitLookback 3 # Skip changelog parsing for performance node memory-mode-controller.js config set gitAnalysis.includeChangelog false # Use lightweight git operations node memory-mode-controller.js config set gitAnalysis.lightweight true ``` ## System Resource Optimization ### Memory Usage Optimization Monitor and optimize Node.js memory usage: ```bash # Check current memory usage node --expose-gc -e " const used = process.memoryUsage(); console.log('Memory usage:'); for (let key in used) { console.log(\`\${key}: \${Math.round(used[key] / 1024 / 1024 * 100) / 100} MB\`); } " # Configure garbage collection for better performance export NODE_OPTIONS="--max-old-space-size=512 --gc-interval=100" node memory-mode-controller.js status ``` ### CPU Usage Optimization #### Single-Core Optimization ```bash # Disable background processing for CPU-constrained environments node memory-mode-controller.js config set performance.backgroundProcessing false # Reduce concurrent operations node memory-mode-controller.js config set performance.maxConcurrentAnalysis 1 ``` #### Multi-Core Optimization ```bash # Enable parallel processing (if available) node memory-mode-controller.js config set performance.enableParallelProcessing true # Increase concurrent analysis threads node memory-mode-controller.js config set performance.maxConcurrentAnalysis 3 ``` ## Performance Troubleshooting ### Common Performance Issues #### High Latency **Symptoms**: Response times consistently above target thresholds **Diagnosis**: ```bash # Identify bottlenecks node memory-mode-controller.js metrics --breakdown # Test memory service directly curl -w "@curl-format.txt" -k https://localhost:8443/api/health # Check system resources top -p $(pgrep -f memory-mode-controller) ``` **Solutions**: 1. **Switch to faster profile**: `node memory-mode-controller.js profile speed_focused` 2. **Optimize cache**: Increase cache size and check hit rates 3. **Memory service optimization**: Check backend performance 4. **Reduce analysis depth**: Lower commit lookback and max commits #### Cache Misses **Symptoms**: Low cache hit rate (< 20%) **Diagnosis**: ```bash node memory-mode-controller.js cache analyze ``` **Solutions**: 1. **Increase cache size**: `node memory-mode-controller.js config set performance.cacheSize 100` 2. **Adjust cache retention**: Increase cache cleanup threshold 3. **Pattern analysis**: Review most common missed patterns #### Memory Service Timeouts **Symptoms**: Frequent timeout errors in metrics **Diagnosis**: ```bash # Test memory service responsiveness time curl -k https://localhost:8443/api/health # Check service logs tail -f ~/Library/Logs/Claude/mcp-server-memory.log ``` **Solutions**: 1. **Increase timeout**: `node memory-mode-controller.js config set memoryService.timeout 10000` 2. **Check backend**: Switch to faster backend if available 3. **Network optimization**: Ensure local service deployment ### Performance Profiling #### Detailed Timing Analysis Enable detailed timing for performance analysis: ```bash # Enable timing instrumentation export CLAUDE_HOOKS_TIMING=true node memory-mode-controller.js test "What did we decide about authentication?" # Example output with timing: 🧪 Testing Natural Memory Triggers [TIMING ENABLED] Query: "What did we decide about authentication?" [0ms] Starting analysis [2ms] Cache check: miss [7ms] Pattern analysis complete [45ms] Instant tier complete (confidence: 0.85) [147ms] Fast tier complete (confidence: 0.78) [389ms] Intensive tier complete (confidence: 0.92) [421ms] Memory query generated [567ms] Memory service response received [572ms] Analysis complete Total Time: 572ms ``` #### Memory Profiling Profile memory usage patterns: ```bash # Generate memory profile node --inspect ~/.claude/hooks/memory-mode-controller.js status & # Open Chrome DevTools to chrome://inspect for memory analysis ``` ## Performance Best Practices ### Workflow-Specific Optimization #### Development Sessions ```bash # Morning setup for general development node memory-mode-controller.js profile balanced node memory-mode-controller.js sensitivity 0.6 ``` #### Architecture Sessions ```bash # Setup for architecture work node memory-mode-controller.js profile memory_aware node memory-mode-controller.js sensitivity 0.4 ``` #### Quick Fixes/Debugging ```bash # Setup for focused debugging node memory-mode-controller.js profile speed_focused node memory-mode-controller.js sensitivity 0.8 ``` ### Maintenance Routines #### Daily Maintenance ```bash # Check system health node memory-mode-controller.js health # Review performance metrics node memory-mode-controller.js metrics # Clear cache if hit rate is low if [ $(node memory-mode-controller.js cache stats --json | jq '.hitRate < 0.2') ]; then node memory-mode-controller.js cache clear fi ``` #### Weekly Optimization ```bash # Export performance data for analysis node memory-mode-controller.js export metrics > weekly-metrics.json # Review and adjust configuration based on usage patterns node memory-mode-controller.js metrics --recommendations # Update adaptive learning if needed node memory-mode-controller.js config set performance.learningRate 0.1 ``` ## Advanced Performance Features ### Custom Performance Profiles Create custom performance profiles for specific use cases: ```bash # Create custom profile for code reviews node memory-mode-controller.js config set performance.profiles.code_review '{ "maxLatency": 250, "enabledTiers": ["instant", "fast"], "backgroundProcessing": true, "degradeThreshold": 500, "description": "Optimized for code review sessions" }' # Activate custom profile node memory-mode-controller.js profile code_review ``` ### Performance Automation Automate performance optimization based on context: ```bash # Create context-aware performance script cat > ~/nmt-auto-optimize.sh << 'EOF' #!/bin/bash # Check current time and adjust profile accordingly HOUR=$(date +%H) if [ $HOUR -ge 9 ] && [ $HOUR -le 11 ]; then # Morning: architecture work node ~/.claude/hooks/memory-mode-controller.js profile memory_aware elif [ $HOUR -ge 14 ] && [ $HOUR -le 16 ]; then # Afternoon: general development node ~/.claude/hooks/memory-mode-controller.js profile balanced else # Other times: speed focused node ~/.claude/hooks/memory-mode-controller.js profile speed_focused fi EOF chmod +x ~/nmt-auto-optimize.sh # Add to login scripts or IDE startup ``` --- **Natural Memory Triggers v7.1.0** provides extensive performance optimization capabilities to ensure optimal speed and accuracy for your specific development workflow! 🚀