Hook Configuration - Claude Memory System

Overview

Integrate claude-mem with Claude Code through hooks that compress transcripts, load context, and manage memory. Configure hooks in Claude Code’s settings.json file.

Hook Types

Three main hooks integrate with Claude Code’s lifecycle:

1. SessionStart Hook

Triggered: When you start a new Claude Code session
Purpose: Loads relevant context from your previous sessions
Location: ~/.claude-mem/hooks/session-start.js

2. PreCompact Hook

Triggered: Before Claude Code compacts/clears your session
Purpose: Compresses your transcript into memory before data is lost
Location: ~/.claude-mem/hooks/pre-compact.js

3. SessionEnd Hook

Triggered: When you end your Claude Code session or use /clear
Purpose: Optionally saves your memories before clearing context
Location: ~/.claude-mem/hooks/session-end.js

Hook Configuration File

Configure hooks in ~/.claude/.claude/settings.json:

{
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/username/.claude-mem/hooks/pre-compact.js",
            "timeout": 180000
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/username/.claude-mem/hooks/session-start.js"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/username/.claude-mem/hooks/session-end.js",
            "timeout": 180000
          }
        ]
      }
    ]
  }
}

Hook Configuration Options

Command Type

type: Always "command" for claude-mem hooks
command: Absolute path to the hook script
timeout: Maximum execution time in milliseconds (default: 120000)

Timeout Settings

{
  "PreCompact": { "timeout": 180000 },  // 3 minutes for compression
  "SessionStart": { "timeout": 60000 }, // 1 minute for loading
  "SessionEnd": { "timeout": 180000 }   // 3 minutes for saving
}

Hook Behavior Customization

Environment Variables

You can control hook behavior with environment variables:

# Enable debug logging for hooks
export CLAUDE_MEM_DEBUG=true

# Disable auto-compression
export DISABLE_AUTO_COMPRESSION=true

# Silent operation
export CLAUDE_MEM_SILENT=true

# Custom project name
export CLAUDE_MEM_PROJECT_NAME="my-project"

Configuration File Overrides

You can create a config.json in the hooks directory to override CLI commands:

{
  "cliCommand": "claude-mem"
}

Advanced Hook Configuration

Multiple Hook Instances

You can configure multiple hooks for the same event:

{
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/custom-pre-hook.js"
          },
          {
            "type": "command",
            "command": "/Users/username/.claude-mem/hooks/pre-compact.js",
            "timeout": 180000
          }
        ]
      }
    ]
  }
}

Conditional Hook Execution

Your hooks can check conditions before executing:

// In custom hook
if (process.env.NODE_ENV === 'development') {
  // Skip compression in dev
  process.exit(0);
}

Hook Response Format

Your hooks communicate with Claude Code using standardized JSON responses:

PreCompact Hook Response

{
  "continue": true,
  "suppressOutput": true
}

SessionStart Hook Response

{
  "continue": true,
  "suppressOutput": true,
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "🧠 Loaded 15 memories from previous sessions..."
  }
}

Error Response

{
  "continue": false,
  "stopReason": "Compression failed: disk full",
  "suppressOutput": true
}

Hook Development

Creating Custom Hooks

You can create custom hooks that integrate with claude-mem:

#!/usr/bin/env node

import { spawn } from 'child_process';

// Read hook payload from stdin
let input = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => input += chunk);

process.stdin.on('end', async () => {
  try {
    const payload = JSON.parse(input);

    // Your custom logic here

    // Return standardized response
    console.log(JSON.stringify({
      continue: true,
      suppressOutput: true
    }));

  } catch (error) {
    console.log(JSON.stringify({
      continue: false,
      stopReason: error.message
    }));
  }
});

Hook Payload Structure

Your hooks receive different payloads based on their type:

interface PreCompactPayload {
  session_id: string;
  transcript_path: string;
  hook_event_name: 'PreCompact';
  trigger: 'manual' | 'auto';
  custom_instructions?: string;
}

Installation and Management

