mnemo_engine/store/recall.rs
1//! Retrieval: memories(), about(), exact search, recall (scoring, filters, budgets, the ANN and BM25 candidate paths).
2
3use super::*;
4
5/// The thread a recall filter pins with `_mnemo.thread` equality, if any.
6fn filter_thread_pin(f: &Filter) -> Option<&str> {
7 f.terms.iter().find_map(|t| match t {
8 FilterTerm::Eq(k, Value::String(s)) if k == MNEMO_META_THREAD => Some(s.as_str()),
9 _ => None,
10 })
11}
12
13/// Whether a recall filter can only match records that aren't in the ANN
14/// (R-004.2): it pins `_mnemo.thread`, or restricts `_mnemo.kind` to turns,
15/// essence items or thread links. Such recalls scan exactly instead.
16fn filter_bypasses_ann(f: &Filter) -> bool {
17 let non_ann = |v: &Value| {
18 matches!(
19 v.as_str(),
20 Some(MNEMO_META_KIND_TURN)
21 | Some(MNEMO_META_KIND_ESSENCE)
22 | Some(MNEMO_META_KIND_THREAD_LINK)
23 )
24 };
25 filter_thread_pin(f).is_some()
26 || f.terms.iter().any(|t| match t {
27 FilterTerm::Eq(k, v) => k == MNEMO_META_KIND && non_ann(v),
28 FilterTerm::In(k, vs) => {
29 k == MNEMO_META_KIND && !vs.is_empty() && vs.iter().all(non_ann)
30 }
31 _ => false,
32 })
33}
34
35impl Mnemo {
36 /// Return every live memory (used by tooling and compaction).
37 pub fn memories(&mut self) -> Result<Vec<Memory>> {
38 // FMT-9b: one pass over the vector pages instead of one per record.
39 self.ensure_column()?;
40 let entries: Vec<CatalogEntry> = self
41 .catalog
42 .iter()
43 .filter(|e| !e.deleted)
44 .cloned()
45 .collect();
46 let mut out = Vec::with_capacity(entries.len());
47 for e in &entries {
48 out.push(self.read_memory(e)?);
49 }
50 Ok(out)
51 }
52
53 /// 12.2 (`mnemo://recent`): the `n` most recently written live memories,
54 /// newest first. Only facts: no thread turns, essence items, thread
55 /// links or onboarding records, and nothing superseded or expired. A
56 /// keyed replacement is a new record, so it counts from when it was
57 /// written; an in-place [`Mnemo::update`] keeps its `created_at`. Reads
58 /// the catalog's rows and decrypts only the records it returns (on v9),
59 /// and doesn't count as an access.
60 pub fn recent(&mut self, n: usize) -> Result<Vec<Memory>> {
61 let now = crate::memory::now_secs();
62 let mut rows: Vec<(i64, CatalogEntry)> = Vec::new();
63 let mut unrowed: Vec<CatalogEntry> = Vec::new();
64 for e in self.catalog.iter().filter(|e| !e.deleted) {
65 match e.v9 {
66 Some(r) => {
67 if r.kind != ROW_KIND_FACT
68 || r.flags & ROW_SUPERSEDED != 0
69 || (r.flags & ROW_HAS_TTL != 0 && now >= r.expires_at)
70 || self.superseded.as_ref().is_some_and(|s| s.contains(&e.id))
71 {
72 continue;
73 }
74 rows.push((r.created_at, e.clone()));
75 }
76 // A v8 file (read-only) has no rows: its records are read.
77 None => unrowed.push(e.clone()),
78 }
79 }
80 rows.sort_by(|a, b| b.0.cmp(&a.0).then_with(|| b.1.id.cmp(&a.1.id)));
81 let keep = |m: &Memory| {
82 !m.metadata.contains_key(MNEMO_META_SUPERSEDED_BY)
83 && !m.metadata.contains_key(MNEMO_META_KIND)
84 && !is_onboarding(m)
85 && !m.is_expired(now)
86 };
87 let mut out = Vec::new();
88 for (_, e) in rows {
89 if out.len() >= n {
90 break;
91 }
92 let m = self.read_memory(&e)?;
93 if keep(&m) {
94 out.push(m);
95 }
96 }
97 for e in unrowed {
98 let m = self.read_memory(&e)?;
99 if keep(&m) {
100 out.push(m);
101 }
102 }
103 out.sort_by(|a, b| {
104 b.created_at
105 .cmp(&a.created_at)
106 .then_with(|| b.id.cmp(&a.id))
107 });
108 out.truncate(n);
109 Ok(out)
110 }
111
112 /// Return the database's **self-describing onboarding memories** — the
113 /// ones tagged `metadata.area = "onboarding"`. This is the engine-level
114 /// surface for the *single-file philosophy*: an agent who receives a
115 /// `.mnemo` file (and its passphrase) can call this to learn what the
116 /// file is, which embedder it expects, the recommended agent id, and any
117 /// other conventions the file's author chose to record — all without
118 /// needing any external documentation.
119 ///
120 /// Ordering: the canonical manifest (tag `metadata.topic = "manifest"`)
121 /// always comes first; everything else follows in `importance` descending,
122 /// then `created_at` ascending for deterministic results.
123 pub fn about(&mut self) -> Result<Vec<Memory>> {
124 // Phase 12.1: drop records that have been superseded by a newer
125 // keyed write. They still live in snapshot history and
126 // `history(key)` — just not here.
127 // R-004.2: read only the onboarding records, from the handle caches.
128 self.ensure_key_caches()?;
129 let ids: Vec<u128> = self
130 .layers
131 .as_ref()
132 .map(|l| l.onboarding.iter().copied().collect())
133 .unwrap_or_default();
134 let mut out: Vec<Memory> = Vec::new();
135 for e in self.live_entries(ids) {
136 let m = self.read_memory(&e)?;
137 if !m.metadata.contains_key(MNEMO_META_SUPERSEDED_BY) && is_onboarding(&m) {
138 out.push(m);
139 }
140 }
141 out.sort_by(|a, b| {
142 let a_manifest = is_manifest(a);
143 let b_manifest = is_manifest(b);
144 // Manifest topic wins first; then importance desc; then created_at asc.
145 b_manifest
146 .cmp(&a_manifest)
147 .then_with(|| b.importance.total_cmp(&a.importance))
148 .then_with(|| a.created_at.cmp(&b.created_at))
149 });
150 Ok(out)
151 }
152
153 /// The project essence for the `about` briefing (Phase 12.7d): the
154 /// [`EssenceScope::Project`] render at the default budget
155 /// ([`ESSENCE_DEFAULT_RENDER_BYTES`]), or `None` when the file has no
156 /// open project-scope item or timeline entry. The CLI and MCP `about`
157 /// append it after the manifest and onboarding memories; [`Mnemo::about`]
158 /// itself keeps returning records.
159 pub fn about_essence(&mut self) -> Result<Option<String>> {
160 let entries = self.essence_entries()?;
161 let mut any = false;
162 for e in &entries {
163 let m = self.read_memory(e)?;
164 let is_project_essence = m.metadata.get(MNEMO_META_KIND).and_then(|v| v.as_str())
165 == Some(MNEMO_META_KIND_ESSENCE)
166 && !m.metadata.contains_key(MNEMO_META_THREAD);
167 if is_project_essence && status_of(&m) != Some(essence_status::RESOLVED) {
168 any = true;
169 break;
170 }
171 }
172 if !any {
173 return Ok(None);
174 }
175 self.essence(EssenceScope::Project, ESSENCE_DEFAULT_RENDER_BYTES)
176 .map(Some)
177 }
178
179 // --- retrieval --------------------------------------------------------
180
181 /// Phase-1 brute-force search: rank live memories by raw similarity only.
182 /// Read-only — does not update access statistics.
183 pub fn search(
184 &mut self,
185 query: &[f32],
186 top_k: usize,
187 metric: Metric,
188 ) -> Result<Vec<(Memory, f32)>> {
189 if query.len() != self.dimensions {
190 return Err(MnemoError::DimensionMismatch {
191 expected: self.dimensions,
192 got: query.len(),
193 });
194 }
195 let now = memory::now_secs();
196 let entries: Vec<CatalogEntry> = self
197 .catalog
198 .iter()
199 .filter(|e| !e.deleted)
200 .cloned()
201 .collect();
202
203 let mut scored: Vec<(Memory, f32)> = Vec::new();
204 for e in &entries {
205 let m = self.read_memory(e)?;
206 if m.is_expired(now) {
207 continue;
208 }
209 let sim = memory::similarity(metric, query, &m.vector);
210 scored.push((m, sim));
211 }
212 scored.sort_by(|a, b| b.1.total_cmp(&a.1));
213 scored.truncate(top_k);
214 Ok(scored)
215 }
216
217 /// Phase-5 multi-signal recall: rank by
218 /// `α·similarity + β·recency + γ·importance + δ·ln(freq)`, with type and
219 /// agent filtering. Updates `accessed_at` / `access_count` on the
220 /// returned memories (persisted on the next `flush`).
221 ///
222 /// When an ANN index has been built ([`Mnemo::build_index`]), recall runs
223 /// the tiered IVF→PQ→rerank pipeline: it scores only the similarity-nearest
224 /// `n_rerank` candidates rather than every memory. Without an index it
225 /// scores every live memory exactly.
226 /// One pass of filter + score for [`Mnemo::recall`]. Factored out of
227 /// `recall` so the outer path can retry with a wider shortlist when
228 /// the type/agent/supersession/TTL filters starve the ANN-narrowed
229 /// result below `top_k` (Phase 12.1 short-results-on-indexed-path
230 /// fix).
231 ///
232 /// * `force_exact = false` → use the ANN index when one exists; fall
233 /// back to a full scan only if none is built.
234 /// * `force_exact = true` → skip the ANN index and scan every live
235 /// non-superseded record. Used by the outer path as the last-resort
236 /// attempt when widening the shortlist would already touch half or
237 /// more of the live non-superseded set.
238 ///
239 /// Returns an unsorted, un-truncated `Vec<RecallResult>`; the outer
240 /// `recall` sorts and truncates once.
241 pub(super) fn score_once(
242 &mut self,
243 req: &RecallRequest,
244 now: i64,
245 force_exact: bool,
246 ) -> Result<Vec<RecallResult>> {
247 // Candidate set: ANN-narrowed when an index exists and the
248 // caller hasn't forced an exact scan, else everything live.
249 // R-004.2: a filter pinning `_mnemo.thread` scans just that
250 // thread's records (from the handle caches); one that can only
251 // match non-fact kinds skips the ANN, which doesn't hold them.
252 // FMT-9d: keyword matches, normalised by the best one.
253 self.kw = None;
254 // 12.3 step 4: a recall by text uses its text when no keywords
255 // were given (hybrid by default); empty keywords opt out.
256 if let Some(text) = req.keywords_for(self.is_v9()).map(str::to_string) {
257 let scores = self.bm25_scores(&text, req.bm25_k1, req.bm25_b)?;
258 let max = scores.values().copied().fold(0.0f32, f32::max);
259 if max > 0.0 {
260 self.kw = Some(
261 scores
262 .into_iter()
263 .map(|(row, s)| (self.catalog[row].id, s / max))
264 .collect(),
265 );
266 } else {
267 self.kw = Some(std::collections::HashMap::new());
268 }
269 }
270 if let Some(thread) = filter_thread_pin(&req.filter) {
271 let thread = thread.to_string();
272 let entries = self.thread_entries(&thread)?;
273 return self.score_entries(req, now, &entries);
274 }
275 // Keyword-only: the candidates are the matches.
276 if req.query.is_empty() {
277 let ids: Vec<u128> = self
278 .kw
279 .as_ref()
280 .map_or(Vec::new(), |k| k.keys().copied().collect());
281 let entries: Vec<CatalogEntry> = ids
282 .into_iter()
283 .filter_map(|id| self.index.get(id, &self.catalog))
284 .map(|i| self.catalog[i].clone())
285 .filter(|e| !e.deleted)
286 .collect();
287 return self.score_entries(req, now, &entries);
288 }
289 let force_exact = force_exact || filter_bypasses_ann(&req.filter);
290 let mut entries: Vec<CatalogEntry> = match (&self.ann, force_exact) {
291 (Some(ann), false) => {
292 let n_rerank = self.rerank_for(ann, req);
293 let ids = ann.query(&req.query, req.n_probe, n_rerank);
294 ids.iter()
295 .filter_map(|&id| self.index.get(id, &self.catalog))
296 .map(|i| self.catalog[i].clone())
297 .filter(|e| !e.deleted)
298 .collect()
299 }
300 _ => self
301 .catalog
302 .iter()
303 .filter(|e| !e.deleted)
304 .cloned()
305 .collect(),
306 };
307 // FMT-9d: an ANN shortlist plus the keyword matches it missed.
308 if let Some(kw) = &self.kw {
309 if entries.len() < self.catalog.len() {
310 let have: std::collections::HashSet<u128> = entries.iter().map(|e| e.id).collect();
311 let extra: Vec<u128> = kw.keys().copied().filter(|id| !have.contains(id)).collect();
312 for id in extra {
313 if let Some(i) = self.index.get(id, &self.catalog) {
314 if !self.catalog[i].deleted {
315 entries.push(self.catalog[i].clone());
316 }
317 }
318 }
319 }
320 }
321
322 self.score_entries(req, now, &entries)
323 }
324
325 /// FMT-9d: a candidate's relevance: its vector similarity plus ε times
326 /// its normalised keyword score (keyword-only requests: just the
327 /// keyword score). Returns `(relevance, reported similarity)`.
328 pub(super) fn relevance(&self, req: &RecallRequest, id: u128, sim: f32) -> (f32, f32) {
329 let kw = self
330 .kw
331 .as_ref()
332 .and_then(|k| k.get(&id).copied())
333 .unwrap_or(0.0);
334 if req.query.is_empty() {
335 (kw, kw)
336 } else {
337 (sim + req.effective_keyword_weight() * kw, sim)
338 }
339 }
340
341 /// Score one candidate set for [`Mnemo::score_once`].
342 pub(super) fn score_entries(
343 &mut self,
344 req: &RecallRequest,
345 now: i64,
346 entries: &[CatalogEntry],
347 ) -> Result<Vec<RecallResult>> {
348 // FMT-9b: score v9 candidates from their rows and the fp16 column,
349 // decrypting only what makes `top_k`. A metadata filter needs the
350 // record body, so it takes the general path below.
351 if self.is_v9() && req.filter.is_empty() {
352 return self.score_rows(req, now, entries);
353 }
354 let mut scored: Vec<RecallResult> = Vec::with_capacity(entries.len());
355 for e in entries {
356 // Phase 12.1: drop superseded records.
357 //
358 // Fast path: if the lazy `superseded` set has already been
359 // built by a prior keyed op on this handle, check it before
360 // decrypt — O(1), no AES work. On a fresh read-only handle
361 // it is typically `None`, so we fall through to the slow
362 // path (one `_mnemo.superseded_by` lookup per surviving
363 // record, O(k) over user metadata), and never trigger the
364 // full-file scan that `ensure_key_caches()` would do.
365 if self.superseded.as_ref().is_some_and(|s| s.contains(&e.id)) {
366 continue;
367 }
368 let m = self.read_memory(e)?;
369 if m.metadata.contains_key(MNEMO_META_SUPERSEDED_BY) {
370 continue;
371 }
372 if m.is_expired(now) {
373 continue;
374 }
375 if let Some(types) = &req.memory_types {
376 if !types.contains(&m.memory_type) {
377 continue;
378 }
379 }
380 if let Some(agent) = &req.agent_id {
381 let visible = m.agent_id == *agent || m.scope == Scope::Shared;
382 if !visible {
383 continue;
384 }
385 }
386 // Phase 12.6: pre-scoring filter (session_id + metadata
387 // conditions). Cheap when `req.filter.is_empty()`; the
388 // filter struct's `matches` is a short-circuit AND.
389 if !req.filter.is_empty() && !req.filter.matches(&m) {
390 continue;
391 }
392 // v0.16.1: a turn of nothing but markers (`[thinking]`, a
393 // tool call) is never a recall hit, whatever the filter: it
394 // would match any query weakly. Its content decides, so a turn
395 // saved before v0.16.1 is left out too.
396 if is_markers_only_turn(&m) {
397 continue;
398 }
399 // Phase 12.7: default-exclude the thread layers from fact
400 // recall: archive turns (12.7a), essence items (12.7b; read
401 // by scope through the render, not by similarity) and
402 // thread-link markers (12.7c; they carry an all-equal
403 // sentinel vector and would surface as junk hits). A caller
404 // that wants them opts in by placing any `_mnemo.*` term in
405 // the filter (equality, `$in`, `$exists`, or a range on
406 // `_mnemo.thread` / `_mnemo.kind` / `_mnemo.seq`).
407 if !req.filter.mentions_mnemo_meta()
408 && matches!(
409 m.metadata.get(MNEMO_META_KIND).and_then(|v| v.as_str()),
410 Some(MNEMO_META_KIND_TURN)
411 | Some(MNEMO_META_KIND_ESSENCE)
412 | Some(MNEMO_META_KIND_THREAD_LINK)
413 )
414 {
415 continue;
416 }
417 let sim = if req.query.is_empty() {
418 0.0
419 } else {
420 memory::similarity(req.metric, &req.query, &m.vector)
421 };
422 let (rel, sim) = self.relevance(req, e.id, sim);
423 let age_secs = (now - m.created_at) as f32;
424 let score = req
425 .weights
426 .score(rel, age_secs, m.importance, m.access_count);
427 scored.push(RecallResult {
428 memory: m,
429 score,
430 similarity: sim,
431 });
432 }
433 Ok(scored)
434 }
435
436 /// FMT-9b: [`Mnemo::score_entries`] for a v9 file with no metadata
437 /// filter. Every check the general path makes on the decrypted record
438 /// is made on the row instead (supersession, TTL, type, agent
439 /// visibility, the thread-layer kinds), the similarity comes from the
440 /// fp16 column, and the score from the row's `created_at` and
441 /// `importance`. Candidates are then decrypted best-first until `top_k`
442 /// survive; the agent check is repeated on the record, since the row
443 /// only has a hash of the agent id.
444 pub(super) fn score_rows(
445 &mut self,
446 req: &RecallRequest,
447 now: i64,
448 entries: &[CatalogEntry],
449 ) -> Result<Vec<RecallResult>> {
450 self.ensure_column()?;
451 let d = self.dimensions;
452 let q = &req.query;
453 let q_norm = q.iter().map(|x| x * x).sum::<f32>().sqrt();
454 let agent_h = req.agent_id.as_deref().map(|a| fnv1a32(&[a.as_bytes()]));
455 let types: Option<Vec<u8>> = req
456 .memory_types
457 .as_ref()
458 .map(|ts| ts.iter().map(|&t| memory_type_code(t)).collect());
459 let mut cand: Vec<(f32, f32, usize)> = Vec::with_capacity(entries.len());
460 for (pos, e) in entries.iter().enumerate() {
461 let Some(r) = e.v9 else { continue };
462 if r.flags & ROW_SUPERSEDED != 0 {
463 continue;
464 }
465 if self.superseded.as_ref().is_some_and(|s| s.contains(&e.id)) {
466 continue;
467 }
468 if r.flags & ROW_HAS_TTL != 0 && now >= r.expires_at {
469 continue;
470 }
471 if let Some(ts) = &types {
472 if !ts.contains(&r.memory_type) {
473 continue;
474 }
475 }
476 if let Some(ah) = agent_h {
477 if r.flags & ROW_SHARED == 0 && r.agent_hash != ah {
478 continue;
479 }
480 }
481 if matches!(
482 r.kind,
483 ROW_KIND_TURN | ROW_KIND_ESSENCE | ROW_KIND_THREAD_LINK
484 ) {
485 continue;
486 }
487 let Some(idx) = self.index.get(e.id, &self.catalog) else {
488 continue;
489 };
490 if !req.query.is_empty()
491 && self.col.resident
492 && idx < self.col.have.len()
493 && !self.col.have[idx]
494 && !self.col.hot.contains_key(&idx)
495 {
496 self.fill_column_page(idx)?;
497 }
498 let sim = if req.query.is_empty() {
499 0.0
500 } else if let Some((h, n)) = self.col.hot.get(&idx) {
501 veccol::similarity_f16(req.metric, q, q_norm, h, *n)
502 } else if self.col.resident && self.col.have.get(idx).copied().unwrap_or(false) {
503 veccol::similarity_f16(
504 req.metric,
505 q,
506 q_norm,
507 &self.col.data[idx * d..(idx + 1) * d],
508 self.col.norms[idx],
509 )
510 } else {
511 let (h, n) = self.column_entry(e)?;
512 veccol::similarity_f16(req.metric, q, q_norm, &h, n)
513 };
514 let (rel, sim) = self.relevance(req, e.id, sim);
515 let score = req.weights.score(
516 rel,
517 (now - r.created_at) as f32,
518 r.importance,
519 e.access_count,
520 );
521 cand.push((score, sim, pos));
522 }
523 cand.sort_by(|a, b| b.0.total_cmp(&a.0));
524 let mut out: Vec<RecallResult> = Vec::with_capacity(req.top_k.min(cand.len()));
525 for (score, sim, pos) in cand {
526 if out.len() >= req.top_k {
527 break;
528 }
529 let m = self.read_memory(&entries[pos])?;
530 if let Some(agent) = &req.agent_id {
531 if !(m.agent_id == *agent || m.scope == Scope::Shared) {
532 continue;
533 }
534 }
535 out.push(RecallResult {
536 memory: m,
537 score,
538 similarity: sim,
539 });
540 }
541 Ok(out)
542 }
543
544 /// 12.3 step 5: the keywords the registered embedder chooses for this
545 /// request ([`crate::Embedder::query_keywords`]): asked only for a recall
546 /// by text with no keywords given, on a v9 file (a v8 file has no
547 /// keyword index and ignores the text).
548 fn embedder_keywords(&self, req: &RecallRequest) -> Option<String> {
549 if req.keywords.is_some() || !self.is_v9() {
550 return None;
551 }
552 let text = req.text.as_deref().filter(|t| !t.trim().is_empty())?;
553 self.embedder.as_ref()?.query_keywords(text)
554 }
555
556 /// Phase-5 multi-signal recall under the v0.7.0 scoring-v2 formula
557 /// (see [`crate::ScoreWeights`]). Thin wrapper over
558 /// [`Mnemo::recall_budgeted`] that drops the `truncated` flag;
559 /// use the budgeted form if you need to know whether
560 /// [`RecallRequest::max_bytes`] cut anything.
561 pub fn recall(&mut self, req: &RecallRequest) -> Result<Vec<RecallResult>> {
562 Ok(self.recall_budgeted(req)?.hits)
563 }
564
565 /// Phase 12.8 budgeted recall: scoring v2 (see [`crate::ScoreWeights`])
566 /// with an optional UTF-8-content byte cap. Ranks by
567 /// `sim + max(sim, 0) · (β·recency + γ·(importance − 0.5) + δ·tanh(uses/5))`,
568 /// with type / agent / supersession / TTL filters and the 12.6
569 /// `Filter` applied before the scorer. Updates `accessed_at` /
570 /// `access_count` on the returned memories (persisted on the next
571 /// `flush`).
572 ///
573 /// When an ANN index has been built ([`Mnemo::build_index`]),
574 /// recall runs the tiered IVF→PQ→rerank pipeline. If the filters
575 /// (type / agent / supersession / TTL / 12.6) reduce the ANN
576 /// shortlist below `top_k`, Phase 12.1's short-results-on-indexed-
577 /// path fix kicks in: the query is retried with `n_probe` and
578 /// `n_rerank` doubled, and if that would already touch half or
579 /// more of the live non-superseded records, the ANN pass is
580 /// skipped for an exact scan. Without an index, recall scores
581 /// every live non-superseded memory.
582 ///
583 /// Phase 12.8: after `top_k` is applied, if
584 /// [`RecallRequest::max_bytes`] is set, hits are dropped in rank
585 /// order once the running sum of `content` UTF-8 bytes would
586 /// exceed the budget. The top-1 hit is always kept even if it
587 /// alone exceeds the budget. [`RecallResponse::truncated`] is
588 /// `true` iff at least one hit was dropped by the budget.
589 pub fn recall_budgeted(&mut self, req: &RecallRequest) -> Result<RecallResponse> {
590 // 12.3 step 5 (v0.15): the registered embedder may name the keywords
591 // for a recall by text (the built-in's identifier-aware recall).
592 let chosen;
593 let req = match self.embedder_keywords(req) {
594 Some(k) => {
595 chosen = req.clone().keywords(k);
596 &chosen
597 }
598 None => req,
599 };
600 // FMT-9d: keyword recall needs a v9 file's BM25 index; a
601 // keyword-only request has no vector.
602 if req
603 .keywords
604 .as_deref()
605 .is_some_and(|k| !k.trim().is_empty())
606 && !self.is_v9()
607 {
608 return Err(MnemoError::Invalid(
609 "keyword recall (keywords) needs a v9 file; run `mnemo compact` to upgrade".into(),
610 ));
611 }
612 let keyword_only = req.query.is_empty() && req.keywords.is_some();
613 if !keyword_only && req.query.len() != self.dimensions {
614 return Err(MnemoError::DimensionMismatch {
615 expected: self.dimensions,
616 got: req.query.len(),
617 });
618 }
619 // PERF-1 step 3: the ANN index loads on the first recall.
620 self.ensure_ann()?;
621 // Access-tracking bumps `accessed_at` / `access_count` in the
622 // catalog, which is a mutation. On a read-only handle the caller
623 // must pass `track_access(false)` (via CLI `--no-track`).
624 // 12.4: a shared read (read-only for the call, with a delta) keeps
625 // the bumps for the handle's next commit instead.
626 if self.read_only && req.track_access && self.access_delta.is_none() {
627 return Err(MnemoError::ReadOnly);
628 }
629 // Phase 12.1 **fix** (lane A v0.8.0 REVIEW): do NOT call
630 // `ensure_key_caches()` here. A fresh read-only handle that
631 // only ever recalls would otherwise pay a full-file decrypt
632 // on its first query to build the lazy superseded set. Instead
633 // `score_once` checks `_mnemo.superseded_by` per-record after
634 // decrypt (slow path) and consults the set only when it has
635 // already been built by a prior keyed op on this handle (fast
636 // path). `live_non_superseded` is not knowable without a
637 // decrypt pass either, so we approximate by `live_count`; the
638 // exact-scan gate uses this as a conservative upper bound,
639 // which errs toward widening (cheaper) rather than skipping
640 // straight to a full scan.
641 let live_count = self.catalog.iter().filter(|e| !e.deleted).count();
642 let live_non_superseded = live_count;
643 let now = memory::now_secs();
644
645 // Scoring v2 (shipped v0.7.0). Single-pass filter + score:
646 // * `age_secs = now - m.created_at`, so a recall doesn't bump
647 // its own results' recency on later queries.
648 // * `ScoreWeights::score` applies the similarity-gated,
649 // importance-centered, saturating-usage formula documented
650 // on `ScoreWeights`.
651 //
652 // Phase 12.1 + 12.6 short-results-on-indexed-path fix: when the
653 // ANN shortlist is narrower than the live count, the filters
654 // (type / agent / supersession / TTL / 12.6) can reduce the
655 // result below `top_k`. If that happens, re-query the index
656 // with `n_probe` / `n_rerank` doubled from their *effective*
657 // base; if that would already cover ≥50% of the live set,
658 // skip the index and do an exact scan.
659 //
660 // Lane A v0.8.0 REVIEW fix: widen from
661 // `IvfPqIndex::effective_defaults()` when the caller didn't
662 // pin the knobs. The pre-fix code only doubled when `req.n_*`
663 // was already `Some(_)`, which skipped the widen step for the
664 // default (unpinned) recall path and jumped straight to an
665 // exact scan on moderately selective filters.
666 let mut scored = self.score_once(req, now, false)?;
667 let mut used_exact_scan = self.ann.is_none() || filter_bypasses_ann(&req.filter);
668 if !used_exact_scan && scored.len() < req.top_k && live_non_superseded > req.top_k {
669 if let Some(ann) = &self.ann {
670 let (default_probe, default_rerank) = ann.effective_defaults();
671 let base_probe = req.n_probe.unwrap_or(default_probe);
672 let base_rerank = self.rerank_for(ann, req).unwrap_or(default_rerank);
673 let widen_probe = base_probe.saturating_mul(2);
674 let widen_rerank = base_rerank.saturating_mul(2);
675 // Attempt 2: widen once, 2× from the effective base.
676 // Only worth another ANN pass if either knob actually
677 // grew (saturating_mul on usize::MAX would cap).
678 if widen_probe > base_probe || widen_rerank > base_rerank {
679 let widened = RecallRequest {
680 n_probe: Some(widen_probe),
681 n_rerank: Some(widen_rerank),
682 ..req.clone()
683 };
684 scored = self.score_once(&widened, now, false)?;
685 }
686 // Attempt 3: if still short after widening, pay the
687 // exact scan — it's the only path that guarantees
688 // `top_k` correct hits when the filter is more
689 // selective than `widen_rerank / live_count`. Before
690 // the fix this was gated on `widened_rerank * 2 >=
691 // live_non_superseded`, which silently returned fewer
692 // than `top_k` hits on selective filters that fell in
693 // the gap. Exact scan is bounded (one decrypt per
694 // live record); the previous widen is an optimization.
695 if scored.len() < req.top_k {
696 scored = self.score_once(req, now, true)?;
697 used_exact_scan = true;
698 }
699 }
700 }
701 scored.sort_by(|a, b| b.score.total_cmp(&a.score));
702 scored.truncate(req.top_k);
703
704 // Update access statistics for everything we surfaced — but only
705 // mutate the catalog entry, not the full record on disk. Pre-v5
706 // this loop called `self.put(r.memory.clone())`, which serialized
707 // and rewrote every result (vector included) to fresh pages,
708 // turning a top-K recall into K full record rewrites. Now the
709 // catalog is the source of truth for these two fields and the
710 // record body stays untouched until the next real edit.
711 if req.track_access && self.read_only {
712 if let Some(delta) = self.access_delta.as_mut() {
713 for r in &scored {
714 delta.memory_hit(r.memory.id.0, now);
715 }
716 }
717 } else if req.track_access {
718 for r in &mut scored {
719 if let Some(idx) = self.index.get(r.memory.id.0, &self.catalog) {
720 self.touch(idx);
721 let entry = &mut self.catalog[idx];
722 entry.accessed_at = now;
723 entry.access_count = entry.access_count.saturating_add(1);
724 // Propagate the just-updated values onto the returned
725 // Memory so the caller sees the post-recall state.
726 r.memory.accessed_at = entry.accessed_at;
727 r.memory.access_count = entry.access_count;
728 }
729 }
730 // Mark the catalog dirty so the next flush persists these
731 // bumps. The records themselves are not dirty.
732 if !scored.is_empty() {
733 self.dirty_catalog = true;
734 }
735 }
736
737 // Phase 12.8: apply the `max_bytes` budget *after* tracking has
738 // seen the full top-k list. Access stats record what the scorer
739 // chose; the byte budget shouldn't suppress the signal.
740 let truncated = if let Some(budget) = req.max_bytes {
741 let orig_len = scored.len();
742 let mut running = 0usize;
743 let mut cut_at: Option<usize> = None;
744 for (i, r) in scored.iter().enumerate() {
745 let w = r.memory.content.len();
746 if i == 0 {
747 // Always keep the top hit, even if it's over budget
748 // on its own. Avoid "I asked for top_k results and
749 // got zero" when a single memory exceeds the cap.
750 running += w;
751 continue;
752 }
753 if running.saturating_add(w) > budget {
754 cut_at = Some(i);
755 break;
756 }
757 running += w;
758 }
759 if let Some(idx) = cut_at {
760 scored.truncate(idx);
761 scored.len() < orig_len
762 } else {
763 false
764 }
765 } else {
766 false
767 };
768
769 self.kw = None;
770 Ok(RecallResponse {
771 hits: scored,
772 truncated,
773 used_exact_scan,
774 })
775 }
776
777 // --- approximate index ------------------------------------------------
778}