Skip to main content

mnemo_engine/store/
ann.rs

1//! The approximate (IVF+PQ) index: build, rebuild, drop, lazy load and reconcile.
2
3use super::*;
4
5impl Mnemo {
6    /// Build an IVF+PQ approximate-nearest-neighbour index over every live
7    /// memory, using default tuning. After this, [`Mnemo::recall`] runs the
8    /// tiered pipeline instead of an exact scan. Persisted on the next
9    /// `flush`. Returns a snapshot of the index shape.
10    pub fn build_index(&mut self) -> Result<IndexInfo> {
11        self.build_index_with(IndexConfig::default())
12    }
13
14    /// Build the ANN index with explicit tuning.
15    pub fn build_index_with(&mut self, cfg: IndexConfig) -> Result<IndexInfo> {
16        if self.read_only {
17            return Err(MnemoError::ReadOnly);
18        }
19        // R-004.2: facts only; turns, essence items and thread links stay
20        // out of the ANN.
21        let mems: Vec<Memory> = self.memories()?.into_iter().filter(is_ann_kind).collect();
22        if mems.is_empty() {
23            return Err(MnemoError::Invalid(
24                "cannot build an index over an empty database".into(),
25            ));
26        }
27        // FMT-9b: a v9 file below V9_ANN_MIN_FACTS recalls by an exact fp16
28        // scan, which is faster than the index there and costs no disk.
29        // Report it as an index with no partitions, and drop a stale one.
30        // `MNEMO_DEV_ANN_MIN_FACTS` overrides the threshold. Unsupported,
31        // for tests (and the recall-grid bench) only: it lets the index
32        // suites exercise a v9 ANN on small files. Not documented, and
33        // compiled only with `dev-hooks` (HOOKS-1), so a release build
34        // ignores the variable.
35        #[cfg(feature = "dev-hooks")]
36        let min_facts = std::env::var("MNEMO_DEV_ANN_MIN_FACTS")
37            .ok()
38            .and_then(|v| v.parse::<usize>().ok())
39            .unwrap_or(V9_ANN_MIN_FACTS);
40        #[cfg(not(feature = "dev-hooks"))]
41        let min_facts = V9_ANN_MIN_FACTS;
42        if self.is_v9() && mems.len() < min_facts {
43            if self.ann.is_some() || self.ann_unloaded {
44                self.ann = None;
45                self.ann_unloaded = false;
46                self.dirty_index = true;
47                self.index_persist.forced = true;
48            }
49            return Ok(IndexInfo {
50                vectors: mems.len(),
51                partitions: 0,
52                subspaces: 0,
53                n_probe: 0,
54                n_rerank: 0,
55            });
56        }
57        let items: Vec<(u128, &[f32])> =
58            mems.iter().map(|m| (m.id.0, m.vector.as_slice())).collect();
59        let mut idx = IvfPqIndex::build(self.dimensions, &items, cfg)?;
60        let info = idx.info();
61        if self.is_v9() {
62            idx.enable_log();
63            self.index_rebase = true;
64        }
65        self.ann = Some(idx);
66        self.ann_unloaded = false;
67        self.dirty_index = true;
68        self.index_persist.forced = true;
69        Ok(info)
70    }
71
72    /// Rebuild the ANN index from scratch — re-clusters centroids and retrains
73    /// the PQ codebook, undoing the cluster drift that accumulates as memories
74    /// are inserted against fixed centroids.
75    pub fn rebuild_index(&mut self) -> Result<IndexInfo> {
76        // ANN-1.1: re-derive every parameter (partitions, subspaces,
77        // n_probe, n_rerank) for the current corpus size by passing
78        // `IndexConfig::default()`. Previously this freezed the
79        // stored `(n_probe, n_rerank)` from the current index,
80        // defeating the point of rebuilding on a grown corpus. If
81        // you really want to pin specific values, call
82        // `build_index_with(IndexConfig { … })` directly.
83        self.build_index_with(IndexConfig::default())
84    }
85
86    /// Drop the ANN index; recall reverts to exact scans. Persisted on flush.
87    /// No-op on a read-only handle (signature is infallible — callers of
88    /// `build_index` / `flush` on a read-only handle already get a typed
89    /// `ReadOnly` error, which is the enforceable boundary).
90    pub fn drop_index(&mut self) {
91        if self.read_only {
92            return;
93        }
94        if self.ann.is_some() || self.ann_unloaded {
95            self.ann = None;
96            self.ann_unloaded = false;
97            self.dirty_index = true;
98            self.index_persist.forced = true;
99        }
100    }
101
102    /// PERF-1 (R-004.1): bring a just-loaded ANN index up to date with the
103    /// catalog. Called wherever an index run is loaded: on first use after
104    /// `open` / `open_read_only` (`ensure_ann`, PERF-1 step 3) and by
105    /// `restore_to`, with the first page of that run.
106    ///
107    /// `flush` persists the index only every so often, so that run can lag
108    /// the catalog. It does two things:
109    ///
110    /// 1. **Prune** every indexed id the catalog no longer has live
111    ///    (missing or deleted).
112    /// 2. **Re-add** every live record written after the index run. Pages
113    ///    are allocated monotonically in v8, and every write, including an
114    ///    in-place `update` or `essence_update` (they rewrite the record to
115    ///    fresh pages), lands at a page `> index_start`. Those records are
116    ///    read and re-assigned. A record of a non-fact kind (turn, essence,
117    ///    thread link) is removed instead: those never belong in the ANN.
118    ///
119    /// The work is bounded by [`INDEX_PERSIST_EVERY_CHANGES`] in the common
120    /// case, since a writer persists the index at least that often.
121    ///
122    /// **v9:** pages are reused, so "a page past the run" no longer means
123    /// "written after it". A v9 record is newer than the index run when its
124    /// generation is greater than the run's (`index_gen`).
125    pub(super) fn reconcile_ann_with_catalog(
126        &mut self,
127        index_start: u64,
128        index_gen: u64,
129    ) -> Result<()> {
130        if self.ann.is_none() {
131            return Ok(());
132        }
133        let mut changed = 0usize;
134        // 1. Prune ids that are no longer live.
135        let stale: Vec<u128> = match &self.ann {
136            Some(ann) => ann
137                .ids()
138                .filter(|&id| !matches!(self.index.get(id, &self.catalog), Some(i) if !self.catalog[i].deleted))
139                .collect(),
140            None => Vec::new(),
141        };
142        if let Some(ann) = &mut self.ann {
143            for id in &stale {
144                ann.remove(*id);
145                changed += 1;
146            }
147        }
148        // 2. Re-add records written after the index run.
149        let v9 = self.is_v9();
150        let pending: Vec<CatalogEntry> = self
151            .catalog
152            .iter()
153            .filter(|e| !e.deleted && written_after_index(e, v9, index_start, index_gen))
154            .cloned()
155            .collect();
156        for e in &pending {
157            let m = self.read_memory(e)?;
158            if let Some(ann) = &mut self.ann {
159                if is_ann_kind(&m) {
160                    ann.add(e.id, &m.vector);
161                } else {
162                    ann.remove(e.id);
163                }
164                changed += 1;
165            }
166        }
167        if changed > 0 {
168            self.dirty_index = true;
169            self.index_persist.changes += changed;
170        }
171        Ok(())
172    }
173
174    /// Whether the database has an ANN index (loaded, or persisted and
175    /// loading on first use).
176    pub fn has_index(&self) -> bool {
177        self.ann.is_some() || self.ann_unloaded
178    }
179
180    /// PERF-1 step 3: load the persisted ANN index on first use, then bring
181    /// it up to date with the catalog (`reconcile_ann_with_catalog`) and,
182    /// when the handle caches are already built, prune non-fact ids an
183    /// older persisted index may hold.
184    pub(super) fn ensure_ann(&mut self) -> Result<()> {
185        if !self.ann_unloaded {
186            return Ok(());
187        }
188        self.ann_unloaded = false;
189        self.ann = load_index(
190            &mut self.pager,
191            self.header.index_start,
192            self.header.index_pages,
193            self.header.index_len,
194            self.header.index_gen,
195            self.dimensions,
196        )?;
197        // FMT-9c.3: replay the v9 index delta chain, then record changes.
198        if self.is_v9() {
199            if let Some(ann) = self.ann.as_mut() {
200                let (chain, n) = apply_index_chain(&mut self.pager, ann, self.header.index_delta)?;
201                self.index_chain = chain;
202                self.index_chain_ops = n;
203                ann.enable_log();
204            } else if self.header.index_pages > 0 {
205                // FMT-9f (the 9d leak): an unknown-layout base loads as no
206                // index; still track its delta runs, so rebuilding or
207                // dropping the index frees them along with the base.
208                self.index_chain = index_chain_runs(&mut self.pager, self.header.index_delta);
209                self.index_chain_ops = 0;
210            }
211        }
212        let (index_start, index_gen) = (self.header.index_start, self.index_gen_now());
213        self.reconcile_ann_with_catalog(index_start, index_gen)?;
214        let non_facts: Vec<u128> = match &self.layers {
215            Some(l) => l
216                .essence
217                .iter()
218                .copied()
219                .chain(l.threads.values().flat_map(|t| t.records.iter().copied()))
220                .chain(l.cold_turns.values().flatten().copied())
221                .collect(),
222            None => Vec::new(),
223        };
224        if let Some(ann) = &mut self.ann {
225            let mut pruned = 0usize;
226            for id in non_facts {
227                if ann.contains(id) {
228                    ann.remove(id);
229                    pruned += 1;
230                }
231            }
232            if pruned > 0 {
233                self.dirty_index = true;
234                self.index_persist.changes += pruned;
235            }
236        }
237        Ok(())
238    }
239
240    // --- durability & maintenance ----------------------------------------
241}