🕐 feat: Configurable Retention Period for Temporary Chats

[danny-avila]

Originally #7917

Summary

This PR implements configurable retention periods for temporary chats, replacing the hardcoded 30-day limit with flexible configuration options via environment variables or librechat.yaml. Users can now set retention periods from 1 day to 1 year based on their needs.

Closes #7673

Change Type

• New feature (non-breaking change which adds functionality)

Changes Made

Core Implementation

• New utility: api/server/utils/tempChatRetention.js
  • getTempChatRetentionDays(): Retrieves configured retention period with validation
  • createTempChatExpirationDate(): Creates expiration dates using configured period
  • Built-in validation (min: 1 day, max: 365 days) with fallback to defaults
• Updated models: api/models/Message.js and api/models/Conversation.js now use configurable retention
• Schema updates: Added temporaryChatRetentionDays to interface schema in packages/data-provider/src/config.ts
• Configuration integration: Updated AppService.js to make config available to models

Configuration Options

1. Environment Variable: TEMP_CHAT_RETENTION_DAYS=7
2. LibreChat.yaml: interface.temporaryChatRetentionDays: 14
3. Default: 30 days (maintains backward compatibility)

Validation & Safety

• Minimum: 1 day (prevents immediate deletion)
• Maximum: 365 days (prevents indefinite retention)
• Priority: Config file > Environment variable > Default
• Error handling: Invalid values fall back to defaults with warnings

Testing

Automated Testing

• Test suite: api/server/utils/__tests__/tempChatRetention.test.js
• Coverage: 12 test cases covering all scenarios
• Edge cases: Invalid values, boundary conditions, precedence rules
• Results: ✅ All tests passing

Manual Testing & Verification

Test 1: Default Behavior (30 days)

# Configuration: No custom settings
# Expected: 30-day retention

Database Verification:

// Conversation ID: 91e6a871-de82-4240-836e-7f83ea1ad4cc
Created: 2025-06-15T14:59:42.764Z
Expires: 2025-07-15T14:59:45.705Z
Retention: 30.00 days ✅

Results:

• ✅ Conversation and messages both expire in exactly 30 days
• ✅ Default behavior maintained for backward compatibility

Test 2: Custom 1-Day Retention

# Configuration: librechat.yaml
interface:
  temporaryChatRetentionDays: 1

Database Verification:

// Conversation ID: 4b5629af-fdc2-4a4c-83c2-4619f7e60ac7
Created: 2025-06-15T15:01:28.710Z
Expires: 2025-06-16T15:01:31.451Z
Retention: 1.00 days ✅

Results:

• ✅ Configuration change immediately applied to new conversations
• ✅ Precise 24-hour retention period
• ✅ Both conversation and messages have consistent expiration dates
• ✅ MongoDB TTL index will auto-delete expired records

Test 3: Configuration Priority

# Environment: TEMP_CHAT_RETENTION_DAYS=15
# Config file: temporaryChatRetentionDays: 1
# Expected: Config file wins (1 day)

Results:

• ✅ Config file setting (1 day) took precedence over environment variable
• ✅ Priority system working correctly

Database Schema Verification

// Conversation Document
{
  conversationId: "4b5629af-fdc2-4a4c-83c2-4619f7e60ac7",
  expiredAt: ISODate('2025-06-16T15:01:31.451Z'), // ✅ 1-day retention
  createdAt: ISODate('2025-06-15T15:01:28.710Z'),
  // ... other fields
}

// Message Documents
{
  messageId: "783e67d9-a6d4-403d-a91f-03eb6b7ad090",
  expiredAt: ISODate('2025-06-16T15:01:30.795Z'), // ✅ 1-day retention
  text: "Testing temp chat",
  // ... other fields
}

Documentation

• Updated: librechat.example.yaml with configuration example and comments
• Added: Comprehensive JSDoc comments in utility functions
• Included: Validation ranges and error handling documentation

Backward Compatibility

• ✅ Fully backward compatible: Existing installations continue working unchanged
• ✅ Default behavior preserved: 30-day retention when no configuration is provided
• ✅ No breaking changes: All existing temporary chats maintain their expiration dates

Performance Impact

• ✅ Minimal overhead: Configuration loaded once at startup
• ✅ Efficient validation: Simple numeric range checks
• ✅ Database optimized: Uses existing MongoDB TTL indexes for cleanup

Security Considerations

• ✅ Input validation: Prevents invalid retention periods
• ✅ Bounds enforcement: Prevents both immediate deletion and indefinite retention
• ✅ Error handling: Graceful fallback to safe defaults

[KiGamji]

@danny-avila @ConstantTime so does this use hours or days? According to the PR description, it uses days, but in the dev branch, after the merge, you can see that it is in hours:

[ConstantTime]

@danny-avila @ConstantTime so does this use hours or days? According to the PR description, it uses days, but in the dev branch, after the merge, you can see that it is in hours:

My bad, should have updated PR desc also. It's in hours only.