Claude Code Integration - Claude Memory System

Overview

Integrate with Claude Code through hooks and MCP (Model Context Protocol) server. Enable automatic memory compression, context loading, and session management.

Integration Architecture

Integration Components

1. Hook System

Integration through Claude Code’s native hook system:

Automatic trigger: Hooks execute at specific Claude Code lifecycle events
Non-blocking operation: Hooks run independently without interrupting your session
Error tolerance: Failed hooks don’t break Claude Code functionality

2. MCP Server Integration

Chroma MCP Server: Provides vector database functionality
Semantic search: Enables intelligent context retrieval
Document storage: Manages compressed memories efficiently

3. CLI Commands

Direct invocation: Hooks use claude-mem CLI commands
Standardized responses: Consistent JSON communication format
Timeout handling: Graceful handling of long-running operations

Installation Process

Automatic Installation

# Install with interactive wizard
claude-mem install

# Force reinstall (updates existing installation)
claude-mem install --force

# Install to specific scope
claude-mem install --user    # Global settings
claude-mem install --project # Project-specific
claude-mem install --local   # Custom directory

Installation Scopes

# Installs to global Claude Code settings
claude-mem install --user

# Settings location:
~/.claude/settings.json

# Hook scripts location:
~/.claude-mem/hooks/

Hook Configuration

Settings File Structure

Claude-mem modifies Claude Code’s settings.json file to register hooks:

{
  "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 Execution Flow

1. Claude Code starts new session
2. Triggers SessionStart hook
3. Hook loads project context via:
   claude-mem load-context --project current-project
4. Context displayed in Claude Code
5. Session begins with full context

Context Loading

Automatic Context Injection

When starting a new session, claude-mem automatically:

Detects project name from current working directory
Queries memory database for relevant context
Formats context for optimal Claude Code display
Injects context as additional session context

Context Format Examples

🧠 Loaded 15 memories from previous sessions for my-project (last worked: 2025-01-15)

🎯 Recent components: UserAuthentication, DatabaseManager, APIRouter

🔄 Recent decisions: Switched to TypeScript, Added Redis caching

💡 Use search_nodes("keywords") to find related work or open_nodes(["entity_name"]) to load specific components

Memory Compression

Automatic Compression

Claude-mem automatically compresses transcripts using:

Intelligent chunking: Breaks large transcripts into manageable segments
Semantic analysis: Identifies key components, decisions, and patterns
Vector embedding: Creates searchable memory representations
Storage optimization: Compresses and archives original transcripts

Compression Triggers

# User initiates via Claude Code
/compact

# Direct CLI usage
claude-mem compress [transcript-file]

Error Handling

Graceful Degradation

Claude-mem is designed to fail gracefully:

// Hook error handling pattern
try {
  const result = await executeClaudeMemCommand();
  return successResponse(result);
} catch (error) {
  // Log error but don't block Claude Code
  return continueResponse();
}

Common Error Scenarios

{
  "continue": false,
  "stopReason": "Hook execution timeout",
  "suppressOutput": true
}

Performance Optimization

Reducing Integration Overhead

// Async execution pattern
executeCliCommand('claude-mem', ['compress'])
  .catch(error => debugLog('Compression failed', error));

// Quick exit for invalid conditions
if (payload.source === 'resume') {
  process.exit(0);
}

Memory Usage

Streaming operations: Large files processed in chunks
Separate processes: Hooks run independently of Claude Code
Cleanup: Temporary files automatically removed

Debugging Integration

Enable Debug Mode

# Environment variable
export CLAUDE_MEM_DEBUG=true

# View hook execution logs
claude-mem logs --debug

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

Debug Output Examples

[2025-01-15T10:30:45.123Z] HOOK DEBUG: Session start hook started {
  payload: {
    session_id: "abc123",
    transcript_path: "/home/user/.claude/projects/myproject/transcript.jsonl",
    hook_event_name: "SessionStart",
    source: "startup"
  }
}

Integration Status

Check Installation Status

# Comprehensive status check
claude-mem status

# Verify hook registration
cat ~/.claude/settings.json | jq .hooks

# Test specific hook
claude-mem test-hook session-start

Status Output Example

🔍 Claude Memory System Status Check
=====================================

📂 Installed Hook Scripts:
  ✅ pre-compact.js: Found at /Users/username/.claude-mem/hooks/pre-compact.js
  ✅ session-start.js: Found at /Users/username/.claude-mem/hooks/session-start.js
  ✅ session-end.js: Found at /Users/username/.claude-mem/hooks/session-end.js

⚙️ Settings Configuration:
  📋 Global: /Users/username/.claude/settings.json
     PreCompact: ✅
     SessionStart: ✅
     SessionEnd: ✅

🧠 Chroma Storage Status:
  ✅ Storage backend: Chroma MCP
  📍 Data location: /Users/username/.claude-mem/chroma
  🔍 Features: Vector search, semantic similarity, document storage

📊 Summary:
  ✅ Claude Memory System is installed (Global)

💡 To test: Use /compact in Claude Code

Customization Options

Environment-Based Configuration

# Disable auto-compression
export DISABLE_AUTO_COMPRESSION=true

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

# Silent operation
export CLAUDE_MEM_SILENT=true

# Debug mode
export CLAUDE_MEM_DEBUG=true

Project-Specific Overrides

// .claude/settings.json (project-level)
{
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/custom/path/pre-compact.js",
            "env": {
              "CUSTOM_PROJECT_CONFIG": "true"
            }
          }
        ]
      }
    ]
  }
}

