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}