# Natural Memory Triggers v7.1.3 - Installation Guide

This guide provides detailed installation instructions for Natural Memory Triggers, the intelligent automatic memory awareness system for Claude Code.

## Prerequisites

Before installing Natural Memory Triggers, ensure you have:

- ✅ **Claude Code CLI** installed and working (`claude --version`)
- ✅ **Node.js 14+** for hook execution (`node --version`)
- ✅ **MCP Memory Service** running (`curl -k https://localhost:8443/api/health`)
- ✅ **Valid configuration** at `~/.claude/hooks/config.json`

## Installation Methods

### Method 1: Automated Installation (Recommended)

The automated installer handles the complete setup with comprehensive testing:

```bash
# Navigate to the claude-hooks directory
cd mcp-memory-service/claude-hooks

# Install with unified Python installer
python install_hooks.py --natural-triggers
```

**What the installer does:**

1. **System Verification**
   - Checks Claude Code CLI availability
   - Validates Node.js version compatibility
   - Tests MCP Memory Service connectivity
   - Verifies directory permissions

2. **Backup Operations**
   - Creates backup of existing `~/.claude/hooks/` directory
   - Preserves current configuration files
   - Backs up existing hook implementations

3. **Component Installation**
   - Copies Natural Memory Triggers core components
   - Installs multi-tier conversation monitor
   - Sets up performance manager and git analyzer
   - Installs CLI management controller

4. **Configuration Setup**
   - Merges new configuration sections with existing settings
   - Preserves user customizations
   - Adds Natural Memory Triggers specific settings
   - Configures performance profiles

5. **Testing and Validation**
   - Runs 18 comprehensive tests
   - Tests semantic analysis functionality
   - Validates CLI controller operations
   - Checks memory service integration

6. **Installation Report**
   - Provides detailed installation summary
   - Lists installed components and their versions
   - Shows configuration status and recommendations
   - Provides next steps and usage instructions

### Method 2: Manual Installation

For users who prefer manual control or need custom configurations:

#### Step 1: Directory Setup

```bash
# Create required directory structure
mkdir -p ~/.claude/hooks/{core,utilities,tests}

# Verify directory creation
ls -la ~/.claude/hooks/
```

#### Step 2: Copy Core Components

```bash
# Copy main hook implementation
cp claude-hooks/core/mid-conversation.js ~/.claude/hooks/core/

# Copy utility modules
cp claude-hooks/utilities/tiered-conversation-monitor.js ~/.claude/hooks/utilities/
cp claude-hooks/utilities/performance-manager.js ~/.claude/hooks/utilities/
cp claude-hooks/utilities/git-analyzer.js ~/.claude/hooks/utilities/
cp claude-hooks/utilities/mcp-client.js ~/.claude/hooks/utilities/

# Copy CLI management system
cp claude-hooks/memory-mode-controller.js ~/.claude/hooks/

# Copy test suite
cp claude-hooks/test-natural-triggers.js ~/.claude/hooks/
```

#### Step 3: Configuration Setup

```bash
# Copy base configuration if it doesn't exist
if [ ! -f ~/.claude/hooks/config.json ]; then
    cp claude-hooks/config.template.json ~/.claude/hooks/config.json
fi

# Edit configuration file
nano ~/.claude/hooks/config.json
```

Add the following sections to your configuration:

```json
{
  "naturalTriggers": {
    "enabled": true,
    "triggerThreshold": 0.6,
    "cooldownPeriod": 30000,
    "maxMemoriesPerTrigger": 5
  },
  "performance": {
    "defaultProfile": "balanced",
    "enableMonitoring": true,
    "autoAdjust": true,
    "profiles": {
      "speed_focused": {
        "maxLatency": 100,
        "enabledTiers": ["instant"],
        "backgroundProcessing": false,
        "degradeThreshold": 200,
        "description": "Fastest response, minimal memory awareness"
      },
      "balanced": {
        "maxLatency": 200,
        "enabledTiers": ["instant", "fast"],
        "backgroundProcessing": true,
        "degradeThreshold": 400,
        "description": "Moderate latency, smart memory triggers"
      },
      "memory_aware": {
        "maxLatency": 500,
        "enabledTiers": ["instant", "fast", "intensive"],
        "backgroundProcessing": true,
        "degradeThreshold": 1000,
        "description": "Full memory awareness, accept higher latency"
      },
      "adaptive": {
        "autoAdjust": true,
        "degradeThreshold": 800,
        "backgroundProcessing": true,
        "description": "Auto-adjust based on performance and user preferences"
      }
    }
  }
}
```

