use std::collections::HashSet;
use anyhow::Result;
use uuid::Uuid;
use crate::schema::Memory;
use crate::store::Store;
#[derive(Debug, Clone)]
pub struct QueryRequest {
pub text: String,
pub embedding: Vec<f32>,
pub limit: usize,
pub filters: QueryFilters,
}
#[derive(Debug, Clone, Default)]
pub struct QueryFilters {
pub source: Option<String>,
pub memory_type: Option<crate::schema::MemoryType>,
pub min_confidence: Option<f32>,
pub entity_names: Vec<String>,
pub project_path: Option<String>,
}
#[derive(Debug, Clone)]
pub struct QueryResult {
pub memory: Memory,
pub score: f32,
pub relevance: f32,
pub path: Vec<Uuid>,
}
use crate::retrieval::blend::{self, MIN_SIMILARITY, PROJECT_AFFINITY_BOOST};
pub struct QueryEngine<'a, S: Store + ?Sized> {
store: &'a S,
vector_weight: f32,
graph_weight: f32,
recency_weight: f32,
}
impl<'a, S: Store + ?Sized> QueryEngine<'a, S> {
pub fn new(store: &'a S) -> Self {
Self {
store,
vector_weight: 0.5,
graph_weight: 0.3,
recency_weight: 0.2,
}
}
pub fn with_weights(mut self, vector: f32, graph: f32, recency: f32) -> Self {
self.vector_weight = vector;
self.graph_weight = graph;
self.recency_weight = recency;
self
}
pub fn recall(&self, request: &QueryRequest) -> Result<Vec<QueryResult>> {
let vector_results = if request.filters.source.is_some()
|| request.filters.memory_type.is_some()
|| request.filters.project_path.is_some()
{
self.store.filtered_vector_search(
&request.embedding,
request.filters.source.as_deref(),
request.filters.memory_type,
request.filters.project_path.as_deref(),
request.limit * 3,
)?
} else {
self.store
.vector_search(&request.embedding, request.limit * 3)?
};
let query_entity_ids = self.resolve_query_entities(&request.filters.entity_names);
let mut scored: Vec<QueryResult> = Vec::new();
for (memory, similarity) in vector_results {
if similarity < MIN_SIMILARITY {
continue;
}
if let Some(min_conf) = request.filters.min_confidence
&& memory.confidence < min_conf
{
continue;
}
if let Some(ref source) = request.filters.source
&& !self.store.source_admits(&memory, source)?
{
continue;
}
if let Some(ref mt) = request.filters.memory_type
&& &memory.memory_type != mt
{
continue;
}
let recency_score = self.compute_recency(&memory);
let graph_score = self
.compute_graph_relevance(&memory, &query_entity_ids)
.unwrap_or(0.0);
let mut rank_score = (similarity * self.vector_weight)
+ (graph_score * self.graph_weight)
+ (recency_score * self.recency_weight);
if let Some(ref qp) = request.filters.project_path
&& memory.project_path.as_deref() == Some(qp.as_str())
{
rank_score *= PROJECT_AFFINITY_BOOST;
}
scored.push(QueryResult {
memory,
score: rank_score,
relevance: similarity,
path: Vec::new(),
});
}
scored.sort_by(|a, b| {
b.score
.partial_cmp(&a.score)
.unwrap_or(std::cmp::Ordering::Equal)
});
scored.truncate(request.limit);
Ok(scored)
}
fn compute_recency(&self, memory: &Memory) -> f32 {
blend::compute_recency(memory)
}
fn resolve_query_entities(&self, names: &[String]) -> HashSet<Uuid> {
blend::resolve_query_entities(self.store, names)
}
fn compute_graph_relevance(
&self,
memory: &Memory,
query_entity_ids: &HashSet<Uuid>,
) -> Result<f32> {
blend::compute_graph_relevance(self.store, memory, query_entity_ids)
}
pub fn store(&self) -> &S {
self.store
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::schema::{Conversation, Entity, MemoryType, Relation, RelationType};
use chrono::{Duration, Utc};
struct StubStore {
vector_results: Vec<(Memory, f32)>,
relations: Vec<Relation>,
entities: Vec<Entity>,
}
impl StubStore {
fn new(vector_results: Vec<(Memory, f32)>, relations: Vec<Relation>) -> Self {
Self {
vector_results,
relations,
entities: Vec::new(),
}
}
}
impl Store for StubStore {
fn vector_search(&self, _embedding: &[f32], limit: usize) -> Result<Vec<(Memory, f32)>> {
Ok(self.vector_results.iter().take(limit).cloned().collect())
}
fn filtered_vector_search(
&self,
_embedding: &[f32],
source: Option<&str>,
memory_type: Option<MemoryType>,
project_path: Option<&str>,
limit: usize,
) -> Result<Vec<(Memory, f32)>> {
Ok(self
.vector_results
.iter()
.filter(|(m, _)| source.is_none_or(|s| self.source_admits(m, s).unwrap()))
.filter(|(m, _)| memory_type.is_none_or(|t| m.memory_type == t))
.filter(|(m, _)| project_path.is_none_or(|p| m.project_path.as_deref() == Some(p)))
.take(limit)
.cloned()
.collect())
}
fn source_admits(&self, memory: &Memory, source: &str) -> Result<bool> {
Ok(memory.source == source || (memory.source == "consolidation" && source == "cursor"))
}
fn get_relations(
&self,
node_id: Uuid,
relation_type: Option<RelationType>,
) -> Result<Vec<Relation>> {
Ok(self
.relations
.iter()
.filter(|r| r.from_id == node_id)
.filter(|r| {
relation_type
.map(|rt| rt == r.relation_type)
.unwrap_or(true)
})
.cloned()
.collect())
}
fn store_memory(&self, _m: &Memory) -> Result<()> {
unimplemented!()
}
fn get_memory(&self, _id: Uuid) -> Result<Option<Memory>> {
unimplemented!()
}
fn delete_memory(&self, _id: Uuid) -> Result<()> {
unimplemented!()
}
fn store_entity(&self, _e: &Entity) -> Result<()> {
unimplemented!()
}
fn get_entity(&self, _id: Uuid) -> Result<Option<Entity>> {
unimplemented!()
}
fn find_entity_by_name(&self, name: &str) -> Result<Option<Entity>> {
Ok(self.entities.iter().find(|e| e.name == name).cloned())
}
fn store_conversation(&self, _c: &Conversation) -> Result<()> {
unimplemented!()
}
fn store_relation(&self, _r: &Relation) -> Result<()> {
unimplemented!()
}
fn traverse(&self, _id: Uuid, _depth: u32) -> Result<Vec<(Memory, Vec<Relation>)>> {
unimplemented!()
}
fn memories_by_source(&self, _s: &str) -> Result<Vec<Memory>> {
unimplemented!()
}
fn memories_by_type(&self, _mt: MemoryType) -> Result<Vec<Memory>> {
unimplemented!()
}
fn update_memory(&self, _m: &Memory) -> Result<()> {
unimplemented!()
}
fn record_access(&self, _memory: &Memory) -> Result<()> {
unimplemented!()
}
fn bm25_search(&self, _q: &str, _limit: usize) -> Result<Vec<Memory>> {
unimplemented!()
}
fn get_memory_with_embedding(&self, _id: Uuid) -> Result<Option<Memory>> {
unimplemented!()
}
fn memory_count(&self) -> Result<usize> {
unimplemented!()
}
fn all_memory_ids(&self) -> Result<Vec<Uuid>> {
unimplemented!()
}
fn all_relations(&self) -> Result<Vec<Relation>> {
unimplemented!()
}
}
fn memory_aged(content: &str, days_old: i64) -> Memory {
let when = Utc::now() - Duration::days(days_old);
let mut m = Memory::new(
content.to_string(),
MemoryType::Semantic,
"test".to_string(),
String::new(),
);
m.created_at = when;
m.last_accessed = when;
m
}
fn query() -> QueryRequest {
QueryRequest {
text: "query text".to_string(),
embedding: vec![0.0_f32; 384],
limit: 10,
filters: QueryFilters::default(),
}
}
#[test]
fn source_filter_reaches_past_the_unfiltered_cutoff() {
let mut corpus: Vec<(Memory, f32)> = (0..30)
.map(|i| (memory_aged(&format!("crowding note {i}"), 1), 0.95))
.collect();
let mut wanted = memory_aged("the memory the caller asked to scope to", 1);
wanted.source = "ask".to_string();
let wanted_id = wanted.id;
corpus.push((wanted, 0.80));
let store = StubStore::new(corpus, Vec::new());
let mut request = query();
request.filters.source = Some("ask".to_string());
let results = QueryEngine::new(&store).recall(&request).unwrap();
assert_eq!(results.len(), 1);
assert_eq!(results[0].memory.id, wanted_id);
}
#[test]
fn source_filter_defers_to_the_store_for_distillates() {
let mut distillate = memory_aged("distilled from a cursor transcript", 1);
distillate.source = "consolidation".to_string();
let mut other = memory_aged("distilled from something else", 1);
other.source = "claude-code".to_string();
let distillate_id = distillate.id;
let store = StubStore::new(vec![(distillate, 0.9), (other, 0.9)], Vec::new());
let mut request = query();
request.filters.source = Some("cursor".to_string());
let results = QueryEngine::new(&store).recall(&request).unwrap();
let ids: Vec<Uuid> = results.iter().map(|r| r.memory.id).collect();
assert_eq!(ids, vec![distillate_id]);
}
#[test]
fn aged_unconnected_memory_survives_on_strong_similarity() {
let store = StubStore::new(
vec![(
memory_aged("kuzu was chosen as the embedded graph store", 180),
0.92,
)],
Vec::new(),
);
let results = QueryEngine::new(&store).recall(&query()).unwrap();
assert_eq!(results.len(), 1);
}
#[test]
fn well_connected_low_similarity_memory_is_excluded() {
let weak = memory_aged("an entirely unrelated topic", 0);
let weak_id = weak.id;
let reinforces = |to| Relation {
from_id: weak_id,
to_id: to,
relation_type: RelationType::Reinforces,
strength: 1.0,
context: None,
};
let store = StubStore::new(
vec![(weak, 0.45)],
vec![
reinforces(Uuid::new_v4()),
reinforces(Uuid::new_v4()),
reinforces(Uuid::new_v4()),
],
);
let results = QueryEngine::new(&store).recall(&query()).unwrap();
assert!(results.is_empty());
}
#[test]
fn results_are_ranked_by_blended_score() {
let store = StubStore::new(
vec![
(memory_aged("older relevant note", 200), 0.80),
(memory_aged("fresher relevant note", 0), 0.80),
],
Vec::new(),
);
let results = QueryEngine::new(&store).recall(&query()).unwrap();
assert_eq!(results.len(), 2);
assert_eq!(results[0].memory.content, "fresher relevant note");
}
fn mentions(from: Uuid, to: Uuid) -> Relation {
Relation {
from_id: from,
to_id: to,
relation_type: RelationType::Mentions,
strength: 1.0,
context: None,
}
}
#[test]
fn memory_mentioning_a_query_entity_outranks_an_equal_match_that_does_not() {
let on_topic = memory_aged("note about the kuzu store", 10);
let off_topic = memory_aged("note about something else", 10);
let kuzu = Entity::new("kuzu".to_string(), "technology".to_string());
let mut store = StubStore::new(
vec![(off_topic.clone(), 0.80), (on_topic.clone(), 0.80)],
vec![mentions(on_topic.id, kuzu.id)],
);
store.entities = vec![kuzu];
let mut req = query();
req.filters.entity_names = vec!["kuzu".to_string()];
let results = QueryEngine::new(&store).recall(&req).unwrap();
assert_eq!(results.len(), 2);
assert_eq!(results[0].memory.content, "note about the kuzu store");
}
#[test]
fn unresolvable_query_entity_falls_back_to_structural_ranking() {
let store = StubStore::new(
vec![
(memory_aged("older relevant note", 200), 0.80),
(memory_aged("fresher relevant note", 0), 0.80),
],
Vec::new(),
);
let mut req = query();
req.filters.entity_names = vec!["never-seen-entity".to_string()];
let results = QueryEngine::new(&store).recall(&req).unwrap();
assert_eq!(results.len(), 2);
assert_eq!(results[0].memory.content, "fresher relevant note");
}
}