Skip to content

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

Rust

feat(retrieval): surface the typed edge kind in graph explain (P3)

AkitaOnRails20e06ab2f0eb
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8164f67e..048cfeda 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- Retrieval `explain` now names the **typed edge** a graph-stream neighbour
+ was reached by: `memory_query(explain=true)` reports `graph_via.edge` =
+ `causes` / `fixes` / `contradicts` (omitted for a plain `references` link), so
+ it is visible *why* a page surfaced through the link graph. Retrieval ranking
+ is unchanged — this is explanation only; typed-edge weighting and `contradicts`
+ capping are deferred behind the eval harness (docs/design-hindsight-borrowings.md P3).
- Page-grain ingestion windows (`pages.valid_from` / `valid_to`, V62) and
a second `as_of` stream: `memory_query(as_of=T)` now fuses the entity
timeline with version-filtered full-text search over the page versions
diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rs
index 775f974a..44530b72 100644
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@ -2891,6 +2891,8 @@ mod tests {
let via = target_details.graph_via.as_ref().unwrap();
assert_eq!(via.seed_path, "source.md");
assert_eq!(via.direction, "outgoing");
+ // P3: a plain `references` link carries no typed edge kind.
+ assert_eq!(via.edge.as_deref(), None);
for (hit, details) in [(source_hit, source_details), (target_hit, target_details)] {
let authority = details.authority.unwrap();
@@ -2956,6 +2958,70 @@ mod tests {
);
}
+ /// P3 (docs/design-hindsight-borrowings.md): a typed edge (`fixes`) is
+ /// surfaced as the graph_via `edge` kind in explain. Ranking is untouched;
+ /// only the explanation names why the neighbour was reached.
+ #[tokio::test]
+ async fn graph_via_reports_the_typed_edge_kind() {
+ let tmp = TempDir::new().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let ws = store
+ .writer
+ .get_or_create_workspace("default")
+ .await
+ .unwrap();
+ let proj = store
+ .writer
+ .get_or_create_project(ws, "ai-memory", None)
+ .await
+ .unwrap();
+
+ store
+ .writer
+ .upsert_page(sample_page(ws, proj, "target.md", "neighbor-only content"))
+ .await
+ .unwrap();
+ let mut source = sample_page(ws, proj, "source.md", "needle source content");
+ source.links = vec![ai_memory_core::LinkTarget {
+ workspace: None,
+ project: None,
+ path: PagePath::new("target.md").unwrap(),
+ relation: Some(ai_memory_core::Relation::Fixes),
+ }];
+ store.writer.upsert_page(source).await.unwrap();
+
+ let explained = store
+ .reader
+ .hybrid_search_explained(
+ ws,
+ proj,
+ "needle".into(),
+ None,
+ String::new(),
+ String::new(),
+ 0,
+ 10,
+ None,
+ )
+ .await
+ .unwrap();
+
+ let (_, target_details) = explained
+ .iter()
+ .find(|(hit, _)| hit.path.as_str() == "target.md")
+ .expect("the fixes-linked neighbour must surface via the graph stream");
+ let via = target_details
+ .graph_via
+ .as_ref()
+ .expect("target reached via the graph stream");
+ assert_eq!(via.seed_path, "source.md");
+ assert_eq!(
+ via.edge.as_deref(),
+ Some("fixes"),
+ "the typed edge kind must be reported in explain"
+ );
+ }
+
/// P2 (docs/design-hindsight-borrowings.md §3), ship scope for 2.2.0:
/// evidence is substrate + explain surfacing ONLY. `hybrid_search_explained`
/// reports `evidence_count`, but citing a page from two distinct sessions
diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rs
index 880916fb..536af8ee 100644
--- a/crates/ai-memory-store/src/reader.rs
+++ b/crates/ai-memory-store/src/reader.rs
@@ -502,6 +502,10 @@ struct GraphNeighbor {
seed_ord: usize,
/// `true` when the neighbour links TO the seed (backlink).
incoming: bool,
+ /// The typed edge the neighbour was reached by (`causes` / `fixes` /
+ /// `contradicts`), or `None` for a plain `references` link. Informational
+ /// only — it is surfaced in `explain` and does not affect ranking.
+ edge: Option<String>,
}
/// Which seed page pulled a hit in via graph expansion, and the link
@@ -513,6 +517,12 @@ pub struct GraphVia {
/// `outgoing` = seed links to the hit; `incoming` = hit links to
/// the seed (backlink).
pub direction: &'static str,
+ /// The typed edge kind followed (`causes` / `fixes` / `contradicts`),
+ /// omitted for a plain `references` link. Informational: it explains *why*
+ /// a neighbour surfaced; it does not weight ranking (typed-edge weighting
+ /// and `contradicts` capping are deferred behind the eval harness).
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub edge: Option<String>,
}
/// Per-stream RRF contributions (`1/(k+rank)`, k=60) for one hit.
@@ -4263,7 +4273,8 @@ impl ReaderPool {
neighbors AS ( \
SELECT tp.id AS id, tp.path AS path, tp.title AS title, \
{out_descriptor} AS snippet, \
- seeds.seed_ord * 2 AS stream_ord, tp.updated_at AS updated_at \
+ seeds.seed_ord * 2 AS stream_ord, tp.updated_at AS updated_at, \
+ l.link_type AS link_type \
FROM seeds \
JOIN links l ON l.from_page_id = seeds.seed_id \
JOIN pages tp ON tp.id = l.to_page_id \
@@ -4271,13 +4282,14 @@ impl ReaderPool {
UNION ALL \
SELECT fp.id AS id, fp.path AS path, fp.title AS title, \
{in_descriptor} AS snippet, \
- seeds.seed_ord * 2 + 1 AS stream_ord, fp.updated_at AS updated_at \
+ seeds.seed_ord * 2 + 1 AS stream_ord, fp.updated_at AS updated_at, \
+ l.link_type AS link_type \
FROM seeds \
JOIN links l ON l.to_page_id = seeds.seed_id \
JOIN pages fp ON fp.id = l.from_page_id \
WHERE fp.workspace_id = ? AND fp.project_id = ? AND fp.is_latest = 1{in_not_expired} \
) \
- SELECT id, path, title, snippet, stream_ord \
+ SELECT id, path, title, snippet, stream_ord, link_type \
FROM neighbors \
WHERE NOT EXISTS (SELECT 1 FROM seeds s WHERE s.seed_id = neighbors.id) \
ORDER BY stream_ord ASC, updated_at DESC, path ASC"
@@ -4291,11 +4303,12 @@ impl ReaderPool {
let title: String = row.get(2)?;
let snippet = page_descriptor(&row.get::<_, String>(3)?, &title);
let stream_ord: i64 = row.get(4)?;
- Ok((id_bytes, path, title, snippet, stream_ord))
+ let link_type: String = row.get(5)?;
+ Ok((id_bytes, path, title, snippet, stream_ord, link_type))
})?;
for row in rows {
- let (id_bytes, path, title, snippet, stream_ord) = row?;
+ let (id_bytes, path, title, snippet, stream_ord, link_type) = row?;
let id = PageId::from_slice(&id_bytes)?;
if !seen.insert(id) {
continue;
@@ -4312,6 +4325,7 @@ impl ReaderPool {
},
seed_ord,
incoming: stream_ord % 2 == 1,
+ edge: (link_type != "references").then_some(link_type),
});
if out.len() >= limit {
break;
@@ -4851,6 +4865,7 @@ impl ReaderPool {
.cloned()
.unwrap_or_default(),
direction: if n.incoming { "incoming" } else { "outgoing" },
+ edge: n.edge.clone(),
});
details.rrf.graph = contrib;
details.fused += contrib;