Skip to content

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

Rust

wip(lab): OpenViking-inspired ranking experiments — hotness (negative), recency (negative), session-recall routing (positive), L0 abstract stream (positive)

evanmaranzano17010745a5ca
diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rs
index f2b01fed..b3ec701e 100644
--- a/crates/ai-memory-cli/src/commands/serve.rs
+++ b/crates/ai-memory-cli/src/commands/serve.rs
@@ -733,8 +733,12 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
migrations::snapshot_before_db_migration(&config.data_dir, backup_dest_override.as_deref())
.with_context(|| "taking the pre-migration safety backup")?;
- let store = Store::open(&config.data_dir)
+ let mut store = Store::open(&config.data_dir)
.with_context(|| format!("opening store at {}", config.data_dir.display()))?;
+ // Every reader handle below is cloned from this one, so the opt-in
+ // ranking signals are set once, here, and inherited everywhere.
+ store.reader.set_retrieval_tuning(config.retrieval.tuning());
+ let store = store;
// One-shot legacy heal (issue #103): NULL out any project repo_path that
// is a prefix-match catch-all. That means the $HOME and filesystem-root
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index 4b330060..06cf1f67 100644
--- a/crates/ai-memory-cli/src/config.rs
+++ b/crates/ai-memory-cli/src/config.rs
@@ -313,6 +313,9 @@ pub struct Config {
pub decay: DecaySettings,
/// Server-side scheduled maintenance. Jobs run outside hook latency.
pub maintenance: MaintenanceSettings,
+ /// Opt-in post-fusion ranking signals for `memory_query` (hotness boost,
+ /// lexical query-intent routing). All off by default.
+ pub retrieval: RetrievalSettings,
/// Memory-slot behaviour.
pub slots: SlotSettings,
/// LLM consolidation prompt limits. Defaults are sized for a model with a
@@ -717,6 +720,7 @@ impl Default for Config {
embedding_base_url: None,
decay: DecaySettings::default(),
maintenance: MaintenanceSettings::default(),
+ retrieval: RetrievalSettings::default(),
slots: SlotSettings::default(),
consolidation: ConsolidationSettings::default(),
auto_improve: AutoImproveSettings::default(),
@@ -983,6 +987,68 @@ impl Default for MaintenanceSettings {
}
}
+/// `[retrieval]` opt-in ranking signals layered on the RRF fusion in
+/// `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`.
+#[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.
+ 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`,
+ /// on top of cancelling their default kind/tier penalty.
+ pub session_recall_bonus: f64,
+ /// Add the L0 abstract-embedding stream (`page_abstract_embeddings`) to
+ /// the RRF fusion. Pages gain an abstract vector when their frontmatter
+ /// carries `abstract:` and the embedding backfill runs.
+ pub abstract_vectors: bool,
+}
+
+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,
+ session_recall_bonus: base.session_recall_bonus,
+ abstract_vectors: base.abstract_vectors,
+ }
+ }
+}
+
+impl RetrievalSettings {
+ /// Store-side tuning consumed by `ReaderPool::set_retrieval_tuning`.
+ #[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_bonus: self.session_recall_bonus.max(0.0),
+ abstract_vectors: self.abstract_vectors,
+ }
+ }
+}
+
impl Config {
/// Load the merged configuration: defaults → file → env → CLI.
///
diff --git a/crates/ai-memory-consolidate/src/embed.rs b/crates/ai-memory-consolidate/src/embed.rs
index 4e10b3b3..e98bda3a 100644
--- a/crates/ai-memory-consolidate/src/embed.rs
+++ b/crates/ai-memory-consolidate/src/embed.rs
@@ -35,6 +35,9 @@ pub struct EmbedBackfillCounts {
/// Pages that would be embedded in a live run (only meaningful
/// when `dry_run` was requested).
pub would_embed: usize,
+ /// L0 abstracts (frontmatter `abstract:`) embedded into
+ /// `page_abstract_embeddings` — the opt-in fifth retrieval stream.
+ pub abstracts_embedded: usize,
}
impl EmbedBackfillCounts {
@@ -44,6 +47,7 @@ impl EmbedBackfillCounts {
self.skipped += other.skipped;
self.failed += other.failed;
self.would_embed += other.would_embed;
+ self.abstracts_embedded += other.abstracts_embedded;
}
}
@@ -106,17 +110,46 @@ pub async fn run_embedding_backfill(
.into_iter()
.collect()
};
+ // L0 abstracts ride the same pass: only pages whose frontmatter carries
+ // an `abstract:` can need one, so a page with neither a missing body
+ // vector nor a missing abstract vector is still skipped without a read.
+ let abstract_bearing: HashSet<_> = reader
+ .abstract_bearing_page_ids(workspace_id, project_id)
+ .await?
+ .into_iter()
+ .collect();
+ let already_abstract: HashSet<_> = if options.reembed {
+ HashSet::new()
+ } else {
+ reader
+ .abstract_embedded_page_ids(
+ workspace_id,
+ project_id,
+ provider.clone(),
+ model.clone(),
+ dim,
+ )
+ .await?
+ .into_iter()
+ .collect()
+ };
let mut counts = EmbedBackfillCounts::default();
let mut pending = Vec::with_capacity(EMBEDDING_WRITE_BATCH);
+ let mut pending_abstract = Vec::with_capacity(EMBEDDING_WRITE_BATCH);
for cand in candidates {
- if already.contains(&cand.id) {
+ let need_body = !already.contains(&cand.id);
+ let need_abstract =
+ abstract_bearing.contains(&cand.id) && !already_abstract.contains(&cand.id);
+ if !need_body && !need_abstract {
counts.skipped += 1;
continue;
}
if options.dry_run {
- counts.would_embed += 1;
+ if need_body {
+ counts.would_embed += 1;
+ }
continue;
}
let md = match wiki.read_page(workspace_id, project_id, &cand.path) {
@@ -136,47 +169,99 @@ pub async fn run_embedding_backfill(
continue;
}
};
- if md.body.trim().is_empty() {
- // Permanent until the body changes. Recorded because a page
- // skipped on every pass is otherwise indistinguishable from an
- // idle one, which is what made #509 undiagnosable.
- let _ = writer
- .record_embed_failure(cand.id, ai_memory_store::EmbedOutcome::SkippedEmpty, None)
- .await;
- counts.skipped += 1;
- continue;
- }
- let vec = match embedder.embed_document(&md.body).await {
- Ok(vec) => vec,
- Err(e) => {
- warn!(path = %cand.path, error = %e, "embed: provider call failed");
+ if need_body {
+ if md.body.trim().is_empty() {
+ // Permanent until the body changes. Recorded because a page
+ // skipped on every pass is otherwise indistinguishable from an
+ // idle one, which is what made #509 undiagnosable.
let _ = writer
.record_embed_failure(
cand.id,
- ai_memory_store::EmbedOutcome::Failed,
- Some(e.to_string()),
+ ai_memory_store::EmbedOutcome::SkippedEmpty,
+ None,
)
.await;
- counts.failed += 1;
- continue;
+ counts.skipped += 1;
+ } else {
+ match embedder.embed_document(&md.body).await {
+ Ok(vec) => pending.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: provider call failed");
+ let _ = writer
+ .record_embed_failure(
+ cand.id,
+ ai_memory_store::EmbedOutcome::Failed,
+ Some(e.to_string()),
+ )
+ .await;
+ counts.failed += 1;
+ }
+ }
+ if pending.len() >= EMBEDDING_WRITE_BATCH {
+ flush_embedding_batch(writer, &mut pending, &mut counts).await;
+ }
+ }
+ }
+ 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;
+ }
}
- };
- pending.push(EmbeddingWrite {
- page_id: cand.id,
- vector_bytes: f32_vec_to_bytes(&vec),
- provider: provider.clone(),
- model: model.clone(),
- dim,
- });
- if pending.len() >= EMBEDDING_WRITE_BATCH {
- flush_embedding_batch(writer, &mut pending, &mut counts).await;
}
}
flush_embedding_batch(writer, &mut pending, &mut counts).await;
+ flush_abstract_batch(writer, &mut pending_abstract, &mut counts).await;
Ok(counts)
}
+/// The frontmatter `abstract:` line, when it is a non-empty string.
+fn frontmatter_abstract(frontmatter: &serde_json::Value) -> Option<&str> {
+ frontmatter
+ .get("abstract")
+ .and_then(serde_json::Value::as_str)
+ .map(str::trim)
+ .filter(|s| !s.is_empty())
+}
+
+async fn flush_abstract_batch(
+ writer: &WriterHandle,
+ pending: &mut Vec<EmbeddingWrite>,
+ counts: &mut EmbedBackfillCounts,
+) {
+ if pending.is_empty() {
+ return;
+ }
+ let batch = std::mem::replace(pending, Vec::with_capacity(EMBEDDING_WRITE_BATCH));
+ let count = batch.len();
+ if let Err(e) = writer.store_abstract_embeddings(batch).await {
+ counts.failed += count;
+ warn!(count, error = %e, "embed: store_abstract_embeddings failed");
+ } else {
+ counts.abstracts_embedded += count;
+ }
+}
+
async fn flush_embedding_batch(
writer: &WriterHandle,
pending: &mut Vec<EmbeddingWrite>,
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index 298d8ca7..402e2f23 100644
--- a/crates/ai-memory-mcp/src/server.rs
+++ b/crates/ai-memory-mcp/src/server.rs
@@ -2126,11 +2126,15 @@ impl AiMemoryServer {
Vec::new()
};
let streams_active = explain.then(|| {
+ let mut streams = vec!["fts", "entity"];
if query_vec.is_some() {
- vec!["fts", "entity", "vector", "graph"]
- } else {
- vec!["fts", "entity", "graph"]
+ streams.push("vector");
+ if self.reader.retrieval_tuning().abstract_vectors {
+ streams.push("abstract");
+ }
}
+ streams.push("graph");
+ streams
});
let hits = hits
.into_iter()
diff --git a/crates/ai-memory-store/migrations/V61__page_abstract_embeddings.sql b/crates/ai-memory-store/migrations/V61__page_abstract_embeddings.sql
new file mode 100644
index 00000000..2d2fcc10
--- /dev/null
+++ b/crates/ai-memory-store/migrations/V61__page_abstract_embeddings.sql
@@ -0,0 +1,20 @@
+-- L0 abstract embeddings (opt-in `[retrieval] abstract_vectors`).
+--
+-- A page whose frontmatter carries `abstract:` — the one-line summary the
+-- consolidator writes, or a curator adds — gets that line embedded on its
+-- own, separately from the body. A short abstract embeds far more sharply
+-- than a multi-thousand-character body, so this table backs a fifth RRF
+-- stream in hybrid search. Mirrors `page_embeddings`: one row per page,
+-- keyed on the same `(provider, model, dim)` triple so the same
+-- refuse-on-mismatch and stale-row rules apply.
+CREATE TABLE page_abstract_embeddings (
+ page_id BLOB PRIMARY KEY NOT NULL REFERENCES pages(id) ON DELETE CASCADE,
+ vector BLOB NOT NULL,
+ provider TEXT NOT NULL,
+ model TEXT NOT NULL,
+ dim INTEGER NOT NULL CHECK (dim > 0),
+ created_at INTEGER NOT NULL
+);
+
+CREATE INDEX idx_page_abstract_embeddings_provider
+ ON page_abstract_embeddings(provider, model, dim);
diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rs
index 8a42ad94..17675db7 100644
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@ -24,6 +24,7 @@ mod migrations;
mod ops;
pub mod password;
mod reader;
+mod retrieval_tuning;
mod scope;
mod session_consolidation;
pub mod users;
@@ -67,6 +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 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/ops.rs b/crates/ai-memory-store/src/ops.rs
index 48fde177..28b5137e 100644
--- a/crates/ai-memory-store/src/ops.rs
+++ b/crates/ai-memory-store/src/ops.rs
@@ -1803,22 +1803,41 @@ pub fn store_embedding(
/// Store / replace a batch of page embeddings in one transaction.
pub fn store_embeddings(conn: &mut Connection, embeddings: &[EmbeddingWrite]) -> StoreResult<()> {
+ store_embeddings_in_table(conn, "page_embeddings", embeddings)
+}
+
+/// Store / replace a batch of L0 abstract embeddings
+/// (`page_abstract_embeddings`) in one transaction. Same row shape and
+/// upsert rule as [`store_embeddings`]; only the table differs.
+pub fn store_abstract_embeddings(
+ conn: &mut Connection,
+ embeddings: &[EmbeddingWrite],
+) -> StoreResult<()> {
+ store_embeddings_in_table(conn, "page_abstract_embeddings", embeddings)
+}
+
+fn store_embeddings_in_table(
+ conn: &mut Connection,
+ table: &'static str,
+ embeddings: &[EmbeddingWrite],
+) -> StoreResult<()> {
if embeddings.is_empty() {
return Ok(());
}
let now = Timestamp::now().as_microsecond();
let tx = conn.transaction()?;
{
- let mut stmt = tx.prepare(
- "INSERT INTO page_embeddings (page_id, vector, provider, model, dim, created_at) \
+ let sql = format!(
+ "INSERT INTO {table} (page_id, vector, provider, model, dim, created_at) \
VALUES (?1, ?2, ?3, ?4, ?5, ?6) \
ON CONFLICT(page_id) DO UPDATE SET \
vector = excluded.vector, \
provider = excluded.provider, \
model = excluded.model, \
dim = excluded.dim, \
- created_at = excluded.created_at",
- )?;
+ created_at = excluded.created_at"
+ );
+ let mut stmt = tx.prepare(&sql)?;
for embedding in embeddings {
stmt.execute(params![
embedding.page_id.as_bytes(),
diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rs
index 380e44f1..8e328b1a 100644
--- a/crates/ai-memory-store/src/reader.rs
+++ b/crates/ai-memory-store/src/reader.rs
@@ -35,6 +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::users::TOKEN_HASH_LEN;
use crate::workstream::{ManagedRunContext, StoredManagedRunStatus, StoredWorkstreamSummary};
@@ -200,6 +201,9 @@ const AUTHORITY_MAX_EXTRA_CANDIDATES: usize = 300;
#[derive(Debug, Clone, Copy)]
struct PageAuthority {
factor: f64,
+ /// Kind/tier penalty this page carries *because* it is a session page
+ /// (`0.0` for every other kind). A `session_recall` query gives it back.
+ session_penalty: f64,
}
impl PageAuthority {
@@ -215,19 +219,25 @@ impl PageAuthority {
// out at 0.55x rather than excluding the page.
let mut factor = 1.0_f64;
- factor += match kind {
+ let kind_adjust = match kind {
"rule" | "decision" => 0.15,
"procedure" | "gotcha" => 0.12,
"concept" | "slot" => 0.07,
"session" => -0.15,
_ => 0.0,
};
- factor += match tier {
+ let tier_adjust = match tier {
"semantic" | "procedural" => 0.10,
"episodic" => -0.08,
"working" => -0.03,
_ => 0.0,
};
+ factor += kind_adjust + tier_adjust;
+ let session_penalty = if kind == "session" {
+ -(kind_adjust + tier_adjust.min(0.0))
+ } else {
+ 0.0
+ };
if pinned {
factor += 0.08;
}
@@ -265,14 +275,54 @@ impl PageAuthority {
Self {
factor: factor.clamp(0.55, 1.50),
+ session_penalty,
}
}
fn adjust_rank(&self, rank: f64) -> f64 {
- if rank <= 0.0 {
- rank * self.factor
- } else {
- rank / self.factor
+ 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,
+ }
+ }
+}
+
+/// Scale a rank by a `> 0` multiplier so a larger multiplier always means a
+/// better (lower) rank, whichever sign convention the rank arrived in: fused
+/// RRF ranks are negated scores (`<= 0`), raw FTS5 ranks are positive.
+fn apply_rank_multiplier(rank: f64, multiplier: f64) -> f64 {
+ if rank <= 0.0 {
+ rank * multiplier
+ } else {
+ rank / multiplier
+ }
+}
+
+/// The two embedding tables share one schema; scans differ only by name.
+#[derive(Debug, Clone, Copy)]
+enum EmbeddingTable {
+ /// `page_embeddings`: one vector per page over the full body.
+ Body,
+ /// `page_abstract_embeddings`: one vector per page over its L0
+ /// frontmatter `abstract:` line (opt-in stream).
+ Abstract,
+}
+
+impl EmbeddingTable {
+ fn name(self) -> &'static str {
+ match self {
+ Self::Body => "page_embeddings",
+ Self::Abstract => "page_abstract_embeddings",
}
}
}
@@ -477,6 +527,14 @@ pub struct RrfContributions {
pub graph: f64,
/// Entity-match stream contribution.
pub entity: f64,
+ /// L0 abstract-embedding stream contribution (opt-in
+ /// `[retrieval] abstract_vectors`; 0.0 when off or missed).
+ #[serde(rename = "abstract", skip_serializing_if = "is_zero")]
+ pub abstract_vector: f64,
+}
+
+fn is_zero(v: &f64) -> bool {
+ *v == 0.0
}
/// Score transparency for one `memory_query` hit: where the hit ranked
@@ -500,6 +558,12 @@ pub struct SearchExplain {
/// Cosine similarity against the query embedding.
#[serde(skip_serializing_if = "Option::is_none")]
pub cosine: Option<f32>,
+ /// 1-based rank in the L0 abstract-embedding stream (opt-in).
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub abstract_rank: Option<usize>,
+ /// Cosine similarity of the page's abstract embedding against the query.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub abstract_cosine: Option<f32>,
/// 1-based rank in the graph-neighbour stream.
#[serde(skip_serializing_if = "Option::is_none")]
pub graph_rank: Option<usize>,
@@ -528,6 +592,21 @@ 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.
+ #[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.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub intent_boost: Option<f64>,
/// Relevance in `[0, 1]` assigned by the optional post-RRF
/// reranker. `None` when no reranker is configured, when it
/// degraded, or when the hit fell outside the bounded judged prefix.
@@ -1371,6 +1450,10 @@ pub struct HealthDetail {
#[derive(Clone)]
pub struct ReaderPool {
inner: Arc<Inner>,
+ /// Opt-in post-fusion ranking signals (see [`RetrievalTuning`]). Lives
+ /// on the handle, so clones taken after [`Self::set_retrieval_tuning`]
+ /// share the operator's choice while the pool itself stays untouched.
+ tuning: RetrievalTuning,
}
struct Inner {
@@ -1392,9 +1475,22 @@ impl ReaderPool {
pool: Mutex::new(Vec::with_capacity(soft_cap.max(1))),
soft_cap: soft_cap.max(1),
}),
+ tuning: RetrievalTuning::default(),
})
}
+ /// Configure the opt-in ranking signals used by [`Self::hybrid_search`].
+ /// Only handles cloned from this one afterwards observe the change.
+ pub fn set_retrieval_tuning(&mut self, tuning: RetrievalTuning) {
+ self.tuning = tuning;
+ }
+
+ /// The ranking signals this handle applies (default: none).
+ #[must_use]
+ pub fn retrieval_tuning(&self) -> RetrievalTuning {
+ self.tuning
+ }
+
/// Run a synchronous closure against a pooled read-only connection.
///
/// The closure runs on the tokio blocking pool so it never starves the
@@ -3112,19 +3208,103 @@ impl ReaderPool {
provider: String,
model: String,
dim: u32,
+ ) -> StoreResult<Vec<PageId>> {
+ self.embedded_page_ids_in_table(
+ EmbeddingTable::Body,
+ workspace_id,
+ project_id,
+ provider,
+ model,
+ dim,
+ )
+ .await
+ }
+
+ /// Page ids whose L0 abstract already has a matching embedding row
+ /// (`page_abstract_embeddings`). The backfill uses it to skip pages
+ /// whose abstract is already indexed under the current triple.
+ ///
+ /// # Errors
+ /// Propagates any SQL or pool error.
+ pub async fn abstract_embedded_page_ids(
+ &self,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ provider: String,
+ model: String,
+ dim: u32,
+ ) -> StoreResult<Vec<PageId>> {
+ self.embedded_page_ids_in_table(
+ EmbeddingTable::Abstract,
+ workspace_id,
+ project_id,
+ provider,
+ model,
+ dim,
+ )
+ .await
+ }
+
+ /// Latest pages of a project whose frontmatter carries a non-empty
+ /// `abstract` string — the only pages the L0 stream can index. Lets the
+ /// backfill decide without reading every page off disk.
+ ///
+ /// # Errors
+ /// Propagates any SQL or pool error.
+ pub async fn abstract_bearing_page_ids(
+ &self,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
) -> StoreResult<Vec<PageId>> {
self.with_conn(move |conn| {
let mut stmt = conn.prepare_cached(
- "SELECT page_embeddings.page_id \
- FROM page_embeddings \
- JOIN pages ON pages.id = page_embeddings.page_id \
+ "SELECT pages.id \
+ FROM pages \
WHERE pages.workspace_id = ?1 \
AND pages.project_id = ?2 \
AND pages.is_latest = 1 \
- AND page_embeddings.provider = ?3 \
- AND page_embeddings.model = ?4 \
- AND page_embeddings.dim = ?5",
+ AND json_type(pages.frontmatter_json, '$.abstract') = 'text' \
+ AND length(trim(json_extract(pages.frontmatter_json, '$.abstract'))) > 0",
)?;
+ let rows = stmt.query_map(
+ params![workspace_id.as_bytes(), project_id.as_bytes()],
+ |row| {
+ let id_bytes: Vec<u8> = row.get(0)?;
+ Ok(id_bytes)
+ },
+ )?;
+ let mut out = Vec::new();
+ for row in rows {
+ out.push(PageId::from_slice(&row?)?);
+ }
+ Ok(out)
+ })
+ .await
+ }
+
+ async fn embedded_page_ids_in_table(
+ &self,
+ table: EmbeddingTable,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ provider: String,
+ model: String,
+ dim: u32,
+ ) -> StoreResult<Vec<PageId>> {
+ let table = table.name();
+ self.with_conn(move |conn| {
+ let sql = format!(
+ "SELECT {table}.page_id \
+ 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 \
+ AND {table}.provider = ?3 \
+ AND {table}.model = ?4 \
+ AND {table}.dim = ?5"
+ );
+ let mut stmt = conn.prepare_cached(&sql)?;
let rows = stmt.query_map(
params![
workspace_id.as_bytes(),
@@ -3158,21 +3338,52 @@ impl ReaderPool {
dim: u32,
limit: usize,
expiry_cutoff_us: i64,
+ ) -> StoreResult<Vec<(PageId, PagePath, f32)>> {
+ self.top_embedding_hits_in_table(
+ EmbeddingTable::Body,
+ workspace_id,
+ project_id,
+ query_vec,
+ provider,
+ model,
+ dim,
+ limit,
+ expiry_cutoff_us,
+ )
+ .await
+ }
+
+ /// Cosine top-`limit` over one embedding table for the latest, unexpired
+ /// pages of a project. The body and L0-abstract tables share a schema,
+ /// so the scan differs only in which table it reads.
+ #[allow(clippy::too_many_arguments)]
+ async fn top_embedding_hits_in_table(
+ &self,
+ table: EmbeddingTable,
+ workspace_id: WorkspaceId,
+ project_id: ProjectId,
+ query_vec: Vec<f32>,
+ provider: String,
+ model: String,
+ dim: u32,
+ limit: usize,
+ expiry_cutoff_us: i64,
) -> StoreResult<Vec<(PageId, PagePath, f32)>> {
if limit == 0 {
return Ok(Vec::new());
}
+ let table = table.name();
self.with_conn(move |conn| {
let sql = format!(
- "SELECT page_embeddings.page_id, page_embeddings.vector, pages.path \
- FROM page_embeddings \
- JOIN pages ON pages.id = page_embeddings.page_id \
+ "SELECT {table}.page_id, {table}.vector, pages.path \
+ 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 page_embeddings.provider = ?3 \
- AND page_embeddings.model = ?4 \
- AND page_embeddings.dim = ?5",
+ AND {table}.provider = ?3 \
+ AND {table}.model = ?4 \
+ AND {table}.dim = ?5",
not_expired = not_expired("pages", "?6"),
);
let mut stmt = conn.prepare_cached(&sql)?;
@@ -3965,6 +4176,56 @@ 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
@@ -4069,6 +4330,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`.
+ let tuning = self.tuning;
+ let intent = tuning.intent_for(&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
@@ -4103,7 +4368,23 @@ impl ReaderPool {
.map(|(hit, _authority)| hit)
.collect();
let mut vec_hits: Vec<(PageId, PagePath, f32)> = Vec::new();
+ let mut abstract_hits: Vec<(PageId, PagePath, f32)> = Vec::new();
if let Some(qv) = query_vec {
+ if tuning.abstract_vectors {
+ abstract_hits = self
+ .top_embedding_hits_in_table(
+ EmbeddingTable::Abstract,
+ workspace_id,
+ project_id,
+ qv.clone(),
+ provider.clone(),
+ model.clone(),
+ dim,
+ candidate_limit,
+ cutoff,
+ )
+ .await?;
+ }
vec_hits = self
.top_embedding_hits_for_project(
workspace_id,
@@ -4129,7 +4410,7 @@ impl ReaderPool {
}
}
}
- for (id, path, _) in &vec_hits {
+ for (id, path, _) in vec_hits.iter().chain(abstract_hits.iter()) {
if seed_seen.insert(*id) {
seed_ids.push(*id);
if let Some(paths) = &mut seed_paths {
@@ -4200,6 +4481,23 @@ impl ReaderPool {
details.fused += contrib;
}
}
+ for (rank, (id, path, cosine)) in abstract_hits.iter().enumerate() {
+ let contrib = 1.0 / (k + (rank + 1) as f64);
+ let entry = fused.entry(*id).or_insert_with(|| Fused {
+ path: path.clone(),
+ title: String::new(),
+ snippet: String::new(),
+ score: 0.0,
+ explain: explain.then(SearchExplain::default),
+ });
+ entry.score += contrib;
+ if let Some(details) = &mut entry.explain {
+ details.abstract_rank = Some(rank + 1);
+ details.abstract_cosine = Some(*cosine);
+ details.rrf.abstract_vector = contrib;
+ details.fused += contrib;
+ }
+ }
for (rank, e) in entity_hits.iter().enumerate() {
let contrib = 1.0 / (k + (rank + 1) as f64);
let entry = fused.entry(e.hit.id).or_insert_with(|| Fused {
@@ -4286,14 +4584,48 @@ 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) {
- hit.rank = authority.adjust_rank(hit.rank);
+ let factor = authority.factor_for(intent, 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(authority.factor);
+ details.authority = Some(factor);
+ if intent.is_some() {
+ details.intent = intent;
+ 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);
+ }
}
}
}
diff --git a/crates/ai-memory-store/src/retrieval_tuning.rs b/crates/ai-memory-store/src/retrieval_tuning.rs
new file mode 100644
index 00000000..e2495f70
--- /dev/null
+++ b/crates/ai-memory-store/src/retrieval_tuning.rs
@@ -0,0 +1,401 @@
+//! Opt-in post-fusion ranking signals for `hybrid_search`.
+//!
+//! Three bounded, independently switchable signals, all 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.
+//!
+//! Every multiplier and stream is 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.
+ 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.
+ pub abstract_vectors: bool,
+}
+
+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,
+ 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
+// ("的会话 / 次会话 / 会话里"), so a query *about* sessions as a topic —
+// "user_sessions 异常会话" — is not routed to past-session recall.
+const SESSION_RECALL_ZH: &[&str] = &[
+ "之前",
+ "上次",
+ "上回",
+ "上一次",
+ "那次",
+ "那回",
+ "前几天",
+ "前天",
+ "昨天",
+ "那天",
+ "上周",
+ "上星期",
+ "上个月",
+ "的会话",
+ "次会话",
+ "个会话",
+ "会话里",
+ "会话中",
+ "历史会话",
+ "当时我们",
+ "我们当时",
+];
+const SESSION_RECALL_EN: &[&str] = &[
+ "last time",
+ "last session",
+ "previous session",
+ "earlier session",
+ "that session",
+ "the session where",
+ "yesterday",
+ "the other day",
+ "last week",
+ "when we",
+ "we did",
+ "did we",
+ "what did we",
+ "how did we",
+ "back then",
+ "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.
+#[must_use]
+pub fn detect_query_intent(query: &str) -> Option<QueryIntent> {
+ 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
+ }
+}
+
+/// Replace every non-alphanumeric Latin character with a space and pad the
+/// ends, so multi-word markers can be matched as ` word word `.
+fn latin_word_padded(lowered: &str) -> String {
+ let mut out = String::with_capacity(lowered.len() + 2);
+ out.push(' ');
+ for ch in lowered.chars() {
+ if ch.is_ascii_alphanumeric() || (!ch.is_ascii() && ch.is_alphabetic()) {
+ out.push(ch);
+ } else {
+ out.push(' ');
+ }
+ }
+ out.push(' ');
+ out
+}
+
+#[cfg(test)]
+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}");
+ }
+ }
+
+ #[test]
+ fn detects_session_recall_intent_and_wins_over_recency() {
+ for q in [
+ "上次排查 Caddy 配置的会话完成了吗",
+ "之前那次我们把端口改成了什么",
+ "之前 agent-memory 方案推到 GitHub 的首次提交哈希是什么",
+ "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}"
+ );
+ }
+ }
+
+ #[test]
+ fn plain_fact_queries_have_no_intent() {
+ for q in [
+ "PowerShell 没有 head 命令",
+ "lark-cli docs update 报错 degrade_code 1011",
+ "known issue with snow rendering",
+ "git commit unable to auto-detect email",
+ // "会话" as a topic, not a recall frame.
+ "user_sessions 异常会话 登录失败",
+ ] {
+ assert_eq!(detect_query_intent(q), None, "{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)
+ );
+ }
+}
diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rs
index e8bb6941..9e42461c 100644
--- a/crates/ai-memory-store/src/writer.rs
+++ b/crates/ai-memory-store/src/writer.rs
@@ -311,6 +311,10 @@ pub(crate) enum WriteCmd {
embeddings: Vec<EmbeddingWrite>,
reply: oneshot::Sender<StoreResult<()>>,
},
+ StoreAbstractEmbeddingBatch {
+ embeddings: Vec<EmbeddingWrite>,
+ reply: oneshot::Sender<StoreResult<()>>,
+ },
DeleteStalePageEmbeddings {
workspace_id: WorkspaceId,
project_id: Option<ProjectId>,
@@ -1292,6 +1296,24 @@ impl WriterHandle {
rx.await.map_err(|_| StoreError::WriterClosed)?
}
+ /// Store or replace a batch of L0 abstract embeddings
+ /// (`page_abstract_embeddings`) in one SQLite transaction.
+ ///
+ /// # Errors
+ /// Returns [`StoreError::WriterClosed`] or propagates SQL errors.
+ pub async fn store_abstract_embeddings(
+ &self,
+ embeddings: Vec<EmbeddingWrite>,
+ ) -> StoreResult<()> {
+ let (tx, rx) = oneshot::channel();
+ self.send(WriteCmd::StoreAbstractEmbeddingBatch {
+ embeddings,
+ reply: tx,
+ })
+ .await?;
+ rx.await.map_err(|_| StoreError::WriterClosed)?
+ }
+
/// Remove embedding rows in a workspace/project scope whose triple does not match the configured provider/model/dim.
///
/// Used when re-embedding after a model migration (e.g. Gemini → OpenRouter).
@@ -2934,6 +2956,10 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {
let result = ops::store_embeddings(&mut conn, &embeddings);
send_or_warn(reply, result, "store_embeddings");
}
+ WriteCmd::StoreAbstractEmbeddingBatch { embeddings, reply } => {
+ let result = ops::store_abstract_embeddings(&mut conn, &embeddings);
+ send_or_warn(reply, result, "store_abstract_embeddings");
+ }
WriteCmd::DeleteStalePageEmbeddings {
workspace_id,
project_id,