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