Module gc 

Garbage collection module.

This module provides garbage collection utilities for cleaning up stale memories, particularly those associated with deleted git branches, memories that have exceeded their retention period, or memories that have exceeded their explicit TTL (expires_at timestamp).

Overview

The garbage collector identifies memories associated with branches that no longer exist in the git repository and marks them as tombstoned. It also enforces retention policies to clean up old memories.

Example

use subcog::gc::BranchGarbageCollector;
use subcog::storage::index::SqliteBackend;
use std::sync::Arc;

let backend = Arc::new(SqliteBackend::new("memories.db")?);
let gc = BranchGarbageCollector::new(backend);

// Dry run to see what would be cleaned up
let result = gc.gc_stale_branches("github.com/org/repo", true)?;
println!("Would tombstone {} memories from {} stale branches",
         result.memories_tombstoned, result.stale_branches.len());

// Actually perform the cleanup
let result = gc.gc_stale_branches("github.com/org/repo", false)?;
println!("Tombstoned {} memories", result.memories_tombstoned);

Retention Policy

Memories can be automatically cleaned up based on age using the retention garbage collector:

use subcog::gc::{RetentionConfig, RetentionGarbageCollector};

// Load retention config from environment (default: 365 days)
let config = RetentionConfig::from_env();

// Create retention GC with index backend
let gc = RetentionGarbageCollector::new(backend, config);

// Clean up expired memories
let result = gc.gc_expired_memories(false)?;
println!("Tombstoned {} expired memories", result.memories_tombstoned);

Lazy GC

The garbage collector can be integrated into the recall path for lazy, opportunistic cleanup. When memories are retrieved, the system can check if any are from stale branches and mark them accordingly.

Modules

branch 🔒

Branch garbage collector implementation.

expiration 🔒

TTL-based expiration garbage collector implementation.

retention 🔒

Retention policy garbage collector implementation.

Structs

BranchGarbageCollector

Garbage collector for branch-scoped memories.

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.

GcResult

Result of a garbage collection operation.

RetentionConfig

Retention policy configuration.

RetentionGarbageCollector

Garbage collector for expired memories based on retention policy.

RetentionGcResult

Result of a retention garbage collection operation.

Constants

DEFAULT_CLEANUP_PROBABILITY

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

DEFAULT_RETENTION_DAYS

Default retention period in days (1 year).

EXPIRATION_CLEANUP_PROBABILITY_ENV

Environment variable for cleanup probability (0.0 to 1.0).

RETENTION_DAYS_ENV

Environment variable for default retention period in days.

Functions

branch_exists

Performs a quick check if the current branch exists.

retention_days

Returns the configured retention period in days.