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