#### Step 4: Set File Permissions

```bash
# Make hook files executable
chmod +x ~/.claude/hooks/core/*.js
chmod +x ~/.claude/hooks/memory-mode-controller.js
chmod +x ~/.claude/hooks/test-natural-triggers.js

# Set appropriate directory permissions
chmod 755 ~/.claude/hooks
chmod -R 644 ~/.claude/hooks/*.json
```

#### Step 5: Test Installation

```bash
# Run comprehensive test suite
cd ~/.claude/hooks
node test-natural-triggers.js

# Test CLI controller
node memory-mode-controller.js status

# Test specific components
node -e "
const { TieredConversationMonitor } = require('./utilities/tiered-conversation-monitor');
const monitor = new TieredConversationMonitor();
console.log('✅ TieredConversationMonitor loaded successfully');
"
```

## Installation Verification

### Test 1: System Components

```bash
# Verify all components are in place
ls ~/.claude/hooks/core/mid-conversation.js
ls ~/.claude/hooks/utilities/tiered-conversation-monitor.js
ls ~/.claude/hooks/utilities/performance-manager.js
ls ~/.claude/hooks/utilities/git-analyzer.js
ls ~/.claude/hooks/memory-mode-controller.js
```

### Test 2: Configuration Validation

```bash
# Check configuration syntax
cat ~/.claude/hooks/config.json | node -e "
try {
  const config = JSON.parse(require('fs').readFileSync(0, 'utf8'));
  console.log('✅ Configuration JSON is valid');
  console.log('Natural Triggers enabled:', config.naturalTriggers?.enabled);
  console.log('Default profile:', config.performance?.defaultProfile);
} catch (error) {
  console.error('❌ Configuration error:', error.message);
}
"
```

### Test 3: CLI Controller

```bash
# Test CLI management system
node ~/.claude/hooks/memory-mode-controller.js status
node ~/.claude/hooks/memory-mode-controller.js profiles
```

Expected output:
```
📊 Memory Hook Status
Current Profile: balanced
Description: Moderate latency, smart memory triggers
Natural Triggers: enabled
Sensitivity: 0.6
Performance: 0ms avg latency, 0 degradation events
```

### Test 4: Memory Service Integration

```bash
# Test memory service connectivity
node ~/.claude/hooks/memory-mode-controller.js test "What did we decide about authentication?"
```

Expected behavior:
- Should attempt to analyze the test query
- Should show tier processing (instant → fast → intensive)
- Should either retrieve relevant memories or show "no relevant memories found"
- Should complete without errors

## Post-Installation Configuration

### Performance Profile Selection

Choose the appropriate profile for your workflow:

```bash
# For quick coding sessions (minimal interruption)
node memory-mode-controller.js profile speed_focused

# For general development work (recommended)
node memory-mode-controller.js profile balanced

# For architecture and research work (maximum context)
node memory-mode-controller.js profile memory_aware

# For adaptive learning (system learns your preferences)
node memory-mode-controller.js profile adaptive
```

### Sensitivity Tuning

Adjust trigger sensitivity based on your preferences:

```bash
# More triggers (lower threshold)
node memory-mode-controller.js sensitivity 0.4

# Balanced triggers (recommended)
node memory-mode-controller.js sensitivity 0.6

# Fewer triggers (higher threshold)
node memory-mode-controller.js sensitivity 0.8
```

### Git Integration Setup

For enhanced Git-aware context, ensure your repository has:

