Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(search): hydrate vector-ranked hits that fusion left undescribed (#488)

Fabio Akita84872ce61d66
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b04e8ee1..2c5e04a7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
expiry remains a more specific instruction than a pin. A `tools/list`
assertion pins the wording so a fourth pass cannot silently make it stale
again. Reported by @samirhvbr (#485).
+- Hits ranked by the vector stream returned an empty `title` and `snippet`,
+ even when the entity or graph stream had also found the page and already
+ computed a real descriptor for it. The fusion map is built with
+ `or_insert_with` and the vector loop only has `(PageId, PagePath, f32)` to
+ insert, so first-writer-wins left the entry empty and nothing downstream
+ repaired it. Beyond the empty display, `title` and `snippet` are the
+ reranker's candidate text, so an affected page was scored as an empty
+ document and could then be truncated out of the results a reranker was
+ meant to improve. Fused hits that still lack a title are now hydrated in
+ one bounded lookup; hits another stream already described keep that
+ stream's snippet, so an FTS excerpt centred on the matched term is not
+ downgraded to a generic descriptor. Affects instances with an embedding
+ provider configured. Reported by @samirhvbr (#486).
## [1.32.0] - 2026-08-24
diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rs
index d55163df..83e147e6 100644
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@ -2753,6 +2753,15 @@ mod tests {
assert_eq!(source_details.fts_rank, Some(1));
assert!(source_details.vector_rank.is_none());
assert!(source_details.graph_rank.is_none());
+ // #486: the hydrate must fill only what is empty. An FTS hit carries
+ // a `snippet()` excerpt centred on the matched term, which is more
+ // useful than the generic page descriptor — re-describing every hit
+ // would quietly downgrade it, so the fix keys on an empty title.
+ assert!(
+ source_hit.snippet.contains("needle"),
+ "an FTS hit must keep its term-centred excerpt, got {:?}",
+ source_hit.snippet
+ );
let (target_hit, target_details) = explained
.iter()
@@ -2805,6 +2814,28 @@ mod tests {
assert_eq!(target_vector_details.vector_rank, Some(1));
assert_eq!(target_vector_details.cosine, Some(1.0));
assert!(target_vector_details.rrf.vector > 0.0);
+
+ // #486: a hit the vector stream ranked must still be describable.
+ // The fusion map is built with `or_insert_with` and the vector loop
+ // has only `(PageId, PagePath, f32)` to insert, so before the
+ // post-fusion hydrate these came back as empty strings — and with a
+ // reranker enabled an empty candidate is scored as an empty document
+ // and can be truncated away. This test previously asserted the rank
+ // and nothing about what the caller actually receives.
+ let (target_vector_hit, _) = vector_explained
+ .iter()
+ .find(|(hit, _)| hit.path.as_str() == "target.md")
+ .unwrap();
+ assert!(
+ !target_vector_hit.title.is_empty(),
+ "a vector-ranked hit must carry a title, got {:?}",
+ target_vector_hit.title
+ );
+ assert!(
+ !target_vector_hit.snippet.is_empty(),
+ "a vector-ranked hit must carry a snippet, got {:?}",
+ target_vector_hit.snippet
+ );
}
#[tokio::test]
diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rs
index b67ebe2d..297887a8 100644
--- a/crates/ai-memory-store/src/reader.rs
+++ b/crates/ai-memory-store/src/reader.rs
@@ -3522,6 +3522,73 @@ impl ReaderPool {
.await
}
+ /// Title and descriptor for a bounded set of already-fused page ids
+ /// (#486).
+ ///
+ /// The vector stream returns `(PageId, PagePath, f32)` and nothing else,
+ /// so a page it reaches first is inserted into the fusion map with empty
+ /// strings and — because every fusion site uses `or_insert_with` — stays
+ /// empty even when entity or graph later find it with a real descriptor
+ /// already computed.
+ ///
+ /// Deliberately a post-fusion lookup rather than a wider embedding query.
+ /// `top_embedding_hits_for_project` has no SQL `LIMIT`: it scores every
+ /// embedded page in the project in Rust and takes top-k afterwards, so a
+ /// descriptor column there would compute one for the whole corpus on
+ /// every search. Here the input is only the handful of ids that survived
+ /// fusion and still lack a title.
+ async fn page_descriptors_for_ids(
+ &self,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ page_ids: Vec<PageId>,
+ ) -> StoreResult<std::collections::HashMap<PageId, (String, String)>> {
+ if page_ids.is_empty() {
+ return Ok(std::collections::HashMap::new());
+ }
+ self.with_conn(move |conn| {
+ let mut values_clause = String::with_capacity(page_ids.len() * 5);
+ let mut sql_params = Vec::with_capacity(page_ids.len() + 2);
+ for (idx, page_id) in page_ids.iter().enumerate() {
+ if idx > 0 {
+ values_clause.push_str(", ");
+ }
+ values_clause.push_str("(?)");
+ sql_params.push(Value::Blob(page_id.as_bytes().to_vec()));
+ }
+ sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));
+ sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));
+
+ let sql = format!(
+ "WITH requested(id) AS (VALUES {values_clause}) \
+ SELECT pages.id, pages.title, {descriptor} AS descriptor \
+ FROM requested \
+ JOIN pages ON pages.id = requested.id \
+ WHERE pages.workspace_id = ? \
+ AND pages.project_id = ? \
+ AND pages.is_latest = 1",
+ descriptor = page_descriptor_expr("pages.body", "pages.frontmatter_json"),
+ );
+ let mut stmt = conn.prepare(&sql)?;
+ let rows = stmt.query_map(params_from_iter(sql_params.iter()), |row| {
+ let id_bytes: Vec<u8> = row.get(0)?;
+ let title: String = row.get(1)?;
+ let descriptor: String = row.get(2)?;
+ Ok((id_bytes, title, descriptor))
+ })?;
+
+ let mut out = std::collections::HashMap::new();
+ for row in rows {
+ let (id_bytes, title, descriptor) = row?;
+ if let Ok(id) = PageId::from_slice(&id_bytes) {
+ out.insert(id, (title, descriptor));
+ }
+ }
+ Ok(out)
+ })
+ .await
+ }
+
async fn page_authorities_for_project(
&self,
workspace_id: WorkspaceId,
@@ -3872,6 +3939,26 @@ impl ReaderPool {
)
})
.collect();
+ // #486: fill in hits the vector stream reached first. Only those with
+ // an empty title are looked up — a page fts, entity or graph already
+ // described keeps the descriptor those streams computed, which is the
+ // whole reason not to recompute it here.
+ let undescribed: Vec<PageId> = out
+ .iter()
+ .filter_map(|(hit, _)| hit.title.is_empty().then_some(hit.id))
+ .collect();
+ if !undescribed.is_empty() {
+ let descriptors = self
+ .page_descriptors_for_ids(workspace_id, project_id, undescribed)
+ .await?;
+ for (hit, _) in &mut out {
+ if let Some((title, descriptor)) = descriptors.get(&hit.id) {
+ hit.title = title.clone();
+ hit.snippet = descriptor.clone();
+ }
+ }
+ }
+
let missing_authorities: Vec<PageId> = out
.iter()
.filter_map(|(hit, _)| (!authorities.contains_key(&hit.id)).then_some(hit.id))