Transform lengthy conversations into searchable, actionable memories.

​
Compression Pipeline

​
When Compression Happens

Compression triggers: By default only /compact is active. Enable save-on-clear during install or call claude-mem compress <transcript> manually.

​
What Gets Compressed

Analyzes conversations for:

​
1. Key Insights

  • Problem solutions
  • Bug fixes
  • Implementation decisions
  • Architecture choices

​
2. Code Changes

  • New features added
  • Refactoring performed
  • Dependencies installed
  • Configurations updated

​
3. Context

  • Project information
  • User preferences
  • Technical decisions
  • Future todos

​
Compression Algorithm

// Extract structured messages
const transcript = await readTranscript(sessionId);
const messages = parseMessages(transcript);

// Filter relevant content
const relevant = messages.filter(msg => {
  return msg.role === 'assistant' &&
         msg.content.length > 100 &&
         containsInsight(msg.content);
});

​
Compression Strategies

claude-mem uses different strategies based on content:

​
Code-Heavy Sessions

For sessions with lots of code:
  • Extracts function/class definitions
  • Captures implementation patterns
  • Records dependency changes

​
Discussion Sessions

For conceptual discussions:
  • Summarizes decisions made
  • Records architectural choices
  • Captures requirements

​
Debugging Sessions

For troubleshooting:
  • Records error messages
  • Documents solutions found
  • Notes workarounds

​
Memory Document Structure

Each compressed memory becomes a searchable document: 
{
  "id": "mem_abc123",
  "content": "Fixed authentication bug by updating JWT token validation...",
  "metadata": {
    "session_id": "session_xyz",
    "timestamp": "2025-09-15T10:30:00Z",
    "type": "bug_fix",
    "keywords": ["auth", "jwt", "validation"],
    "project": "my-app",
    "importance": "high"
  }
}

​
Compression Levels

Configure compression in settings.json: 
{
  "compressionLevel": "minimal",
  "maxMemoriesPerSession": 5
}
  • Quick compression
  • Key points only
  • Small storage footprint

​
Smart Deduplication

claude-mem prevents duplicate memories:
  1. Content Hashing - Detects identical content
  2. Similarity Check - Finds near-duplicates
  3. Time Window - Merges related memories
  4. Update Strategy - Updates existing vs creating new

​
Compression Output

After compression, you’ll see: 
✅ Compressed

5 memories extracted:
- Fixed authentication bug with JWT validation
- Implemented dark mode using Tailwind CSS
- Optimized database queries for dashboard
- Added error handling for API calls
- Configured CI/CD pipeline with GitHub Actions

​
Manual Compression

Trigger compression manually: 
# Via Claude Code
/compact

# Via CLI
claude-mem compress --session latest

# Specific session
claude-mem compress --session abc123

​
Compression Statistics

View compression stats: 
claude-mem stats
Output: 
📊 Compression Statistics
────────────────────────

Total Sessions: 42
Compressed: 38
Total Memories: 312
Average per Session: 8.2
Storage Used: 12.4 MB
Compression Ratio: 94:1

​
Performance

Compression is optimized for speed:
MetricValue
Average Time2-3 seconds
Memory Usage< 50MB
CPU Usage< 10%
Compression Ratio50:1 - 100:1

​
Troubleshooting Compression

​
Best Practices

​
Next Steps