🚨 CRITICAL: Memory leak causes freeze after 20+ minutes (15GB RAM consumption)

Claude Code CLI - Memory Leak Critical Bug Report

Date: 2026-01-28 04:45 UTC
Reporter: Rickard Wilhelmsson (wilhelmsson424@gmail.com)
Claude Code Version: Latest (2.1.21)
OS: Linux 6.6.87.2-microsoft-standard-WSL2 (WSL2)
RAM: 16GB total

---

🚨 CRITICAL: Claude process freezes after 20+ minutes, consuming 15GB RAM

Incident Summary

11th occurrence of Claude process completely freezing, requiring force kill (kill -9).

Symptom: Claude CLI becomes unresponsive, consuming 90%+ of system RAM, making entire system unusable.

Technical Details

Process Analysis (PID 718 - frozen instance):

VmSize:    89738368 kB (87.6 GB virtual memory)
VmRSS:     15024756 kB (14.7 GB resident memory)
Threads:   20
Open files: 371
Runtime:   40 minutes (frozen at 04:05-04:45)
CPU:       46.6% (stuck in processing loop)

Memory State at Freeze:

Total RAM:  15Gi
Used:       15Gi (100%)
Available:  46Mi (0.3%)
Swap:       2.8Gi used of 4.0Gi

Root Cause Analysis

Evidence from ~/.claude.json (project config):

{
  "numStartups": 303,
  "lastTotalCacheReadInputTokens": 9656824,  // 9.6 MILLION tokens
  "lastTotalCacheCreationInputTokens": 367980,
  "lastTotalInputTokens": 187950,
  "lastCost": 4.7301332
}

Findings:

1. Unbounded cache growth:

• Claude reads 9.6M tokens from conversation cache
• ~35 MB raw text → 15GB in-memory after parsing/compilation
• No garbage collection implemented
• No cache size limits enforced

1. Memory leak pattern:

• Each session accumulates conversation history
• After 303 startups, cache grows to critical size
• Process never releases memory
• Leads to swap thrashing → I/O bottleneck → freeze

1. No recovery mechanism:

• Once frozen, process cannot self-recover
• Requires manual kill -9
• Other Claude windows also affected (shared memory?)

Reproduction Steps

1. Use Claude Code CLI extensively over weeks (300+ sessions)
2. Work on complex tasks with long conversations
3. Let conversation history accumulate (9M+ tokens cached)
4. Start new session → Memory usage spikes to 15GB
5. After 20-40 minutes → Complete freeze

Impact

User Impact:

• Work interruption every ~30 minutes
• Data loss if unsaved work in frozen window
• System becomes unresponsive (swap thrashing)
• Requires force kill, losing context

Frequency: 11 occurrences reported by user, likely more unreported

Attempted Workarounds

What DOESN'T work:

• MCP server optimization (reduced startup from 28s to 6s, but freeze persists)
• Direct SSH database access (bypassing MCP)
• Reducing number of MCP servers

What DOES work (temporarily):

• kill -9 <pid> (loses all context)
• Manual cache cleanup (not user-friendly)

Proposed Fixes

Immediate (Hot-fix)

1. Implement cache size limits:

const MAX_CACHE_TOKENS = 1_000_000; // 1M token limit
const MAX_HISTORY_LENGTH = 100; // Keep last 100 messages

1. Add garbage collection:

• Prune old conversation turns after threshold
• Release memory for messages older than N hours
• Implement LRU eviction for cached contexts

1. Add memory monitoring:

• Detect when process uses >8GB RAM
• Warn user before freeze
• Auto-cleanup if memory exceeds threshold

Long-term (Architecture)

1. Streaming cache architecture:

• Don't load entire conversation history into RAM
• Stream from disk on-demand
• Use memory-mapped files for large contexts

1. Conversation chunking:

• Split long conversations into chunks
• Load only relevant chunks for current context
• Implement smart context window management

1. User-visible controls:

claude config set max-cache-size 1000000
claude cache clear
claude cache status

Diagnostic Data

System Info:

# Memory at freeze
$ free -h
               total        used        free      shared  buff/cache   available
Mem:            15Gi        15Gi        46Mi       2.0Mi        76Mi        46Mi
Swap:          4.0Gi       2.8Gi       1.2Gi

# Process state
$ ps aux | grep claude
rickard  718 46.6 94.5 91180160 15370036 pts/0 Rl+ 04:05 19:09 claude

# Cache stats from config
lastTotalCacheReadInputTokens: 9,656,824
lastTotalCacheCreationInputTokens: 367,980

MCP Servers Running (not the cause):

• grokipedia (45MB RAM)
• n8n-mcp (43MB RAM)
• github (12MB RAM)
• postgres (removed, was causing ECONNREFUSED but not freeze)

Total MCP overhead: ~100MB RAM (negligible)

Files for Investigation

Config:

• ~/.claude.json (conversation cache metadata)
• ~/.cache/claude-cli-nodejs/-home-rickard/ (cache files)

Logs:

• ~/.cache/claude-cli-nodejs/-home-rickard/mcp-logs-*/

Example affected session:

• Session ID: 7d66760d-6f8e-45eb-a0e1-bc99532b3576
• Cost: $4.73
• Cache read: 9.6M tokens

Workaround for Users (until fixed)

Emergency recovery:

# Find frozen Claude processes
ps aux | grep claude | grep -v grep

# Kill frozen process
kill -9 <pid>

# Clear cache manually (nuclear option)
rm -rf ~/.cache/claude-cli-nodejs/*/mcp-logs-*/*.jsonl

Prevention:

# Restart Claude daily to prevent cache buildup
# (Not ideal, loses context)

---

Request to Claude Team

Priority: CRITICAL (P0)

Ask:

1. Implement hard limits on cache token count (1M tokens max)
2. Add memory-aware garbage collection
3. Provide user-facing cache management commands
4. Document expected memory usage for long-running sessions

Contact:

• Email: wilhelmsson424@gmail.com
• GitHub: wilhelmsson424-jpg/restaurangai_sync

Willing to provide:

• Anonymized cache dumps
• Memory profiling data
• Beta testing of fixes

---

Generated: 2026-01-28 04:45 UTC
Status: Awaiting Claude Engineering review