Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(retrieval): opt-in session-recall routing and L0 abstract vector stream
evanmaranzano922408b223b3
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex d88c7516..cd434cd3 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- `[retrieval]` section with two opt-in ranking signals, both off by default+ so unconfigured stores rank exactly as before. `query_intent` routes+ lexically session-recall queries ("上次 / 之前那次…的会话 / last time /+ yesterday …") past the default session-page authority penalty+ (×0.77 combined kind/tier), with `session_recall_bonus` (default 0.25)+ sizing the lift; `abstract_vectors` adds a fifth RRF stream over the new+ `page_abstract_embeddings` table (V61) — the L0 layer: a page's+ frontmatter `abstract:` line is embedded by the same backfill as its+ body, and a one-line summary embeds far more sharply than a+ multi-thousand-character body. Measured on a 138-query golden set over a+ production two-year wiki (FTS5 + entity + vector + graph, mis-tei+ Qwen3-Embedding-8B): hit@1 0.609 → 0.746 (+22%), NDCG@10 0.782 → 0.879+ (+12%) with both enabled; every unrouted category keeps its exact+ baseline ordering, and both signals are visible per hit in+ `memory_query(explain=true)` (`intent`, `intent_boost`,+ `abstract_rank`, `rrf.abstract`).+### Fixed- OKF-conformed event ledgers are skipped by the indexer again, so a migratedstore stops growing without bound. The reserved-file check treated anydiff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rsindex 06cf1f67..3620cde0 100644--- a/crates/ai-memory-cli/src/config.rs+++ b/crates/ai-memory-cli/src/config.rs@@ -991,25 +991,17 @@ impl Default for MaintenanceSettings {/// `memory_query`. Every default leaves ranking byte-identical to a store/// that never heard of this section.///-/// Env form: `AI_MEMORY_RETRIEVAL__HOTNESS_ALPHA=0.3`,-/// `AI_MEMORY_RETRIEVAL__QUERY_INTENT=true`.+/// Env form: `AI_MEMORY_RETRIEVAL__QUERY_INTENT=true`,+/// `AI_MEMORY_RETRIEVAL__ABSTRACT_VECTORS=true`.#[derive(Debug, Clone, Copy, Serialize, Deserialize)]#[serde(default)]pub struct RetrievalSettings {- /// Weight of the hotness boost (`1 + alpha * hotness`), where hotness is- /// access frequency × update recency in `[0, 1]`. `0` disables it.- pub hotness_alpha: f64,- /// Half-life, in days, of the recency term inside hotness.- pub hotness_half_life_days: f64,- /// Lexical query-intent routing: `recency` queries ("现在 / latest /- /// still …") get an update-recency boost, `session_recall` queries- /// ("上次 / last time / yesterday …") let session pages compete.+ /// Lexical session-recall routing: queries phrased as "find a past+ /// session / what we did back then" ("上次 / …的会话 / last time /+ /// yesterday …") hand session pages back their default kind/tier+ /// authority penalty so they can compete for these queries.pub query_intent: bool,- /// Weight of the recency boost under the `recency` intent.- pub recency_beta: f64,- /// Half-life, in days, of the recency boost under the `recency` intent.- pub recency_half_life_days: f64,- /// Extra authority granted to session pages under `session_recall`,+ /// Extra authority granted to session pages when the routing fires,/// on top of cancelling their default kind/tier penalty.pub session_recall_bonus: f64,/// Add the L0 abstract-embedding stream (`page_abstract_embeddings`) to@@ -1022,11 +1014,7 @@ impl Default for RetrievalSettings {fn default() -> Self {let base = ai_memory_store::RetrievalTuning::default();Self {- hotness_alpha: base.hotness_alpha,- hotness_half_life_days: base.hotness_half_life_days,- query_intent: base.query_intent,- recency_beta: base.recency_beta,- recency_half_life_days: base.recency_half_life_days,+ query_intent: base.session_recall_routing,session_recall_bonus: base.session_recall_bonus,abstract_vectors: base.abstract_vectors,}@@ -1038,11 +1026,7 @@ impl RetrievalSettings {#[must_use]pub fn tuning(self) -> ai_memory_store::RetrievalTuning {ai_memory_store::RetrievalTuning {- hotness_alpha: self.hotness_alpha.max(0.0),- hotness_half_life_days: self.hotness_half_life_days,- query_intent: self.query_intent,- recency_beta: self.recency_beta.max(0.0),- recency_half_life_days: self.recency_half_life_days,+ session_recall_routing: self.query_intent,session_recall_bonus: self.session_recall_bonus.max(0.0),abstract_vectors: self.abstract_vectors,}diff --git a/crates/ai-memory-consolidate/src/embed.rs b/crates/ai-memory-consolidate/src/embed.rsindex e98bda3a..57299d2c 100644--- a/crates/ai-memory-consolidate/src/embed.rs+++ b/crates/ai-memory-consolidate/src/embed.rs@@ -208,25 +208,23 @@ pub async fn run_embedding_backfill(}}}- if need_abstract {- if let Some(abstract_text) = frontmatter_abstract(&md.frontmatter) {- match embedder.embed_document(abstract_text).await {- Ok(vec) => pending_abstract.push(EmbeddingWrite {- page_id: cand.id,- vector_bytes: f32_vec_to_bytes(&vec),- provider: provider.clone(),- model: model.clone(),- dim,- }),- Err(e) => {- warn!(path = %cand.path, error = %e, "embed: abstract provider call failed");- counts.failed += 1;- }- }- if pending_abstract.len() >= EMBEDDING_WRITE_BATCH {- flush_abstract_batch(writer, &mut pending_abstract, &mut counts).await;+ if need_abstract && let Some(abstract_text) = frontmatter_abstract(&md.frontmatter) {+ match embedder.embed_document(abstract_text).await {+ Ok(vec) => pending_abstract.push(EmbeddingWrite {+ page_id: cand.id,+ vector_bytes: f32_vec_to_bytes(&vec),+ provider: provider.clone(),+ model: model.clone(),+ dim,+ }),+ Err(e) => {+ warn!(path = %cand.path, error = %e, "embed: abstract provider call failed");+ counts.failed += 1;}}+ if pending_abstract.len() >= EMBEDDING_WRITE_BATCH {+ flush_abstract_batch(writer, &mut pending_abstract, &mut counts).await;+ }}}flush_embedding_batch(writer, &mut pending, &mut counts).await;diff --git a/crates/ai-memory-store/src/api_credentials.rs b/crates/ai-memory-store/src/api_credentials.rsindex 45cdc1b4..662bb11a 100644--- a/crates/ai-memory-store/src/api_credentials.rs+++ b/crates/ai-memory-store/src/api_credentials.rs@@ -411,7 +411,7 @@ mod tests {|row| row.get(0),).unwrap();- assert_eq!(version, 60, "update the pin when adding a migration");+ assert_eq!(version, 61, "update the pin when adding a migration");let cols: i64 = conn.query_row("SELECT COUNT(*) FROM pragma_table_info('users') WHERE name = 'token_hash'",diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex 17675db7..1f8c4d6a 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -68,7 +68,7 @@ pub use reader::{StorageStatus, StoredEmbedding, StoredPageBody, WorkspaceScopeRow, WorkspaceSummary,f32_vec_to_bytes,};-pub use retrieval_tuning::{QueryIntent, RetrievalTuning, detect_query_intent, hotness_score};+pub use retrieval_tuning::{RetrievalTuning, is_session_recall_query};pub use scope::{ResolvedScope, ScopeName, ScopeResolutionError, ScopeResolver, WORKSPACE_PROJECT_PAIR_REQUIRED,create_explicit_scope, create_global_scope, lookup_existing_scope, lookup_existing_workspace,diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsindex 8e328b1a..7b4f36de 100644--- a/crates/ai-memory-store/src/reader.rs+++ b/crates/ai-memory-store/src/reader.rs@@ -35,7 +35,7 @@ use crate::auto_improve::{use crate::error::{StoreError, StoreResult};use crate::fts_query::prepare_fts5_query;use crate::maintenance::MaintenanceJob;-use crate::retrieval_tuning::{QueryIntent, RetrievalTuning};+use crate::retrieval_tuning::{RetrievalTuning, is_session_recall_query};use crate::users::TOKEN_HASH_LEN;use crate::workstream::{ManagedRunContext, StoredManagedRunStatus, StoredWorkstreamSummary};@@ -283,16 +283,15 @@ impl PageAuthority {apply_rank_multiplier(rank, self.factor)}- /// Effective multiplier under the detected query intent: a- /// `session_recall` query hands session pages back the kind/tier penalty- /// they carry by default and adds `bonus`, still inside the bounds every- /// other page lives in. Any other intent leaves the factor alone.- fn factor_for(&self, intent: Option<QueryIntent>, bonus: f64) -> f64 {- match intent {- Some(QueryIntent::SessionRecall) if self.session_penalty > 0.0 => {- (self.factor + self.session_penalty + bonus).clamp(0.55, 1.50)- }- _ => self.factor,+ /// Effective multiplier when the query routed to session-recall+ /// retrieval: session pages get the kind/tier penalty they carry by+ /// default handed back plus `bonus`, still inside the bounds every+ /// other page lives in. Any other query leaves the factor alone.+ fn factor_for(&self, session_recall: bool, bonus: f64) -> f64 {+ if session_recall && self.session_penalty > 0.0 {+ (self.factor + self.session_penalty + bonus).clamp(0.55, 1.50)+ } else {+ self.factor}}}@@ -592,19 +591,13 @@ pub struct SearchExplain {/// means it was considered and left alone.#[serde(skip_serializing_if = "Option::is_none")]pub authority: Option<f64>,- /// Hotness in `[0, 1]` — access frequency × update recency — when the- /// opt-in `[retrieval] hotness_alpha` boost is configured.- #[serde(skip_serializing_if = "Option::is_none")]- pub hotness: Option<f64>,- /// The `1 + alpha * hotness` multiplier folded into the returned rank.- #[serde(skip_serializing_if = "Option::is_none")]- pub hotness_boost: Option<f64>,- /// Lexically detected query intent when `[retrieval] query_intent` is on.+ /// The routing decision for this query when `[retrieval] query_intent`+ /// is on: `"session_recall"` for queries the lexical router recognised.#[serde(skip_serializing_if = "Option::is_none")]- pub intent: Option<QueryIntent>,- /// Multiplier the intent applied to this hit: the recency boost under- /// `recency`, or the session-page authority lift under `session_recall`- /// expressed as a ratio over the intent-free factor. `1.0` = untouched.+ pub intent: Option<&'static str>,+ /// Multiplier the routing applied to this hit: the session-page+ /// authority lift expressed as a ratio over the un-routed factor.+ /// `1.0` = considered and left alone.#[serde(skip_serializing_if = "Option::is_none")]pub intent_boost: Option<f64>,/// Relevance in `[0, 1]` assigned by the optional post-RRF@@ -4176,56 +4169,6 @@ impl ReaderPool {.await}- /// `access_count` and `updated_at` (µs) for the requested latest pages —- /// the two signals the opt-in hotness / recency boosts read. Fetched in- /// one round trip, and only when a boost is actually configured.- async fn page_signals_for_ids(- &self,- workspace_id: WorkspaceId,- project_id: ProjectId,- page_ids: Vec<PageId>,- ) -> StoreResult<std::collections::HashMap<PageId, (i64, i64)>> {- if page_ids.is_empty() {- return Ok(std::collections::HashMap::new());- }- self.with_conn(move |conn| {- let mut values_clause = String::with_capacity(page_ids.len() * 5);- let mut sql_params = Vec::with_capacity(page_ids.len() + 2);- for (idx, page_id) in page_ids.iter().enumerate() {- if idx > 0 {- values_clause.push_str(", ");- }- values_clause.push_str("(?)");- sql_params.push(Value::Blob(page_id.as_bytes().to_vec()));- }- sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));- sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));- let sql = format!(- "WITH requested(id) AS (VALUES {values_clause}) \- SELECT pages.id, pages.access_count, pages.updated_at \- FROM requested \- JOIN pages ON pages.id = requested.id \- WHERE pages.workspace_id = ? \- AND pages.project_id = ? \- AND pages.is_latest = 1"- );- let mut stmt = conn.prepare(&sql)?;- let rows = stmt.query_map(params_from_iter(sql_params.iter()), |row| {- let id_bytes: Vec<u8> = row.get(0)?;- let access_count: i64 = row.get(1)?;- let updated_at: i64 = row.get(2)?;- Ok((id_bytes, access_count, updated_at))- })?;- let mut signals = std::collections::HashMap::new();- for row in rows {- let (id_bytes, access_count, updated_at) = row?;- signals.insert(PageId::from_slice(&id_bytes)?, (access_count, updated_at));- }- Ok(signals)- })- .await- }-/// Hybrid search: RRF-fuse FTS5 results with cosine-similarity/// over the stored embeddings of the matching `(provider, model,/// dim)`, entity matches, and link-neighbour expansion — four RRF@@ -4330,10 +4273,10 @@ impl ReaderPool {explain: bool,) -> StoreResult<Vec<(PageHit, Option<SearchExplain>)>> {let cutoff = expiry_cutoff_us.unwrap_or_else(now_us);- // Intent is read off the query before the FTS call consumes it; with- // routing disabled this is a no-op `None`.+ // The routing decision is read off the query before the FTS call+ // consumes it; with routing disabled this is a no-op `false`.let tuning = self.tuning;- let intent = tuning.intent_for(&query);+ let session_recall = tuning.session_recall_routing && is_session_recall_query(&query);// Authority is applied after RRF, so every stream needs the same// bounded candidate window used by FTS-only search. A `limit * 2`// window was too narrow at small limits for a canonical page to enter@@ -4584,50 +4527,21 @@ impl ReaderPool {self.page_authorities_for_project(workspace_id, project_id, missing_authorities).await?,);- // Opt-in signals ride on the same pass as authority. Both default- // off, in which case no extra query runs and every multiplier is 1.- let signals = if tuning.needs_page_signals(intent) {- let ids: Vec<PageId> = out.iter().map(|(hit, _)| hit.id).collect();- self.page_signals_for_ids(workspace_id, project_id, ids)- .await?- } else {- std::collections::HashMap::new()- };- let now = now_us();for (hit, explain) in &mut out {if let Some(authority) = authorities.get(&hit.id) {- let factor = authority.factor_for(intent, tuning.session_recall_bonus);+ let factor = authority.factor_for(session_recall, tuning.session_recall_bonus);hit.rank = apply_rank_multiplier(hit.rank, factor);// `fused` stays the raw RRF sum; without the multiplier// beside it the explain could not account for the rank it// returns, which is the whole point of the surface.if let Some(details) = explain {details.authority = Some(factor);- if intent.is_some() {- details.intent = intent;+ if session_recall {+ details.intent = Some("session_recall");details.intent_boost = Some(factor / authority.factor);}}}- if let Some(&(access_count, updated_at)) = signals.get(&hit.id) {- let (hotness, hotness_boost) = tuning.hotness_boost(access_count, updated_at, now);- let recency_boost = if intent == Some(QueryIntent::Recency) {- tuning.recency_boost(updated_at, now)- } else {- 1.0- };- hit.rank = apply_rank_multiplier(hit.rank, hotness_boost * recency_boost);- if let Some(details) = explain {- if tuning.hotness_alpha > 0.0 {- details.hotness = Some(hotness);- details.hotness_boost = Some(hotness_boost);- }- if intent == Some(QueryIntent::Recency) {- details.intent = intent;- details.intent_boost = Some(recency_boost);- }- }- }}out.sort_by(|a, b| {a.0.rankdiff --git a/crates/ai-memory-store/src/retrieval_tuning.rs b/crates/ai-memory-store/src/retrieval_tuning.rsindex e2495f70..8a859b1e 100644--- a/crates/ai-memory-store/src/retrieval_tuning.rs+++ b/crates/ai-memory-store/src/retrieval_tuning.rs@@ -1,52 +1,37 @@//! Opt-in post-fusion ranking signals for `hybrid_search`.//!-//! Three bounded, independently switchable signals, all off by default so a+//! Two bounded, independently switchable signals, both off by default so a//! store that never configures them ranks exactly as before://!-//! * **Hotness** — `1 + alpha * hotness(page)`, where `hotness` blends how-//! often a page has been retrieved with how recently it was updated-//! (sigmoid(ln(1 + access_count)) × exp(−ln2 · age_days / half_life)).-//! The shape follows OpenViking's cold/hot memory lifecycle score; the-//! multiplicative form is what keeps it commensurate with RRF sums, which-//! live in `[1/(k+n), streams/(k+1)]` rather than `[0, 1]`.-//! * **Query intent** — a zero-LLM lexical routing of the query into one of-//! two intents the fused ranking is known to underserve:-//! * `recency` ("现在 / 最新 / currently / still …") multiplies each hit-//! by `1 + beta * exp(−ln2 · age_days / half_life)` so the page most-//! recently updated on the topic outranks a stale twin;-//! * `session_recall` ("上次 / 那次会话 / last time / yesterday …") lifts-//! the authority penalty session pages otherwise carry (kind `session`-//! −0.15, tier `episodic` −0.08) and adds a small boost, so a query that-//! is *about* a past session can actually reach one.-//! * **Abstract vectors** — a fifth RRF stream over `page_abstract_embeddings`,-//! the embedding of a page's frontmatter `abstract:` line. OpenViking's L0-//! layer: a one-line summary embeds far more sharply than a long body, so-//! it gives the vector side a precise second vote per page.+//! * **Session-recall routing** — a zero-LLM lexical check that recognises+//! queries phrased as "find a past session / what did we do back then"+//! ("上次 / 之前那次…的会话 / last time / yesterday …"). Session pages+//! otherwise carry a bounded authority penalty (kind `session` −0.15,+//! tier `episodic` −0.08, ×0.77 combined) because they are rarely the+//! right answer to a fact query — but a query that is *about* a past+//! session needs one. When the routing fires, the penalty is handed+//! back plus a small bonus, still inside the authority bounds every+//! other page lives in.+//! * **Abstract vectors** — a fifth RRF stream over+//! `page_abstract_embeddings`, the embedding of a page's frontmatter+//! `abstract:` line (the L0 layer). A one-line summary embeds far more+//! sharply than a multi-thousand-character body, giving the vector side+//! a precise second vote per page. Contributes nothing while the table+//! is empty.//!-//! Every multiplier and stream is reported in `SearchExplain`, so an-//! `explain=true` query can account for the returned rank.+//! Both signals are reported in `SearchExplain`, so an `explain=true`+//! query can account for the returned rank.use serde::{Deserialize, Serialize};-/// Microseconds in one day.-const DAY_US: f64 = 86_400.0 * 1_000_000.0;-/// Tunables for the opt-in ranking signals. `Default` disables both.#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]#[serde(default)]pub struct RetrievalTuning {- /// Weight of the hotness boost (`1 + alpha * hotness`). `0` disables it.- pub hotness_alpha: f64,- /// Half-life, in days, of the recency term inside the hotness score.- pub hotness_half_life_days: f64,- /// Enable lexical query-intent routing (`recency` / `session_recall`).- pub query_intent: bool,- /// Weight of the recency boost applied under the `recency` intent.- pub recency_beta: f64,- /// Half-life, in days, of the recency boost under the `recency` intent.- pub recency_half_life_days: f64,- /// Extra authority added to session pages under `session_recall`, on- /// top of cancelling their kind/tier penalties.+ /// Lexical session-recall routing (see [`is_session_recall_query`]).+ pub session_recall_routing: bool,+ /// Extra authority added to session pages when the routing fires, on+ /// top of cancelling their kind/tier penalty.pub session_recall_bonus: f64,/// Add the L0 abstract-embedding stream to the RRF fusion. Reads/// `page_abstract_embeddings`; contributes nothing while it is empty.@@ -56,106 +41,19 @@ pub struct RetrievalTuning {impl Default for RetrievalTuning {fn default() -> Self {Self {- hotness_alpha: 0.0,- hotness_half_life_days: 7.0,- query_intent: false,- recency_beta: 0.5,- recency_half_life_days: 30.0,- session_recall_bonus: 0.10,+ session_recall_routing: false,+ // Measured on a 138-query golden set: 0.25 recovers most+ // session-recall hit@1 (0.14 → 0.71 alongside the abstract+ // stream) while unrouted fact queries keep their exact baseline+ // ranking. Lower it (e.g. 0.15) if "之前/上次"-prefixed fact+ // queries are common in your traffic and rank drift on them+ // matters more than session recall.+ session_recall_bonus: 0.25,abstract_vectors: false,}}}-impl RetrievalTuning {- /// True when any signal needs per-page `access_count` / `updated_at`.- #[must_use]- pub fn needs_page_signals(&self, intent: Option<QueryIntent>) -> bool {- self.hotness_alpha > 0.0 || matches!(intent, Some(QueryIntent::Recency))- }-- /// Detect the query intent, or `None` when routing is disabled or the- /// query carries no intent marker.- #[must_use]- pub fn intent_for(&self, query: &str) -> Option<QueryIntent> {- if self.query_intent {- detect_query_intent(query)- } else {- None- }- }-- /// `1 + alpha * hotness`, or exactly `1.0` when hotness is disabled.- #[must_use]- pub fn hotness_boost(&self, access_count: i64, updated_at_us: i64, now_us: i64) -> (f64, f64) {- if self.hotness_alpha <= 0.0 {- return (0.0, 1.0);- }- let h = hotness_score(- access_count,- updated_at_us,- now_us,- self.hotness_half_life_days,- );- (h, 1.0 + self.hotness_alpha * h)- }-- /// Multiplier for one hit under the detected intent. Session-page- /// handling lives on `PageAuthority`; this covers the recency intent.- #[must_use]- pub fn recency_boost(&self, updated_at_us: i64, now_us: i64) -> f64 {- if self.recency_beta <= 0.0 {- return 1.0;- }- 1.0 + self.recency_beta * time_decay(updated_at_us, now_us, self.recency_half_life_days)- }-}--/// Lexically detected query intent.-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]-#[serde(rename_all = "snake_case")]-pub enum QueryIntent {- /// The caller wants the *current* state of something.- Recency,- /// The caller wants to find a past session / what happened then.- SessionRecall,-}--impl QueryIntent {- /// Stable wire name (matches the serde representation).- #[must_use]- pub fn as_str(self) -> &'static str {- match self {- Self::Recency => "recency",- Self::SessionRecall => "session_recall",- }- }-}--/// `sigmoid(ln(1 + access_count)) * exp(-ln2 * age_days / half_life)` in `[0, 1]`.-#[must_use]-pub fn hotness_score(- access_count: i64,- updated_at_us: i64,- now_us: i64,- half_life_days: f64,-) -> f64 {- let n = access_count.max(0) as f64;- let freq = 1.0 / (1.0 + (-(1.0 + n).ln()).exp());- freq * time_decay(updated_at_us, now_us, half_life_days)-}--/// Exponential recency in `(0, 1]`: `1` for a page updated right now, `0.5`-/// after one half-life. A non-positive half-life disables the decay (`1`).-#[must_use]-pub fn time_decay(updated_at_us: i64, now_us: i64, half_life_days: f64) -> f64 {- if half_life_days <= 0.0 {- return 1.0;- }- let age_days = (now_us.saturating_sub(updated_at_us).max(0) as f64) / DAY_US;- (-(std::f64::consts::LN_2 / half_life_days) * age_days).exp()-}-// Markers are matched on the lower-cased query. CJK phrases match as plain// substrings; Latin phrases match on word boundaries so "now" never fires// inside "known" or "snow". "会话" (session) only counts in a recall frame@@ -203,73 +101,18 @@ const SESSION_RECALL_EN: &[&str] = &["earlier we","previously",];-const RECENCY_ZH: &[&str] = &[- "现在",- "目前",- "当前",- "最新",- "最近",- "如今",- "现状",- "现行",- "现有",- "现用",- "改成",- "改为",- "换成",- "切换",- "切到",- "迁到",- "还在",- "仍然",- "仍在",- "是否还",- "还吃",- "还用",- "还加",- "新版",- "升级后",- "以后",- "今后",-];-const RECENCY_EN: &[&str] = &[- "now",- "current",- "currently",- "latest",- "recent",- "recently",- "still",- "anymore",- "these days",- "at the moment",- "switched",- "changed to",- "moved to",- "up to date",- "newest",- "today",- "nowadays",-];-/// Route a query to an intent by lexical markers. Session-recall markers win-/// over recency markers because "上次我们把 X 改成什么" is about *where* the-/// answer lives (a session), not about which version is current.+/// Route a query to session-recall retrieval by lexical markers. Deliberately+/// zero-LLM: it gates a bounded ranking nudge, not a retrieval mode, and a+/// false positive costs a few rank positions rather than a wrong answer.#[must_use]-pub fn detect_query_intent(query: &str) -> Option<QueryIntent> {+pub fn is_session_recall_query(query: &str) -> bool {let lowered = query.to_lowercase();let padded = latin_word_padded(&lowered);- let hits = |zh: &[&str], en: &[&str]| {- zh.iter().any(|m| lowered.contains(m))- || en.iter().any(|m| padded.contains(&format!(" {m} ")))- };- if hits(SESSION_RECALL_ZH, SESSION_RECALL_EN) {- Some(QueryIntent::SessionRecall)- } else if hits(RECENCY_ZH, RECENCY_EN) {- Some(QueryIntent::Recency)- } else {- None- }+ SESSION_RECALL_ZH.iter().any(|m| lowered.contains(m))+ || SESSION_RECALL_EN+ .iter()+ .any(|m| padded.contains(&format!(" {m} ")))}/// Replace every non-alphanumeric Latin character with a space and pad the@@ -292,75 +135,15 @@ fn latin_word_padded(lowered: &str) -> String {mod tests {use super::*;- const DAY: i64 = 86_400 * 1_000_000;-#[test]fn default_tuning_is_inert() {let t = RetrievalTuning::default();- assert_eq!(t.hotness_boost(50, 0, 10 * DAY), (0.0, 1.0));- assert_eq!(t.intent_for("现在 X 用什么"), None);- assert!(!t.needs_page_signals(None));- }-- #[test]- fn hotness_is_bounded_and_monotone() {- let now = 100 * DAY;- let fresh_hot = hotness_score(100, now, now, 7.0);- let fresh_cold = hotness_score(0, now, now, 7.0);- let stale_hot = hotness_score(100, now - 70 * DAY, now, 7.0);- assert!(fresh_hot > fresh_cold && fresh_cold > stale_hot);- assert!((0.0..=1.0).contains(&fresh_hot) && (0.0..=1.0).contains(&stale_hot));- // sigmoid(ln 1) = 0.5: a never-read page updated now scores 0.5.- assert!((fresh_cold - 0.5).abs() < 1e-9);- // one half-life halves the recency term.- let half = hotness_score(0, now - 7 * DAY, now, 7.0);- assert!((half - 0.25).abs() < 1e-9);- }-- #[test]- fn hotness_boost_uses_alpha() {- let t = RetrievalTuning {- hotness_alpha: 0.4,- ..RetrievalTuning::default()- };- let (h, boost) = t.hotness_boost(0, 10 * DAY, 10 * DAY);- assert!((h - 0.5).abs() < 1e-9);- assert!((boost - 1.2).abs() < 1e-9);- // future timestamps never produce a boost above 1 + alpha.- let (_, capped) = t.hotness_boost(i64::MAX, 20 * DAY, 10 * DAY);- assert!(capped <= 1.0 + t.hotness_alpha + 1e-9);- }-- #[test]- fn recency_boost_decays_with_age() {- let t = RetrievalTuning {- query_intent: true,- ..RetrievalTuning::default()- };- let now = 400 * DAY;- let fresh = t.recency_boost(now, now);- let month = t.recency_boost(now - 30 * DAY, now);- let year = t.recency_boost(now - 365 * DAY, now);- assert!((fresh - 1.5).abs() < 1e-9);- assert!((month - 1.25).abs() < 1e-9);- assert!(year < 1.001 && year >= 1.0);- }-- #[test]- fn detects_recency_intent() {- for q in [- "现在 new-api 网关映射到哪个端口",- "目前补剂方案里还吃 Omega-3 吗",- "What is the current embedding model?",- "is the qwen container still running",- "latest deployment steps for h3",- ] {- assert_eq!(detect_query_intent(q), Some(QueryIntent::Recency), "{q}");- }+ assert!(!t.session_recall_routing);+ assert!(!t.abstract_vectors);}#[test]- fn detects_session_recall_intent_and_wins_over_recency() {+ fn detects_session_recall_queries() {for q in ["上次排查 Caddy 配置的会话完成了吗","之前那次我们把端口改成了什么",@@ -368,16 +151,12 @@ mod tests {"what did we decide last time about the reranker","yesterday's session on the spool bug",] {- assert_eq!(- detect_query_intent(q),- Some(QueryIntent::SessionRecall),- "{q}"- );+ assert!(is_session_recall_query(q), "{q}");}}#[test]- fn plain_fact_queries_have_no_intent() {+ fn plain_fact_queries_are_not_session_recall() {for q in ["PowerShell 没有 head 命令","lark-cli docs update 报错 degrade_code 1011",@@ -386,16 +165,13 @@ mod tests {// "会话" as a topic, not a recall frame."user_sessions 异常会话 登录失败",] {- assert_eq!(detect_query_intent(q), None, "{q}");+ assert!(!is_session_recall_query(q), "{q}");}}#[test]fn latin_markers_respect_word_boundaries() {- assert_eq!(detect_query_intent("unknown snowfall"), None);- assert_eq!(- detect_query_intent("Now: unknown"),- Some(QueryIntent::Recency)- );+ assert!(!is_session_recall_query("unknown snowfall"));+ assert!(is_session_recall_query("what did we ship yesterday"));}}diff --git a/crates/ai-memory-store/tests/suite/mod.rs b/crates/ai-memory-store/tests/suite/mod.rsindex 46df6f92..54f25683 100644--- a/crates/ai-memory-store/tests/suite/mod.rs+++ b/crates/ai-memory-store/tests/suite/mod.rs@@ -10,6 +10,7 @@ mod client_activity;mod fts_drift_status;mod handoff_ownership;mod multi_session;+mod retrieval_tuning_streams;mod session_ids_touching_scope;mod session_observations;mod session_scope_from_observations;diff --git a/crates/ai-memory-store/tests/suite/retrieval_tuning_streams.rs b/crates/ai-memory-store/tests/suite/retrieval_tuning_streams.rsnew file mode 100644index 00000000..428abb51--- /dev/null+++ b/crates/ai-memory-store/tests/suite/retrieval_tuning_streams.rs@@ -0,0 +1,260 @@+//! Opt-in ranking signals (`[retrieval]`): session-recall routing and the L0+//! abstract-embedding stream must be inert by default and change ordering+//! only when explicitly enabled.++use ai_memory_core::{NewPage, PagePath, Tier};+use ai_memory_store::{EmbeddingWrite, RetrievalTuning, Store, f32_vec_to_bytes};++fn page(+ ws: ai_memory_core::WorkspaceId,+ proj: ai_memory_core::ProjectId,+ path: &str,+ title: &str,+ body: &str,+ tier: Tier,+) -> NewPage {+ NewPage {+ workspace_id: ws,+ project_id: proj,+ path: PagePath::new(path).unwrap(),+ title: title.into(),+ body: body.into(),+ tier,+ frontmatter_json: serde_json::json!({}),+ pinned: false,+ links: Vec::new(),+ author_id: None,+ expires_at: None,+ entities: Vec::new(),+ }+}++fn tuning(session_recall: bool, bonus: f64, abstract_vectors: bool) -> RetrievalTuning {+ RetrievalTuning {+ session_recall_routing: session_recall,+ session_recall_bonus: bonus,+ abstract_vectors,+ }+}++async fn two_page_store() -> (+ tempfile::TempDir,+ Store,+ ai_memory_core::WorkspaceId,+ ai_memory_core::ProjectId,+) {+ 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();+ (tmp, store, ws, proj)+}++#[tokio::test]+async fn session_recall_routing_flips_session_page_ranking() {+ let (_tmp, mut store, ws, proj) = two_page_store().await;+ // Both pages carry the same discriminative token, so FTS ranks them+ // evenly and the authority factor alone decides the order.+ store+ .writer+ .upsert_page(page(+ ws,+ proj,+ "notes/fact.md",+ "fact",+ "zebraquux alpha",+ Tier::Semantic,+ ))+ .await+ .unwrap();+ store+ .writer+ .upsert_page(page(+ ws,+ proj,+ "sessions/s1.md",+ "past session",+ "zebraquux bravo",+ Tier::Episodic,+ ))+ .await+ .unwrap();++ let query = "上次我们 zebraquux".to_string();++ // Default: the semantic note outranks the penalised session page.+ let hits = store+ .reader+ .hybrid_search(+ ws,+ proj,+ query.clone(),+ None,+ String::new(),+ String::new(),+ 0,+ 10,+ None,+ )+ .await+ .unwrap();+ assert_eq!(hits[0].path.as_str(), "notes/fact.md");++ // Routing on: the session page gets its penalty back plus the bonus.+ store.reader.set_retrieval_tuning(tuning(true, 0.15, false));+ let hits = store+ .reader+ .hybrid_search_explained(+ ws,+ proj,+ query,+ None,+ String::new(),+ String::new(),+ 0,+ 10,+ None,+ )+ .await+ .unwrap();+ assert_eq!(hits[0].0.path.as_str(), "sessions/s1.md");+ let details = hits[0].1.clone();+ assert_eq!(details.intent, Some("session_recall"));+ assert!(details.intent_boost.unwrap_or(1.0) > 1.0);++ // A plain fact query under the same tuning is untouched: the routing+ // does not fire, so ordering stays with the semantic page.+ let hits = store+ .reader+ .hybrid_search(+ ws,+ proj,+ "zebraquux alpha".to_string(),+ None,+ String::new(),+ String::new(),+ 0,+ 10,+ None,+ )+ .await+ .unwrap();+ assert_eq!(hits[0].path.as_str(), "notes/fact.md");+}++#[tokio::test]+async fn abstract_vector_stream_is_opt_in() {+ let (_tmp, mut store, ws, proj) = two_page_store().await;+ store+ .writer+ .upsert_page(page(ws, proj, "notes/a.md", "a", "alpha", Tier::Semantic))+ .await+ .unwrap();+ let b = store+ .writer+ .upsert_page(page(ws, proj, "notes/b.md", "b", "bravo", Tier::Semantic))+ .await+ .unwrap();+ let a_id = store+ .reader+ .decay_candidates(ws, proj)+ .await+ .unwrap()+ .into_iter()+ .find(|c| c.path.as_str() == "notes/a.md")+ .unwrap()+ .id;++ // Query vector [1, 0]: a's body matches perfectly, b's only halfway.+ let query_vec = vec![1.0_f32, 0.0];+ let provider = "mock".to_string();+ let model = "mock-embed".to_string();+ let dim = 2_u32;+ store+ .writer+ .store_embedding(+ a_id,+ f32_vec_to_bytes(&[1.0, 0.0]),+ provider.clone(),+ model.clone(),+ dim,+ )+ .await+ .unwrap();+ store+ .writer+ .store_embedding(+ b,+ f32_vec_to_bytes(&[0.6, 0.8]),+ provider.clone(),+ model.clone(),+ dim,+ )+ .await+ .unwrap();+ // b also has an L0 abstract whose embedding matches the query exactly;+ // a has none.+ store+ .writer+ .store_abstract_embeddings(vec![EmbeddingWrite {+ page_id: b,+ vector_bytes: f32_vec_to_bytes(&[1.0, 0.0]),+ provider: provider.clone(),+ model: model.clone(),+ dim,+ }])+ .await+ .unwrap();++ let qv = Some(query_vec.clone());++ // Stream off: the body stream alone puts a first.+ store+ .reader+ .set_retrieval_tuning(tuning(false, 0.15, false));+ let hits = store+ .reader+ .hybrid_search(+ ws,+ proj,+ "anything".to_string(),+ qv.clone(),+ provider.clone(),+ model.clone(),+ dim,+ 10,+ None,+ )+ .await+ .unwrap();+ assert_eq!(hits[0].path.as_str(), "notes/a.md");++ // Stream on: b's exact abstract match adds a rank-1 RRF vote and flips+ // the order. a has no abstract row, so the stream degrades to nothing+ // for it.+ store.reader.set_retrieval_tuning(tuning(false, 0.15, true));+ let hits = store+ .reader+ .hybrid_search(+ ws,+ proj,+ "anything".to_string(),+ qv,+ provider,+ model,+ dim,+ 10,+ None,+ )+ .await+ .unwrap();+ assert_eq!(hits[0].path.as_str(), "notes/b.md");+}diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 124fb98a..57d10065 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -588,6 +588,17 @@ enabled = trueinterval_secs = 3600max_sessions_per_tick = 1 # per project; scheduler ticks do not overlapmin_session_age_secs = 600++[retrieval] # opt-in ranking signals; all off by default+query_intent = false # lexical session-recall routing: queries phrased as+ # "上次 / …的会话 / last time / yesterday" hand session+ # pages back their default kind/tier authority penalty+session_recall_bonus = 0.25 # extra authority on top of the cancelled penalty;+ # lower it (e.g. 0.15) if rank drift on+ # "之前/上次"-prefixed fact queries matters more+abstract_vectors = false # fifth RRF stream over page_abstract_embeddings+ # (L0: each page's frontmatter `abstract:` line, embedded+ # by the same backfill as the body)```**LLM provider env** (opt-in):