Skip to main content

second_brain_core/
query.rs

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