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.mdindex 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) anda second `as_of` stream: `memory_query(as_of=T)` now fuses the entitytimeline with version-filtered full-text search over the page versionsdiff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex 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 sessionsdiff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsindex 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;