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.mdindex 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` candiff --git a/crates/ai-memory-consolidate/tests/suite/embeddings.rs b/crates/ai-memory-consolidate/tests/suite/embeddings.rsindex 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.rsindex 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.rsindex 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.rsindex 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.mdindex 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 bydefault. Pass `include_expired: true` only when the user explicitly asks toinspect 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 hitsranked as they did. It adds FTS, lexical entity, optional vector, and graphscore 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.rsindex 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.rsindex 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.rsnew file mode 100644index 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.rsindex 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.rsindex 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 setsdiff --git a/crates/ai-memory-store/tests/suite/mod.rs b/crates/ai-memory-store/tests/suite/mod.rsindex 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.rsnew file mode 100644index 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.rsindex 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.rsindex 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.mdindex 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. |