Migration and Updates

Updating Integration

# Update to latest version
npm install -g claude-mem

# Reinstall hooks
claude-mem install --force

# Verify update
claude-mem status

Version Compatibility

Claude Code: v1.0.0+ (hooks support required)
Node.js: v18.0.0+ (required for MCP integration)
Platform: macOS, Linux, Windows (WSL)

Troubleshooting Integration

Common Issues

# Check hook file permissions
chmod +x ~/.claude-mem/hooks/*.js

# Verify settings registration
claude-mem status

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

Reset Integration

# Complete reset
claude-mem uninstall --all
claude-mem install --force

# Selective reset
claude-mem uninstall --user
claude-mem install --user --force

Security Considerations

File Permissions

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

# Secure settings
chmod 600 ~/.claude/settings.json

Path Security

Always use absolute paths in hook configuration
Validate file paths in custom hooks
Avoid executing user-provided commands

Data Privacy

Memory data stored locally by default
No data transmitted to external services
Transcript compression preserves privacy

Settings Configuration - Main configuration options
Hook Configuration - Detailed hook customization
CLI Reference - Installation and management commands
Troubleshooting Guide - Common issues and solutions

Get Started

Core Concepts

Configuration

Guides

Advanced

​Overview

​Integration Architecture

​Integration Components

​1. Hook System

​2. MCP Server Integration

​3. CLI Commands

​Installation Process

​Automatic Installation

​Installation Scopes

​Hook Configuration

​Settings File Structure

​Hook Execution Flow

​Context Loading

​Automatic Context Injection

​Context Format Examples

​Memory Compression

​Automatic Compression

​Compression Triggers

​Error Handling

​Graceful Degradation

​Common Error Scenarios

​Performance Optimization

​Reducing Integration Overhead

​Memory Usage

​Debugging Integration

​Enable Debug Mode

​Debug Output Examples

​Integration Status

​Check Installation Status

​Status Output Example

​Customization Options

​Environment-Based Configuration

​Project-Specific Overrides

​Migration and Updates

​Updating Integration

​Version Compatibility

​Troubleshooting Integration

​Common Issues

​Reset Integration

​Security Considerations

​File Permissions

​Path Security

​Data Privacy

​Related Documentation