Skip to main content

second_brain_core/
query.rs

1use std::collections::HashSet;
2
3use anyhow::Result;
4use uuid::Uuid;
5
6use crate::schema::Memory;
7use crate::store::Store;
8
9#[derive(Debug, Clone)]
10pub struct QueryRequest {
11    pub text: String,
12    pub embedding: Vec<f32>,
13    pub limit: usize,
14    pub filters: QueryFilters,
15}
16
17#[derive(Debug, Clone, Default)]
18pub struct QueryFilters {
19    pub source: Option<String>,
20    pub memory_type: Option<crate::schema::MemoryType>,
21    pub min_confidence: Option<f32>,
22    pub entity_names: Vec<String>,
23    pub project_path: Option<String>,
24}
25
26#[derive(Debug, Clone)]
27pub struct QueryResult {
28    pub memory: Memory,
29    pub score: f32,
30    pub path: Vec<Uuid>,
31}
32
33use crate::retrieval::blend::{self, MIN_SIMILARITY, PROJECT_AFFINITY_BOOST};
34
35pub struct QueryEngine<'a, S: Store + ?Sized> {
36    store: &'a S,
37    vector_weight: f32,
38    graph_weight: f32,
39    recency_weight: f32,
40}
41
42impl<'a, S: Store + ?Sized> QueryEngine<'a, S> {
43    pub fn new(store: &'a S) -> Self {
44        Self {
45            store,
46            vector_weight: 0.5,
47            graph_weight: 0.3,
48            recency_weight: 0.2,
49        }
50    }
51
52    pub fn with_weights(mut self, vector: f32, graph: f32, recency: f32) -> Self {
53        self.vector_weight = vector;
54        self.graph_weight = graph;
55        self.recency_weight = recency;
56        self
57    }
58
59    pub fn recall(&self, request: &QueryRequest) -> Result<Vec<QueryResult>> {
60        // A scoped recall must scan the scope, not trim an unfiltered top-k:
61        // the filters below can only reject, so anything the unfiltered search
62        // misses stays missing however narrow the scope is.
63        let vector_results = if request.filters.source.is_some()
64            || request.filters.memory_type.is_some()
65            || request.filters.project_path.is_some()
66        {
67            self.store.filtered_vector_search(
68                &request.embedding,
69                request.filters.source.as_deref(),
70                request.filters.memory_type,
71                request.filters.project_path.as_deref(),
72                request.limit * 3,
73            )?
74        } else {
75            self.store
76                .vector_search(&request.embedding, request.limit * 3)?
77        };
78
79        let query_entity_ids = self.resolve_query_entities(&request.filters.entity_names);
80
81        let mut scored: Vec<QueryResult> = Vec::new();
82
83        for (memory, similarity) in vector_results {
84            // Gate membership on similarity alone. Graph and recency only
85            // re-rank, so folding them into the cutoff caps the similarity
86            // term below any useful threshold and would silently drop aged,
87            // unconnected memories that match the query perfectly.
88            if similarity < MIN_SIMILARITY {
89                continue;
90            }
91            if let Some(min_conf) = request.filters.min_confidence
92                && memory.confidence < min_conf
93            {
94                continue;
95            }
96            if let Some(ref source) = request.filters.source
97                && !self.store.source_admits(&memory, source)?
98            {
99                continue;
100            }
101            if let Some(ref mt) = request.filters.memory_type
102                && &memory.memory_type != mt
103            {
104                continue;
105            }
106
107            let recency_score = self.compute_recency(&memory);
108            let graph_score = self
109                .compute_graph_relevance(&memory, &query_entity_ids)
110                .unwrap_or(0.0);
111
112            let mut rank_score = (similarity * self.vector_weight)
113                + (graph_score * self.graph_weight)
114                + (recency_score * self.recency_weight);
115
116            if let Some(ref qp) = request.filters.project_path
117                && memory.project_path.as_deref() == Some(qp.as_str())
118            {
119                rank_score *= PROJECT_AFFINITY_BOOST;
120            }
121
122            scored.push(QueryResult {
123                memory,
124                score: rank_score,
125                path: Vec::new(),
126            });
127        }
128
129        scored.sort_by(|a, b| {
130            b.score
131                .partial_cmp(&a.score)
132                .unwrap_or(std::cmp::Ordering::Equal)
133        });
134        scored.truncate(request.limit);
135
136        Ok(scored)
137    }
138
139    fn compute_recency(&self, memory: &Memory) -> f32 {
140        blend::compute_recency(memory)
141    }
142
143    fn resolve_query_entities(&self, names: &[String]) -> HashSet<Uuid> {
144        blend::resolve_query_entities(self.store, names)
145    }
146
147    fn compute_graph_relevance(
148        &self,
149        memory: &Memory,
150        query_entity_ids: &HashSet<Uuid>,
151    ) -> Result<f32> {
152        blend::compute_graph_relevance(self.store, memory, query_entity_ids)
153    }
154
155    pub fn store(&self) -> &S {
156        self.store
157    }
158}
159
160#[cfg(test)]
161mod tests {
162    use super::*;
163    use crate::schema::{Conversation, Entity, MemoryType, Relation, RelationType};
164    use chrono::{Duration, Utc};
165
166    struct StubStore {
167        vector_results: Vec<(Memory, f32)>,
168        relations: Vec<Relation>,
169        entities: Vec<Entity>,
170    }
171
172    impl StubStore {
173        fn new(vector_results: Vec<(Memory, f32)>, relations: Vec<Relation>) -> Self {
174            Self {
175                vector_results,
176                relations,
177                entities: Vec::new(),
178            }
179        }
180    }
181
182    impl Store for StubStore {
183        // Truncates like a real store, so a test can put a memory past the
184        // cutoff and see whether the filters below it can still reach one.
185        fn vector_search(&self, _embedding: &[f32], limit: usize) -> Result<Vec<(Memory, f32)>> {
186            Ok(self.vector_results.iter().take(limit).cloned().collect())
187        }
188
189        // The stub's whole corpus is vector_results, so a scoped exhaustive
190        // scan is that list filtered, not the unfiltered prefix it returns
191        // above.
192        fn filtered_vector_search(
193            &self,
194            _embedding: &[f32],
195            source: Option<&str>,
196            memory_type: Option<MemoryType>,
197            project_path: Option<&str>,
198            limit: usize,
199        ) -> Result<Vec<(Memory, f32)>> {
200            Ok(self
201                .vector_results
202                .iter()
203                .filter(|(m, _)| source.is_none_or(|s| self.source_admits(m, s).unwrap()))
204                .filter(|(m, _)| memory_type.is_none_or(|t| m.memory_type == t))
205                .filter(|(m, _)| project_path.is_none_or(|p| m.project_path.as_deref() == Some(p)))
206                .take(limit)
207                .cloned()
208                .collect())
209        }
210
211        // Stands in for the sqlite lookup through distillation_log: every
212        // distillate here descends from a "cursor" raw.
213        fn source_admits(&self, memory: &Memory, source: &str) -> Result<bool> {
214            Ok(memory.source == source || (memory.source == "consolidation" && source == "cursor"))
215        }
216
217        fn get_relations(
218            &self,
219            node_id: Uuid,
220            relation_type: Option<RelationType>,
221        ) -> Result<Vec<Relation>> {
222            Ok(self
223                .relations
224                .iter()
225                .filter(|r| r.from_id == node_id)
226                .filter(|r| {
227                    relation_type
228                        .map(|rt| rt == r.relation_type)
229                        .unwrap_or(true)
230                })
231                .cloned()
232                .collect())
233        }
234
235        fn store_memory(&self, _m: &Memory) -> Result<()> {
236            unimplemented!()
237        }
238        fn get_memory(&self, _id: Uuid) -> Result<Option<Memory>> {
239            unimplemented!()
240        }
241        fn delete_memory(&self, _id: Uuid) -> Result<()> {
242            unimplemented!()
243        }
244        fn store_entity(&self, _e: &Entity) -> Result<()> {
245            unimplemented!()
246        }
247        fn get_entity(&self, _id: Uuid) -> Result<Option<Entity>> {
248            unimplemented!()
249        }
250        fn find_entity_by_name(&self, name: &str) -> Result<Option<Entity>> {
251            Ok(self.entities.iter().find(|e| e.name == name).cloned())
252        }
253        fn store_conversation(&self, _c: &Conversation) -> Result<()> {
254            unimplemented!()
255        }
256        fn store_relation(&self, _r: &Relation) -> Result<()> {
257            unimplemented!()
258        }
259        fn traverse(&self, _id: Uuid, _depth: u32) -> Result<Vec<(Memory, Vec<Relation>)>> {
260            unimplemented!()
261        }
262        fn memories_by_source(&self, _s: &str) -> Result<Vec<Memory>> {
263            unimplemented!()
264        }
265        fn memories_by_type(&self, _mt: MemoryType) -> Result<Vec<Memory>> {
266            unimplemented!()
267        }
268        fn update_memory(&self, _m: &Memory) -> Result<()> {
269            unimplemented!()
270        }
271        fn record_access(&self, _memory: &Memory) -> Result<()> {
272            unimplemented!()
273        }
274        fn bm25_search(&self, _q: &str, _limit: usize) -> Result<Vec<Memory>> {
275            unimplemented!()
276        }
277        fn get_memory_with_embedding(&self, _id: Uuid) -> Result<Option<Memory>> {
278            unimplemented!()
279        }
280        fn memory_count(&self) -> Result<usize> {
281            unimplemented!()
282        }
283        fn all_memory_ids(&self) -> Result<Vec<Uuid>> {
284            unimplemented!()
285        }
286        fn all_relations(&self) -> Result<Vec<Relation>> {
287            unimplemented!()
288        }
289    }
290
291    fn memory_aged(content: &str, days_old: i64) -> Memory {
292        let when = Utc::now() - Duration::days(days_old);
293        let mut m = Memory::new(
294            content.to_string(),
295            MemoryType::Semantic,
296            "test".to_string(),
297            String::new(),
298        );
299        m.created_at = when;
300        m.last_accessed = when;
301        m
302    }
303
304    fn query() -> QueryRequest {
305        QueryRequest {
306            text: "query text".to_string(),
307            embedding: vec![0.0_f32; 384],
308            limit: 10,
309            filters: QueryFilters::default(),
310        }
311    }
312
313    #[test]
314    fn source_filter_reaches_past_the_unfiltered_cutoff() {
315        // recall() fetches limit*3 vectors, so 30 same-source memories fill the
316        // window completely. A post-filter over that window can only return
317        // nothing; the scoped scan has to look at the whole corpus.
318        let mut corpus: Vec<(Memory, f32)> = (0..30)
319            .map(|i| (memory_aged(&format!("crowding note {i}"), 1), 0.95))
320            .collect();
321        let mut wanted = memory_aged("the memory the caller asked to scope to", 1);
322        wanted.source = "ask".to_string();
323        let wanted_id = wanted.id;
324        corpus.push((wanted, 0.80));
325
326        let store = StubStore::new(corpus, Vec::new());
327        let mut request = query();
328        request.filters.source = Some("ask".to_string());
329
330        let results = QueryEngine::new(&store).recall(&request).unwrap();
331        assert_eq!(results.len(), 1);
332        assert_eq!(results[0].memory.id, wanted_id);
333    }
334
335    #[test]
336    fn source_filter_defers_to_the_store_for_distillates() {
337        let mut distillate = memory_aged("distilled from a cursor transcript", 1);
338        distillate.source = "consolidation".to_string();
339        let mut other = memory_aged("distilled from something else", 1);
340        other.source = "claude-code".to_string();
341        let distillate_id = distillate.id;
342        let store = StubStore::new(vec![(distillate, 0.9), (other, 0.9)], Vec::new());
343        let mut request = query();
344        request.filters.source = Some("cursor".to_string());
345
346        let results = QueryEngine::new(&store).recall(&request).unwrap();
347        let ids: Vec<Uuid> = results.iter().map(|r| r.memory.id).collect();
348        assert_eq!(ids, vec![distillate_id]);
349    }
350
351    #[test]
352    fn aged_unconnected_memory_survives_on_strong_similarity() {
353        // The memory is 180 days old with no relations, so graph and recency
354        // contribute nothing; it must still be recalled because a strong
355        // semantic match is what relevance means.
356        let store = StubStore::new(
357            vec![(
358                memory_aged("kuzu was chosen as the embedded graph store", 180),
359                0.92,
360            )],
361            Vec::new(),
362        );
363        let results = QueryEngine::new(&store).recall(&query()).unwrap();
364        assert_eq!(results.len(), 1);
365    }
366
367    #[test]
368    fn well_connected_low_similarity_memory_is_excluded() {
369        // A fresh, heavily reinforced memory whose similarity is weak must be
370        // dropped, because graph and recency re-rank matches but must not
371        // promote an irrelevant memory past the similarity floor.
372        let weak = memory_aged("an entirely unrelated topic", 0);
373        let weak_id = weak.id;
374        let reinforces = |to| Relation {
375            from_id: weak_id,
376            to_id: to,
377            relation_type: RelationType::Reinforces,
378            strength: 1.0,
379            context: None,
380        };
381        let store = StubStore::new(
382            vec![(weak, 0.45)],
383            vec![
384                reinforces(Uuid::new_v4()),
385                reinforces(Uuid::new_v4()),
386                reinforces(Uuid::new_v4()),
387            ],
388        );
389        let results = QueryEngine::new(&store).recall(&query()).unwrap();
390        assert!(results.is_empty());
391    }
392
393    #[test]
394    fn results_are_ranked_by_blended_score() {
395        // Both memories clear the similarity floor with equal similarity, so
396        // recency must break the tie and rank the fresher memory first.
397        let store = StubStore::new(
398            vec![
399                (memory_aged("older relevant note", 200), 0.80),
400                (memory_aged("fresher relevant note", 0), 0.80),
401            ],
402            Vec::new(),
403        );
404        let results = QueryEngine::new(&store).recall(&query()).unwrap();
405        assert_eq!(results.len(), 2);
406        assert_eq!(results[0].memory.content, "fresher relevant note");
407    }
408
409    fn mentions(from: Uuid, to: Uuid) -> Relation {
410        Relation {
411            from_id: from,
412            to_id: to,
413            relation_type: RelationType::Mentions,
414            strength: 1.0,
415            context: None,
416        }
417    }
418
419    #[test]
420    fn memory_mentioning_a_query_entity_outranks_an_equal_match_that_does_not() {
421        // Two memories, same similarity and same age. One mentions the entity
422        // the query is about; it must rank first because graph proximity is now
423        // query-conditioned rather than a raw connectedness prior.
424        let on_topic = memory_aged("note about the kuzu store", 10);
425        let off_topic = memory_aged("note about something else", 10);
426        let kuzu = Entity::new("kuzu".to_string(), "technology".to_string());
427
428        let mut store = StubStore::new(
429            vec![(off_topic.clone(), 0.80), (on_topic.clone(), 0.80)],
430            vec![mentions(on_topic.id, kuzu.id)],
431        );
432        store.entities = vec![kuzu];
433
434        let mut req = query();
435        req.filters.entity_names = vec!["kuzu".to_string()];
436
437        let results = QueryEngine::new(&store).recall(&req).unwrap();
438        assert_eq!(results.len(), 2);
439        assert_eq!(results[0].memory.content, "note about the kuzu store");
440    }
441
442    #[test]
443    fn unresolvable_query_entity_falls_back_to_structural_ranking() {
444        // An entity name the store has never seen resolves to nothing, so the
445        // graph term reverts to the structural prior and recency breaks the tie
446        // exactly as when no entities are named.
447        let store = StubStore::new(
448            vec![
449                (memory_aged("older relevant note", 200), 0.80),
450                (memory_aged("fresher relevant note", 0), 0.80),
451            ],
452            Vec::new(),
453        );
454        let mut req = query();
455        req.filters.entity_names = vec!["never-seen-entity".to_string()];
456
457        let results = QueryEngine::new(&store).recall(&req).unwrap();
458        assert_eq!(results.len(), 2);
459        assert_eq!(results[0].memory.content, "fresher relevant note");
460    }
461}