Custom Retention Standard

Standard retention configuration preset that balances privacy requirements with practical session history needs for typical development workflows.

When to Use This Setting

Apply this setting when you need to:

• Implement a balanced retention policy that preserves recent context without accumulating excessive history
• Comply with standard data governance policies requiring defined retention windows for tool-generated data
• Establish a baseline retention configuration that individual teams can adjust based on their specific needs

Consider alternatives when:

• Your compliance requirements mandate specific retention periods (use a custom retention value)
• You need indefinite retention for audit trails or long-term project documentation

Quick Start

Configuration

Copy
name: custom-retention-standard
type: setting
category: cleanup

Example Application

Copy
claude setting:apply custom-retention-standard

Example Output

Setting applied successfully. Configuration changes:
- cleanupPeriodDays: 30
- Transcript retention: 30 days (standard)
- Auto-cleanup: enabled
- Archive: optional export before cleanup

Core Concepts

Standard Retention Overview

Aspect	Details
Default Window	30 calendar days
Cleanup Mode	Automatic with optional archiving
Scope	Chat transcripts, session logs, temp files
Compliance	Meets most standard data governance policies
Flexibility	Adjustable per-project or per-team

Retention Lifecycle Architecture

┌─────────────────────────────────────┐
│        Retention Lifecycle          │
│                                     │
│  Active     Archive     Delete      │
│  (0-30d)    (optional)  (>30d)      │
│                                     │
│  ┌────┐    ┌────────┐   ┌───────┐   │
│  │Live│───>│Archive │──>│Purge  │   │
│  │Use │    │(export)│   │(perm) │   │
│  └────┘    └────────┘   └───────┘   │
│                                     │
│  configurable at each stage         │
└─────────────────────────────────────┘

Configuration

Parameter	Type	Default	Description
cleanupPeriodDays	number	30	Standard retention window in days
archiveBeforeDelete	boolean	false	Export sessions before cleanup removes them
archivePath	string	~/.claude/archive	Directory for archived session exports
cleanupSchedule	string	"startup"	When cleanup runs: startup, daily, or weekly
retainStarred	boolean	true	Keep sessions explicitly starred by user

Best Practices

1. Start with 30 Days and Adjust - The 30-day standard window covers most sprint cycles and provides enough historical context for ongoing work. Monitor whether developers frequently need older sessions and adjust the window accordingly.

2. Enable Archive for Compliance - Turn on archiveBeforeDelete if your organization may need to retrieve old sessions for compliance reviews. Archives consume less space than active sessions and can be stored on cheaper storage tiers.

3. Use Starred Session Protection - Encourage developers to star important sessions that contain critical decisions or architectural discussions. Starred sessions survive cleanup regardless of age, providing a manual override for the automatic retention policy.

4. Align with Sprint Cadence - Set the retention window to be at least twice your sprint length. A two-week sprint should have at least a 30-day retention to ensure context from the previous sprint is still available during retrospectives.

5. Review Archive Size Quarterly - If archiving is enabled, the archive directory grows continuously. Schedule quarterly reviews to purge archives older than your compliance retention requirement and prevent storage bloat.

Common Issues

1. Archive directory consuming excessive disk space - Archives accumulate faster than expected with active usage. Set up a secondary cleanup for archives older than 90 days, or move archives to cloud storage periodically.

2. Starred sessions preventing cleanup - Over time, developers star many sessions and the cleanup becomes ineffective. Periodically review starred sessions and unstar those that are no longer relevant.

3. Inconsistent retention across team members - Without organization-level enforcement, individual developers may override the standard retention. Apply the setting at the organization config level to establish a baseline that cannot be shortened.