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