Skip to main content

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