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}