mnemo_engine/store/cache_api.rs
1//! The Phase 10 result cache API: exact-key and semantic put/get, purge, budgets, flush policy and eviction.
2
3use super::*;
4
5impl Mnemo {
6 /// Insert or overwrite a cache entry at `(namespace, key)`.
7 ///
8 /// The engine SHA-256-hashes `key` — callers pass the raw input
9 /// string. Persists to disk on the next `flush()` under the current
10 /// flush policy (see [`Mnemo::set_cache_flush_policy`]); in
11 /// [`CacheFlushPolicy::Batched`] the engine may call `flush()`
12 /// internally when a threshold trips.
13 ///
14 /// On overflow of the namespace's [`CacheBudget`] (default 10,000
15 /// entries / 64 MiB) the LRU entry is tombstoned before the new
16 /// insert. Tombstones are reclaimed by
17 /// [`Mnemo::compact_file`], not the runtime flush.
18 ///
19 /// Returns [`MnemoError::ReadOnly`] on a read-only handle.
20 pub fn cache_put(
21 &mut self,
22 namespace: &str,
23 key: &str,
24 value: &[u8],
25 opts: CachePutOpts,
26 ) -> Result<()> {
27 if self.read_only {
28 return Err(MnemoError::ReadOnly);
29 }
30 let key_hash = result_cache::hash_key(key);
31 let key_preview = result_cache::key_preview(key);
32 let now = memory::now_secs();
33 let size_bytes = value.len() as u64;
34
35 let entry = CacheEntry {
36 namespace: namespace.to_string(),
37 key_hash,
38 key_preview: key_preview.clone(),
39 value: value.to_vec(),
40 content_type: opts.content_type.clone(),
41 created_at: now,
42 accessed_at: now,
43 access_count: 0,
44 ttl_secs: opts.ttl_secs,
45 cost_hint_ms: opts.cost_hint_ms,
46 size_bytes,
47 vector: None,
48 model: None,
49 };
50 let bytes = rmp_serde::to_vec(&entry).map_err(|e| MnemoError::Serialize(e.to_string()))?;
51 let (start_page, page_count, gen) = self.write_record(&bytes)?;
52
53 // Tombstone any prior entry for this key. Its pages remain on
54 // disk until `compact_file`, exactly like memory-record
55 // overwrites — the tombstone just hides it from lookups.
56 if let Some(prev_pos) = self.cache_idx.get(namespace, &key_hash) {
57 self.cache_dir[prev_pos].deleted = true;
58 self.release_cache_pages(prev_pos);
59 self.cache_idx.remove(namespace, &key_hash);
60 }
61
62 let dir_entry = CacheDirectoryEntry {
63 namespace: namespace.to_string(),
64 key_hash,
65 start_page,
66 page_count,
67 len: bytes.len() as u32,
68 deleted: false,
69 accessed_at: now,
70 access_count: 0,
71 size_bytes,
72 ttl_secs: opts.ttl_secs,
73 created_at: now,
74 vector: None,
75 model: None,
76 gen,
77 };
78 let pos = self.cache_dir.len();
79 self.cache_dir.push(dir_entry);
80 self.cache_idx.insert(namespace, key_hash, pos);
81
82 // Enforce budget — evict LRU tombstones until the namespace
83 // fits under both caps.
84 self.evict_to_budget(namespace)?;
85
86 self.dirty_cache = true;
87 self.cache_batch.record_dirty();
88
89 // Batched policy: auto-flush if a threshold tripped. Successful
90 // `flush()` calls `cache_batch.reset()` for us.
91 if self.cache_batch.should_auto_flush(&self.cache_flush_policy) {
92 self.flush()?;
93 }
94 Ok(())
95 }
96
97 /// Look up `(namespace, key)`. Returns `None` on miss (either the
98 /// key was never inserted or the entry is TTL-expired). On hit
99 /// updates catalog-side access stats (mirrors the recall v5-trick);
100 /// on a read-only handle the stats update is silently skipped.
101 ///
102 /// A miss is recorded as a miss in this handle's counters even if
103 /// the key was TTL-expired — from the caller's perspective the two
104 /// are indistinguishable.
105 pub fn cache_get(&mut self, namespace: &str, key: &str) -> Result<Option<CachedValue>> {
106 // FIX-1 R-001.8 part 4: under `Batched`, honor `max_age` on
107 // reads too. Pre-FIX-1 the age check only fired on `cache_put`,
108 // so a workload that wrote a few entries and then switched to
109 // pure reads could sit with its pending batch past the
110 // nominal max_age indefinitely. `max_dirty` is already
111 // maintained per-write; this adds the symmetric time-bound
112 // check on the read path. Only runs on read-write handles —
113 // flush() returns ReadOnly for shared-lock readers.
114 if !self.read_only && self.cache_batch.should_auto_flush(&self.cache_flush_policy) {
115 self.flush()?;
116 }
117 let key_hash = result_cache::hash_key(key);
118 let pos = match self.cache_idx.get(namespace, &key_hash) {
119 Some(p) => p,
120 None => {
121 self.cache_counters.misses += 1;
122 return Ok(None);
123 }
124 };
125 let now = memory::now_secs();
126 // Snapshot the directory entry fields we need before any
127 // mutation — the borrow checker gets grumpy otherwise.
128 let (start_page, page_count, len, ttl_secs, expired, created_at, gen) = {
129 let e = &self.cache_dir[pos];
130 (
131 e.start_page,
132 e.page_count,
133 e.len,
134 e.ttl_secs,
135 e.is_expired(now),
136 e.created_at,
137 e.gen,
138 )
139 };
140 if expired {
141 // Treat expired as a miss for the caller. Don't tombstone
142 // here — cache_purge does that. Just skip.
143 self.cache_counters.misses += 1;
144 return Ok(None);
145 }
146 // Decrypt and decode the record body.
147 let buf = self.read_record_run(start_page, page_count, len, gen)?;
148 let entry: CacheEntry =
149 rmp_serde::from_slice(&buf).map_err(|e| MnemoError::Serialize(e.to_string()))?;
150
151 // Bump access stats catalog-only (v5 trick — no full record
152 // rewrite on a hit). Skipped on read-only handles so a shared-lock
153 // reader can't dirty the catalog.
154 if !self.read_only {
155 self.cache_dir[pos].accessed_at = now;
156 self.cache_dir[pos].access_count = self.cache_dir[pos].access_count.saturating_add(1);
157 self.dirty_cache = true;
158 }
159 self.cache_counters.hits += 1;
160 // On a mutating handle: access_count reflects the just-bumped
161 // value. On a read-only handle: the on-disk directory value is
162 // unchanged, so returning it verbatim is honest (the caller's
163 // reads did not, and cannot, alter the persisted counter).
164 //
165 // FIX-1 R-002.2 part 1: `accessed_at` must also come from the
166 // directory on a read-only handle, not from `entry.accessed_at`
167 // in the record body. The record body is written once at insert
168 // time and never updated on a hit — every live `accessed_at`
169 // update lands in the directory (see the `!self.read_only`
170 // branch above). The pre-FIX-1 code returned
171 // `entry.accessed_at`, which is really the entry's **creation
172 // time** by then, so a read-only reader saw "last accessed =
173 // when it was inserted" even after many successful hits by
174 // concurrent writers.
175 let access_count = self.cache_dir[pos].access_count;
176 let accessed_at = if self.read_only {
177 self.cache_dir[pos].accessed_at
178 } else {
179 now
180 };
181 Ok(Some(CachedValue {
182 value: entry.value,
183 content_type: entry.content_type,
184 created_at,
185 accessed_at,
186 access_count,
187 ttl_secs,
188 }))
189 }
190
191 /// Tombstone the entry at `(namespace, key)`. Silently succeeds if
192 /// no such entry exists. Space is reclaimed by `compact_file`.
193 pub fn cache_delete(&mut self, namespace: &str, key: &str) -> Result<()> {
194 if self.read_only {
195 return Err(MnemoError::ReadOnly);
196 }
197 let key_hash = result_cache::hash_key(key);
198 if let Some(pos) = self.cache_idx.get(namespace, &key_hash) {
199 self.cache_dir[pos].deleted = true;
200 self.release_cache_pages(pos);
201 self.cache_idx.remove(namespace, &key_hash);
202 self.dirty_cache = true;
203 self.cache_batch.record_dirty();
204 if self.cache_batch.should_auto_flush(&self.cache_flush_policy) {
205 self.flush()?;
206 }
207 }
208 Ok(())
209 }
210
211 /// Purge cache entries. If `namespace` is `Some`, restrict to that
212 /// namespace; otherwise purge across the whole cache. If
213 /// `expired_only` is `true`, only TTL-expired entries are removed;
214 /// otherwise every live entry in the target scope is tombstoned.
215 /// Returns the number of entries newly tombstoned.
216 pub fn cache_purge(&mut self, namespace: Option<&str>, expired_only: bool) -> Result<usize> {
217 if self.read_only {
218 return Err(MnemoError::ReadOnly);
219 }
220 let now = memory::now_secs();
221 let mut purged = 0usize;
222 // Iterate the directory by index; mark matching entries as
223 // deleted and pull them out of the in-memory index.
224 for pos in 0..self.cache_dir.len() {
225 if self.cache_dir[pos].deleted {
226 continue;
227 }
228 if let Some(ns) = namespace {
229 if self.cache_dir[pos].namespace != ns {
230 continue;
231 }
232 }
233 if expired_only && !self.cache_dir[pos].is_expired(now) {
234 continue;
235 }
236 let key_hash = self.cache_dir[pos].key_hash;
237 let ns = self.cache_dir[pos].namespace.clone();
238 self.cache_dir[pos].deleted = true;
239 self.release_cache_pages(pos);
240 self.cache_idx.remove(&ns, &key_hash);
241 purged += 1;
242 }
243 if purged > 0 {
244 self.dirty_cache = true;
245 self.cache_batch.record_dirty();
246 if self.cache_batch.should_auto_flush(&self.cache_flush_policy) {
247 self.flush()?;
248 }
249 }
250 Ok(purged)
251 }
252
253 /// Statistics for `namespace` (or the whole cache if `None`).
254 /// `hits`/`misses`/`evictions` are per-handle in-memory counters
255 /// that reset on reopen; `entries`/`bytes` reflect the durable
256 /// on-disk state (live entries only, tombstones excluded).
257 pub fn cache_stats(&self, namespace: Option<&str>) -> CacheStats {
258 let mut entries = 0usize;
259 let mut bytes = 0u64;
260 for e in &self.cache_dir {
261 if e.deleted {
262 continue;
263 }
264 if let Some(ns) = namespace {
265 if e.namespace != ns {
266 continue;
267 }
268 }
269 entries += 1;
270 bytes += e.size_bytes;
271 }
272 let hits = self.cache_counters.hits;
273 let misses = self.cache_counters.misses;
274 let total = hits + misses;
275 let hit_rate = if total > 0 {
276 hits as f64 / total as f64
277 } else {
278 0.0
279 };
280 CacheStats {
281 entries,
282 bytes,
283 hits,
284 misses,
285 hit_rate,
286 evictions: self.cache_counters.evictions,
287 }
288 }
289
290 /// Set (or update) the eviction budget for `namespace`. Applies to
291 /// subsequent `cache_put` calls; does not retroactively evict
292 /// entries that already sit under a looser cap.
293 pub fn set_cache_budget(&mut self, namespace: &str, budget: CacheBudget) {
294 self.cache_budgets.insert(namespace.to_string(), budget);
295 }
296
297 /// Set the per-handle cache flush policy. Defaults to
298 /// [`CacheFlushPolicy::Strict`]. Memory writes are never batched;
299 /// this affects only cache mutations.
300 pub fn set_cache_flush_policy(&mut self, policy: CacheFlushPolicy) {
301 self.cache_flush_policy = policy;
302 // Switching mid-run: if we're moving to Strict and the batch is
303 // non-empty, the pending count still counts toward dirty_cache
304 // which the next flush() will consume.
305 }
306
307 /// FMT-9 (a): free a just-tombstoned cache entry's record pages at the
308 /// next commit (v9; no-op on v8).
309 pub(super) fn release_cache_pages(&mut self, pos: usize) {
310 let (p, c) = (
311 self.cache_dir[pos].start_page,
312 self.cache_dir[pos].page_count as u64,
313 );
314 self.release_pages(p, c);
315 }
316
317 /// Evict LRU live entries in `namespace` until it fits under both
318 /// budget caps. Called from `cache_put` after the insert; the new
319 /// entry is included in the count so we always leave room.
320 pub(super) fn evict_to_budget(&mut self, namespace: &str) -> Result<()> {
321 let budget = self
322 .cache_budgets
323 .get(namespace)
324 .copied()
325 .unwrap_or_default();
326 loop {
327 // Sum current live count + bytes in the namespace.
328 let mut live_count = 0usize;
329 let mut live_bytes = 0u64;
330 for e in &self.cache_dir {
331 if !e.deleted && e.namespace == namespace {
332 live_count += 1;
333 live_bytes += e.size_bytes;
334 }
335 }
336 if live_count <= budget.max_entries && live_bytes <= budget.max_bytes {
337 return Ok(());
338 }
339 // Find the LRU (oldest accessed_at) live entry.
340 let victim_pos = self
341 .cache_dir
342 .iter()
343 .enumerate()
344 .filter(|(_, e)| !e.deleted && e.namespace == namespace)
345 .min_by_key(|(_, e)| e.accessed_at)
346 .map(|(i, _)| i);
347 let Some(pos) = victim_pos else {
348 // Nothing to evict but still over budget — the single
349 // just-inserted entry itself is bigger than
350 // max_bytes. Nothing we can safely do here without
351 // rejecting the put; leave it and return.
352 return Ok(());
353 };
354 let key_hash = self.cache_dir[pos].key_hash;
355 let ns = self.cache_dir[pos].namespace.clone();
356 self.cache_dir[pos].deleted = true;
357 self.release_cache_pages(pos);
358 self.cache_idx.remove(&ns, &key_hash);
359 self.cache_counters.evictions += 1;
360 }
361 }
362
363 // === Semantic cache (Phase 10.2) ==================================
364
365 /// Insert or overwrite a **semantic** cache entry — same as
366 /// [`Mnemo::cache_put`] but with a required embedding vector and
367 /// model identifier. The vector is stored on the directory entry
368 /// so [`Mnemo::cache_get_semantic`] can score without decrypting
369 /// record bodies.
370 ///
371 /// Vector dimensionality is validated against the database's
372 /// configured `dimensions` — a mismatch returns
373 /// [`MnemoError::DimensionMismatch`], the same signal `remember`
374 /// gives for the memory catalog.
375 ///
376 /// The `model` string is matched **exactly** on lookup — a
377 /// different model's cache is invisible to a given query. Pick
378 /// canonical identifiers (`"text-embedding-3-small"`,
379 /// `"bge-large-en-v1.5"`, ...) and stick to them.
380 pub fn cache_put_semantic(
381 &mut self,
382 namespace: &str,
383 key: &str,
384 vector: Vec<f32>,
385 value: &[u8],
386 opts: SemanticCachePutOpts,
387 ) -> Result<()> {
388 if self.read_only {
389 return Err(MnemoError::ReadOnly);
390 }
391 if vector.len() != self.dimensions {
392 return Err(MnemoError::DimensionMismatch {
393 expected: self.dimensions,
394 got: vector.len(),
395 });
396 }
397 let key_hash = result_cache::hash_key(key);
398 let key_preview = result_cache::key_preview(key);
399 let now = memory::now_secs();
400 let size_bytes = value.len() as u64;
401
402 let entry = CacheEntry {
403 namespace: namespace.to_string(),
404 key_hash,
405 key_preview: key_preview.clone(),
406 value: value.to_vec(),
407 content_type: opts.content_type.clone(),
408 created_at: now,
409 accessed_at: now,
410 access_count: 0,
411 ttl_secs: opts.ttl_secs,
412 cost_hint_ms: opts.cost_hint_ms,
413 size_bytes,
414 vector: Some(vector.clone()),
415 model: Some(opts.model.clone()),
416 };
417 let bytes = rmp_serde::to_vec(&entry).map_err(|e| MnemoError::Serialize(e.to_string()))?;
418 let (start_page, page_count, gen) = self.write_record(&bytes)?;
419
420 if let Some(prev_pos) = self.cache_idx.get(namespace, &key_hash) {
421 self.cache_dir[prev_pos].deleted = true;
422 self.release_cache_pages(prev_pos);
423 self.cache_idx.remove(namespace, &key_hash);
424 }
425
426 let dir_entry = CacheDirectoryEntry {
427 namespace: namespace.to_string(),
428 key_hash,
429 start_page,
430 page_count,
431 len: bytes.len() as u32,
432 deleted: false,
433 accessed_at: now,
434 access_count: 0,
435 size_bytes,
436 ttl_secs: opts.ttl_secs,
437 created_at: now,
438 vector: Some(vector),
439 model: Some(opts.model),
440 gen,
441 };
442 let pos = self.cache_dir.len();
443 self.cache_dir.push(dir_entry);
444 self.cache_idx.insert(namespace, key_hash, pos);
445
446 self.evict_to_budget(namespace)?;
447
448 self.dirty_cache = true;
449 self.cache_batch.record_dirty();
450 if self.cache_batch.should_auto_flush(&self.cache_flush_policy) {
451 self.flush()?;
452 }
453 Ok(())
454 }
455
456 /// Semantic recall over the cache: score every live entry in
457 /// `namespace` whose `model` matches against `query_vector` using
458 /// cosine similarity; return the top-1 hit and its similarity iff
459 /// `sim >= threshold`. `None` otherwise.
460 ///
461 /// Uses [`crate::result_cache::DEFAULT_SEMANTIC_THRESHOLD`] if you
462 /// want a sensible default — pass it explicitly (`0.97` today).
463 ///
464 /// Exact-key entries (those without a vector) are transparently
465 /// skipped, as are entries whose model doesn't match — a
466 /// different-model hit would be a semantic bug, not a win.
467 /// TTL-expired entries are also skipped.
468 ///
469 /// Access-stat updates on hit follow the same policy as
470 /// [`Mnemo::cache_get`]: bumped on read-write handles, silently
471 /// skipped on read-only. Hits and misses are recorded in the
472 /// per-handle counters just like exact-key lookups.
473 pub fn cache_get_semantic(
474 &mut self,
475 namespace: &str,
476 query_vector: &[f32],
477 threshold: f32,
478 model: &str,
479 ) -> Result<Option<(CachedValue, f32)>> {
480 if query_vector.len() != self.dimensions {
481 return Err(MnemoError::DimensionMismatch {
482 expected: self.dimensions,
483 got: query_vector.len(),
484 });
485 }
486 // FIX-1 R-001.8 part 4: same Batched max_age check as
487 // `cache_get`. See the comment there.
488 if !self.read_only && self.cache_batch.should_auto_flush(&self.cache_flush_policy) {
489 self.flush()?;
490 }
491 let now = memory::now_secs();
492
493 // Scan namespace live entries, filter by model, compute
494 // cosine, keep the best. Exact-key entries have `vector: None`
495 // and are skipped by the filter.
496 let mut best: Option<(usize, f32)> = None;
497 for (i, e) in self.cache_dir.iter().enumerate() {
498 if e.deleted || e.namespace != namespace || e.is_expired(now) {
499 continue;
500 }
501 let Some(ref v) = e.vector else { continue };
502 let Some(ref m) = e.model else { continue };
503 if m != model {
504 continue;
505 }
506 let sim = memory::cosine(query_vector, v);
507 if best.map(|(_, s)| sim > s).unwrap_or(true) {
508 best = Some((i, sim));
509 }
510 }
511
512 let Some((pos, sim)) = best else {
513 self.cache_counters.misses += 1;
514 return Ok(None);
515 };
516 if sim < threshold {
517 self.cache_counters.misses += 1;
518 return Ok(None);
519 }
520
521 // Extract fields before any mutation to keep the borrow checker
522 // happy.
523 let (start_page, page_count, len, ttl_secs, created_at, gen) = {
524 let e = &self.cache_dir[pos];
525 (
526 e.start_page,
527 e.page_count,
528 e.len,
529 e.ttl_secs,
530 e.created_at,
531 e.gen,
532 )
533 };
534
535 // Decrypt and decode the record body.
536 let buf = self.read_record_run(start_page, page_count, len, gen)?;
537 let entry: CacheEntry =
538 rmp_serde::from_slice(&buf).map_err(|e| MnemoError::Serialize(e.to_string()))?;
539
540 if !self.read_only {
541 self.cache_dir[pos].accessed_at = now;
542 self.cache_dir[pos].access_count = self.cache_dir[pos].access_count.saturating_add(1);
543 self.dirty_cache = true;
544 }
545 self.cache_counters.hits += 1;
546 let access_count = self.cache_dir[pos].access_count;
547 // FIX-1 R-002.2 part 1: same read-only `accessed_at` fix as
548 // `cache_get`. The directory carries the live value; the record
549 // body only holds the insert-time snapshot.
550 let accessed_at = if self.read_only {
551 self.cache_dir[pos].accessed_at
552 } else {
553 now
554 };
555 Ok(Some((
556 CachedValue {
557 value: entry.value,
558 content_type: entry.content_type,
559 created_at,
560 accessed_at,
561 access_count,
562 ttl_secs,
563 },
564 sim,
565 )))
566 }
567}