Skip to main content

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}