- **Recent commit history** (Natural Memory Triggers analyzes last 14 days)
- **Readable CHANGELOG.md** (parsed for version context)
- **Proper git configuration** (for commit author and timestamps)

## Troubleshooting Installation Issues

### Issue 1: Node.js Not Found

**Error**: `node: command not found`

**Solution**:
```bash
# Install Node.js (version 14 or higher)
# macOS with Homebrew:
brew install node

# Ubuntu/Debian:
sudo apt update && sudo apt install nodejs npm

# Windows:
# Download from https://nodejs.org/

# Verify installation
node --version
npm --version
```

### Issue 2: Permission Errors

**Error**: `Permission denied` when running hooks

**Solution**:
```bash
# Fix file permissions
chmod +x ~/.claude/hooks/core/*.js
chmod +x ~/.claude/hooks/memory-mode-controller.js

# Fix directory permissions
chmod 755 ~/.claude/hooks
chmod -R 644 ~/.claude/hooks/*.json
```

### Issue 3: Memory Service Connection Failed

**Error**: `Network error` or `ENOTFOUND`

**Diagnosis**:
```bash
# Test memory service directly
curl -k https://localhost:8443/api/health

# Check configuration
cat ~/.claude/hooks/config.json | grep -A 5 "memoryService"
```

**Solutions**:
1. **Start Memory Service**: `uv run memory server`
2. **Check API Key**: Ensure valid API key in configuration
3. **Firewall Settings**: Verify port 8443 is accessible
4. **SSL Issues**: Self-signed certificates may need special handling

### Issue 4: Configuration Conflicts

**Error**: `Parse error: Expected property name or '}' in JSON`

**Solution**:
```bash
# Validate JSON syntax
cat ~/.claude/hooks/config.json | python -m json.tool

# If corrupted, restore from backup
cp ~/.claude/hooks/config.json.backup ~/.claude/hooks/config.json

# Or reset to defaults
node memory-mode-controller.js reset
```

### Issue 5: Claude Code Integration Issues

**Error**: Hooks not detected by Claude Code

**Diagnosis**:
```bash
# Check Claude Code settings
cat ~/.claude/settings.json | grep -A 10 "hooks"

# Verify hook files location
ls -la ~/.claude/hooks/core/
```

**Solutions**:
1. **Correct Location**: Ensure hooks are in `~/.claude/hooks/` not `~/.claude-code/hooks/`
2. **Settings Update**: Update `~/.claude/settings.json` with correct paths
3. **Restart Claude Code**: Some changes require restart
4. **Debug Mode**: Run `claude --debug hooks` to see hook loading messages

## Installation Verification Checklist

- [ ] All core components copied to `~/.claude/hooks/`
- [ ] Configuration file includes `naturalTriggers` and `performance` sections
- [ ] File permissions set correctly (executable hooks, readable configs)
- [ ] CLI controller responds to `status` command
- [ ] Test suite passes all 18 tests
- [ ] Memory service connectivity verified
- [ ] Performance profile selected and applied
- [ ] Git integration working (if applicable)
- [ ] Claude Code detects and loads hooks

## Next Steps

After successful installation:

1. **Read the User Guide**: Comprehensive usage instructions at [Natural Memory Triggers v7.1.3 Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Natural-Memory-Triggers-v7.1.0)

2. **Try the System**: Ask Claude Code questions like:
   - "What approach did we use for authentication?"
   - "How did we handle error handling in this project?"
   - "What were the main architectural decisions we made?"

3. **Monitor Performance**: Check system metrics periodically:
   ```bash
   node memory-mode-controller.js metrics
   ```

4. **Customize Settings**: Adjust profiles and sensitivity based on your workflow:
   ```bash
   node memory-mode-controller.js profile memory_aware
   node memory-mode-controller.js sensitivity 0.7
   ```

5. **Provide Feedback**: The adaptive profile learns from your usage patterns, so use the system regularly for best results.

---

**Natural Memory Triggers v7.1.3** transforms Claude Code into an intelligent development assistant that automatically understands when you need context from your project history! 🚀