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 chunk_window(&self, memory_id: Uuid, ord: usize) -> Result<Option<String>> {
124        self.inner.chunk_window(memory_id, ord)
125    }
126
127    fn store_entity(&self, entity: &Entity) -> Result<()> {
128        self.inner.store_entity(entity)
129    }
130
131    fn get_entity(&self, id: Uuid) -> Result<Option<Entity>> {
132        self.inner.get_entity(id)
133    }
134
135    fn find_entity_by_name(&self, name: &str) -> Result<Option<Entity>> {
136        self.inner.find_entity_by_name(name)
137    }
138
139    fn store_conversation(&self, conversation: &Conversation) -> Result<()> {
140        self.inner.store_conversation(conversation)
141    }
142
143    fn store_relation(&self, relation: &Relation) -> Result<()> {
144        self.inner.store_relation(relation)
145    }
146
147    fn vector_search(&self, embedding: &[f32], limit: usize) -> Result<Vec<(Memory, f32)>> {
148        let corpus = self.vector_corpus.read().unwrap();
149        let Some(corpus) = corpus.as_ref() else {
150            return self.inner.vector_search(embedding, limit);
151        };
152        let mut scored: Vec<(usize, f32)> = corpus
153            .iter()
154            .enumerate()
155            .map(|(i, m)| {
156                (
157                    i,
158                    second_brain_core::retrieval::cosine(embedding, &m.embedding),
159                )
160            })
161            .collect();
162        scored.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
163        scored.truncate(limit);
164        Ok(scored
165            .into_iter()
166            .map(|(i, sim)| {
167                let mut m = corpus[i].clone();
168                // The store's vector_search strips embeddings from results.
169                m.embedding = Vec::new();
170                (m, sim)
171            })
172            .collect())
173    }
174
175    fn filtered_vector_search(
176        &self,
177        embedding: &[f32],
178        source: Option<&str>,
179        memory_type: Option<MemoryType>,
180        project_path: Option<&str>,
181        limit: usize,
182    ) -> Result<Vec<(Memory, f32)>> {
183        self.inner
184            .filtered_vector_search(embedding, source, memory_type, project_path, limit)
185    }
186
187    fn traverse(&self, start_id: Uuid, depth: u32) -> Result<Vec<(Memory, Vec<Relation>)>> {
188        self.inner.traverse(start_id, depth)
189    }
190
191    fn memories_by_source(&self, source: &str) -> Result<Vec<Memory>> {
192        self.inner.memories_by_source(source)
193    }
194
195    fn memories_by_type(&self, memory_type: MemoryType) -> Result<Vec<Memory>> {
196        self.inner.memories_by_type(memory_type)
197    }
198
199    fn update_memory(&self, memory: &Memory) -> Result<()> {
200        self.inner.update_memory(memory)
201    }
202
203    fn record_access(&self, memory: &Memory) -> Result<()> {
204        self.inner.record_access(memory)
205    }
206
207    fn bm25_search(&self, query: &str, limit: usize) -> Result<Vec<Memory>> {
208        self.inner.bm25_search(query, limit)
209    }
210    fn get_memory_with_embedding(&self, id: Uuid) -> Result<Option<Memory>> {
211        self.inner.get_memory_with_embedding(id)
212    }
213
214    fn memory_count(&self) -> Result<usize> {
215        self.inner.memory_count()
216    }
217
218    fn all_memory_ids(&self) -> Result<Vec<Uuid>> {
219        self.inner.all_memory_ids()
220    }
221
222    fn all_relations(&self) -> Result<Vec<Relation>> {
223        self.inner.all_relations()
224    }
225}
226
227#[cfg(test)]
228mod tests {
229    use super::*;
230    use chrono::{Duration, Utc};
231    use second_brain_core::query::{QueryEngine, QueryFilters, QueryRequest};
232    use second_brain_core::schema::MemoryType;
233    use second_brain_core::sqlite_store::SqliteStore;
234    use second_brain_core::store::StoreAdmin;
235
236    struct InMemoryStore {
237        vector_results: Vec<(Memory, f32)>,
238        relations: Vec<Relation>,
239        get_relations_calls: std::sync::atomic::AtomicUsize,
240    }
241
242    impl Store for InMemoryStore {
243        fn vector_search(&self, _embedding: &[f32], _limit: usize) -> Result<Vec<(Memory, f32)>> {
244            Ok(self.vector_results.clone())
245        }
246
247        fn filtered_vector_search(
248            &self,
249            _embedding: &[f32],
250            source: Option<&str>,
251            memory_type: Option<MemoryType>,
252            project_path: Option<&str>,
253            limit: usize,
254        ) -> Result<Vec<(Memory, f32)>> {
255            Ok(self
256                .vector_results
257                .iter()
258                .filter(|(m, _)| source.is_none_or(|s| m.source == s))
259                .filter(|(m, _)| memory_type.is_none_or(|t| m.memory_type == t))
260                .filter(|(m, _)| project_path.is_none_or(|p| m.project_path.as_deref() == Some(p)))
261                .take(limit)
262                .cloned()
263                .collect())
264        }
265
266        fn get_relations(
267            &self,
268            node_id: Uuid,
269            relation_type: Option<RelationType>,
270        ) -> Result<Vec<Relation>> {
271            self.get_relations_calls
272                .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
273            Ok(self
274                .relations
275                .iter()
276                .filter(|r| r.from_id == node_id)
277                .filter(|r| {
278                    relation_type
279                        .map(|rt| rt == r.relation_type)
280                        .unwrap_or(true)
281                })
282                .cloned()
283                .collect())
284        }
285
286        fn store_memory(&self, _m: &Memory) -> Result<()> {
287            unimplemented!()
288        }
289        fn get_memory(&self, _id: Uuid) -> Result<Option<Memory>> {
290            unimplemented!()
291        }
292        fn delete_memory(&self, _id: Uuid) -> Result<()> {
293            unimplemented!()
294        }
295        fn store_entity(&self, _e: &Entity) -> Result<()> {
296            unimplemented!()
297        }
298        fn get_entity(&self, _id: Uuid) -> Result<Option<Entity>> {
299            unimplemented!()
300        }
301        fn find_entity_by_name(&self, _name: &str) -> Result<Option<Entity>> {
302            unimplemented!()
303        }
304        fn store_conversation(&self, _c: &Conversation) -> Result<()> {
305            unimplemented!()
306        }
307        fn store_relation(&self, _r: &Relation) -> Result<()> {
308            unimplemented!()
309        }
310        fn traverse(&self, _id: Uuid, _depth: u32) -> Result<Vec<(Memory, Vec<Relation>)>> {
311            unimplemented!()
312        }
313        fn memories_by_source(&self, _s: &str) -> Result<Vec<Memory>> {
314            unimplemented!()
315        }
316        fn memories_by_type(&self, _mt: MemoryType) -> Result<Vec<Memory>> {
317            unimplemented!()
318        }
319        fn update_memory(&self, _m: &Memory) -> Result<()> {
320            unimplemented!()
321        }
322        fn record_access(&self, _memory: &Memory) -> Result<()> {
323            unimplemented!()
324        }
325        fn bm25_search(&self, _q: &str, _limit: usize) -> Result<Vec<Memory>> {
326            unimplemented!()
327        }
328        fn get_memory_with_embedding(&self, _id: Uuid) -> Result<Option<Memory>> {
329            unimplemented!()
330        }
331        fn memory_count(&self) -> Result<usize> {
332            unimplemented!()
333        }
334        fn all_memory_ids(&self) -> Result<Vec<Uuid>> {
335            Ok(self.vector_results.iter().map(|(m, _)| m.id).collect())
336        }
337        fn all_relations(&self) -> Result<Vec<Relation>> {
338            Ok(self.relations.clone())
339        }
340    }
341
342    #[test]
343    fn methods_with_trait_defaults_reach_the_inner_store() {
344        let sqlite = SqliteStore::in_memory("m".to_string()).unwrap();
345        let raw = Memory::new(
346            "a transcript chunk".to_string(),
347            MemoryType::Semantic,
348            "claude-code".to_string(),
349            String::new(),
350        );
351        let distillate = Memory::new(
352            "its distillate".to_string(),
353            MemoryType::Semantic,
354            "consolidation".to_string(),
355            String::new(),
356        );
357        sqlite.store_memory(&raw).unwrap();
358        sqlite.store_memory(&distillate).unwrap();
359        sqlite
360            .mark_consolidated(raw.id, distillate.id, "model")
361            .unwrap();
362
363        let caching = CachingStore::new(&sqlite);
364        assert!(
365            caching.source_admits(&distillate, "claude-code").unwrap(),
366            "a distillate answers for its raws' source, as it does in the live store"
367        );
368
369        caching.record_accesses(&[raw.id]).unwrap();
370        let touched = sqlite.get_memory(raw.id).unwrap().unwrap();
371        assert_eq!(touched.access_count, 1);
372        assert!((touched.confidence - raw.confidence).abs() < f32::EPSILON);
373
374        assert!(!caching.remove_memory(Uuid::new_v4()).unwrap());
375        assert!(caching.remove_memory(raw.id).unwrap());
376    }
377
378    fn memory(content: &str, days_old: i64) -> Memory {
379        let when = Utc::now() - Duration::days(days_old);
380        let mut m = Memory::new(
381            content.to_string(),
382            MemoryType::Semantic,
383            "test".to_string(),
384            String::new(),
385        );
386        m.created_at = when;
387        m.last_accessed = when;
388        m
389    }
390
391    fn fixture() -> (Vec<(Memory, f32)>, Vec<Relation>) {
392        let a = memory("kuzu was chosen as the embedded graph store", 10);
393        let b = memory("sync runs bidirectionally over ssh", 40);
394        let c = memory("embeddings use the bge model", 5);
395        let rel = |from: Uuid, rt: RelationType, strength: f32| Relation {
396            from_id: from,
397            to_id: Uuid::new_v4(),
398            relation_type: rt,
399            strength,
400            context: None,
401        };
402        let relations = vec![
403            rel(a.id, RelationType::Reinforces, 1.0),
404            rel(a.id, RelationType::RelatesTo, 0.7),
405            rel(b.id, RelationType::Mentions, 1.0),
406            rel(c.id, RelationType::RelatesTo, 0.4),
407            rel(c.id, RelationType::Supersedes, 1.0),
408        ];
409        let vector_results = vec![(a, 0.91), (b, 0.78), (c, 0.66)];
410        (vector_results, relations)
411    }
412
413    fn request() -> QueryRequest {
414        QueryRequest {
415            text: "graph store choice".to_string(),
416            embedding: vec![0.1_f32; 384],
417            limit: 10,
418            filters: QueryFilters::default(),
419        }
420    }
421
422    #[test]
423    fn caching_store_recall_matches_raw_store() {
424        let (vector_results, relations) = fixture();
425        let raw = InMemoryStore {
426            vector_results,
427            relations,
428            get_relations_calls: std::sync::atomic::AtomicUsize::new(0),
429        };
430
431        let baseline = QueryEngine::new(&raw).recall(&request()).unwrap();
432
433        let cached = CachingStore::new(&raw);
434        let first = QueryEngine::new(&cached).recall(&request()).unwrap();
435        let second = QueryEngine::new(&cached).recall(&request()).unwrap();
436
437        assert_eq!(baseline.len(), first.len());
438        assert_eq!(first.len(), second.len());
439        for (b, c) in baseline.iter().zip(first.iter()) {
440            assert_eq!(b.memory.id, c.memory.id, "result order must match");
441            assert!(
442                (b.score - c.score).abs() < 1e-6,
443                "scores must match: {} vs {}",
444                b.score,
445                c.score
446            );
447        }
448        // The second recall through the cache must produce the identical
449        // ranking, proving the memoized path is faithful across repeats.
450        for (a, c) in first.iter().zip(second.iter()) {
451            assert_eq!(a.memory.id, c.memory.id);
452            assert!((a.score - c.score).abs() < 1e-6);
453        }
454    }
455
456    #[test]
457    fn prewarmed_store_recall_matches_raw_and_skips_live_reads() {
458        use std::sync::atomic::Ordering;
459        let (vector_results, relations) = fixture();
460        let raw = InMemoryStore {
461            vector_results,
462            relations,
463            get_relations_calls: std::sync::atomic::AtomicUsize::new(0),
464        };
465
466        let baseline = QueryEngine::new(&raw).recall(&request()).unwrap();
467        let calls_after_baseline = raw.get_relations_calls.load(Ordering::Relaxed);
468        assert!(calls_after_baseline > 0, "baseline must hit the live store");
469
470        let cached = CachingStore::new(&raw);
471        cached.prewarm().unwrap();
472        let prewarm_calls = raw.get_relations_calls.load(Ordering::Relaxed);
473
474        let recalled = QueryEngine::new(&cached).recall(&request()).unwrap();
475
476        // prewarm uses all_relations, never get_relations, and seeds every
477        // (id, scored_type) pair, so recall must trigger zero live reads.
478        assert_eq!(
479            raw.get_relations_calls.load(Ordering::Relaxed),
480            prewarm_calls,
481            "prewarmed recall must not call inner.get_relations"
482        );
483        assert_eq!(
484            prewarm_calls, calls_after_baseline,
485            "prewarm must not read via get_relations"
486        );
487
488        assert_eq!(baseline.len(), recalled.len());
489        for (b, c) in baseline.iter().zip(recalled.iter()) {
490            assert_eq!(b.memory.id, c.memory.id, "result order must match");
491            assert!(
492                (b.score - c.score).abs() < 1e-6,
493                "scores must match: {} vs {}",
494                b.score,
495                c.score
496            );
497        }
498    }
499}