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        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}