pub mod blend;
mod onnx_rerank;
pub mod rerank;
pub mod rrf;
pub use rerank::{RerankScorer, RerankTimeoutError, Reranker};
use std::collections::HashMap;
use anyhow::Result;
use uuid::Uuid;
use crate::index::Indexes;
use crate::query::{QueryRequest, QueryResult};
use crate::schema::Memory;
use crate::sqlite_store::SqliteStore;
use crate::store::Store;
use blend::BlendWeights;
const SCOPED_LEXICAL_MAX_K: usize = 5000;
#[derive(Debug, Clone, Default)]
pub struct Candidates {
pub dense: Vec<(Uuid, f32)>,
pub lexical: Vec<(Uuid, f32)>,
pub scope_exhausted: bool,
}
impl Candidates {
pub fn new(dense: Vec<(Uuid, f32)>, lexical: Vec<(Uuid, f32)>) -> Self {
Self {
dense,
lexical,
scope_exhausted: false,
}
}
}
#[derive(Debug, Clone, Copy)]
pub struct RetrievalTunables {
pub dense_k: usize,
pub lexical_k: usize,
pub fuse_top: usize,
pub rerank_gate: f32,
pub cosine_gate: f32,
pub exhausted_cosine_gate: f32,
pub weights: BlendWeights,
}
impl Default for RetrievalTunables {
fn default() -> Self {
Self {
dense_k: 150,
lexical_k: 150,
fuse_top: 100,
rerank_gate: 0.30,
cosine_gate: blend::MIN_SIMILARITY,
exhausted_cosine_gate: blend::EXHAUSTED_MIN_SIMILARITY,
weights: BlendWeights::default(),
}
}
}
#[derive(Default)]
pub struct Retriever {
pub tunables: RetrievalTunables,
}
pub fn cosine(a: &[f32], b: &[f32]) -> f32 {
if a.len() != b.len() || a.is_empty() {
return 0.0;
}
let dot: f32 = a.iter().zip(b).map(|(x, y)| x * y).sum();
let na: f32 = a.iter().map(|x| x * x).sum::<f32>().sqrt();
let nb: f32 = b.iter().map(|x| x * x).sum::<f32>().sqrt();
if na == 0.0 || nb == 0.0 {
return 0.0;
}
dot / (na * nb)
}
impl Retriever {
pub fn candidates(
&self,
indexes: &Indexes,
store: &SqliteStore,
request: &QueryRequest,
) -> Result<Candidates> {
let source = request.filters.source.as_deref();
let memory_type = request.filters.memory_type;
let project_path = request.filters.project_path.as_deref();
if source.is_some() || memory_type.is_some() || project_path.is_some() {
return self.scoped_candidates(
indexes,
store,
request,
source,
memory_type,
project_path,
);
}
let dense = indexes.vector_search(store, &request.embedding, self.tunables.dense_k)?;
let lexical = indexes.bm25_search(&request.text, self.tunables.lexical_k)?;
Ok(Candidates::new(dense, lexical))
}
#[allow(clippy::too_many_arguments)]
fn scoped_candidates(
&self,
indexes: &Indexes,
store: &SqliteStore,
request: &QueryRequest,
source: Option<&str>,
memory_type: Option<crate::schema::MemoryType>,
project_path: Option<&str>,
) -> Result<Candidates> {
let dense: Vec<(Uuid, f32)> = store
.filtered_vector_search(
&request.embedding,
source,
memory_type,
project_path,
self.tunables.dense_k,
)?
.into_iter()
.map(|(memory, similarity)| (memory.id, similarity))
.collect();
if dense.len() < self.tunables.dense_k {
return Ok(Candidates {
dense,
lexical: Vec::new(),
scope_exhausted: true,
});
}
let scoped = store
.scoped_count(source, memory_type, project_path)?
.max(1);
let total = <SqliteStore as Store>::memory_count(store)?.max(scoped);
let widen = total.div_ceil(scoped);
let k = self
.tunables
.lexical_k
.saturating_mul(widen)
.min(SCOPED_LEXICAL_MAX_K);
let hits = indexes.bm25_search(&request.text, k)?;
let hit_ids: Vec<Uuid> = hits.iter().map(|(id, _)| *id).collect();
let in_scope = store.retain_in_scope(&hit_ids, source, memory_type, project_path)?;
let lexical = hits
.into_iter()
.filter(|(id, _)| in_scope.contains(id))
.take(self.tunables.lexical_k)
.collect();
Ok(Candidates::new(dense, lexical))
}
pub fn rank<S: Store + ?Sized>(
&self,
store: &S,
request: &QueryRequest,
pool: &Candidates,
reranker: Option<&dyn RerankScorer>,
) -> Result<Vec<QueryResult>> {
let dense_ids: Vec<Uuid> = pool.dense.iter().map(|(id, _)| *id).collect();
let lexical_ids: Vec<Uuid> = pool.lexical.iter().map(|(id, _)| *id).collect();
let fused = rrf::fuse(
&[&dense_ids, &lexical_ids],
rrf::RRF_K,
self.tunables.fuse_top,
);
let dense_sim: HashMap<Uuid, f32> = pool.dense.iter().copied().collect();
let mut candidates: Vec<Memory> = Vec::new();
for (id, _) in &fused {
let Some(memory) = store.get_memory_with_embedding(*id)? else {
continue;
};
if memory.tier != crate::schema::Tier::Hot || memory.superseded_by.is_some() {
continue;
}
if let Some(min_conf) = request.filters.min_confidence
&& memory.confidence < min_conf
{
continue;
}
if let Some(ref source) = request.filters.source
&& !store.source_admits(&memory, source)?
{
continue;
}
if let Some(ref mt) = request.filters.memory_type
&& &memory.memory_type != mt
{
continue;
}
candidates.push(memory);
}
let cosine_primaries = |cands: &[Memory]| -> Vec<f32> {
cands
.iter()
.map(|m| {
dense_sim
.get(&m.id)
.copied()
.unwrap_or_else(|| cosine(&request.embedding, &m.embedding))
})
.collect()
};
let (primaries, reranked) = match reranker {
Some(r) => {
let docs: Vec<&str> = candidates.iter().map(|m| m.content.as_str()).collect();
match r.rerank(&request.text, &docs) {
Ok(scores) if scores.len() != docs.len() => anyhow::bail!(
"rerank scorer returned {} scores for {} documents",
scores.len(),
docs.len()
),
Ok(scores) => (scores, true),
Err(e) if e.downcast_ref::<RerankTimeoutError>().is_some() => {
tracing::warn!(
"rerank unavailable ({e}); falling back to the \
non-reranked hybrid path for this query"
);
(cosine_primaries(&candidates), false)
}
Err(e) => return Err(e),
}
}
None => (cosine_primaries(&candidates), false),
};
let cosines = cosine_primaries(&candidates);
let admitted = |i: usize, primary: f32| -> bool {
if pool.scope_exhausted {
cosines[i] >= self.tunables.exhausted_cosine_gate
} else if reranked {
primary >= self.tunables.rerank_gate
} else {
primary >= self.tunables.cosine_gate
}
};
let query_entity_ids = blend::resolve_query_entities(store, &request.filters.entity_names);
let mut shortlist: Vec<(usize, Memory, f32)> = candidates
.into_iter()
.zip(primaries)
.enumerate()
.map(|(i, (memory, primary))| (i, memory, primary))
.collect();
shortlist.sort_by(|a, b| b.2.partial_cmp(&a.2).unwrap_or(std::cmp::Ordering::Equal));
shortlist.truncate(request.limit * 3);
let mut scored: Vec<QueryResult> = Vec::new();
for (i, memory, primary) in shortlist {
if !admitted(i, primary) {
continue;
}
let recency = blend::compute_recency(&memory);
let graph =
blend::compute_graph_relevance(store, &memory, &query_entity_ids).unwrap_or(0.0);
let score = blend::blend(primary, graph, recency, self.tunables.weights);
let score = blend::apply_project_affinity(
score,
&memory,
request.filters.project_path.as_deref(),
);
scored.push(QueryResult {
memory,
score,
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)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::query::QueryFilters;
use crate::schema::{Conversation, Entity, MemoryType, Relation};
use crate::store::Store;
use chrono::Utc;
struct StubStore {
memories: Vec<Memory>,
}
impl Store for StubStore {
fn store_memory(&self, _: &Memory) -> Result<()> {
unimplemented!()
}
fn get_memory(&self, id: Uuid) -> Result<Option<Memory>> {
Ok(self.memories.iter().find(|m| m.id == id).cloned())
}
fn get_memory_with_embedding(&self, id: Uuid) -> Result<Option<Memory>> {
self.get_memory(id)
}
fn delete_memory(&self, _: Uuid) -> Result<()> {
unimplemented!()
}
fn store_entity(&self, _: &Entity) -> Result<()> {
unimplemented!()
}
fn get_entity(&self, _: Uuid) -> Result<Option<Entity>> {
Ok(None)
}
fn find_entity_by_name(&self, _: &str) -> Result<Option<Entity>> {
Ok(None)
}
fn store_conversation(&self, _: &Conversation) -> Result<()> {
unimplemented!()
}
fn store_relation(&self, _: &Relation) -> Result<()> {
unimplemented!()
}
fn get_relations(
&self,
_: Uuid,
_: Option<crate::schema::RelationType>,
) -> Result<Vec<Relation>> {
Ok(Vec::new())
}
fn vector_search(&self, _: &[f32], _: usize) -> Result<Vec<(Memory, f32)>> {
unimplemented!()
}
fn filtered_vector_search(
&self,
embedding: &[f32],
source: Option<&str>,
memory_type: Option<MemoryType>,
project_path: Option<&str>,
limit: usize,
) -> Result<Vec<(Memory, f32)>> {
let mut scored: Vec<(Memory, f32)> = self
.memories
.iter()
.filter(|m| source.is_none_or(|s| m.source == s))
.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)))
.map(|m| (m.clone(), cosine(embedding, &m.embedding)))
.collect();
scored.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
scored.truncate(limit);
Ok(scored)
}
fn traverse(&self, _: Uuid, _: u32) -> Result<Vec<(Memory, Vec<Relation>)>> {
unimplemented!()
}
fn memories_by_source(&self, _: &str) -> Result<Vec<Memory>> {
unimplemented!()
}
fn memories_by_type(&self, _: MemoryType) -> Result<Vec<Memory>> {
unimplemented!()
}
fn update_memory(&self, _: &Memory) -> Result<()> {
unimplemented!()
}
fn record_access(&self, _: &Memory) -> Result<()> {
unimplemented!()
}
fn bm25_search(&self, _: &str, _: usize) -> Result<Vec<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(content: &str, embedding: Vec<f32>) -> Memory {
let mut m = Memory::new(
content.to_string(),
MemoryType::Semantic,
"test".to_string(),
String::new(),
);
m.embedding = embedding;
m
}
fn request(embedding: Vec<f32>) -> QueryRequest {
QueryRequest {
text: "query".to_string(),
embedding,
limit: 10,
filters: QueryFilters::default(),
}
}
#[test]
fn candidate_on_both_lists_outranks_dense_only_at_equal_similarity() {
let both = memory("on both lists", vec![1.0, 0.0]);
let dense_only = memory("dense only", vec![1.0, 0.0]);
let store = StubStore {
memories: vec![both.clone(), dense_only.clone()],
};
let retriever = Retriever::default();
let dense = vec![(dense_only.id, 0.9), (both.id, 0.9)];
let lexical = vec![(both.id, 5.0)];
let results = store_rank(
&retriever,
&store,
&request(vec![1.0, 0.0]),
&dense,
&lexical,
);
assert_eq!(results[0].memory.id, both.id);
}
#[test]
fn low_cosine_candidate_is_gated_out_on_the_no_rerank_path() {
let strong = memory("strong match", vec![1.0, 0.0]);
let weak = memory("weak match", vec![1.0, 0.0]);
let store = StubStore {
memories: vec![strong.clone(), weak.clone()],
};
let retriever = Retriever::default();
let dense = vec![(strong.id, 0.92), (weak.id, 0.45)];
let results = store_rank(&retriever, &store, &request(vec![1.0, 0.0]), &dense, &[]);
assert_eq!(results.len(), 1);
assert_eq!(results[0].memory.id, strong.id);
}
#[test]
fn lexical_only_candidate_gets_cosine_from_stored_embedding() {
let lexical_hit = memory("lexical only", vec![0.6, 0.8]);
let store = StubStore {
memories: vec![lexical_hit.clone()],
};
let retriever = Retriever::default();
let lexical = vec![(lexical_hit.id, 3.0)];
let results = store_rank(&retriever, &store, &request(vec![0.6, 0.8]), &[], &lexical);
assert_eq!(results.len(), 1);
}
#[test]
fn blend_only_reorders_the_primary_shortlist() {
let old = |content: &str, sim: f32| {
let mut m = memory(content, vec![1.0, 0.0]);
m.created_at = Utc::now() - chrono::Duration::days(200);
m.last_accessed = m.created_at;
(m, sim)
};
let (a, a_sim) = old("strong a", 0.95);
let (b, b_sim) = old("strong b", 0.94);
let (c, c_sim) = old("strong c", 0.93);
let fresh = memory("fresh diluter", vec![1.0, 0.0]);
let store = StubStore {
memories: vec![a.clone(), b.clone(), c.clone(), fresh.clone()],
};
let retriever = Retriever::default();
let dense = vec![
(a.id, a_sim),
(b.id, b_sim),
(c.id, c_sim),
(fresh.id, 0.60),
];
let mut req = request(vec![1.0, 0.0]);
req.limit = 1;
let results = retriever
.rank(&store, &req, &Candidates::new(dense, Vec::new()), None)
.unwrap();
assert_eq!(results[0].memory.id, a.id);
}
#[test]
fn source_filter_still_applies() {
let mut filtered = memory("wrong source", vec![1.0, 0.0]);
filtered.source = "other".to_string();
let kept = memory("right source", vec![1.0, 0.0]);
let store = StubStore {
memories: vec![filtered.clone(), kept.clone()],
};
let retriever = Retriever::default();
let mut req = request(vec![1.0, 0.0]);
req.filters.source = Some("test".to_string());
let dense = vec![(filtered.id, 0.9), (kept.id, 0.9)];
let results = store_rank(&retriever, &store, &req, &dense, &[]);
assert_eq!(results.len(), 1);
assert_eq!(results[0].memory.id, kept.id);
}
#[test]
fn archived_and_superseded_candidates_are_dropped_by_rank() {
let live = memory("live", vec![1.0, 0.0]);
let mut archived = memory("archived", vec![1.0, 0.0]);
archived.tier = crate::schema::Tier::Archived;
let mut superseded = memory("superseded", vec![1.0, 0.0]);
superseded.superseded_by = Some(live.id);
let store = StubStore {
memories: vec![live.clone(), archived.clone(), superseded.clone()],
};
let retriever = Retriever::default();
let dense = vec![(archived.id, 0.99), (superseded.id, 0.98), (live.id, 0.9)];
let results = store_rank(&retriever, &store, &request(vec![1.0, 0.0]), &dense, &[]);
let ids: Vec<Uuid> = results.iter().map(|r| r.memory.id).collect();
assert_eq!(ids, vec![live.id]);
}
#[test]
fn an_exhausted_scope_keeps_a_similarity_floor() {
let w = blend::EXHAUSTED_MIN_SIMILARITY + 0.005;
let weak = memory("weak match", vec![w, (1.0f32 - w * w).sqrt()]);
let noise = memory("noise", vec![0.3, (1.0f32 - 0.09).sqrt()]);
let store = StubStore {
memories: vec![weak.clone(), noise.clone()],
};
let retriever = Retriever::default();
let pool = Candidates {
dense: vec![(weak.id, w), (noise.id, 0.3)],
lexical: Vec::new(),
scope_exhausted: true,
};
let results = retriever
.rank(&store, &request(vec![1.0, 0.0]), &pool, None)
.unwrap();
let ids: Vec<Uuid> = results.iter().map(|r| r.memory.id).collect();
assert_eq!(ids, vec![weak.id]);
}
#[test]
fn an_exhausted_scope_gates_on_cosine_even_when_reranked() {
struct LowScorer;
impl RerankScorer for LowScorer {
fn rerank(&self, _: &str, docs: &[&str]) -> Result<Vec<f32>> {
Ok(docs.iter().map(|_| 0.02).collect())
}
}
let w = blend::EXHAUSTED_MIN_SIMILARITY + 0.005;
let weak = memory("weak match", vec![w, (1.0f32 - w * w).sqrt()]);
let noise = memory("noise", vec![0.3, (1.0f32 - 0.09).sqrt()]);
let store = StubStore {
memories: vec![weak.clone(), noise.clone()],
};
let retriever = Retriever::default();
let pool = Candidates {
dense: vec![(weak.id, w), (noise.id, 0.3)],
lexical: Vec::new(),
scope_exhausted: true,
};
let results = retriever
.rank(&store, &request(vec![1.0, 0.0]), &pool, Some(&LowScorer))
.unwrap();
let ids: Vec<Uuid> = results.iter().map(|r| r.memory.id).collect();
assert_eq!(ids, vec![weak.id]);
}
fn store_rank(
retriever: &Retriever,
store: &StubStore,
request: &QueryRequest,
dense: &[(Uuid, f32)],
lexical: &[(Uuid, f32)],
) -> Vec<QueryResult> {
retriever
.rank(
store,
request,
&Candidates::new(dense.to_vec(), lexical.to_vec()),
None,
)
.unwrap()
}
}