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