# Memory Hooks & Natural Triggers - Complete Guide **Transform Claude Code with intelligent memory awareness that learns from your development patterns.** > **📌 Version**: v7.1.4 (Latest Stable) > **🚀 Quick Install**: `cd claude-hooks && python install_hooks.py --natural-triggers` > **📖 Status**: This is the **single source of truth** for all Memory Hooks documentation ## Table of Contents - [Overview](#overview) - [Quick Start](#quick-start) - [Installation](#installation) - [Configuration](#configuration) - [Features](#features) - [Natural Memory Triggers](#natural-memory-triggers) - [Context-Provider Integration](#context-provider-integration) - [Mid-Conversation Hooks](#mid-conversation-hooks) - [Legacy Session Hooks](#legacy-session-hooks) - [CLI Management](#cli-management) - [Performance Profiles](#performance-profiles) - [Troubleshooting](#troubleshooting) - [Advanced Usage](#advanced-usage) - [Architecture](#architecture) - [Version History](#version-history) - [Migration Guide](#migration-guide) --- ## Overview Memory Hooks provide automatic memory awareness for Claude Code, evolving from basic session events to intelligent pattern recognition that detects when you need context from your project history. ### 🎯 Evolution Timeline | Version | Feature | Description | Status | |---------|---------|-------------|---------| | **v6.0.0** | Basic Memory Hooks | Session start/end memory loading | Legacy | | **v7.1.0** | Natural Memory Triggers | Intelligent pattern detection (85%+ accuracy) | Stable | | **v7.1.3** | Mid-Conversation Hooks | Real-time memory injection during chats | Stable | | **v7.1.4** | Unified Installer | Cross-platform Python installer | **Current** | ### 🚀 Key Benefits - **🧠 Intelligent Detection**: Automatically recognizes when you need memory context - **⚡ Multi-Tier Performance**: Optimized response times (50ms/150ms/500ms) - **🎮 CLI Management**: Real-time configuration without editing files - **🔄 Zero Downtime**: Install and configure without restarting Claude Code - **📊 Adaptive Learning**: Improves based on your usage patterns --- ## Quick Start ### 1️⃣ Check Current Status ```bash # Check if hooks are installed ls ~/.claude/hooks/ # Check Natural Memory Triggers specifically node ~/.claude/hooks/memory-mode-controller.js status ``` ### 2️⃣ Install (30 seconds) ```bash # Clone repository (if not already done) git clone https://github.com/doobidoo/mcp-memory-service.git cd mcp-memory-service/claude-hooks # Install with Natural Memory Triggers (recommended) python install_hooks.py --natural-triggers ``` ### 3️⃣ Verify Installation ```bash # Test the system node ~/.claude/hooks/test-natural-triggers.js # Check CLI controller node ~/.claude/hooks/memory-mode-controller.js status ``` ### ✅ That's It! Natural Memory Triggers automatically activate when you ask questions like: - "What approach did we use for authentication?" - "How did we handle this error before?" - "What were our main architectural decisions?" --- ## Installation ### 🎯 Unified Python Installer (v7.1.4+) The unified installer provides cross-platform compatibility with enhanced safety features: #### Installation Options ```bash # Basic memory hooks only python install_hooks.py --basic # Natural Memory Triggers (recommended) python install_hooks.py --natural-triggers # Everything including all features python install_hooks.py --all # Test mode (dry run) python install_hooks.py --dry-run --natural-triggers # Uninstall python install_hooks.py --uninstall ``` #### What the Installer Does 1. **✅ Backs up** existing hooks and settings 2. **✅ Intelligently merges** configurations (preserves your settings) 3. **✅ Installs** selected components 4. **✅ Validates** Node.js and memory service connectivity 5. **✅ Runs** comprehensive test suite (18+ tests) 6. **✅ Provides** detailed installation report ### 📁 Manual Installation For advanced users who need custom control: ```bash # 1. Create hooks directory mkdir -p ~/.claude/hooks/{core,utilities,tests} # 2. Copy hook files cp -r claude-hooks/* ~/.claude/hooks/ # 3. Update Claude settings # Add to ~/.claude/settings.json: { "hooks": [ { "pattern": "session-start", "command": "node ~/.claude/hooks/core/session-start.js" }, { "pattern": "user-prompt-submit", "command": "node ~/.claude/hooks/core/mid-conversation.js" }, { "pattern": "session-end", "command": "node ~/.claude/hooks/core/session-end.js" } ] } ``` ### 🐳 Docker Installation ```bash # With hooks pre-configured docker run -v ~/.claude:/home/user/.claude \ doobidoo/mcp-memory-service:latest \ install-hooks --natural-triggers ``` --- ## Configuration ### 📝 Main Configuration File Location: `~/.claude/hooks/config.json` ```json { "memoryService": { "protocol": "auto", // auto, mcp, or http "preferredProtocol": "mcp", // Primary protocol to try "fallbackEnabled": true, // Enable protocol fallback "maxMemoriesPerSession": 8, // Memory limit per session "enableSessionConsolidation": true }, "naturalTriggers": { "enabled": true, // Enable Natural Memory Triggers "triggerThreshold": 0.6, // Sensitivity (0.0-1.0) "cooldownPeriod": 30000, // Milliseconds between triggers "maxMemoriesPerTrigger": 5 // Memories per trigger event }, "performance": { "defaultProfile": "balanced", // speed_focused, balanced, memory_aware "enableMonitoring": true, "autoAdjust": true }, "output": { "verbose": true, // Show hook activity "showMemoryDetails": false, // Show detailed scoring "cleanMode": false // Minimal output mode } } ``` ### ⚙️ Environment Variables ```bash # Optional: Override config file settings export MCP_MEMORY_HOOK_VERBOSE=true export MCP_MEMORY_TRIGGER_THRESHOLD=0.7 export MCP_MEMORY_PERFORMANCE_PROFILE=memory_aware ``` --- ## Features ### Natural Memory Triggers **Intelligent automatic memory retrieval with 85%+ accuracy** #### How It Works 1. **Pattern Detection**: Analyzes your messages for memory-seeking patterns 2. **Semantic Analysis**: Understands context and intent 3. **Relevance Scoring**: Ranks memories by relevance 4. **Injection**: Seamlessly adds context to your conversation #### Trigger Examples | Your Question | What Gets Retrieved | |--------------|-------------------| | "What approach did we use for auth?" | Authentication implementations, decisions | | "How did we handle this error?" | Previous error solutions, debugging sessions | | "What were our design decisions?" | Architecture choices, trade-offs discussed | | "Remember when we optimized...?" | Performance improvements, benchmarks | #### Configuration ```bash # Check current settings node ~/.claude/hooks/memory-mode-controller.js status # Adjust sensitivity (0.0-1.0, default 0.6) node ~/.claude/hooks/memory-mode-controller.js sensitivity 0.7 # Change performance profile node ~/.claude/hooks/memory-mode-controller.js profile balanced ``` ### Context-Provider Integration **Deterministic memory management that makes your already sophisticated system bulletproof for project-specific workflows.** > **🎯 Core Value**: Transform 85% AI accuracy into 100% guaranteed coverage for critical development patterns #### The Problem with AI-Only Memory Systems Even with Natural Memory Triggers' impressive 85%+ accuracy, gaps remain: | Scenario | AI-Based Result | Business Impact | |----------|----------------|-----------------| | "cloudflare backend error" | 70% retrieval chance | 30% chance developer manually searches | | Commit message formatting | Inconsistent enforcement | Team standards violations | | Domain-specific terminology | Generic interpretation | Missing project-specific solutions | | Rapid development sessions | Cooldown periods | Memory gaps during intensive work | #### The Context-Provider Solution **Rule-based triggers that guarantee capture and retrieval of project-critical patterns:** ```bash # Automatic setup - no manual commands needed # Context-provider activates automatically with Claude Code sessions ``` #### Key Improvements ##### 1. **100% Guaranteed Coverage** ``` Before: "I'm having cloudflare vectorize issues" → Natural Memory Triggers: 70% chance of retrieval → Developer: Manual search required After: "cloudflare vectorize issues" → Rule-based trigger: 100% guaranteed retrieval → Natural Memory Triggers: Additional semantic context → Result: Comprehensive, immediate solution access ``` ##### 2. **Workflow Standardization** ``` Before: Developer types "Fix auth bug" → Inconsistent commit formatting After: "Fix auth bug" → Auto-corrected to "fix: auth bug" → 100% semantic commit compliance ``` ##### 3. **Domain Expertise Capture** ``` MCP Memory Service-specific patterns automatically captured: ✅ "storage backend switch" → Configuration memories ✅ "hybrid backend setup" → Setup procedures ✅ "25ms page load" → Performance optimizations ✅ "oauth integration" → Authentication solutions ``` #### Architecture: Complementary Intelligence ``` User Query: "How did we handle cloudflare errors?" Layer 1: Context-Provider (Rule-based) ├── Pattern Match: "cloudflare error" → 100% trigger ├── Tags: ["troubleshooting", "cloudflare", "backend"] └── Memories: Guaranteed retrieval of exact solutions Layer 2: Natural Memory Triggers (AI-based) ├── Semantic Analysis: Understanding context and intent ├── Relevance Scoring: Additional related memories └── Adaptive Learning: Pattern refinement over time Result: Complete coverage with zero gaps ``` #### Quantified Business Benefits | Metric | Before | After | Improvement | |--------|--------|-------|-------------| | **Context Switching Time** | 5-10 minutes searching | Instant retrieval | **80% reduction** | | **Commit Compliance** | ~60% team adherence | 100% automatic | **100% standardization** | | **Knowledge Retention** | 85% capture rate | 100% for critical patterns | **15% improvement** | | **Onboarding Speed** | 2-3 days learning patterns | Immediate access | **60% faster** | | **Problem Resolution** | Variable success rate | Guaranteed pattern access | **30% faster resolution** | #### Project-Specific Intelligence **Why This Matters for MCP Memory Service:** ##### Technical Complexity Demands Reliability - **4 Storage Backends**: sqlite-vec, Milvus, Cloudflare, Hybrid (ChromaDB was removed; see the migration guide) - **Multiple Integration Patterns**: OAuth, dashboard, MCP protocol - **Performance-Critical Operations**: 25ms response requirements ##### Domain Language Requires Precision - **MCP Protocol Terminology**: `tool handler`, `storage backend`, `vector embedding` - **Backend-Specific Errors**: `cloudflare vectorize failure`, `sqlite-vec fallback` - **Integration Patterns**: `hybrid sync`, `oauth configuration`, `dashboard validation` ##### Development Velocity Needs Consistency - **Architectural Decisions**: Previous choices immediately accessible - **Error Solutions**: Proven fixes guaranteed retrieval - **Configuration Patterns**: Setup procedures always available #### Setup & Configuration **Automatic Integration** (No manual setup required): 1. Context-provider automatically detects MCP Memory Service project 2. Python MCP Memory Service context activates 3. Enhanced memory context patterns enable 4. Works alongside existing Natural Memory Triggers **Manual Verification** (Optional): ```bash # Check integration status # (Context-provider operates transparently via Claude Code MCP client) # Verify Natural Memory Triggers still active node ~/.claude/hooks/memory-mode-controller.js status ``` #### Before/After Development Scenarios ##### Scenario 1: Troubleshooting Backend Issues **Before Context-Provider:** ``` Developer: "The cloudflare backend is throwing errors" → Manual search through documentation → 70% chance Natural Memory Triggers finds relevant info → 5-10 minutes context switching → Possible missed edge cases ``` **After Context-Provider:** ``` Developer: "cloudflare backend error" → Rule-based trigger: Instant guaranteed retrieval → Natural Memory Triggers: Additional semantic context → < 30 seconds to solution → Comprehensive coverage including edge cases ``` ##### Scenario 2: Maintaining Development Standards **Before Context-Provider:** ``` Team commits: - "fix auth" - "Add new feature" - "updated README" → Inconsistent formatting → Manual code review enforcement needed ``` **After Context-Provider:** ``` Auto-corrected commits: - "fix: auth" ✅ - "feat: add new feature" ✅ - "docs: update README" ✅ → 100% semantic commit compliance → Automated standards enforcement ``` #### Integration Benefits Summary **For Individual Developers:** - **Zero Context Switching**: Instant access to project solutions - **Consistent Workflows**: Automatic standards enforcement - **Comprehensive Coverage**: No knowledge gaps in critical areas **For Development Teams:** - **Knowledge Standardization**: Consistent capture and access patterns - **Onboarding Acceleration**: New developers get immediate project intelligence - **Quality Assurance**: Automated compliance with team standards **For Project Velocity:** - **Faster Problem Resolution**: 30% improvement in troubleshooting speed - **Reduced Manual Documentation**: Automatic pattern capture - **Enhanced Code Quality**: Consistent formatting and standards > **💡 Bottom Line**: Context-Provider transforms your already sophisticated Natural Memory Triggers system from "smart but sometimes unpredictable" to "smart AND completely reliable for project-specific patterns." ### Mid-Conversation Hooks **Real-time memory injection as topics evolve** - **Dynamic Updates**: Injects memories as conversation progresses - **Context Shifts**: Detects topic changes and loads relevant context - **Non-Intrusive**: Works in background without interrupting flow ### Legacy Session Hooks **Traditional event-based memory loading** - **session-start**: Loads project context when Claude Code starts - **session-end**: Stores session insights and decisions - **memory-retrieval**: Manual memory refresh command Use legacy hooks when: - You need predictable, event-based behavior - Working with older Claude Code versions - Custom integration requirements --- ## CLI Management ### Memory Mode Controller ```bash # Check system status node ~/.claude/hooks/memory-mode-controller.js status # Performance profiles node ~/.claude/hooks/memory-mode-controller.js profile [speed_focused|balanced|memory_aware] # Adjust sensitivity node ~/.claude/hooks/memory-mode-controller.js sensitivity 0.7 # Enable/disable features node ~/.claude/hooks/memory-mode-controller.js toggle-triggers node ~/.claude/hooks/memory-mode-controller.js toggle-monitoring # View statistics node ~/.claude/hooks/memory-mode-controller.js stats ``` ### Testing Commands ```bash # Run all tests node ~/.claude/hooks/test-natural-triggers.js # Test specific components node ~/.claude/hooks/tests/test-pattern-detector.js node ~/.claude/hooks/tests/test-memory-retrieval.js # Integration test node ~/.claude/hooks/tests/integration-test.js ``` --- ## Performance Profiles ### Available Profiles | Profile | Latency | Memory Awareness | Best For | |---------|---------|-----------------|----------| | **speed_focused** | <100ms | Basic | Quick responses, minimal memory | | **balanced** | 200ms | Smart triggers | General development (default) | | **memory_aware** | 500ms | Full awareness | Complex projects, deep context | | **adaptive** | Variable | Auto-adjusts | Learns from your usage | ### Profile Configuration ```json { "performance": { "profiles": { "balanced": { "maxLatency": 200, "enabledTiers": ["instant", "fast"], "backgroundProcessing": true, "degradeThreshold": 400, "description": "Moderate latency, smart memory triggers" } } } } ``` ### Switching Profiles ```bash # Via CLI node ~/.claude/hooks/memory-mode-controller.js profile memory_aware # Via config.json "defaultProfile": "memory_aware" # Via environment variable export MCP_MEMORY_PERFORMANCE_PROFILE=memory_aware ``` --- ## Troubleshooting ### Common Issues & Solutions #### 🔴 Hooks Not Detected ```bash # Check Claude settings cat ~/.claude/settings.json | grep hooks # Solution: Reinstall cd mcp-memory-service/claude-hooks python install_hooks.py --natural-triggers ``` #### 🔴 Natural Triggers Not Working ```bash # Check if enabled node ~/.claude/hooks/memory-mode-controller.js status # Enable if disabled node ~/.claude/hooks/memory-mode-controller.js toggle-triggers # Adjust sensitivity node ~/.claude/hooks/memory-mode-controller.js sensitivity 0.5 ``` #### 🔴 Memory Service Connection Failed ```bash # Test memory service curl -k https://localhost:8443/api/health # Check MCP server claude mcp list # Restart memory service uv run memory server ``` #### 🔴 High Latency/Performance Issues ```bash # Switch to speed-focused profile node ~/.claude/hooks/memory-mode-controller.js profile speed_focused # Disable background processing # In config.json: "backgroundProcessing": false # Reduce memory limit # In config.json: "maxMemoriesPerSession": 5 ``` ### Debug Mode ```bash # Enable debug output export DEBUG=hooks:* claude --debug hooks # Check logs tail -f ~/.claude/logs/hooks.log # Test individual hooks node ~/.claude/hooks/core/session-start.js --test ``` ### Platform-Specific Issues #### Windows - Use forward slashes in paths: `C:/Users/name/.claude/hooks` - Run as Administrator if permission errors - Check Node.js is in PATH #### macOS - Grant terminal full disk access for file operations - Check for conflicting hook matchers in settings.json #### Linux - Ensure Node.js 16+ installed - Check file permissions: `chmod +x ~/.claude/hooks/*.js` --- ## Advanced Usage ### Custom Hook Development ```javascript // Example: Custom trigger pattern // ~/.claude/hooks/custom/my-trigger.js const { PatternDetector } = require('../utilities/pattern-detector'); const { MemoryClient } = require('../utilities/memory-client'); class CustomTrigger { constructor() { this.detector = new PatternDetector({ patterns: [ /custom pattern/i, /specific keyword/i ] }); this.client = new MemoryClient(); } async process(input) { if (this.detector.shouldTrigger(input)) { const memories = await this.client.retrieve({ query: input, limit: 3 }); return this.formatMemories(memories); } return null; } } ``` ### Integration with Git ```json { "gitAnalysis": { "enabled": true, "commitLookback": 14, // Days to look back "maxCommits": 20, // Maximum commits to analyze "includeChangelog": true, "gitContextWeight": 1.2 // Boost git-related memories } } ``` ### Custom Memory Scoring ```javascript // Implement custom relevance scoring { "memoryScoring": { "weights": { "timeDecay": 0.25, // Recent memories "tagRelevance": 0.35, // Tag matching "contentRelevance": 0.15, // Content similarity "contentQuality": 0.25, // Quality assessment "customScore": 0.0 // Your custom scoring }, "customScoringFunction": "~/.claude/hooks/custom/scoring.js" } } ``` --- ## Architecture ### Component Overview ``` ~/.claude/hooks/ ├── core/ # Main hook implementations │ ├── session-start.js # Session initialization │ ├── mid-conversation.js # Natural Memory Triggers │ └── session-end.js # Session consolidation ├── utilities/ # Shared utilities │ ├── pattern-detector.js # Pattern recognition │ ├── memory-client.js # Memory service client │ └── performance.js # Performance monitoring ├── tests/ # Test suite ├── config.json # Main configuration └── memory-mode-controller.js # CLI management tool ``` ### Data Flow 1. **Input Analysis** → Pattern detection evaluates user message 2. **Trigger Decision** → Determines if memory retrieval needed 3. **Memory Retrieval** → Fetches relevant memories from service 4. **Context Injection** → Seamlessly adds to conversation 5. **Performance Monitoring** → Tracks latency and adjusts ### Protocol Support > **⚠️ IMPORTANT ARCHITECTURAL DECISION**: After comprehensive investigation (macOS + Linux), hooks should use **HTTP-only** protocol, not dual protocol MCP, due to process conflicts. #### Current Recommended Configuration: HTTP-Only ```json { "memoryService": { "endpoint": "https://localhost:8443", "apiKey": "your-api-key" } } ``` #### Why HTTP-Only is Optimal: - **✅ Process Isolation**: Avoids duplicate MCP server spawning - **✅ No Conflicts**: Claude Code keeps its direct MCP connection - **✅ Proven Reliable**: HTTP hooks work consistently across platforms - **✅ Same Backend**: Both HTTP and MCP connect to identical storage (Cloudflare/SQLite) #### Investigation Results: **MCP Protocol Issues (Both macOS & Linux):** - ❌ **Duplicate Processes**: Hooks spawn separate MCP servers (12+ processes observed) - ❌ **TaskGroup Errors**: Conflicts with Claude Code's existing MCP connection - ❌ **Resource Waste**: Multiple server instances accessing same backend **HTTP Protocol Benefits:** - ✅ **Clean Architecture**: Hooks → HTTP → Memory Service ← MCP ← Claude Code - ✅ **Stable Performance**: No process conflicts or connection issues - ✅ **Easy Debugging**: Standard HTTP logs and error handling > **Technical Note**: The dual protocol design exists for future MCP client improvements (connection reuse, useExistingServer), but current limitations make HTTP-only the optimal choice. --- ## Version History ### v7.1.4 (Current - 2025-09-28) - ✅ Unified cross-platform Python installer - ✅ Intelligent JSON configuration merging - ✅ Enhanced safety with atomic installations - ✅ Comprehensive migration documentation ### v7.1.3 (2025-09-25) - ✅ Mid-conversation hooks implementation - ✅ Dual protocol support (MCP + HTTP) - ✅ Enhanced performance profiles - ✅ Git-aware context integration ### v7.1.0 (2025-09-20) - ✅ Natural Memory Triggers with 85%+ accuracy - ✅ Multi-tier processing architecture - ✅ CLI management system - ✅ Adaptive learning capabilities ### v6.0.0 (2025-09-01) - ✅ Initial memory hooks implementation - ✅ Session start/end events - ✅ Basic project detection --- ## Migration Guide ### From Legacy Shell Scripts (pre-v7.1.4) ```bash # Old method (deprecated) ./install.sh ./install-natural-triggers.sh # New method (v7.1.4+) python install_hooks.py --natural-triggers ``` ### From Basic Hooks to Natural Triggers 1. **Backup current setup**: `cp -r ~/.claude/hooks ~/.claude/hooks.backup` 2. **Install Natural Triggers**: `python install_hooks.py --natural-triggers` 3. **Verify**: `node ~/.claude/hooks/memory-mode-controller.js status` 4. **Remove backup**: `rm -rf ~/.claude/hooks.backup` (after confirming it works) ### From v7.1.0 to v7.1.4 No action required - v7.1.4 is backwards compatible. Optionally update to unified installer for better cross-platform support. --- ## Support & Resources - **GitHub Issues**: [Report bugs or request features](https://github.com/doobidoo/mcp-memory-service/issues) - **Wiki Home**: [Return to main documentation](./Home) - **Installation Guide**: [Platform-specific setup](./01-Installation-Guide) - **FAQ**: [Frequently asked questions](./08-FAQ) --- > **Note**: This guide consolidates information from Memory-Awareness-Hooks-Detailed-Guide.md, Natural-Memory-Triggers-v7.1.0.md, and Claude-Code-v7.1.3-Enhanced-Memory-Hooks.md into a single source of truth. For legacy documentation, see the [archive](./archive/) folder. --- ## 📚 Documentation | 🚀 Features | 🤖 Automation | 🌟 Community **Documentation**: [Home](./Home) • [Installation](./01-Installation-Guide) • [Integration](./03-Integration-Guide) • [Troubleshooting](./07-TROUBLESHOOTING) **Features**: [All 33 Features](./10-Complete-Feature-List) • [Memory Hooks](./Memory-Hooks-Complete-Guide) • [Web Dashboard](./Web-Dashboard-Guide) • [OAuth 2.1](./OAuth-2.1-Setup-Guide) **Automation**: [Agent Guide](./11-Agent-Integrations-Guide) • [Cross-Repo Setup](./12-Using-Agents-in-Other-Repositories) • [Context Provider](./Context-Provider-Workflow-Automation) **Community**: [GitHub](https://github.com/doobidoo/mcp-memory-service) • [Discussions](https://github.com/doobidoo/mcp-memory-service/discussions) • [Issues](https://github.com/doobidoo/mcp-memory-service/issues) • [Contribute](https://github.com/doobidoo/mcp-memory-service/blob/main/CONTRIBUTING.md) --- **MCP Memory Service** • Zero database locks • 5ms reads • 85% accurate memory triggers • [MIT License](https://github.com/doobidoo/mcp-memory-service/blob/main/LICENSE)