subcog/gc/
mod.rs

1//! Garbage collection module.
2//!
3//! This module provides garbage collection utilities for cleaning up stale
4//! memories, particularly those associated with deleted git branches,
5//! memories that have exceeded their retention period, or memories that
6//! have exceeded their explicit TTL (`expires_at` timestamp).
7//!
8//! # Overview
9//!
10//! The garbage collector identifies memories associated with branches that
11//! no longer exist in the git repository and marks them as tombstoned.
12//! It also enforces retention policies to clean up old memories.
13//!
14//! # Example
15//!
16//! ```rust,ignore
17//! use subcog::gc::BranchGarbageCollector;
18//! use subcog::storage::index::SqliteBackend;
19//! use std::sync::Arc;
20//!
21//! let backend = Arc::new(SqliteBackend::new("memories.db")?);
22//! let gc = BranchGarbageCollector::new(backend);
23//!
24//! // Dry run to see what would be cleaned up
25//! let result = gc.gc_stale_branches("github.com/org/repo", true)?;
26//! println!("Would tombstone {} memories from {} stale branches",
27//!          result.memories_tombstoned, result.stale_branches.len());
28//!
29//! // Actually perform the cleanup
30//! let result = gc.gc_stale_branches("github.com/org/repo", false)?;
31//! println!("Tombstoned {} memories", result.memories_tombstoned);
32//! ```
33//!
34//! # Retention Policy
35//!
36//! Memories can be automatically cleaned up based on age using the retention
37//! garbage collector:
38//!
39//! ```rust,ignore
40//! use subcog::gc::{RetentionConfig, RetentionGarbageCollector};
41//!
42//! // Load retention config from environment (default: 365 days)
43//! let config = RetentionConfig::from_env();
44//!
45//! // Create retention GC with index backend
46//! let gc = RetentionGarbageCollector::new(backend, config);
47//!
48//! // Clean up expired memories
49//! let result = gc.gc_expired_memories(false)?;
50//! println!("Tombstoned {} expired memories", result.memories_tombstoned);
51//! ```
52//!
53//! # Lazy GC
54//!
55//! The garbage collector can be integrated into the recall path for lazy,
56//! opportunistic cleanup. When memories are retrieved, the system can check
57//! if any are from stale branches and mark them accordingly.
58
59mod branch;
60mod expiration;
61mod retention;
62
63pub use branch::{BranchGarbageCollector, GcResult, branch_exists};
64pub use expiration::{
65    DEFAULT_CLEANUP_PROBABILITY, EXPIRATION_CLEANUP_PROBABILITY_ENV, ExpirationConfig,
66    ExpirationGcResult, ExpirationService,
67};
68pub use retention::{
69    DEFAULT_RETENTION_DAYS, RETENTION_DAYS_ENV, RetentionConfig, RetentionGarbageCollector,
70    RetentionGcResult, retention_days,
71};