Automatic Installation

You can automatically install hooks during setup:

# Install hooks with default configuration
claude-mem install

# Force reinstall hooks
claude-mem install --force

# Install to custom location
claude-mem install --local --path /custom/path

Manual Hook Management

# Check hook installation status
claude-mem status

# View hook execution logs
claude-mem logs

# Uninstall hooks
claude-mem uninstall

Troubleshooting Hooks

Common Issues

Hook Not Executing

Check file permissions:
```
chmod +x ~/.claude-mem/hooks/*.js
```

Verify paths in settings:

cat ~/.claude/.claude/settings.json | jq .hooks

Test hook manually:

echo '{"session_id":"test","transcript_path":"/tmp/test","hook_event_name":"SessionStart"}' | ~/.claude-mem/hooks/session-start.js

Timeout Issues

Increase timeout values in hook configuration
Check for blocking operations in custom hooks
Verify system performance

Context Not Loading

Check project name detection:
```
claude-mem status
```

Verify memory existence:

claude-mem load-context --project your-project

Enable debug logging:
```
export CLAUDE_MEM_DEBUG=true
```

Debug Mode

Enable comprehensive debugging:

# Environment variable method
export CLAUDE_MEM_DEBUG=true

# Or in hook configuration
{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "/path/to/hook.js",
        "env": {
          "CLAUDE_MEM_DEBUG": "true"
        }
      }]
    }]
  }
}

Performance Optimization

Reducing Hook Latency

Optimize compression settings:

{
  "autoCompress": false,  // Manual compression only
  "embedded": true       // Use embedded Chroma
}

Limit context loading:

# In custom session-start hook
claude-mem load-context --limit 10 --format brief

Async operations:

// Don't wait for non-critical operations
executeCliCommand('claude-mem', ['compress']).catch(() => {});

Memory Management

Hooks run in separate processes
Large context data is streamed, not held in memory
Cleanup temporary files in custom hooks

Security Considerations

File Permissions

# Secure hook files
chmod 700 ~/.claude-mem/hooks/
chmod 600 ~/.claude-mem/hooks/*.js

Path Validation

Always use absolute paths in hook configuration
Validate file paths in custom hooks
Avoid user input in command execution

Environment Isolation

Hooks inherit environment variables
Sensitive data should use secure storage
Consider using environment-specific configurations

Migration Guide

Upgrading Hook Configuration

When upgrading claude-mem versions:

Backup current configuration:

cp ~/.claude/.claude/settings.json ~/.claude/.claude/settings.json.backup

Run installation:
```
claude-mem install --force
```
Restore custom modifications if needed

Version Compatibility

v3.6.x: Current hook format (no changes required)
v3.5.x: Compatible with current hooks
v3.4.x and earlier: Requires reinstallation

Settings Configuration - Main settings file
Claude Integration - Integration details
CLI Reference - Installation commands
Troubleshooting - Common issues

Get Started

Core Concepts

Configuration

Guides

Advanced

​Overview

​Hook Types

​1. SessionStart Hook

​2. PreCompact Hook

​3. SessionEnd Hook

​Hook Configuration File

​Hook Configuration Options

​Command Type

​Timeout Settings

​Hook Behavior Customization

​Environment Variables

​Configuration File Overrides

​Advanced Hook Configuration

​Multiple Hook Instances

​Conditional Hook Execution

​Hook Response Format

​PreCompact Hook Response

​SessionStart Hook Response

​Error Response

​Hook Development

​Creating Custom Hooks

​Hook Payload Structure

​Installation and Management

​Automatic Installation

​Manual Hook Management

​Troubleshooting Hooks

​Common Issues

​Hook Not Executing

​Timeout Issues

​Context Not Loading

​Debug Mode

​Performance Optimization

​Reducing Hook Latency

​Memory Management

​Security Considerations

​File Permissions

​Path Validation

​Environment Isolation

​Migration Guide

​Upgrading Hook Configuration

​Version Compatibility

​Related Documentation