Skip to main content

second_brain_api/eval/
caching_store.rs

1use std::collections::HashMap;
2use std::sync::RwLock;
3
4use anyhow::Result;
5use uuid::Uuid;
6
7use second_brain_core::schema::{Conversation, Entity, Memory, MemoryType, Relation, RelationType};
8use second_brain_core::store::Store;
9
10type RelationsCache = HashMap<(Uuid, Option<RelationType>), Vec<Relation>>;
11
12// get_relations(memory_id, rel_type) is deterministic and query-independent, so
13// caching it is sound: the eval replays the same snapshot read-only and recall
14// asks for the same (id, rel_type) pairs across all 836 queries x 2 arms.
15// Kuzu serializes these reads, so memoizing turns repeated graph hits into
16// HashMap lookups without changing any recall output.
17pub struct CachingStore<'a> {
18    inner: &'a dyn Store,
19    relations_cache: RwLock<RelationsCache>,
20    vector_corpus: RwLock<Option<Vec<Memory>>>,
21}
22
23impl<'a> CachingStore<'a> {
24    pub fn new(inner: &'a dyn Store) -> Self {
25        Self {
26            inner,
27            relations_cache: RwLock::new(HashMap::new()),
28            vector_corpus: RwLock::new(None),
29        }
30    }
31
32    /// Serve vector_search from an in-memory corpus instead of re-reading and
33    /// re-parsing every embedding blob through the store's connection mutex on
34    /// each call. The caller must supply exactly the rows the store's own
35    /// vector_search would scan: embedding present, tier hot, not superseded.
36    pub fn prewarm_vectors(&self, corpus: Vec<Memory>) {
37        *self.vector_corpus.write().unwrap() = Some(corpus);
38    }
39
40    // Populate the relation cache in two bulk scans (ids + all edges) instead of
41    // letting recall trigger ~corpus_size x 7 serialized Kuzu point reads. Every
42    // (memory_id, Some(rt)) the recall path queries is seeded, empty included, so
43    // the parallel arms run entirely from the in-memory map. get_relations is
44    // query-independent, so a prewarmed cache is interchangeable with live reads.
45    pub fn prewarm(&self) -> Result<()> {
46        let scored_types = [
47            RelationType::Reinforces,
48            RelationType::RelatesTo,
49            RelationType::DistilledFrom,
50            RelationType::Mentions,
51            RelationType::DerivedFrom,
52            RelationType::Contradicts,
53            RelationType::Supersedes,
54        ];
55
56        let ids = self.inner.all_memory_ids()?;
57        let mut cache = self.relations_cache.write().unwrap();
58        cache.reserve(ids.len() * scored_types.len());
59        for id in &ids {
60            for rt in &scored_types {
61                cache.entry((*id, Some(*rt))).or_default();
62            }
63        }
64
65        for rel in self.inner.all_relations()? {
66            // get_relations only matches edges whose source is the queried node,
67            // so key on from_id; an unseeded type (none of the scored set) is
68            // ignored here and would fall through to a live read if ever asked.
69            if let Some(bucket) = cache.get_mut(&(rel.from_id, Some(rel.relation_type))) {
70                bucket.push(rel);
71            }
72        }
73
74        Ok(())
75    }
76}
77
78impl Store for CachingStore<'_> {
79    fn get_relations(
80        &self,
81        node_id: Uuid,
82        relation_type: Option<RelationType>,
83    ) -> Result<Vec<Relation>> {
84        let key = (node_id, relation_type);
85        if let Some(hit) = self.relations_cache.read().unwrap().get(&key) {
86            return Ok(hit.clone());
87        }
88        let fetched = self.inner.get_relations(node_id, relation_type)?;
89        self.relations_cache
90            .write()
91            .unwrap()
92            .insert(key, fetched.clone());
93        Ok(fetched)
94    }
95
96    fn store_memory(&self, memory: &Memory) -> Result<()> {
97        self.inner.store_memory(memory)
98    }
99
100    fn get_memory(&self, id: Uuid) -> Result<Option<Memory>> {
101        self.inner.get_memory(id)
102    }
103
104    fn delete_memory(&self, id: Uuid) -> Result<()> {
105        self.inner.delete_memory(id)
106    }
107
108    // Every method the Store trait gives a default body must be forwarded
109    // too: the default would otherwise run here instead of the inner
110    // store's override, and the eval would measure a different recall.
111    fn remove_memory(&self, id: Uuid) -> Result<bool> {
112        self.inner.remove_memory(id)
113    }
114
115    fn source_admits(&self, memory: &Memory, source: &str) -> Result<bool> {
116        self.inner.source_admits(memory, source)
117    }
118
119    fn record_accesses(&self, ids: &[Uuid]) -> Result<()> {
120        self.inner.record_accesses(ids)
121    }
122
123    fn store_entity(&self, entity: &Entity) -> Result<()> {
124        self.inner.store_entity(entity)
125    }
126
127    fn get_entity(&self, id: Uuid) -> Result<Option<Entity>> {
128        self.inner.get_entity(id)
129    }
130
131    fn find_entity_by_name(&self, name: &str) -> Result<Option<Entity>> {
132        self.inner.find_entity_by_name(name)
133    }
134
135    fn store_conversation(&self, conversation: &Conversation) -> Result<()> {
136        self.inner.store_conversation(conversation)
137    }
138
139    fn store_relation(&self, relation: &Relation) -> Result<()> {
140        self.inner.store_relation(relation)
141    }
142
143    fn vector_search(&self, embedding: &[f32], limit: usize) -> Result<Vec<(Memory, f32)>> {
144        let corpus = self.vector_corpus.read().unwrap();
145        let Some(corpus) = corpus.as_ref() else {
146            return self.inner.vector_search(embedding, limit);
147        };
148        let mut scored: Vec<(usize, f32)> = corpus
149            .iter()
150            .enumerate()
151            .map(|(i, m)| {
152                (
153                    i,
154                    second_brain_core::retrieval::cosine(embedding, &m.embedding),
155                )
156            })
157            .collect();
158        scored.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
159        scored.truncate(limit);
160        Ok(scored
161            .into_iter()
162            .map(|(i, sim)| {
163                let mut m = corpus[i].clone();
164                // The store's vector_search strips embeddings from results.
165                m.embedding = Vec::new();
166                (m, sim)
167            })
168            .collect())
169    }
170
171    fn filtered_vector_search(
172        &self,
173        embedding: &[f32],
174        source: Option<&str>,
175        memory_type: Option<MemoryType>,
176        project_path: Option<&str>,
177        limit: usize,
178    ) -> Result<Vec<(Memory, f32)>> {
179        self.inner
180            .filtered_vector_search(embedding, source, memory_type, project_path, limit)
181    }
182
183    fn traverse(&self, start_id: Uuid, depth: u32) -> Result<Vec<(Memory, Vec<Relation>)>> {
184        self.inner.traverse(start_id, depth)
185    }
186
187    fn memories_by_source(&self, source: &str) -> Result<Vec<Memory>> {
188        self.inner.memories_by_source(source)
189    }
190
191    fn memories_by_type(&self, memory_type: MemoryType) -> Result<Vec<Memory>> {
192        self.inner.memories_by_type(memory_type)
193    }
194
195    fn update_memory(&self, memory: &Memory) -> Result<()> {
196        self.inner.update_memory(memory)
197    }
198
199    fn record_access(&self, memory: &Memory) -> Result<()> {
200        self.inner.record_access(memory)
201    }
202
203    fn bm25_search(&self, query: &str, limit: usize) -> Result<Vec<Memory>> {
204        self.inner.bm25_search(query, limit)
205    }
206    fn get_memory_with_embedding(&self, id: Uuid) -> Result<Option<Memory>> {
207        self.inner.get_memory_with_embedding(id)
208    }
209
210    fn memory_count(&self) -> Result<usize> {
211        self.inner.memory_count()
212    }
213
214    fn all_memory_ids(&self) -> Result<Vec<Uuid>> {
215        self.inner.all_memory_ids()
216    }
217
218    fn all_relations(&self) -> Result<Vec<Relation>> {
219        self.inner.all_relations()
220    }
221}
222
223#[cfg(test)]
224mod tests {
225    use super::*;
226    use chrono::{Duration, Utc};
227    use second_brain_core::query::{QueryEngine, QueryFilters, QueryRequest};
228    use second_brain_core::schema::MemoryType;
229    use second_brain_core::sqlite_store::SqliteStore;
230    use second_brain_core::store::StoreAdmin;
231
232    struct InMemoryStore {
233        vector_results: Vec<(Memory, f32)>,
234        relations: Vec<Relation>,
235        get_relations_calls: std::sync::atomic::AtomicUsize,
236    }
237
238    impl Store for InMemoryStore {
239        fn vector_search(&self, _embedding: &[f32], _limit: usize) -> Result<Vec<(Memory, f32)>> {
240            Ok(self.vector_results.clone())
241        }
242
243        fn filtered_vector_search(
244            &self,
245            _embedding: &[f32],
246            source: Option<&str>,
247            memory_type: Option<MemoryType>,
248            project_path: Option<&str>,
249            limit: usize,
250        ) -> Result<Vec<(Memory, f32)>> {
251            Ok(self
252                .vector_results
253                .iter()
254                .filter(|(m, _)| source.is_none_or(|s| m.source == s))
255                .filter(|(m, _)| memory_type.is_none_or(|t| m.memory_type == t))
256                .filter(|(m, _)| project_path.is_none_or(|p| m.project_path.as_deref() == Some(p)))
257                .take(limit)
258                .cloned()
259                .collect())
260        }
261
262        fn get_relations(
263            &self,
264            node_id: Uuid,
265            relation_type: Option<RelationType>,
266        ) -> Result<Vec<Relation>> {
267            self.get_relations_calls
268                .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
269            Ok(self
270                .relations
271                .iter()
272                .filter(|r| r.from_id == node_id)
273                .filter(|r| {
274                    relation_type
275                        .map(|rt| rt == r.relation_type)
276                        .unwrap_or(true)
277                })
278                .cloned()
279                .collect())
280        }
281
282        fn store_memory(&self, _m: &Memory) -> Result<()> {
283            unimplemented!()
284        }
285        fn get_memory(&self, _id: Uuid) -> Result<Option<Memory>> {
286            unimplemented!()
287        }
288        fn delete_memory(&self, _id: Uuid) -> Result<()> {
289            unimplemented!()
290        }
291        fn store_entity(&self, _e: &Entity) -> Result<()> {
292            unimplemented!()
293        }
294        fn get_entity(&self, _id: Uuid) -> Result<Option<Entity>> {
295            unimplemented!()
296        }
297        fn find_entity_by_name(&self, _name: &str) -> Result<Option<Entity>> {
298            unimplemented!()
299        }
300        fn store_conversation(&self, _c: &Conversation) -> Result<()> {
301            unimplemented!()
302        }
303        fn store_relation(&self, _r: &Relation) -> Result<()> {
304            unimplemented!()
305        }
306        fn traverse(&self, _id: Uuid, _depth: u32) -> Result<Vec<(Memory, Vec<Relation>)>> {
307            unimplemented!()
308        }
309        fn memories_by_source(&self, _s: &str) -> Result<Vec<Memory>> {
310            unimplemented!()
311        }
312        fn memories_by_type(&self, _mt: MemoryType) -> Result<Vec<Memory>> {
313            unimplemented!()
314        }
315        fn update_memory(&self, _m: &Memory) -> Result<()> {
316            unimplemented!()
317        }
318        fn record_access(&self, _memory: &Memory) -> Result<()> {
319            unimplemented!()
320        }
321        fn bm25_search(&self, _q: &str, _limit: usize) -> Result<Vec<Memory>> {
322            unimplemented!()
323        }
324        fn get_memory_with_embedding(&self, _id: Uuid) -> Result<Option<Memory>> {
325            unimplemented!()
326        }
327        fn memory_count(&self) -> Result<usize> {
328            unimplemented!()
329        }
330        fn all_memory_ids(&self) -> Result<Vec<Uuid>> {
331            Ok(self.vector_results.iter().map(|(m, _)| m.id).collect())
332        }
333        fn all_relations(&self) -> Result<Vec<Relation>> {
334            Ok(self.relations.clone())
335        }
336    }
337
338    #[test]
339    fn methods_with_trait_defaults_reach_the_inner_store() {
340        let sqlite = SqliteStore::in_memory("m".to_string()).unwrap();
341        let raw = Memory::new(
342            "a transcript chunk".to_string(),
343            MemoryType::Semantic,
344            "claude-code".to_string(),
345            String::new(),
346        );
347        let distillate = Memory::new(
348            "its distillate".to_string(),
349            MemoryType::Semantic,
350            "consolidation".to_string(),
351            String::new(),
352        );
353        sqlite.store_memory(&raw).unwrap();
354        sqlite.store_memory(&distillate).unwrap();
355        sqlite
356            .mark_consolidated(raw.id, distillate.id, "model")
357            .unwrap();
358
359        let caching = CachingStore::new(&sqlite);
360        assert!(
361            caching.source_admits(&distillate, "claude-code").unwrap(),
362            "a distillate answers for its raws' source, as it does in the live store"
363        );
364
365        caching.record_accesses(&[raw.id]).unwrap();
366        let touched = sqlite.get_memory(raw.id).unwrap().unwrap();
367        assert_eq!(touched.access_count, 1);
368        assert!((touched.confidence - raw.confidence).abs() < f32::EPSILON);
369
370        assert!(!caching.remove_memory(Uuid::new_v4()).unwrap());
371        assert!(caching.remove_memory(raw.id).unwrap());
372    }
373
374    fn memory(content: &str, days_old: i64) -> Memory {
375        let when = Utc::now() - Duration::days(days_old);
376        let mut m = Memory::new(
377            content.to_string(),
378            MemoryType::Semantic,
379            "test".to_string(),
380            String::new(),
381        );
382        m.created_at = when;
383        m.last_accessed = when;
384        m
385    }
386
387    fn fixture() -> (Vec<(Memory, f32)>, Vec<Relation>) {
388        let a = memory("kuzu was chosen as the embedded graph store", 10);
389        let b = memory("sync runs bidirectionally over ssh", 40);
390        let c = memory("embeddings use the bge model", 5);
391        let rel = |from: Uuid, rt: RelationType, strength: f32| Relation {
392            from_id: from,
393            to_id: Uuid::new_v4(),
394            relation_type: rt,
395            strength,
396            context: None,
397        };
398        let relations = vec![
399            rel(a.id, RelationType::Reinforces, 1.0),
400            rel(a.id, RelationType::RelatesTo, 0.7),
401            rel(b.id, RelationType::Mentions, 1.0),
402            rel(c.id, RelationType::RelatesTo, 0.4),
403            rel(c.id, RelationType::Supersedes, 1.0),
404        ];
405        let vector_results = vec![(a, 0.91), (b, 0.78), (c, 0.66)];
406        (vector_results, relations)
407    }
408
409    fn request() -> QueryRequest {
410        QueryRequest {
411            text: "graph store choice".to_string(),
412            embedding: vec![0.1_f32; 384],
413            limit: 10,
414            filters: QueryFilters::default(),
415        }
416    }
417
418    #[test]
419    fn caching_store_recall_matches_raw_store() {
420        let (vector_results, relations) = fixture();
421        let raw = InMemoryStore {
422            vector_results,
423            relations,
424            get_relations_calls: std::sync::atomic::AtomicUsize::new(0),
425        };
426
427        let baseline = QueryEngine::new(&raw).recall(&request()).unwrap();
428
429        let cached = CachingStore::new(&raw);
430        let first = QueryEngine::new(&cached).recall(&request()).unwrap();
431        let second = QueryEngine::new(&cached).recall(&request()).unwrap();
432
433        assert_eq!(baseline.len(), first.len());
434        assert_eq!(first.len(), second.len());
435        for (b, c) in baseline.iter().zip(first.iter()) {
436            assert_eq!(b.memory.id, c.memory.id, "result order must match");
437            assert!(
438                (b.score - c.score).abs() < 1e-6,
439                "scores must match: {} vs {}",
440                b.score,
441                c.score
442            );
443        }
444        // The second recall through the cache must produce the identical
445        // ranking, proving the memoized path is faithful across repeats.
446        for (a, c) in first.iter().zip(second.iter()) {
447            assert_eq!(a.memory.id, c.memory.id);
448            assert!((a.score - c.score).abs() < 1e-6);
449        }
450    }
451
452    #[test]
453    fn prewarmed_store_recall_matches_raw_and_skips_live_reads() {
454        use std::sync::atomic::Ordering;
455        let (vector_results, relations) = fixture();
456        let raw = InMemoryStore {
457            vector_results,
458            relations,
459            get_relations_calls: std::sync::atomic::AtomicUsize::new(0),
460        };
461
462        let baseline = QueryEngine::new(&raw).recall(&request()).unwrap();
463        let calls_after_baseline = raw.get_relations_calls.load(Ordering::Relaxed);
464        assert!(calls_after_baseline > 0, "baseline must hit the live store");
465
466        let cached = CachingStore::new(&raw);
467        cached.prewarm().unwrap();
468        let prewarm_calls = raw.get_relations_calls.load(Ordering::Relaxed);
469
470        let recalled = QueryEngine::new(&cached).recall(&request()).unwrap();
471
472        // prewarm uses all_relations, never get_relations, and seeds every
473        // (id, scored_type) pair, so recall must trigger zero live reads.
474        assert_eq!(
475            raw.get_relations_calls.load(Ordering::Relaxed),
476            prewarm_calls,
477            "prewarmed recall must not call inner.get_relations"
478        );
479        assert_eq!(
480            prewarm_calls, calls_after_baseline,
481            "prewarm must not read via get_relations"
482        );
483
484        assert_eq!(baseline.len(), recalled.len());
485        for (b, c) in baseline.iter().zip(recalled.iter()) {
486            assert_eq!(b.memory.id, c.memory.id, "result order must match");
487            assert!(
488                (b.score - c.score).abs() < 1e-6,
489                "scores must match: {} vs {}",
490                b.score,
491                c.score
492            );
493        }
494    }
495}