Skip to content

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.md
index 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 migrated
store stops growing without bound. The reserved-file check treated any
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rank
diff --git a/crates/ai-memory-store/src/retrieval_tuning.rs b/crates/ai-memory-store/src/retrieval_tuning.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.md
index 124fb98a..57d10065 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -588,6 +588,17 @@ enabled = true
interval_secs = 3600
max_sessions_per_tick = 1 # per project; scheduler ticks do not overlap
min_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):