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}