Module expiration 

TTL-based expiration garbage collector implementation.

Identifies and tombstones memories that have exceeded their TTL (expires_at timestamp).

Unlike retention-based GC which calculates expiration from created_at + retention_days, expiration GC uses the explicit expires_at field set at capture time.

Configuration

TTL can be set at capture time via:

• CLI: subcog capture --ttl 7d "content"
• MCP: { "ttl": "30d" } in capture arguments
• Config file: [memory.ttl] section with per-namespace defaults

Example

use subcog::gc::{ExpirationConfig, ExpirationService};
use subcog::storage::index::SqliteBackend;
use std::sync::Arc;

// Create expiration service with index backend
let backend = Arc::new(SqliteBackend::new("memories.db")?);
let config = ExpirationConfig::default();
let service = ExpirationService::new(backend, config);

// Dry run to see what would be cleaned up
let result = service.gc_expired_memories(true)?;
println!("Would tombstone {} expired memories", result.memories_tombstoned);

// Actually perform the cleanup
let result = service.gc_expired_memories(false)?;
println!("Tombstoned {} memories", result.memories_tombstoned);

Probabilistic Cleanup

To avoid expensive full scans on every operation, the expiration service can be triggered probabilistically during capture operations:

use subcog::gc::ExpirationService;

// 5% chance to trigger cleanup after a capture
if service.should_run_cleanup() {
    let _ = service.gc_expired_memories(false);
}

Structs

ExpirationConfig

Configuration for expiration-based garbage collection.

ExpirationGcResult

Result of an expiration garbage collection operation.

ExpirationService

Service for garbage collecting memories that have exceeded their TTL.

Constants

DEFAULT_CLEANUP_PROBABILITY

Default probability of running cleanup after a capture (5%).

EXPIRATION_CLEANUP_PROBABILITY_ENV

Environment variable for cleanup probability (0.0 to 1.0).

Functions

duration_to_millis 🔒

Safely converts Duration to milliseconds as u64, capping at u64::MAX.

rand_float 🔒

Generates a random float between 0.0 and 1.0.

u64_to_f64 🔒

Converts u64 to f64 for metrics, capping at u32::MAX.

usize_to_f64 🔒

Converts usize to f64 for metrics, capping at u32::MAX.