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