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