MCP Memory Service

# Natural Memory Triggers for Claude Code 🧠 **Intelligent mid-conversation memory awareness with performance optimization** ## Overview The Natural Memory Triggers system provides seamless, intelligent memory awareness during conversations that feels like Claude naturally "remembers" rather than executing explicit system hooks. It uses multi-tiered performance architecture to balance memory intelligence with responsiveness. > **🎯 v8.5.1 NEW**: **Dynamic Memory Weight Adjustment** - Intelligent auto-calibration automatically detects when memories are stale and adjusts scoring weights to prioritize recent work. No more outdated context! ## Key Features ### 🎯 **Natural Language Pattern Detection** - **Explicit Memory Requests**: "What did we decide about...?", "Remind me how we..." - **Past Work References**: "Similar to what we did...", "Like we discussed before..." - **Technical Discussions**: Architecture, security, database topics that benefit from context - **Project Continuity**: "Continue with...", "Next step...", problem-solving patterns ### ⚡ **Performance-Aware Architecture** - **Tiered Processing**: Instant (< 50ms), Fast (< 150ms), Intensive (< 500ms) - **Smart Performance Profiles**: Speed-focused, Balanced, Memory-aware, Adaptive - **Automatic Degradation**: Gracefully reduces complexity when performance budgets are exceeded - **User-Configurable Trade-offs**: Full control over speed vs intelligence balance ### 🔄 **Adaptive Learning** - **User Preference Learning**: Adapts to user tolerance for latency vs memory awareness - **Pattern Confidence Adjustment**: Learns which patterns are most valuable to the user - **Context-Aware Triggering**: Considers project context, conversation history, and topic shifts ## Quick Start ### Installation The system is integrated into the existing Claude Code hooks. No additional installation required. ### Basic Usage ```bash # Check current status node claude-hooks/memory-mode-controller.js status # Switch to balanced mode (recommended) node claude-hooks/memory-mode-controller.js profile balanced # Enable natural triggers node claude-hooks/memory-mode-controller.js enable ``` ### Performance Profiles Choose the profile that best matches your preferences: ```bash # Fastest response, minimal memory awareness (< 100ms) node claude-hooks/memory-mode-controller.js profile speed_focused # Moderate latency, smart triggers (< 200ms) - RECOMMENDED node claude-hooks/memory-mode-controller.js profile balanced # Full memory awareness, accept higher latency (< 500ms) node claude-hooks/memory-mode-controller.js profile memory_aware # Auto-adjust based on usage patterns node claude-hooks/memory-mode-controller.js profile adaptive ``` ## How It Works ### Trigger Detection The system uses a three-tiered approach to detect when memory context would be helpful: #### **Tier 1: Instant Detection (< 50ms)** - Regex-based pattern matching for explicit memory requests - Cache lookups for previously analyzed messages - Simple keyword extraction for technical terms #### **Tier 2: Fast Analysis (< 150ms)** - Contextual analysis with project information - Topic shift detection from conversation history - Enhanced pattern matching with semantic context #### **Tier 3: Intensive Analysis (< 500ms)** - Deep semantic understanding (when available) - Full conversation context analysis - Complex pattern relationships ### Example Triggers **Explicit Memory Requests** (High Confidence): ``` "What did we decide about the authentication approach?" "Remind me how we handled user sessions" "Remember when we discussed the database schema?" ``` **Past Work References** (Medium Confidence): ``` "Similar to what we implemented last time" "Like we discussed in the previous meeting" "The same approach we used for the API" ``` **Technical Discussions** (Context-Dependent): ``` "Let's design the authentication architecture" "How should we handle database migrations?" "What's our security strategy?" ``` ## Configuration ### Basic Configuration Edit `claude-hooks/config.json`: ```json { "naturalTriggers": { "enabled": true, "sensitivity": 0.7, // 0-1, higher = more sensitive "triggerThreshold": 0.6, // 0-1, confidence needed to trigger "cooldownPeriod": 30000, // Milliseconds between triggers "maxMemoriesPerTrigger": 5, // Max memories to inject per trigger "adaptiveLearning": true // Learn from user feedback } } ``` ### Performance Profiles Customize performance profiles in the configuration: ```json { "performance": { "defaultProfile": "balanced", "profiles": { "speed_focused": { "maxLatency": 100, "enabledTiers": ["instant"], "backgroundProcessing": false }, "balanced": { "maxLatency": 200, "enabledTiers": ["instant", "fast"], "backgroundProcessing": true }, "memory_aware": { "maxLatency": 500, "enabledTiers": ["instant", "fast", "intensive"], "backgroundProcessing": true } } } } ``` ## Command Line Interface ### Memory Mode Controller ```bash # Get current status and configuration node claude-hooks/memory-mode-controller.js status # Switch performance profiles node claude-hooks/memory-mode-controller.js profile <speed_focused|balanced|memory_aware|adaptive> # Adjust sensitivity (0-1, higher = more triggers) node claude-hooks/memory-mode-controller.js sensitivity 0.8 # Adjust trigger threshold (0-1, higher = need more confidence) node claude-hooks/memory-mode-controller.js threshold 0.7 # Enable/disable natural triggers node claude-hooks/memory-mode-controller.js enable node claude-hooks/memory-mode-controller.js disable node claude-hooks/memory-mode-controller.js toggle # List all available profiles node claude-hooks/memory-mode-controller.js list # Reset to defaults node claude-hooks/memory-mode-controller.js reset ``` ## Testing Run the comprehensive test suite: ```bash # Full test suite node claude-hooks/test-natural-triggers.js # Test dual protocol functionality node claude-hooks/test-dual-protocol-hook.js ``` The test suite covers: - Performance management and timing - Pattern detection accuracy - Conversation monitoring - Integration testing - Performance profile behavior ## Performance Optimization ### Latency Targets | Profile | Target Latency | Use Case | |---------|---------------|----------| | Speed Focused | < 100ms | Priority on responsiveness | | Balanced | < 200ms | Good balance (recommended) | | Memory Aware | < 500ms | Maximum memory intelligence | | Adaptive | Variable | Learns user preferences | ### Performance Monitoring The system automatically tracks: - Hook execution latency - Pattern detection accuracy - User acceptance rates - Memory query performance ### Optimization Tips 1. **Start with Balanced Mode**: Good default for most users 2. **Monitor Performance**: Check status regularly to see average latencies 3. **Adjust Sensitivity**: Lower sensitivity = fewer false positives 4. **Use Cooldown Period**: Prevents excessive triggering 5. **Enable Learning**: Let the system adapt to your preferences ## Architecture ### Component Overview ``` ┌─────────────────────────────────────────────────────────────┐ │ Mid-Conversation Hook │ ├─────────────────────────────────────────────────────────────┤ │ ┌─────────────────┐ ┌──────────────────┐ ┌─────────────┐ │ │ │ Performance │ │ Conversation │ │ Pattern │ │ │ │ Manager │ │ Monitor │ │ Detector │ │ │ │ │ │ │ │ │ │ │ │ • Timing │ │ • Topic Extract │ │ • Regex │ │ │ │ • Profiles │ │ • Semantic Shift │ │ • Context │ │ │ │ • Learning │ │ • Caching │ │ • Learning │ │ │ └─────────────────┘ └──────────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Memory Client │ │ (Dual Protocol: HTTP + MCP) │ └─────────────────────────────────────────────────────────────┘ ``` ### Key Classes - **`MidConversationHook`**: Main orchestrator for trigger detection and execution - **`TieredConversationMonitor`**: Multi-tier conversation analysis with performance awareness - **`AdaptivePatternDetector`**: Natural language pattern detection with learning - **`PerformanceManager`**: Performance monitoring, budgeting, and profile management - **`MemoryClient`**: Unified interface for HTTP and MCP memory operations ## Troubleshooting ### Common Issues **Q: Triggers aren't firing when expected** ```bash # Check if natural triggers are enabled node claude-hooks/memory-mode-controller.js status # Lower the trigger threshold node claude-hooks/memory-mode-controller.js threshold 0.5 # Increase sensitivity node claude-hooks/memory-mode-controller.js sensitivity 0.8 ``` **Q: Performance is slower than expected** ```bash # Switch to speed-focused mode node claude-hooks/memory-mode-controller.js profile speed_focused # Check current latency node claude-hooks/memory-mode-controller.js status ``` **Q: Too many false positive triggers** ```bash # Lower sensitivity node claude-hooks/memory-mode-controller.js sensitivity 0.5 # Increase threshold node claude-hooks/memory-mode-controller.js threshold 0.8 # Increase cooldown period (edit config.json) ``` ### Debug Mode Enable detailed logging: ```json { "logging": { "level": "debug", "enableDebug": true, "logToFile": true } } ``` ### Performance Analysis Monitor hook performance: ```bash # Check status for performance metrics node claude-hooks/memory-mode-controller.js status # Run performance tests node claude-hooks/test-natural-triggers.js ``` ## Integration with Claude Code ### Session Start Integration The natural triggers work alongside the existing session start hooks: 1. **Session Start**: Loads initial memory context (existing functionality) 2. **Mid-Conversation**: Intelligently refreshes context when patterns suggest it's needed 3. **Adaptive Learning**: Learns from user interactions to improve trigger accuracy ### Memory Storage Integration Uses the existing dual-protocol memory service: - **HTTP Protocol**: Web-based memory service (https://localhost:8443) - **MCP Protocol**: Direct server process communication - **Smart Fallback**: Automatically switches protocols if one fails ## Roadmap ### Planned Enhancements 1. **Advanced Semantic Analysis**: Integration with more sophisticated NLP models 2. **Cross-Session Learning**: Remember user preferences across Claude Code sessions 3. **Project-Specific Patterns**: Learn patterns specific to different projects 4. **Real-time Performance Tuning**: Dynamic adjustment based on system resources 5. **Visual Performance Dashboard**: Web-based interface for monitoring and configuration ### Contributing The natural triggers system is designed to be extensible: 1. **Custom Pattern Categories**: Add new pattern types in `AdaptivePatternDetector` 2. **Performance Profiles**: Define custom profiles in the configuration 3. **Integration Points**: Hook into additional Claude Code events 4. **Learning Algorithms**: Enhance the adaptive learning mechanisms ## License This system is part of the MCP Memory Service project and follows the same licensing terms. --- 🧠 **The goal is to make memory awareness feel natural and seamless, like Claude simply "remembers" your conversations and project context.**