Session Pruning

+15 Mana ✨
OpenClaw Session Pruning Guide(DOCUMENTATION)OpenClaw Storage Management(DOCUMENTATION)

Introduction

Over time, OpenClaw accumulates session transcripts from every conversation. These JSONL files provide a complete audit trail but consume disk space. Session pruning is the process of cleaning up old sessions to manage storage while preserving important history. Understanding pruning strategies helps you balance storage costs with historical access needs.

Key Concepts

  • Session Transcript: A JSONL file containing every message, tool call, and result from a conversation session
  • Transcript Accumulation: The natural growth of stored sessions over days, weeks, and months of agent usage
  • Pruning Strategy: The rules that determine which sessions to keep and which to delete based on age, size, or importance
  • Archival: Moving old sessions to cheaper storage (object storage like S3) before deletion from local disk
  • Retention Policy: A configured rule specifying how long sessions are kept before becoming pruning candidates

Real World Context

After six months of daily use, a developer's OpenClaw session directory contains over 1,000 JSONL transcripts totaling 2 GB of disk space. Most are routine coding sessions with no long-term value. A few contain important architectural discussions and debugging sessions worth keeping. A pruning strategy lets them clean up the routine sessions while archiving the valuable ones.

Deep Dive

Session transcripts accumulate in the sessions directory:

bash
ls ~/.openclaw/sessions/

This command lists all session directories, each containing a transcript.jsonl file and associated metadata.

The transcript format uses JSONL (JSON Lines), where each line is a self-contained JSON object:

json
{"type": "user_message", "content": "Help me refactor the auth module", "timestamp": "2026-02-15T10:30:00Z"}
{"type": "assistant_message", "content": "I will analyze the current auth module...", "timestamp": "2026-02-15T10:30:05Z"}
{"type": "tool_call", "tool": "file_read", "args": {"path": "src/auth/index.ts"}, "timestamp": "2026-02-15T10:30:06Z"}
{"type": "tool_result", "content": "(file contents)", "timestamp": "2026-02-15T10:30:07Z"}

Each line represents one event in the conversation. The JSONL format makes it easy to process transcripts with standard command-line tools and scripts.

Pruning Commands

OpenClaw provides built-in pruning commands:

bash
# List sessions with age and size
openclaw sessions list --sort-by age

# Prune sessions older than 30 days
openclaw sessions prune --older-than 30d

# Prune sessions larger than 10MB
openclaw sessions prune --larger-than 10MB

# Dry run to see what would be pruned
openclaw sessions prune --older-than 30d --dry-run

The --dry-run flag is especially important. It shows which sessions would be deleted without actually deleting them, letting you verify the pruning criteria before committing.

Archival to Object Storage

Before pruning, you can archive sessions to cheaper storage:

bash
# Archive old sessions to S3
openclaw sessions archive --older-than 60d --destination s3://my-bucket/openclaw-sessions/

# Archive and then prune the local copies
openclaw sessions archive --older-than 60d --destination s3://my-bucket/openclaw-sessions/ --prune-after

The archive command compresses and uploads session transcripts to the specified object storage destination. With --prune-after, it automatically deletes the local copies after successful upload.

Retention Policies

For automated management, configure a retention policy:

json
{
  "sessions": {
    "retention": {
      "maxAge": "90d",
      "maxSize": "5GB",
      "archiveDestination": "s3://my-bucket/openclaw-sessions/",
      "archiveBeforePrune": true
    }
  }
}

This configuration automatically archives and prunes sessions older than 90 days, and also prunes when total session storage exceeds 5 GB. The archiveBeforePrune: true flag ensures sessions are safely stored in S3 before being deleted locally.

Common Pitfalls

  • Never pruning sessions: Transcript accumulation is slow but relentless. After a year, you could have tens of gigabytes of session data consuming local disk.
  • Pruning without archiving: Deleting sessions permanently loses the audit trail. Archive important sessions before pruning.
  • Setting retention too aggressively: A 7-day retention policy deletes sessions you might need for debugging last week's issue. The 30-90 day range works for most teams.

Best Practices

  • Always use dry-run first: Before any prune operation, run with --dry-run to verify what will be deleted.
  • Configure a retention policy: Automated management prevents the disk space problem from ever arising.
  • Archive to object storage: S3 or equivalent storage is cheap and durable. Archive important sessions before pruning local copies.

Summary

  • Session transcripts are stored as JSONL files containing every message, tool call, and result from conversations
  • Transcripts accumulate over time and require periodic pruning to manage disk space
  • Use openclaw sessions prune with age or size criteria, always with --dry-run first
  • Archive important sessions to object storage before pruning local copies
  • Configure automated retention policies to prevent manual management burden
✓ Completed