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        // A build replaces an index that was never loaded: track its delta
43        // runs first, so this commit frees them with the base.
44        if self.ann_unloaded && self.is_v9() {
45            self.track_index_chain();
46        }
47        if self.is_v9() && mems.len() < min_facts {
48            if self.ann.is_some() || self.ann_unloaded || self.index_repair {
49                self.index_repair = false;
50                self.ann = None;
51                self.ann_unloaded = false;
52                self.dirty_index = true;
53                self.index_persist.forced = true;
54            }
55            return Ok(IndexInfo {
56                vectors: mems.len(),
57                partitions: 0,
58                subspaces: 0,
59                n_probe: 0,
60                n_rerank: 0,
61            });
62        }
63        let items: Vec<(u128, &[f32])> =
64            mems.iter().map(|m| (m.id.0, m.vector.as_slice())).collect();
65        let mut idx = IvfPqIndex::build(self.dimensions, &items, cfg)?;
66        let info = idx.info();
67        if self.is_v9() {
68            idx.enable_log();
69            self.index_rebase = true;
70        }
71        self.ann = Some(idx);
72        self.ann_unloaded = false;
73        self.index_repair = false;
74        self.dirty_index = true;
75        self.index_persist.forced = true;
76        Ok(info)
77    }
78
79    /// Rebuild the ANN index from scratch — re-clusters centroids and retrains
80    /// the PQ codebook, undoing the cluster drift that accumulates as memories
81    /// are inserted against fixed centroids.
82    pub fn rebuild_index(&mut self) -> Result<IndexInfo> {
83        // ANN-1.1: re-derive every parameter (partitions, subspaces,
84        // n_probe, n_rerank) for the current corpus size by passing
85        // `IndexConfig::default()`. Previously this freezed the
86        // stored `(n_probe, n_rerank)` from the current index,
87        // defeating the point of rebuilding on a grown corpus. If
88        // you really want to pin specific values, call
89        // `build_index_with(IndexConfig { … })` directly.
90        self.build_index_with(IndexConfig::default())
91    }
92
93    /// Drop the ANN index; recall reverts to exact scans. Persisted on flush.
94    /// No-op on a read-only handle (signature is infallible — callers of
95    /// `build_index` / `flush` on a read-only handle already get a typed
96    /// `ReadOnly` error, which is the enforceable boundary).
97    pub fn drop_index(&mut self) {
98        if self.read_only {
99            return;
100        }
101        if self.ann_unloaded && self.is_v9() {
102            self.track_index_chain();
103        }
104        if self.ann.is_some() || self.ann_unloaded {
105            self.ann = None;
106            self.ann_unloaded = false;
107            self.dirty_index = true;
108            self.index_persist.forced = true;
109        }
110        // RB-015.1: dropping a damaged index persists "no index" too.
111        if self.index_repair {
112            self.index_repair = false;
113            self.dirty_index = true;
114            self.index_persist.forced = true;
115        }
116    }
117
118    /// PERF-1 (R-004.1): bring a just-loaded ANN index up to date with the
119    /// catalog. Called wherever an index run is loaded: on first use after
120    /// `open` / `open_read_only` (`ensure_ann`, PERF-1 step 3) and by
121    /// `restore_to`, with the first page of that run.
122    ///
123    /// `flush` persists the index only every so often, so that run can lag
124    /// the catalog. It does two things:
125    ///
126    /// 1. **Prune** every indexed id the catalog no longer has live
127    ///    (missing or deleted).
128    /// 2. **Re-add** every live record written after the index run. Pages
129    ///    are allocated monotonically in v8, and every write, including an
130    ///    in-place `update` or `essence_update` (they rewrite the record to
131    ///    fresh pages), lands at a page `> index_start`. Those records are
132    ///    read and re-assigned. A record of a non-fact kind (turn, essence,
133    ///    thread link) is removed instead: those never belong in the ANN.
134    ///
135    /// The work is bounded by [`INDEX_PERSIST_EVERY_CHANGES`] in the common
136    /// case, since a writer persists the index at least that often.
137    ///
138    /// **v9:** pages are reused, so "a page past the run" no longer means
139    /// "written after it". A v9 record is newer than the index run when its
140    /// generation is greater than the run's (`index_gen`).
141    pub(super) fn reconcile_ann_with_catalog(
142        &mut self,
143        index_start: u64,
144        index_gen: u64,
145    ) -> Result<()> {
146        if self.ann.is_none() {
147            return Ok(());
148        }
149        let mut changed = 0usize;
150        // 1. Prune ids that are no longer live.
151        let stale: Vec<u128> = match &self.ann {
152            Some(ann) => ann
153                .ids()
154                .filter(|&id| !matches!(self.index.get(id, &self.catalog), Some(i) if !self.catalog[i].deleted))
155                .collect(),
156            None => Vec::new(),
157        };
158        if let Some(ann) = &mut self.ann {
159            for id in &stale {
160                ann.remove(*id);
161                changed += 1;
162            }
163        }
164        // 2. Re-add records written after the index run.
165        let v9 = self.is_v9();
166        let pending: Vec<CatalogEntry> = self
167            .catalog
168            .iter()
169            .filter(|e| !e.deleted && written_after_index(e, v9, index_start, index_gen))
170            .cloned()
171            .collect();
172        for e in &pending {
173            let m = self.read_memory(e)?;
174            if let Some(ann) = &mut self.ann {
175                if is_ann_kind(&m) {
176                    ann.add(e.id, &m.vector);
177                } else {
178                    ann.remove(e.id);
179                }
180                changed += 1;
181            }
182        }
183        if changed > 0 {
184            self.dirty_index = true;
185            self.index_persist.changes += changed;
186        }
187        Ok(())
188    }
189
190    /// Whether the database has an ANN index (loaded, or persisted and
191    /// loading on first use).
192    pub fn has_index(&self) -> bool {
193        self.ann.is_some() || self.ann_unloaded
194    }
195
196    /// PERF-1 step 3: load the persisted ANN index on first use, then bring
197    /// it up to date with the catalog (`reconcile_ann_with_catalog`) and,
198    /// when the handle caches are already built, prune non-fact ids an
199    /// older persisted index may hold.
200    pub(super) fn ensure_ann(&mut self) -> Result<()> {
201        if !self.ann_unloaded {
202            return Ok(());
203        }
204        self.ann_unloaded = false;
205        match self.load_persisted_index() {
206            Ok(()) => {}
207            // RB-015.1 (v0.19.1): the index is derived data. A run that
208            // doesn't decrypt or decode loads as no index, like a layout
209            // this build doesn't know: recall scans exactly, the handle
210            // says so once, and a read-write handle rebuilds it.
211            Err(e) if index_damage(&e) => self.index_damaged(&e),
212            // Anything else (an I/O error) says nothing about the run: the
213            // next call tries the load again (task v0191-1b).
214            Err(e) => {
215                self.ann_unloaded = true;
216                return Err(e);
217            }
218        }
219        let (index_start, index_gen) = (self.header.index_start, self.index_gen_now());
220        self.reconcile_ann_with_catalog(index_start, index_gen)?;
221        let non_facts: Vec<u128> = match &self.layers {
222            Some(l) => l
223                .essence
224                .iter()
225                .copied()
226                .chain(l.threads.values().flat_map(|t| t.records.iter().copied()))
227                .chain(l.cold_turns.values().flatten().copied())
228                .collect(),
229            None => Vec::new(),
230        };
231        if let Some(ann) = &mut self.ann {
232            let mut pruned = 0usize;
233            for id in non_facts {
234                if ann.contains(id) {
235                    ann.remove(id);
236                    pruned += 1;
237                }
238            }
239            if pruned > 0 {
240                self.dirty_index = true;
241                self.index_persist.changes += pruned;
242            }
243        }
244        Ok(())
245    }
246
247    /// Load the header's index run and replay its delta chain into
248    /// `self.ann`, or leave `self.ann` as `None` (no index, or a layout this
249    /// build doesn't know). Nothing is set when it fails.
250    fn load_persisted_index(&mut self) -> Result<()> {
251        let mut ann = load_index(
252            &mut self.pager,
253            self.header.index_start,
254            self.header.index_pages,
255            self.header.index_len,
256            self.header.index_gen,
257            self.dimensions,
258        )?;
259        // FMT-9c.3: replay the v9 index delta chain, then record changes.
260        if self.is_v9() {
261            if let Some(a) = ann.as_mut() {
262                let (chain, n) = apply_index_chain(&mut self.pager, a, self.header.index_delta)?;
263                a.enable_log();
264                self.index_chain = chain;
265                self.index_chain_ops = n;
266            } else if self.header.index_pages > 0 {
267                // FMT-9f (the 9d leak): an unknown-layout base loads as no
268                // index; still track its delta runs, so rebuilding or
269                // dropping the index frees them along with the base.
270                self.track_index_chain();
271            }
272        }
273        self.ann = ann;
274        Ok(())
275    }
276
277    /// FMT-9f: the delta runs of an index that isn't loaded, so the next
278    /// build or drop frees them with the base.
279    fn track_index_chain(&mut self) {
280        self.index_chain = index_chain_runs(&mut self.pager, self.header.index_delta);
281        self.index_chain_ops = 0;
282    }
283
284    /// RB-015.1: the persisted index didn't load. Recall scans exactly; the
285    /// runs stay tracked so a rebuild frees them; the handle's next commit
286    /// that writes rebuilds the index.
287    fn index_damaged(&mut self, e: &MnemoError) {
288        self.ann = None;
289        if self.is_v9() {
290            self.track_index_chain();
291        }
292        // Set on a read-only handle too: a shared handle is read-only only
293        // inside a read window, and its next write window repairs it.
294        self.index_repair = true;
295        let next = if self.read_only {
296            "`mnemo index --rebuild` repairs it"
297        } else {
298            "this handle rebuilds it with its next write, or `mnemo index --rebuild` does now"
299        };
300        let text = format!(
301            "the approximate index is damaged ({e}), so recall scans every memory; \
302             your memories are intact, and {next}"
303        );
304        if !self.notices.contains(&text) {
305            self.notices.push(text);
306        }
307    }
308
309    /// RB-015.1: in a commit that writes, rebuild the index a damaged run
310    /// left this handle without. A file too small for an index (or with no
311    /// facts left) drops the damaged run instead.
312    pub(super) fn repair_index(&mut self) -> Result<()> {
313        if !self.index_repair || self.read_only {
314            return Ok(());
315        }
316        self.index_repair = false;
317        match self.build_index() {
318            Ok(_) => {}
319            Err(MnemoError::Invalid(_)) => {}
320            Err(e) => return Err(e),
321        }
322        if self.ann.is_none() {
323            // Persisted as "no index": frees the damaged base and its chain.
324            self.dirty_index = true;
325            self.index_persist.forced = true;
326        }
327        Ok(())
328    }
329
330    // --- durability & maintenance ----------------------------------------
331}