1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
//! # Query Cache for Episodic Memory Retrieval
//!
//! Provides LRU caching with TTL for query results to improve retrieval performance.
//! Target: 2-3x speedup for repeated queries with ≥40% cache hit rate.
//!
//! ## Supported Workloads
//!
//! This cache is optimized for **interactive/CLI workloads** with moderate query rates:
//! - **Ideal**: 1-100 queries per second
//! - **Use cases**: Agent development, testing, interactive memory queries
//! - **Episode completion rate**: <1 episode/minute for optimal cache effectiveness
//!
//! ### High-Throughput Workloads
//!
//! For streaming/batch workloads (>100 QPS) or high episode completion rates:
//! - Cache effectiveness may decrease due to frequent invalidation
//! - Use **domain-based invalidation** for multi-domain workloads (see below)
//! - Adjust TTL based on your episode completion frequency
//!
//! ## Design Decisions
//!
//! ### Domain-Based Invalidation
//!
//! The cache supports **selective invalidation by domain** (v0.1.11+):
//! - **`invalidate_domain(domain)`**: Clears only entries for the specified domain
//! - **`invalidate_all()`**: Clears all entries (use when domain is unknown)
//! - **Benefits**: Higher cache hit rates in multi-domain workloads
//! - **Performance**: O(k) where k is number of entries in domain
//!
//! #### When to Use Domain-Based Invalidation
//!
//! - ✅ **Use `invalidate_domain()`**: Multi-domain agents, isolated domains
//! - ✅ **Use `invalidate_all()`**: Single domain, cross-domain changes, or uncertain scope
//!
//! #### Performance Comparison
//!
//! | Scenario | `invalidate_all()` | `invalidate_domain()` | Improvement |
//! |----------|-------------------|----------------------|-------------|
//! | 3 domains, invalidate 1 | 100% entries cleared | 33% entries cleared | +15-20% hit rate |
//! | Single domain | 100% entries cleared | 100% entries cleared | No difference |
//! | High-throughput multi-domain | <30% hit rate | 35-40% hit rate | +10-15% hit rate |
//!
//! ### Thread Safety
//!
//! Uses `Arc<RwLock<>>` for thread-safe concurrent access:
//! - Multiple readers can access cache simultaneously
//! - Writers block all readers (but operations are fast)
//! - Lock poisoning is unlikely but handled with descriptive error messages
//!
//! ## Performance Characteristics
//!
//! - **Cache hit latency**: ~1-5µs
//! - **Cache miss overhead**: ~2µs (hash computation)
//! - **Domain invalidation**: <100µs for domains with <1000 entries
//! - **Memory overhead**: ~10KB per cached query + O(d × k) for domain index
//! - **Maximum memory**: ~100MB (10,000 entries × 10KB)
//!
//! ## Example Usage
//!
//! ### Basic Usage
//!
//! ```
//! use do_memory_core::retrieval::{QueryCache, CacheKey};
//!
//! let cache = QueryCache::new();
//!
//! // Create cache key
//! let key = CacheKey::new("implement authentication".to_string())
//! .with_domain(Some("web-api".to_string()))
//! .with_limit(5);
//!
//! // Check cache (miss initially)
//! assert!(cache.get(&key).is_none());
//!
//! // Populate cache
//! # let episodes = vec![];
//! cache.put(key.clone(), episodes);
//!
//! // Check cache again (hit)
//! if let Some(episodes) = cache.get(&key) {
//! println!("Cache hit! Found {} episodes", episodes.len());
//! }
//!
//! // Monitor performance
//! let metrics = cache.metrics();
//! println!("Hit rate: {:.1}%", metrics.hit_rate() * 100.0);
//! // After 1 miss and 1 hit, hit rate is 50%
//! assert!(metrics.hit_rate() >= 0.4);
//! ```
//!
//! ### Domain-Based Invalidation (Multi-Domain Workloads)
//!
//! ```
//! use do_memory_core::retrieval::{QueryCache, CacheKey};
//!
//! let cache = QueryCache::new();
//!
//! // Cache queries from different domains
//! # let episodes = vec![];
//! let web_key = CacheKey::new("query".to_string())
//! .with_domain(Some("web-api".to_string()));
//! let data_key = CacheKey::new("query".to_string())
//! .with_domain(Some("data-processing".to_string()));
//!
//! cache.put(web_key.clone(), episodes.clone());
//! cache.put(data_key.clone(), episodes.clone());
//!
//! // When an episode completes in web-api domain, invalidate only that domain
//! cache.invalidate_domain("web-api");
//!
//! // web-api queries are cleared, but data-processing queries remain cached
//! assert!(cache.get(&web_key).is_none());
//! assert!(cache.get(&data_key).is_some());
//!
//! // For cross-domain changes, use invalidate_all()
//! cache.invalidate_all();
//! assert!(cache.get(&data_key).is_none());
//! ```
// Re-export public API
pub use QueryCache;
pub use ;