Problem

Images received from Discord (and potentially other channels) are being stored as base64-encoded data directly in session transcripts. This causes:

1. Context overflow — Each image can be 50-150KB of base64, leading to sessions hitting the 200K token limit after ~7 images
2. Transcript bloat — Session JSONL files grow to several MB
3. Double storage — Images are saved to ~/.clawdbot/media/inbound/ AND embedded in transcripts

Current Workaround

Phase 1 fix implemented: limitHistoryImages() strips older images from context at runtime, keeping only the last N images (default: 3) within a size limit (default: 500KB).

Proposed Solution

Store image references in transcripts instead of base64 data:

{
  "type": "image",
  "mimeType": "image/jpeg",
  "mediaRef": "abc123.jpg",
  "mediaPath": "/path/to/.clawdbot/media/inbound/abc123.jpg",
  "sizeBytes": 102400
}

Then hydrate from disk when building API context.

Related

• Depends on media rotation for cleanup (separate issue)