-
-
Notifications
You must be signed in to change notification settings - Fork 108
Memory Hooks Complete Guide
Henry edited this page Sep 30, 2025
·
2 revisions
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
- Overview
- Quick Start
- Installation
- Configuration
- Features
- CLI Management
- Performance Profiles
- Troubleshooting
- Advanced Usage
- Architecture
- Version History
- Migration Guide
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.
| 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 |
- 🧠 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
# Check if hooks are installed
ls ~/.claude/hooks/
# Check Natural Memory Triggers specifically
node ~/.claude/hooks/memory-mode-controller.js status# 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# Test the system
node ~/.claude/hooks/test-natural-triggers.js
# Check CLI controller
node ~/.claude/hooks/memory-mode-controller.js statusNatural 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?"
The unified installer provides cross-platform compatibility with enhanced safety features:
# 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- ✅ Backs up existing hooks and settings
- ✅ Intelligently merges configurations (preserves your settings)
- ✅ Installs selected components
- ✅ Validates Node.js and memory service connectivity
- ✅ Runs comprehensive test suite (18+ tests)
- ✅ Provides detailed installation report
For advanced users who need custom control:
# 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"
}
]
}# With hooks pre-configured
docker run -v ~/.claude:/home/user/.claude \
doobidoo/mcp-memory-service:latest \
install-hooks --natural-triggersLocation: ~/.claude/hooks/config.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
}
}# Optional: Override config file settings
export MCP_MEMORY_HOOK_VERBOSE=true
export MCP_MEMORY_TRIGGER_THRESHOLD=0.7
export MCP_MEMORY_PERFORMANCE_PROFILE=memory_awareIntelligent automatic memory retrieval with 85%+ accuracy
- Pattern Detection: Analyzes your messages for memory-seeking patterns
- Semantic Analysis: Understands context and intent
- Relevance Scoring: Ranks memories by relevance
- Injection: Seamlessly adds context to your conversation
| 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 |
# 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 balancedDeterministic 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
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 |
Rule-based triggers that guarantee capture and retrieval of project-critical patterns:
# Automatic setup - no manual commands needed
# Context-provider activates automatically with Claude Code sessionsBefore: "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
Before: Developer types "Fix auth bug"
→ Inconsistent commit formatting
After: "Fix auth bug"
→ Auto-corrected to "fix: auth bug"
→ 100% semantic commit compliance
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
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
| 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 |
Why This Matters for MCP Memory Service:
- 4 Storage Backends: sqlite-vec, chromadb, cloudflare, hybrid
- Multiple Integration Patterns: OAuth, dashboard, MCP protocol
- Performance-Critical Operations: 25ms response requirements
-
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
- Architectural Decisions: Previous choices immediately accessible
- Error Solutions: Proven fixes guaranteed retrieval
- Configuration Patterns: Setup procedures always available
Automatic Integration (No manual setup required):
- Context-provider automatically detects MCP Memory Service project
- Python MCP Memory Service context activates
- Enhanced memory context patterns enable
- Works alongside existing Natural Memory Triggers
Manual Verification (Optional):
# 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 statusBefore 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
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
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."
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
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
# 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# 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| 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 |
{
"performance": {
"profiles": {
"balanced": {
"maxLatency": 200,
"enabledTiers": ["instant", "fast"],
"backgroundProcessing": true,
"degradeThreshold": 400,
"description": "Moderate latency, smart memory triggers"
}
}
}
}# 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# Check Claude settings
cat ~/.claude/settings.json | grep hooks
# Solution: Reinstall
cd mcp-memory-service/claude-hooks
python install_hooks.py --natural-triggers# 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# Test memory service
curl -k https://localhost:8443/api/health
# Check MCP server
claude mcp list
# Restart memory service
uv run memory server# 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# 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- Use forward slashes in paths:
C:/Users/name/.claude/hooks - Run as Administrator if permission errors
- Check Node.js is in PATH
- Grant terminal full disk access for file operations
- Check for conflicting hook matchers in settings.json
- Ensure Node.js 16+ installed
- Check file permissions:
chmod +x ~/.claude/hooks/*.js
// 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;
}
}{
"gitAnalysis": {
"enabled": true,
"commitLookback": 14, // Days to look back
"maxCommits": 20, // Maximum commits to analyze
"includeChangelog": true,
"gitContextWeight": 1.2 // Boost git-related memories
}
}// 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"
}
}~/.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
- Input Analysis → Pattern detection evaluates user message
- Trigger Decision → Determines if memory retrieval needed
- Memory Retrieval → Fetches relevant memories from service
- Context Injection → Seamlessly adds to conversation
- Performance Monitoring → Tracks latency and adjusts
⚠️ IMPORTANT ARCHITECTURAL DECISION: After comprehensive investigation (macOS + Linux), hooks should use HTTP-only protocol, not dual protocol MCP, due to process conflicts.
{
"memoryService": {
"endpoint": "https://localhost:8443",
"apiKey": "your-api-key"
}
}- ✅ 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)
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.
- ✅ Unified cross-platform Python installer
- ✅ Intelligent JSON configuration merging
- ✅ Enhanced safety with atomic installations
- ✅ Comprehensive migration documentation
- ✅ Mid-conversation hooks implementation
- ✅ Dual protocol support (MCP + HTTP)
- ✅ Enhanced performance profiles
- ✅ Git-aware context integration
- ✅ Natural Memory Triggers with 85%+ accuracy
- ✅ Multi-tier processing architecture
- ✅ CLI management system
- ✅ Adaptive learning capabilities
- ✅ Initial memory hooks implementation
- ✅ Session start/end events
- ✅ Basic project detection
# Old method (deprecated)
./install.sh
./install-natural-triggers.sh
# New method (v7.1.4+)
python install_hooks.py --natural-triggers-
Backup current setup:
cp -r ~/.claude/hooks ~/.claude/hooks.backup -
Install Natural Triggers:
python install_hooks.py --natural-triggers -
Verify:
node ~/.claude/hooks/memory-mode-controller.js status -
Remove backup:
rm -rf ~/.claude/hooks.backup(after confirming it works)
No action required - v7.1.4 is backwards compatible. Optionally update to unified installer for better cross-platform support.
- GitHub Issues: Report bugs or request features
- Wiki Home: Return to main documentation
- Installation Guide: Platform-specific setup
- FAQ: Frequently asked questions
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 folder.