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