Skip to content

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

Rust

feat(query): add opt-in include_superseded to memory_query

AkitaOnRails4c0b0c48ab97
diff --git a/CHANGELOG.md b/CHANGELOG.md
index aedb30ba..82cbf796 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Added
+- `memory_query` gained an opt-in `include_superseded` argument (default false;
+ targets the 2.4 line). When set, project and explicit-scope searches also
+ return superseded (older) page versions across the FTS/entity/vector/graph
+ streams, each hit labelled `superseded: true` so callers can tell historical
+ versions from the current one; the current version is never marked. Default-off
+ behaviour is byte-identical to the previous latest-only retrieval, and
+ `global=true` and `as_of` time-travel are unaffected (#NNN).
+
### Fixed
- The generated OpenCode and OpenCode 2 plugins now forward a subagent session's
`parentID` as the `agent_id` marker, so `[capture] drop_subagent_captures` can
diff --git a/crates/ai-memory-consolidate/tests/suite/embeddings.rs b/crates/ai-memory-consolidate/tests/suite/embeddings.rs
index 5120f9f2..b296a468 100644
--- a/crates/ai-memory-consolidate/tests/suite/embeddings.rs
+++ b/crates/ai-memory-consolidate/tests/suite/embeddings.rs
@@ -142,6 +142,7 @@ async fn m9_embeddings_roundtrip_via_synthetic() {
64,
5,
None,
+ false,
)
.await
.expect("hybrid search");
@@ -169,6 +170,7 @@ async fn m9_embeddings_roundtrip_via_synthetic() {
64,
5,
None,
+ false,
)
.await
.expect("hybrid (no query vec)");
diff --git a/crates/ai-memory-consolidate/tests/suite/local_embeddings.rs b/crates/ai-memory-consolidate/tests/suite/local_embeddings.rs
index 97f3c765..00a61187 100644
--- a/crates/ai-memory-consolidate/tests/suite/local_embeddings.rs
+++ b/crates/ai-memory-consolidate/tests/suite/local_embeddings.rs
@@ -153,6 +153,7 @@ async fn paraphrase_recall_fts_alone_cannot_do() {
384,
4,
None,
+ false,
)
.await
.unwrap();
@@ -189,6 +190,7 @@ async fn paraphrase_recall_fts_alone_cannot_do() {
384,
4,
None,
+ false,
)
.await
.unwrap();
diff --git a/crates/ai-memory-consolidate/tests/suite/recall_eval.rs b/crates/ai-memory-consolidate/tests/suite/recall_eval.rs
index 8ddacfad..1a78e3e6 100644
--- a/crates/ai-memory-consolidate/tests/suite/recall_eval.rs
+++ b/crates/ai-memory-consolidate/tests/suite/recall_eval.rs
@@ -243,6 +243,7 @@ async fn graph_neighbor_expansion_recovers_linked_page() {
0,
5,
None,
+ false,
)
.await
.expect("hybrid search");
@@ -318,6 +319,7 @@ async fn entity_stream_recovers_a_probe_fts_and_graph_both_miss() {
0,
5,
None,
+ false,
)
.await
.expect("hybrid search");
@@ -419,6 +421,7 @@ async fn measure_recall(
emb.dim(),
5,
None,
+ false,
)
.await
.expect("hybrid search")
diff --git a/crates/ai-memory-consolidate/tests/suite/search_quality.rs b/crates/ai-memory-consolidate/tests/suite/search_quality.rs
index b77be865..a61a53a2 100644
--- a/crates/ai-memory-consolidate/tests/suite/search_quality.rs
+++ b/crates/ai-memory-consolidate/tests/suite/search_quality.rs
@@ -93,6 +93,7 @@ async fn fts(
0,
10,
None,
+ false,
)
.await
.unwrap()
diff --git a/crates/ai-memory-core/src/routing_skills/ai-memory-retrieval/SKILL.md b/crates/ai-memory-core/src/routing_skills/ai-memory-retrieval/SKILL.md
index a636cb90..13893288 100644
--- a/crates/ai-memory-core/src/routing_skills/ai-memory-retrieval/SKILL.md
+++ b/crates/ai-memory-core/src/routing_skills/ai-memory-retrieval/SKILL.md
@@ -49,6 +49,13 @@ Expired pages are excluded from project, sibling-scope, and global searches by
default. Pass `include_expired: true` only when the user explicitly asks to
inspect expired historical memory; do not broaden ordinary recall to stale data.
+Superseded (older) page versions are excluded by default; only the current
+version of each page is returned. Pass `include_superseded: true` when the user
+wants a page's history, or an answer that a later edit removed. Each older hit is
+labelled `superseded: true` so you can tell it from the live version; the current
+version is never marked. This applies to project and explicit-scope searches;
+`global=true` search and `as_of` time-travel are unaffected.
+
Use `explain: true` only when the user asks why project or explicit-scope hits
ranked as they did. It adds FTS, lexical entity, optional vector, and graph
score provenance to compiled-page hits, including matched entity names.
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index e1b78c22..a55ec518 100644
--- a/crates/ai-memory-mcp/src/server.rs
+++ b/crates/ai-memory-mcp/src/server.rs
@@ -203,7 +203,10 @@ developer, user, and canonical project instructions.\n\
reserved `_global` scope; treat them as context that applies to \
every project. Expired pages are hidden by default; use \
`include_expired=true` only when the user explicitly wants to inspect \
- expired historical memory. Use `explain=true` only when diagnosing \
+ expired historical memory. Superseded (older) page versions are hidden \
+ by default; pass `include_superseded=true` when the user wants a page's \
+ history or an answer a later edit removed — each older hit is labelled \
+ `superseded: true`. Use `explain=true` only when diagnosing \
project/scopes ranking; it adds score provenance, while global search \
reports only its distinct FTS stream.\n\
- `memory_recent` — at session start, or when the user asks 'what's \
@@ -548,6 +551,13 @@ struct QueryArgs {
/// default; they are deleted by the next forget sweep). Default false.
#[serde(default)]
include_expired: Option<bool>,
+ /// Also return superseded (older) page versions, not just the current
+ /// one. Each superseded hit is labelled `superseded: true` so you can
+ /// tell it from the live version. Use when you need the history of a
+ /// page or an answer that a later edit removed. Ignored on `global`
+ /// search and folded into `as_of` time-travel. Default false.
+ #[serde(default)]
+ include_superseded: Option<bool>,
/// Attach `score_details` to project/scopes hits: per-stream ranks
/// (FTS5, entity, vector, graph), raw scores, and RRF contributions, plus a
/// top-level `streams_active` list. A `global=true` query uses a
@@ -623,6 +633,7 @@ struct ProjectSearchOptions<'a> {
limit: usize,
include_expired: bool,
explain: bool,
+ include_superseded: bool,
}
#[derive(Debug, Serialize)]
@@ -1765,6 +1776,7 @@ impl AiMemoryServer {
dim,
options.limit,
expiry_cutoff,
+ options.include_superseded,
)
.await?
.into_iter()
@@ -1782,6 +1794,7 @@ impl AiMemoryServer {
dim,
options.limit,
expiry_cutoff,
+ options.include_superseded,
)
.await?
.into_iter()
@@ -2023,6 +2036,7 @@ impl AiMemoryServer {
let aps_actor = Self::actor_key_from_parts(Some(&parts));
let limit = args.limit.unwrap_or(self.default_limit).clamp(1, 100);
let include_expired = args.include_expired.unwrap_or(false);
+ let include_superseded = args.include_superseded.unwrap_or(false);
let explain = args.explain.unwrap_or(false);
// A repo that opted into `[recall] default_global` (published on the
// ActiveProject by the hook) makes a query with NO explicit scoping
@@ -2154,6 +2168,7 @@ impl AiMemoryServer {
limit: candidate_limit,
include_expired,
explain,
+ include_superseded,
},
)
.await
@@ -2197,6 +2212,7 @@ impl AiMemoryServer {
limit: candidate_limit,
include_expired,
explain,
+ include_superseded,
},
)
.await
@@ -2281,6 +2297,7 @@ impl AiMemoryServer {
limit,
include_expired,
explain,
+ include_superseded,
},
)
.await
@@ -5272,6 +5289,7 @@ mod tests {
title: format!("Page {idx}"),
snippet: format!("candidate {idx}"),
rank: idx as f64,
+ superseded: false,
},
Some(ai_memory_store::SearchExplain::default()),
)
@@ -5468,6 +5486,7 @@ mod tests {
],
global: None,
include_expired: None,
+ include_superseded: None,
explain: Some(true),
as_of: None,
}),
@@ -5499,6 +5518,7 @@ mod tests {
scopes: Vec::new(),
global: Some(true),
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
}),
@@ -7226,6 +7246,7 @@ mod tests {
workspace: Some("default".into()),
global,
include_expired: None,
+ include_superseded: None,
explain: Some(true),
as_of,
};
@@ -7264,6 +7285,7 @@ mod tests {
workspace: Some("default".into()),
global: None,
include_expired: None,
+ include_superseded: None,
explain: Some(true),
as_of: Some(jiff::Timestamp::now().to_string()),
}),
@@ -7333,6 +7355,7 @@ mod tests {
workspace: None,
global: None,
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
}),
@@ -7358,6 +7381,7 @@ mod tests {
workspace: None,
global: None,
include_expired: None,
+ include_superseded: None,
explain: Some(true),
as_of: None,
}),
@@ -7451,6 +7475,7 @@ mod tests {
workspace: None,
global: None,
include_expired: None,
+ include_superseded: None,
explain: Some(true),
as_of: None,
}),
@@ -7538,6 +7563,7 @@ mod tests {
workspace: workspace.map(str::to_string),
global: None,
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
};
@@ -7615,6 +7641,7 @@ mod tests {
workspace: None,
global: None,
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
}),
@@ -7743,6 +7770,7 @@ mod tests {
workspace: None,
global: None,
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
}),
@@ -7822,6 +7850,7 @@ mod tests {
workspace: None,
global: None,
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
}),
@@ -7917,6 +7946,7 @@ mod tests {
workspace: None,
global: None,
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
}),
@@ -7983,6 +8013,7 @@ mod tests {
workspace: None,
global: None,
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
}),
@@ -8025,6 +8056,7 @@ mod tests {
workspace: None,
global: None,
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
}),
@@ -8100,6 +8132,7 @@ mod tests {
workspace: None,
global: None,
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
}),
@@ -8166,6 +8199,7 @@ mod tests {
workspace: Some("practice".into()),
global: None,
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
}),
@@ -9209,6 +9243,7 @@ mod tests {
workspace: None,
global: None,
include_expired: None,
+ include_superseded: None,
explain: Some(true),
as_of: None,
}),
@@ -9318,6 +9353,7 @@ mod tests {
workspace: None,
global: Some(true),
include_expired: None,
+ include_superseded: None,
explain: Some(true),
as_of: None,
}),
@@ -9365,6 +9401,7 @@ mod tests {
workspace: None,
global: Some(true),
include_expired: Some(true),
+ include_superseded: None,
explain: None,
as_of: None,
}),
@@ -9445,6 +9482,7 @@ mod tests {
workspace: None,
global: None,
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
}),
@@ -9477,6 +9515,7 @@ mod tests {
workspace: Some("ops".into()),
global: None,
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
}),
@@ -9513,6 +9552,7 @@ mod tests {
workspace: None,
global: Some(true),
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
}),
@@ -12378,6 +12418,7 @@ mod tests {
workspace: None,
global: None,
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
}),
@@ -12412,6 +12453,7 @@ mod tests {
workspace: None,
global: None,
include_expired: None,
+ include_superseded: None,
explain: None,
as_of: None,
}),
diff --git a/crates/ai-memory-mcp/tests/suite/mod.rs b/crates/ai-memory-mcp/tests/suite/mod.rs
index b7472719..42ee7b84 100644
--- a/crates/ai-memory-mcp/tests/suite/mod.rs
+++ b/crates/ai-memory-mcp/tests/suite/mod.rs
@@ -22,6 +22,7 @@ mod autoscope_multiuser;
mod handoff_admission;
mod handoff_identity;
mod mcp_stateless_http;
+mod query_superseded;
mod retrieval_via_tools;
mod slot_identity;
mod stress_autoscope;
diff --git a/crates/ai-memory-mcp/tests/suite/query_superseded.rs b/crates/ai-memory-mcp/tests/suite/query_superseded.rs
new file mode 100644
index 00000000..091fb0e0
--- /dev/null
+++ b/crates/ai-memory-mcp/tests/suite/query_superseded.rs
@@ -0,0 +1,233 @@
+//! `memory_query(include_superseded=true)` retrieval, proven end to end
+//! through the real MCP tool. Superseded page versions are hidden by default;
+//! the opt-in flag returns them too, each labelled `superseded: true` in the
+//! user-visible JSON. Default-off behaviour must be unchanged.
+//!
+//! This mirrors the superseded-version setup in `retrieval_via_tools.rs`
+//! (`upsert_page` twice on one path), but exercises the plain-query
+//! `include_superseded` path rather than the `as_of` time-travel path.
+
+use ai_memory_core::{NewPage, PagePath, ProjectId, Tier, WorkspaceId};
+use ai_memory_mcp::AiMemoryServer;
+use ai_memory_store::Store;
+use ai_memory_wiki::Wiki;
+use axum::Router;
+use axum::body::Body;
+use axum::http::Request;
+use rmcp::transport::streamable_http_server::session::local::LocalSessionManager;
+use rmcp::transport::streamable_http_server::{StreamableHttpServerConfig, StreamableHttpService};
+use serde_json::{Value, json};
+use tempfile::TempDir;
+use tower::ServiceExt;
+
+const WS: &str = "default";
+const PROJ: &str = "scratch";
+
+struct Harness {
+ router: Router,
+ store: Store,
+ ws: WorkspaceId,
+ proj: ProjectId,
+ _tmp: TempDir,
+}
+
+fn mount(server: AiMemoryServer) -> Router {
+ let service = StreamableHttpService::new(
+ move || Ok(server.clone()),
+ LocalSessionManager::default().into(),
+ StreamableHttpServerConfig::default()
+ .with_stateful_mode(false)
+ .with_json_response(true),
+ );
+ Router::new().nest_service("/mcp", service)
+}
+
+async fn harness() -> Harness {
+ let tmp = TempDir::new().expect("tempdir");
+ let store = Store::open(tmp.path()).expect("store");
+ let ws = store.writer.get_or_create_workspace(WS).await.expect("ws");
+ let proj = store
+ .writer
+ .get_or_create_project(ws, PROJ, None)
+ .await
+ .expect("proj");
+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).expect("wiki");
+ let server =
+ AiMemoryServer::new(store.reader.clone(), store.writer.clone(), ws, proj).with_wiki(wiki);
+
+ Harness {
+ router: mount(server),
+ store,
+ ws,
+ proj,
+ _tmp: tmp,
+ }
+}
+
+async fn call(router: &Router, name: &str, arguments: Value) -> Value {
+ let body = json!({
+ "jsonrpc": "2.0",
+ "id": 1,
+ "method": "tools/call",
+ "params": { "name": name, "arguments": arguments },
+ });
+ let req = Request::builder()
+ .method("POST")
+ .uri("/mcp")
+ .header("host", "localhost")
+ .header("content-type", "application/json")
+ .header("accept", "application/json, text/event-stream")
+ .body(Body::from(body.to_string()))
+ .expect("mcp req");
+ let resp = router.clone().oneshot(req).await.expect("oneshot");
+ let bytes = axum::body::to_bytes(resp.into_body(), 4_000_000)
+ .await
+ .expect("body");
+ let text = String::from_utf8(bytes.to_vec()).expect("utf8");
+ let v: Value = serde_json::from_str(&text).unwrap_or_else(|e| panic!("non-JSON: {text}: {e}"));
+ if let Some(err) = v.get("error") {
+ panic!("JSON-RPC error: {err}\nfull: {text}");
+ }
+ let joined = v
+ .pointer("/result/content")
+ .and_then(|c| c.as_array())
+ .unwrap_or_else(|| panic!("missing result.content: {text}"))
+ .iter()
+ .filter_map(|i| i.get("text").and_then(|t| t.as_str()))
+ .collect::<Vec<_>>()
+ .join("\n");
+ serde_json::from_str(&joined).unwrap_or_else(|e| panic!("tool text not JSON: {joined}: {e}"))
+}
+
+fn page(ws: WorkspaceId, proj: ProjectId, path: &str, title: &str, body: &str) -> NewPage {
+ NewPage {
+ workspace_id: ws,
+ project_id: proj,
+ path: PagePath::new(path).unwrap(),
+ title: title.into(),
+ body: body.into(),
+ tier: Tier::Semantic,
+ frontmatter_json: serde_json::json!({}),
+ pinned: false,
+ links: Vec::new(),
+ author_id: None,
+ expires_at: None,
+ entities: Vec::new(),
+ evidence: Vec::new(),
+ }
+}
+
+fn hits(resp: &Value) -> &Vec<Value> {
+ resp.get("hits")
+ .and_then(|h| h.as_array())
+ .unwrap_or_else(|| panic!("no hits array: {resp}"))
+}
+
+fn hit_for<'a>(resp: &'a Value, path: &str) -> Option<&'a Value> {
+ hits(resp)
+ .iter()
+ .find(|h| h.get("path").and_then(|p| p.as_str()) == Some(path))
+}
+
+fn query_args(query: &str, extra: Value) -> Value {
+ let mut base = json!({
+ "query": query,
+ "workspace": WS,
+ "project": PROJ,
+ "limit": 10,
+ });
+ let obj = base.as_object_mut().unwrap();
+ for (k, v) in extra.as_object().unwrap() {
+ obj.insert(k.clone(), v.clone());
+ }
+ base
+}
+
+/// The superseded version carries a term the latest version dropped. A plain
+/// query never returns it; `include_superseded=true` does, marked.
+#[tokio::test]
+async fn memory_query_include_superseded_returns_marked_historical_version() {
+ let h = harness().await;
+
+ // v1 mentions `postgres`; v2 supersedes it and drops the term.
+ let mut p = page(h.ws, h.proj, "notes/db.md", "DB", "we use postgres");
+ h.store.writer.upsert_page(p.clone()).await.unwrap();
+ p.body = "we migrated to sqlite".into();
+ h.store.writer.upsert_page(p).await.unwrap();
+
+ // Default: the superseded-only term does not surface.
+ let now = call(&h.router, "memory_query", query_args("postgres", json!({}))).await;
+ assert!(
+ hit_for(&now, "notes/db.md").is_none(),
+ "a plain query must not return the superseded version: {now}"
+ );
+
+ // include_superseded=true: the historical version answers, labelled.
+ let historical = call(
+ &h.router,
+ "memory_query",
+ query_args("postgres", json!({ "include_superseded": true })),
+ )
+ .await;
+ let hit = hit_for(&historical, "notes/db.md")
+ .expect("the superseded version must answer when include_superseded=true");
+ assert_eq!(
+ hit.get("superseded").and_then(|s| s.as_bool()),
+ Some(true),
+ "the historical hit must be labelled superseded: {hit}"
+ );
+}
+
+/// The latest version is unchanged and unmarked whether or not the flag is set;
+/// the flag only adds the historical version alongside it.
+#[tokio::test]
+async fn memory_query_latest_version_is_never_marked_superseded() {
+ let h = harness().await;
+
+ // A shared token matches both versions.
+ let mut p = page(h.ws, h.proj, "notes/db.md", "DB", "zebraquux postgres");
+ h.store.writer.upsert_page(p.clone()).await.unwrap();
+ p.body = "zebraquux sqlite".into();
+ h.store.writer.upsert_page(p).await.unwrap();
+
+ // Default: exactly one hit, the latest, not marked.
+ let now = call(
+ &h.router,
+ "memory_query",
+ query_args("zebraquux", json!({})),
+ )
+ .await;
+ assert_eq!(
+ hits(&now).len(),
+ 1,
+ "default returns only the latest: {now}"
+ );
+ let latest = hit_for(&now, "notes/db.md").expect("latest must be present");
+ // Absent (skipped) or explicitly false both mean "not superseded".
+ assert_ne!(
+ latest.get("superseded").and_then(|s| s.as_bool()),
+ Some(true),
+ "the latest version must not be marked superseded: {latest}"
+ );
+
+ // Opt-in: both versions present; the latest still unmarked, one marked.
+ let both = call(
+ &h.router,
+ "memory_query",
+ query_args("zebraquux", json!({ "include_superseded": true })),
+ )
+ .await;
+ assert_eq!(
+ hits(&both).len(),
+ 2,
+ "include_superseded returns both versions: {both}"
+ );
+ let marked = hits(&both)
+ .iter()
+ .filter(|h| h.get("superseded").and_then(|s| s.as_bool()) == Some(true))
+ .count();
+ assert_eq!(
+ marked, 1,
+ "exactly one version is marked superseded: {both}"
+ );
+}
diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rs
index 6d7f58b3..04714625 100644
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@ -2349,6 +2349,7 @@ mod tests {
0,
1,
None,
+ false,
)
.await
.unwrap();
@@ -2547,6 +2548,7 @@ mod tests {
0,
10,
None,
+ false,
)
.await
.unwrap();
@@ -2836,6 +2838,7 @@ mod tests {
0,
10,
None,
+ false,
)
.await
.unwrap();
@@ -2858,6 +2861,7 @@ mod tests {
0,
10,
None,
+ false,
)
.await
.unwrap();
@@ -2925,6 +2929,7 @@ mod tests {
2,
10,
None,
+ false,
)
.await
.unwrap();
@@ -3003,6 +3008,7 @@ mod tests {
0,
10,
None,
+ false,
)
.await
.unwrap();
@@ -3061,6 +3067,7 @@ mod tests {
0,
10,
None,
+ false,
)
.await
.unwrap();
@@ -3100,6 +3107,7 @@ mod tests {
0,
10,
None,
+ false,
)
.await
.unwrap();
@@ -3126,6 +3134,7 @@ mod tests {
0,
10,
None,
+ false,
)
.await
.unwrap();
@@ -6705,7 +6714,7 @@ mod tests {
// as_of between v1 and v2: the superseded version answers.
let then_hits = store
.reader
- .entity_hits_for_project_at(ws, proj, "postgres", 10, None, Some(between))
+ .entity_hits_for_project_at(ws, proj, "postgres", 10, None, Some(between), false)
.await
.unwrap();
assert_eq!(then_hits.len(), 1, "{then_hits:?}");
@@ -6721,6 +6730,7 @@ mod tests {
10,
None,
Some(jiff::Timestamp::now().as_microsecond()),
+ false,
)
.await
.unwrap();
@@ -6730,7 +6740,7 @@ mod tests {
// And before v1 existed: nothing was known.
let before = store
.reader
- .entity_hits_for_project_at(ws, proj, "postgres", 10, None, Some(1))
+ .entity_hits_for_project_at(ws, proj, "postgres", 10, None, Some(1), false)
.await
.unwrap();
assert!(before.is_empty(), "{before:?}");
@@ -7201,7 +7211,7 @@ mod tests {
// window opened at the version's creation.
let later = store
.reader
- .entity_hits_for_project_at(ws, proj, "sqlite", 10, None, Some(created + 1))
+ .entity_hits_for_project_at(ws, proj, "sqlite", 10, None, Some(created + 1), false)
.await
.unwrap();
assert_eq!(later.len(), 1, "{later:?}");
@@ -7244,7 +7254,15 @@ mod tests {
// Before retirement: visible.
let before = store
.reader
- .entity_hits_for_project_at(ws, proj, "postgres", 10, None, Some(retired_at - 1000))
+ .entity_hits_for_project_at(
+ ws,
+ proj,
+ "postgres",
+ 10,
+ None,
+ Some(retired_at - 1000),
+ false,
+ )
.await
.unwrap();
assert_eq!(before.len(), 1, "{before:?}");
@@ -7258,6 +7276,7 @@ mod tests {
10,
None,
Some(jiff::Timestamp::now().as_microsecond()),
+ false,
)
.await
.unwrap();
@@ -7595,6 +7614,7 @@ mod tests {
0,
10,
None,
+ false,
)
.await
.unwrap();
diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rs
index bafff718..51fb97f2 100644
--- a/crates/ai-memory-store/src/reader.rs
+++ b/crates/ai-memory-store/src/reader.rs
@@ -52,6 +52,23 @@ fn not_expired(table: &str, now_param: &str) -> String {
format!(" AND ({table}.expires_at IS NULL OR {table}.expires_at > {now_param})")
}
+/// Latest-version guard for retrieval candidate queries (FTS / vector /
+/// entity / graph). When `include_superseded` is false — the default — this
+/// restricts a candidate query to the current version with
+/// `AND {table}.is_latest = 1`; when true it returns an empty fragment so
+/// superseded versions enter the candidate pool too. `table` is the pages
+/// alias in that query. One definition so the opt-in never drifts between
+/// streams, and the default fragment is byte-identical to the literal it
+/// replaces. The fragment carries no bound placeholder, so dropping it never
+/// disturbs positional parameter ordering.
+fn latest_only(table: &str, include_superseded: bool) -> String {
+ if include_superseded {
+ String::new()
+ } else {
+ format!(" AND {table}.is_latest = 1")
+ }
+}
+
/// Current wall-clock in microseconds, for binding against
/// [`not_expired`] fragments.
fn now_us() -> i64 {
@@ -639,6 +656,12 @@ pub struct PageHit {
pub snippet: String,
/// Relevance rank after the bounded authority adjustment (lower is better).
pub rank: f64,
+ /// True when this hit is a superseded (non-latest) page version, surfaced
+ /// only because the caller opted into `include_superseded`. False for the
+ /// current version — the default. Skipped in JSON when false so default
+ /// retrieval output is unchanged.
+ #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+ pub superseded: bool,
}
/// Completed session selected for scheduled auto-improvement.
@@ -1678,6 +1701,7 @@ impl ReaderPool {
title,
snippet,
rank,
+ superseded: false,
},
authority,
));
@@ -1811,6 +1835,7 @@ impl ReaderPool {
query,
authority_candidate_limit(limit),
expiry_cutoff_us,
+ false,
)
.await?;
Ok(rerank_page_hits(candidates, limit))
@@ -1823,6 +1848,7 @@ impl ReaderPool {
query: String,
candidate_limit: usize,
expiry_cutoff_us: Option<i64>,
+ include_superseded: bool,
) -> StoreResult<Vec<(PageHit, PageAuthority)>> {
let fts_query = normalize_fts_query(&query);
if fts_query.is_empty() || candidate_limit == 0 {
@@ -1840,10 +1866,10 @@ impl ReaderPool {
JOIN pages ON pages.rowid = pages_fts.rowid \
WHERE pages_fts MATCH ?1 \
AND pages.workspace_id = ?2 \
- AND pages.project_id = ?3 \
- AND pages.is_latest = 1{not_expired} \
+ AND pages.project_id = ?3{latest}{not_expired} \
ORDER BY pages_fts.rank \
LIMIT ?4",
+ latest = latest_only("pages", include_superseded),
not_expired = not_expired("pages", "?5"),
);
let mut stmt = conn.prepare(&sql)?;
@@ -1893,6 +1919,7 @@ impl ReaderPool {
title,
snippet,
rank,
+ superseded: false,
},
authority,
));
@@ -1989,6 +2016,7 @@ impl ReaderPool {
title,
snippet,
rank,
+ superseded: false,
},
authority,
));
@@ -2035,6 +2063,9 @@ impl ReaderPool {
candidate_limit,
None,
Some(as_of_us),
+ // The as_of branch resolves versions by ingestion window, so
+ // this flag is inert; false keeps the audit path unchanged.
+ false,
)
.await?;
let fts_candidates = self
@@ -2120,6 +2151,7 @@ impl ReaderPool {
title: entry.title,
snippet: entry.snippet,
rank: -entry.score, // lower = better (matches FTS5 convention)
+ superseded: false,
},
entry.explain,
)
@@ -2257,6 +2289,7 @@ impl ReaderPool {
title,
snippet,
rank,
+ superseded: false,
});
}
Ok(hits)
@@ -2313,6 +2346,7 @@ impl ReaderPool {
title,
snippet,
rank,
+ superseded: false,
});
}
Ok(hits)
@@ -3658,6 +3692,7 @@ impl ReaderPool {
dim: u32,
limit: usize,
expiry_cutoff_us: i64,
+ include_superseded: bool,
) -> StoreResult<Vec<(PageId, PagePath, f32)>> {
self.top_embedding_hits_in_table(
EmbeddingTable::Body,
@@ -3669,6 +3704,7 @@ impl ReaderPool {
dim,
limit,
expiry_cutoff_us,
+ include_superseded,
)
.await
}
@@ -3688,6 +3724,7 @@ impl ReaderPool {
dim: u32,
limit: usize,
expiry_cutoff_us: i64,
+ include_superseded: bool,
) -> StoreResult<Vec<(PageId, PagePath, f32)>> {
if limit == 0 {
return Ok(Vec::new());
@@ -3699,11 +3736,11 @@ impl ReaderPool {
FROM {table} \
JOIN pages ON pages.id = {table}.page_id \
WHERE pages.workspace_id = ?1 \
- AND pages.project_id = ?2 \
- AND pages.is_latest = 1{not_expired} \
+ AND pages.project_id = ?2{latest}{not_expired} \
AND {table}.provider = ?3 \
AND {table}.model = ?4 \
AND {table}.dim = ?5",
+ latest = latest_only("pages", include_superseded),
not_expired = not_expired("pages", "?6"),
);
let mut stmt = conn.prepare_cached(&sql)?;
@@ -4016,6 +4053,7 @@ impl ReaderPool {
limit,
expiry_cutoff_us,
None,
+ false,
)
.await
}
@@ -4026,6 +4064,7 @@ impl ReaderPool {
/// entity-link windows contain `T` — expiry is deliberately ignored
/// there: a page valid at `T` that has since expired was still what
/// we knew at `T`.
+ #[allow(clippy::too_many_arguments)]
pub async fn entity_hits_for_project_at(
&self,
workspace_id: WorkspaceId,
@@ -4034,6 +4073,7 @@ impl ReaderPool {
limit: usize,
expiry_cutoff_us: Option<i64>,
as_of_us: Option<i64>,
+ include_superseded: bool,
) -> StoreResult<Vec<EntityHit>> {
let tokens = entity_query_tokens(query);
if tokens.is_empty() || limit == 0 {
@@ -4123,14 +4163,22 @@ impl ReaderPool {
AND (l.superseded_at IS NULL OR l.superseded_at > ?)"
.to_string()
} else {
- format!(" AND pg.is_latest = 1{}", not_expired("pg", "?"))
+ format!(
+ "{}{}",
+ latest_only("pg", include_superseded),
+ not_expired("pg", "?")
+ )
},
freq_version_filter = if as_of_us.is_some() {
" AND l.valid_from <= ? \
AND (l.superseded_at IS NULL OR l.superseded_at > ?)"
.to_string()
} else {
- format!(" AND p.is_latest = 1{}", not_expired("p", "?"))
+ format!(
+ "{}{}",
+ latest_only("p", include_superseded),
+ not_expired("p", "?")
+ )
},
)
.expect("writing SQL into String cannot fail");
@@ -4158,6 +4206,7 @@ impl ReaderPool {
title,
snippet,
rank: 0.0,
+ superseded: false,
},
weight,
matched,
@@ -4247,6 +4296,7 @@ impl ReaderPool {
seed_ids,
limit,
expiry_cutoff_us,
+ false,
)
.await?
.into_iter()
@@ -4265,6 +4315,7 @@ impl ReaderPool {
seed_ids: Vec<PageId>,
limit: usize,
expiry_cutoff_us: Option<i64>,
+ include_superseded: bool,
) -> StoreResult<Vec<GraphNeighbor>> {
if seed_ids.is_empty() || limit == 0 {
return Ok(Vec::new());
@@ -4294,6 +4345,8 @@ impl ReaderPool {
let out_descriptor = page_descriptor_expr("tp.body", "tp.frontmatter_json");
let in_descriptor = page_descriptor_expr("fp.body", "fp.frontmatter_json");
+ let out_latest = latest_only("tp", include_superseded);
+ let in_latest = latest_only("fp", include_superseded);
let out_not_expired = not_expired("tp", "?");
let in_not_expired = not_expired("fp", "?");
let mut sql = String::with_capacity(values_clause.len() + 1_500);
@@ -4308,7 +4361,7 @@ impl ReaderPool {
FROM seeds \
JOIN links l ON l.from_page_id = seeds.seed_id \
JOIN pages tp ON tp.id = l.to_page_id \
- WHERE tp.workspace_id = ? AND tp.project_id = ? AND tp.is_latest = 1{out_not_expired} \
+ WHERE tp.workspace_id = ? AND tp.project_id = ?{out_latest}{out_not_expired} \
UNION ALL \
SELECT fp.id AS id, fp.path AS path, fp.title AS title, \
{in_descriptor} AS snippet, \
@@ -4317,7 +4370,7 @@ impl ReaderPool {
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} \
+ WHERE fp.workspace_id = ? AND fp.project_id = ?{in_latest}{in_not_expired} \
) \
SELECT id, path, title, snippet, stream_ord, link_type \
FROM neighbors \
@@ -4352,6 +4405,7 @@ impl ReaderPool {
title,
snippet,
rank: 0.0,
+ superseded: false,
},
seed_ord,
incoming: stream_ord % 2 == 1,
@@ -4443,6 +4497,7 @@ impl ReaderPool {
workspace_id: WorkspaceId,
project_id: ProjectId,
page_ids: Vec<PageId>,
+ include_superseded: bool,
) -> StoreResult<std::collections::HashMap<PageId, (String, String)>> {
if page_ids.is_empty() {
return Ok(std::collections::HashMap::new());
@@ -4466,9 +4521,9 @@ impl ReaderPool {
FROM requested \
JOIN pages ON pages.id = requested.id \
WHERE pages.workspace_id = ? \
- AND pages.project_id = ? \
- AND pages.is_latest = 1",
+ AND pages.project_id = ?{latest}",
descriptor = page_descriptor_expr("pages.body", "pages.frontmatter_json"),
+ latest = latest_only("pages", include_superseded),
);
let mut stmt = conn.prepare(&sql)?;
let rows = stmt.query_map(params_from_iter(sql_params.iter()), |row| {
@@ -4590,6 +4645,13 @@ impl ReaderPool {
/// `expiry_cutoff_us`: see [`Self::search_pages_for_project`]. The
/// cutoff resolves once here so all streams agree on it.
///
+ /// `include_superseded`: `false` — the default — restricts every stream
+ /// to the current page version (`is_latest = 1`), the exact hot-path
+ /// behaviour. `true` drops that predicate so superseded versions enter
+ /// the candidate pool too; each returned [`PageHit`] carries
+ /// `superseded` so the caller can tell historical versions from the
+ /// current one (invariant #16: the superseded loser stays reachable).
+ ///
/// k=60 is the canonical RRF constant.
///
/// # Errors
@@ -4606,6 +4668,7 @@ impl ReaderPool {
dim: u32,
limit: usize,
expiry_cutoff_us: Option<i64>,
+ include_superseded: bool,
) -> StoreResult<Vec<PageHit>> {
Ok(self
.hybrid_search_inner(
@@ -4619,6 +4682,7 @@ impl ReaderPool {
limit,
expiry_cutoff_us,
false,
+ include_superseded,
)
.await?
.into_iter()
@@ -4645,6 +4709,7 @@ impl ReaderPool {
dim: u32,
limit: usize,
expiry_cutoff_us: Option<i64>,
+ include_superseded: bool,
) -> StoreResult<Vec<(PageHit, SearchExplain)>> {
let hits = self
.hybrid_search_inner(
@@ -4658,6 +4723,7 @@ impl ReaderPool {
limit,
expiry_cutoff_us,
true,
+ include_superseded,
)
.await?;
// Evidence counts (P2, docs/design-hindsight-borrowings.md §3) are
@@ -4688,6 +4754,7 @@ impl ReaderPool {
limit: usize,
expiry_cutoff_us: Option<i64>,
explain: bool,
+ include_superseded: bool,
) -> StoreResult<Vec<(PageHit, Option<SearchExplain>)>> {
let cutoff = expiry_cutoff_us.unwrap_or_else(now_us);
// The routing decision is read off the query before the FTS call
@@ -4701,15 +4768,29 @@ impl ReaderPool {
let candidate_limit = authority_candidate_limit(limit);
// Tokenize the borrowed query before the FTS candidate call consumes
// it. This avoids cloning a caller-controlled query on the hot path.
- let entity_hits = self
- .entity_hits_for_project(
+ // The default path uses the latest-only entry; the opt-in path reaches
+ // superseded versions through the `_at` entry with no `as_of` instant.
+ let entity_hits = if include_superseded {
+ self.entity_hits_for_project_at(
workspace_id,
project_id,
&query,
candidate_limit,
Some(cutoff),
+ None,
+ true,
)
- .await?;
+ .await?
+ } else {
+ self.entity_hits_for_project(
+ workspace_id,
+ project_id,
+ &query,
+ candidate_limit,
+ Some(cutoff),
+ )
+ .await?
+ };
let fts_candidates = self
.search_page_candidates_for_project(
workspace_id,
@@ -4717,6 +4798,7 @@ impl ReaderPool {
query,
candidate_limit,
Some(cutoff),
+ include_superseded,
)
.await?;
let mut authorities: std::collections::HashMap<PageId, PageAuthority> = fts_candidates
@@ -4742,6 +4824,7 @@ impl ReaderPool {
dim,
candidate_limit,
cutoff,
+ include_superseded,
)
.await?;
}
@@ -4755,6 +4838,7 @@ impl ReaderPool {
dim,
candidate_limit,
cutoff,
+ include_superseded,
)
.await?;
}
@@ -4793,6 +4877,7 @@ impl ReaderPool {
seed_ids,
candidate_limit,
Some(cutoff),
+ include_superseded,
)
.await?;
@@ -4912,6 +4997,7 @@ impl ReaderPool {
title: entry.title,
snippet: entry.snippet,
rank: -entry.score, // lower = better (matches FTS5 convention)
+ superseded: false,
},
entry.explain,
)
@@ -4927,7 +5013,7 @@ impl ReaderPool {
.collect();
if !undescribed.is_empty() {
let descriptors = self
- .page_descriptors_for_ids(workspace_id, project_id, undescribed)
+ .page_descriptors_for_ids(workspace_id, project_id, undescribed, include_superseded)
.await?;
for (hit, _) in &mut out {
if let Some((title, descriptor)) = descriptors.get(&hit.id) {
@@ -4941,10 +5027,18 @@ impl ReaderPool {
.iter()
.filter_map(|(hit, _)| (!authorities.contains_key(&hit.id)).then_some(hit.id))
.collect();
- authorities.extend(
+ // With `include_superseded`, some fused ids are non-latest versions
+ // reached by the vector/graph streams; their authority inputs must be
+ // read without the latest-only filter or they'd get the neutral
+ // default and misrank.
+ let extra_authorities = if include_superseded {
+ self.page_authorities_for_versions(workspace_id, project_id, missing_authorities)
+ .await?
+ } else {
self.page_authorities_for_project(workspace_id, project_id, missing_authorities)
- .await?,
- );
+ .await?
+ };
+ authorities.extend(extra_authorities);
for (hit, explain) in &mut out {
if let Some(authority) = authorities.get(&hit.id) {
let factor = authority.factor_for(session_recall, tuning.session_recall_bonus);
@@ -4971,9 +5065,69 @@ impl ReaderPool {
.then_with(|| a.0.path.as_str().cmp(b.0.path.as_str()))
});
out.truncate(limit);
+ // Label the superseded versions among the final hits so the caller can
+ // tell historical versions from the current one. Only the opt-in path
+ // can surface a non-latest id, so the default path skips this lookup
+ // entirely and every hit keeps `superseded = false`.
+ if include_superseded {
+ let result_ids: Vec<PageId> = out.iter().map(|(hit, _)| hit.id).collect();
+ let superseded = self
+ .superseded_page_ids(workspace_id, project_id, result_ids)
+ .await?;
+ for (hit, _) in &mut out {
+ hit.superseded = superseded.contains(&hit.id);
+ }
+ }
Ok(out)
}
+ /// The subset of `page_ids` that are superseded (non-latest) versions in
+ /// the given project. Used by [`Self::hybrid_search`] to label opt-in
+ /// `include_superseded` hits; the default path never calls it.
+ async fn superseded_page_ids(
+ &self,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ page_ids: Vec<PageId>,
+ ) -> StoreResult<std::collections::HashSet<PageId>> {
+ if page_ids.is_empty() {
+ return Ok(std::collections::HashSet::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 \
+ FROM requested \
+ JOIN pages ON pages.id = requested.id \
+ WHERE pages.workspace_id = ? \
+ AND pages.project_id = ? \
+ AND pages.is_latest = 0"
+ );
+ let mut stmt = conn.prepare(&sql)?;
+ let rows = stmt.query_map(params_from_iter(sql_params.iter()), |row| {
+ row.get::<_, Vec<u8>>(0)
+ })?;
+ let mut out = std::collections::HashSet::new();
+ for row in rows {
+ out.insert(PageId::from_slice(&row?)?);
+ }
+ Ok(out)
+ })
+ .await
+ }
+
/// Return the open handoff the next session should pick up.
///
/// A manual handoff (`memory_handoff_begin`, which always sets
diff --git a/crates/ai-memory-store/tests/suite/mod.rs b/crates/ai-memory-store/tests/suite/mod.rs
index 0ea60013..ff0e3f5e 100644
--- a/crates/ai-memory-store/tests/suite/mod.rs
+++ b/crates/ai-memory-store/tests/suite/mod.rs
@@ -12,6 +12,7 @@ mod fts_drift_status;
mod handoff_ownership;
mod most_recently_active_scope;
mod multi_session;
+mod retrieval_superseded;
mod retrieval_tuning_streams;
mod session_ids_touching_scope;
mod session_observations;
diff --git a/crates/ai-memory-store/tests/suite/retrieval_superseded.rs b/crates/ai-memory-store/tests/suite/retrieval_superseded.rs
new file mode 100644
index 00000000..aafdda8e
--- /dev/null
+++ b/crates/ai-memory-store/tests/suite/retrieval_superseded.rs
@@ -0,0 +1,191 @@
+//! Opt-in `include_superseded` retrieval: superseded page versions are hidden
+//! by default (every hot query constrains `is_latest = 1`), but a caller can
+//! ask `hybrid_search` to return historical versions too, each marked so the
+//! caller can tell them apart from the current version. Default-off behaviour
+//! must be unchanged (invariant #16: the superseded loser stays reachable, but
+//! only when explicitly requested).
+
+use ai_memory_core::{NewPage, PagePath, Tier};
+use ai_memory_store::Store;
+
+fn page(
+ ws: ai_memory_core::WorkspaceId,
+ proj: ai_memory_core::ProjectId,
+ path: &str,
+ title: &str,
+ body: &str,
+) -> NewPage {
+ NewPage {
+ workspace_id: ws,
+ project_id: proj,
+ path: PagePath::new(path).unwrap(),
+ title: title.into(),
+ body: body.into(),
+ tier: Tier::Semantic,
+ frontmatter_json: serde_json::json!({}),
+ pinned: false,
+ links: Vec::new(),
+ author_id: None,
+ expires_at: None,
+ entities: Vec::new(),
+ evidence: Vec::new(),
+ }
+}
+
+async fn store_with_superseded_page() -> (
+ tempfile::TempDir,
+ Store,
+ ai_memory_core::WorkspaceId,
+ ai_memory_core::ProjectId,
+ ai_memory_core::PageId, // v1 (superseded)
+ ai_memory_core::PageId, // v2 (latest)
+) {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let ws = store
+ .writer
+ .get_or_create_workspace("default".to_string())
+ .await
+ .unwrap();
+ let proj = store
+ .writer
+ .get_or_create_project(ws, "app".to_string(), None)
+ .await
+ .unwrap();
+
+ // v1 mentions `postgres`; a shared `zebraquux` token matches both versions.
+ let v1 = store
+ .writer
+ .upsert_page(page(ws, proj, "notes/db.md", "DB", "zebraquux postgres"))
+ .await
+ .unwrap();
+ // v2 supersedes v1: the `postgres` term is gone, `sqlite` replaces it.
+ let v2 = store
+ .writer
+ .upsert_page(page(ws, proj, "notes/db.md", "DB", "zebraquux sqlite"))
+ .await
+ .unwrap();
+ assert_ne!(v1, v2, "the supersede must create a new page version");
+ (tmp, store, ws, proj, v1, v2)
+}
+
+#[tokio::test]
+async fn include_superseded_off_returns_only_latest() {
+ let (_tmp, store, ws, proj, _v1, v2) = store_with_superseded_page().await;
+
+ let hits = store
+ .reader
+ .hybrid_search(
+ ws,
+ proj,
+ "zebraquux".to_string(),
+ None,
+ String::new(),
+ String::new(),
+ 0,
+ 10,
+ None,
+ false,
+ )
+ .await
+ .unwrap();
+
+ assert_eq!(
+ hits.len(),
+ 1,
+ "default query returns only the latest version"
+ );
+ assert_eq!(hits[0].id, v2, "the latest version answers by default");
+ assert!(
+ !hits[0].superseded,
+ "the latest version is not marked superseded"
+ );
+
+ // A term that only the superseded version carried must not surface by
+ // default — the exact current hidden behaviour.
+ let hidden = store
+ .reader
+ .hybrid_search(
+ ws,
+ proj,
+ "postgres".to_string(),
+ None,
+ String::new(),
+ String::new(),
+ 0,
+ 10,
+ None,
+ false,
+ )
+ .await
+ .unwrap();
+ assert!(
+ hidden.is_empty(),
+ "a superseded-only term must not surface by default: {hidden:?}"
+ );
+}
+
+#[tokio::test]
+async fn include_superseded_on_returns_both_versions_marked() {
+ let (_tmp, store, ws, proj, v1, v2) = store_with_superseded_page().await;
+
+ let hits = store
+ .reader
+ .hybrid_search(
+ ws,
+ proj,
+ "zebraquux".to_string(),
+ None,
+ String::new(),
+ String::new(),
+ 0,
+ 10,
+ None,
+ true,
+ )
+ .await
+ .unwrap();
+
+ let latest = hits
+ .iter()
+ .find(|h| h.id == v2)
+ .expect("latest version must be present");
+ let superseded = hits
+ .iter()
+ .find(|h| h.id == v1)
+ .expect("superseded version must be present when include_superseded=true");
+ assert!(
+ !latest.superseded,
+ "the current version is not marked superseded"
+ );
+ assert!(
+ superseded.superseded,
+ "the historical version must be marked superseded"
+ );
+
+ // A superseded-only term now surfaces, marked.
+ let historical = store
+ .reader
+ .hybrid_search(
+ ws,
+ proj,
+ "postgres".to_string(),
+ None,
+ String::new(),
+ String::new(),
+ 0,
+ 10,
+ None,
+ true,
+ )
+ .await
+ .unwrap();
+ let hit = historical
+ .iter()
+ .find(|h| h.id == v1)
+ .expect("the superseded version carrying the term must surface when opted in");
+ assert!(
+ hit.superseded,
+ "the historical hit must be labelled superseded"
+ );
+}
diff --git a/crates/ai-memory-store/tests/suite/retrieval_tuning_streams.rs b/crates/ai-memory-store/tests/suite/retrieval_tuning_streams.rs
index 6774e6c1..1d1e4454 100644
--- a/crates/ai-memory-store/tests/suite/retrieval_tuning_streams.rs
+++ b/crates/ai-memory-store/tests/suite/retrieval_tuning_streams.rs
@@ -104,6 +104,7 @@ async fn session_recall_routing_flips_session_page_ranking() {
0,
10,
None,
+ false,
)
.await
.unwrap();
@@ -123,6 +124,7 @@ async fn session_recall_routing_flips_session_page_ranking() {
0,
10,
None,
+ false,
)
.await
.unwrap();
@@ -145,6 +147,7 @@ async fn session_recall_routing_flips_session_page_ranking() {
0,
10,
None,
+ false,
)
.await
.unwrap();
@@ -233,6 +236,7 @@ async fn abstract_vector_stream_is_opt_in() {
dim,
10,
None,
+ false,
)
.await
.unwrap();
@@ -254,6 +258,7 @@ async fn abstract_vector_stream_is_opt_in() {
dim,
10,
None,
+ false,
)
.await
.unwrap();
diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rs
index 58d0aecb..9bde02cb 100644
--- a/crates/ai-memory-wiki/src/wiki.rs
+++ b/crates/ai-memory-wiki/src/wiki.rs
@@ -4968,6 +4968,7 @@ mod tests {
0,
5,
None,
+ false,
)
.await
.unwrap();
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index c7b43e16..d1997fef 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -369,7 +369,7 @@ invariants below.
| Tool | Hint | Purpose |
|---|---|---|
-| `memory_query` | read-only | FTS5 + entity-match + graph RRF + optional vector RRF search, followed by bounded kind/tier/pinned/tag authority adjustment and raw fallback. Bumps access counters for page hits. Defaults to the current project; default-scoped calls also union the reserved `_global` preferences scope as `global_scope_hits`; `scopes` searches named sibling projects; `global=true` searches every project at once (each hit annotated with its workspace + project). With `AI_MEMORY_RERANKER=llm`, project/scopes candidate pools are fused before at most one final LLM relevance pass; query/title/snippet data is bounded and JSON-encoded, and any timeout, provider error, invalid/incomplete score set, or four-call concurrency saturation preserves the adjusted order. The distinct `global=true` FTS-only ranker and supplemental global-preference hits are not reranked. `explain=true` attaches per-hit `score_details` (per-stream ranks, matched entities, raw FTS/cosine/entity inverse-frequency scores, RRF contributions, graph provenance including the typed edge kind (`causes`/`fixes`/`contradicts`) a neighbour was reached by, the page's evidence count, authority multiplier, and optional rerank score) to project/scopes hits plus a top-level `streams_active` list. The global FTS-only ranker reports its active stream without per-hit details. `include_expired=true` also returns TTL-expired pages. |
+| `memory_query` | read-only | FTS5 + entity-match + graph RRF + optional vector RRF search, followed by bounded kind/tier/pinned/tag authority adjustment and raw fallback. Bumps access counters for page hits. Defaults to the current project; default-scoped calls also union the reserved `_global` preferences scope as `global_scope_hits`; `scopes` searches named sibling projects; `global=true` searches every project at once (each hit annotated with its workspace + project). With `AI_MEMORY_RERANKER=llm`, project/scopes candidate pools are fused before at most one final LLM relevance pass; query/title/snippet data is bounded and JSON-encoded, and any timeout, provider error, invalid/incomplete score set, or four-call concurrency saturation preserves the adjusted order. The distinct `global=true` FTS-only ranker and supplemental global-preference hits are not reranked. `explain=true` attaches per-hit `score_details` (per-stream ranks, matched entities, raw FTS/cosine/entity inverse-frequency scores, RRF contributions, graph provenance including the typed edge kind (`causes`/`fixes`/`contradicts`) a neighbour was reached by, the page's evidence count, authority multiplier, and optional rerank score) to project/scopes hits plus a top-level `streams_active` list. The global FTS-only ranker reports its active stream without per-hit details. `include_expired=true` also returns TTL-expired pages. `include_superseded=true` also returns superseded (non-latest) page versions across the FTS/entity/vector/graph streams, each hit labelled `superseded: true` (the current version is never marked); default-off is byte-identical to the latest-only behaviour, and `global=true` / `as_of` are unaffected. |
| `memory_recent` | read-only | Most-recently-updated `is_latest=1` pages. |
| `memory_read_page` | read-only | Fetch the FULL body of a single wiki page by `path` or by top FTS5 hit for a `query`; optional `workspace` + `project` targets a named sibling workspace/project. Use when an agent needs more than the 24-word snippets from `memory_query`. |
| `memory_read_session_observations` | read-only | Page through ONE session's raw hook observations (`ObservationRecord` with full sanitized body, capped per row by `body_max_chars`), restricted to the rows that landed in the resolved scope and to sessions the caller may see; `total` and `elided_other_scope` report the in-scope count and the rows the session left in another project. `session_id` omitted reads the latest completed visible session. |