mnemo_engine/store/mod.rs
1//! The Mnemo database — ties the storage engine and the memory model together.
2//!
3//! Layout of a populated file:
4//!
5//! ```text
6//! page 0 : Header (unencrypted)
7//! pages 1..W : write-ahead log region
8//! pages W.. : encrypted record runs + catalog runs + index +
9//! snapshot manifest (append-only)
10//! ```
11//!
12//! Durability is provided by a **write-ahead log** ([`crate::wal`]). A `flush`
13//! is one transaction: record data pages are written copy-on-write to fresh
14//! pages, then the new catalog, ANN index, and header are logged to the WAL
15//! and committed with a single fsync. A checkpoint then folds the WAL into the
16//! home pages. A crash before the commit leaves the previous state intact; a
17//! crash after it is repaired by replaying the WAL on open.
18//!
19//! Because pages are only ever appended, every past transaction's runs survive
20//! on disk. Each flush also appends an entry to a **snapshot manifest**, so
21//! [`Mnemo::restore_to`] can reinstate any past state. Stale pages — and the
22//! history along with them — are reclaimed by [`Mnemo::compact_file`].
23
24use std::fs::{File, OpenOptions};
25use std::io::{Read, Seek, SeekFrom, Write};
26use std::path::{Path, PathBuf};
27
28use fs4::fs_std::FileExt;
29use serde::{Deserialize, Serialize};
30use serde_json::{Map, Value};
31use ulid::Ulid;
32
33use crate::crypto::{self, KdfParams, SecretKind};
34use crate::embed::{self, Embedder};
35use crate::error::{MnemoError, Result};
36use crate::format::{
37 Header, RunPtr, FLAG_ENCRYPTED, PAGE_SIZE, PAYLOAD, VERSION, VERSION_V9, WRAPPED_DEK_LEN,
38};
39use crate::freelist::FreeList;
40use crate::index::{IndexConfig, IndexInfo, IndexOp, IvfPqIndex};
41#[cfg(feature = "dev-hooks")]
42use crate::keyslot::KeySlot as KeySlotEntry;
43use crate::keyslot::KeySlotRun;
44use crate::memory::{
45 self, status as essence_status, CommitBatch, CommitReport, EssenceOp, EssenceOpKind,
46 EssenceScope, EssenceSection, ExportedTurn, Filter, FilterTerm, IngestReport, KeyScope, Memory,
47 MemoryPatch, MemoryType, Metric, Scope, ScoreWeights, ThreadTurn, TurnPolicy, WriteOutcome,
48 CONTINUATION_TIMELINE_ENTRIES, ESSENCE_DEFAULT_RENDER_BYTES, ESSENCE_TRANSITIONS,
49 MNEMO_META_CONTINUES, MNEMO_META_INVALID_AT, MNEMO_META_KEY, MNEMO_META_KIND,
50 MNEMO_META_KIND_ESSENCE, MNEMO_META_KIND_THREAD_LINK, MNEMO_META_KIND_TURN, MNEMO_META_LENGTH,
51 MNEMO_META_PART, MNEMO_META_REFS, MNEMO_META_ROLE, MNEMO_META_SECTION, MNEMO_META_SEQ,
52 MNEMO_META_SHA256, MNEMO_META_STATUS, MNEMO_META_STATUS_HISTORY, MNEMO_META_SUPERSEDED_BY,
53 MNEMO_META_SUPERSEDES, MNEMO_META_THREAD, MNEMO_META_TURN_ID, MNEMO_META_UPDATED_AT,
54 THREAD_TOOL_RESULT_TRUNCATE_BYTES, THREAD_TURN_CHUNK_BYTES,
55};
56use crate::pager::{LockedFile, Pager};
57use crate::result_cache::{
58 self, BatchState, CacheBudget, CacheDirectoryEntry, CacheEntry, CacheFlushPolicy, CachePutOpts,
59 CacheStats, CachedValue, CounterState, DirectoryIndex, SemanticCachePutOpts,
60};
61use crate::text;
62use crate::veccol;
63use crate::wal;
64
65mod ann;
66mod cache_api;
67mod continuation;
68mod crud;
69mod essence;
70mod flush;
71#[cfg(test)]
72mod header_graft_tests;
73// HOOKS-1: the hidden test hooks exist only in test, bench and example
74// builds (the `dev-hooks` feature), never in a release build.
75#[cfg(feature = "dev-hooks")]
76mod hooks;
77mod keyed;
78mod load;
79mod maintenance;
80mod open;
81mod recall;
82mod records;
83mod shared;
84mod snapshots;
85mod threads;
86use crud::*;
87use essence::*;
88use load::*;
89pub(crate) use load::{is_file_at, is_lock_conflict};
90pub(crate) use maintenance::{create_temp, remove_dead_temps};
91pub(crate) use open::wal_header_salts;
92pub(crate) use records::plain_record;
93use records::*;
94pub use shared::SharedMnemo;
95
96/// Default initial size of the write-ahead log region, in pages (64 KiB).
97/// The region grows automatically when a transaction's control plane outgrows
98/// it, so this is a *floor* on the fresh-file footprint, not a cap on
99/// transaction size. Was 64 pages (512 KiB) in v0.1.0 — lowered because that
100/// reservation dominated small-file size (~62% of a 31-memory dogfood file).
101const DEFAULT_WAL_PAGES: u64 = 8;
102
103/// Hard floor on the WAL reservation. A single header-page flush already
104/// needs one full DATA frame plus a COMMIT frame; two pages are the bare
105/// minimum that lets the first transaction commit without immediate growth.
106const MIN_WAL_PAGES: u64 = 2;
107
108/// Default cap on retained snapshot manifest entries. Each `flush` appends
109/// one entry; without a cap, long-running processes accumulate entries
110/// forever, growing per-flush manifest-serialize cost as O(total flushes)
111/// and the manifest run size on disk in lockstep. 256 keeps roughly a
112/// week of hourly snapshots while staying tiny (256 × ~82 bytes ≈ 21 KiB
113/// of manifest). Set `MnemoConfig::max_snapshots = 0` to disable the cap.
114pub const DEFAULT_MAX_SNAPSHOTS: usize = 256;
115
116/// PERF-1: the ANN index is derived data, so `flush` persists it only every
117/// this many commits that changed it (or see
118/// [`INDEX_PERSIST_EVERY_CHANGES`], [`Mnemo::flush_index`], [`Mnemo::close`]).
119/// Between persists, only the catalog is rewritten.
120pub const INDEX_PERSIST_EVERY_COMMITS: u32 = 64;
121
122/// PERF-1: …or once this many vectors were added, changed or removed since
123/// the last persist. Records written after the persisted index are
124/// re-assigned when the index is next loaded, so this bounds that work.
125pub const INDEX_PERSIST_EVERY_CHANGES: usize = 1_000;
126
127/// FMT-9d: default weight ε of the normalised BM25 score in hybrid recall
128/// (`relevance = similarity + ε · bm25 / max bm25`).
129pub const DEFAULT_KEYWORD_WEIGHT: f32 = 0.5;
130
131/// 12.3 step 4 (v0.15): default weight of the BM25 score when it comes from
132/// a recall's own text (hybrid by default, no keywords given). Lower than
133/// [`DEFAULT_KEYWORD_WEIGHT`] because a question's common words ("how",
134/// "the") match unrelated memories: on this project's brain at 0.5 a memory
135/// with similarity 0.18 came second on "how releases are approved"; at 0.25
136/// the right fact led all three DOGFOOD-0 questions with no such intruder
137/// (`docs/design/12.3-retrieval.md`, section 5).
138pub const DEFAULT_TEXT_KEYWORD_WEIGHT: f32 = 0.25;
139
140/// FMT-9b: default [`Mnemo::set_vector_cache_budget`]: the fp16 vector
141/// column stays resident while it fits (100K × 384 dims is about 77 MB) and
142/// is read through the page cache above it. PLANNER-A, 2026-11-07.
143pub const DEFAULT_VECTOR_CACHE_BUDGET: usize = 96 * 1024 * 1024;
144
145/// FMT-9b: below this many facts a v9 file has no ANN index: an exact
146/// fp16 scan of 20K × 384 dims is about a millisecond, and the IVF+PQ
147/// codebook alone would cost more disk than it saves time.
148pub const V9_ANN_MIN_FACTS: usize = 20_000;
149
150/// FMT-9f (PLANNER-A, 2026-11-08): on v9 an unpinned recall reranks at
151/// least this many candidates per requested hit (500 for `top_k` 10), or
152/// the index's own auto depth when that's deeper (above 100K). The v9
153/// index is trained on fp16-rounded vectors, and at 20K–50K the auto
154/// depth (×10–×25) lost up to 0.03 recall@10 against v8; ×50 is within
155/// 0.005 at every measured tier. v8 is unchanged.
156pub const V9_RERANK_PER_HIT: usize = 50;
157
158/// FMT-9c: page runs longer than this are written copy-on-write straight
159/// to their home pages (and fsynced) before the commit, instead of through
160/// the WAL, on v9. The WAL then carries only the header and small runs, so
161/// it stays at its 64 KiB default instead of growing to the largest
162/// catalog or index (26 MB at 100K on v8). Safe for the same reason data
163/// pages are: the pages come from the tail or from quarantined free runs,
164/// so nothing committed references them until the header flips.
165const V9_WAL_RUN_MAX_PAGES: u64 = 2;
166
167/// FMT-9c: snapshot retention on v9: the newest 16 snapshots, plus any
168/// from the last 24 hours, with retained snapshots never pinning more than
169/// a quarter of the file (past that, the oldest go first, whatever their
170/// age). `set_max_snapshots` changes the count.
171pub const V9_DEFAULT_MAX_SNAPSHOTS: usize = 16;
172const V9_SNAPSHOT_KEEP_SECS: i64 = 24 * 3600;
173/// FMT-9c: the pin cap never drops below 128 pages (1 MiB).
174const V9_PIN_FLOOR_PAGES: u64 = 128;
175
176/// FMT-9d: the layout byte at the start of a v9 ANN index run (1: the
177/// whole IVF+PQ index, followed by delta runs). A reader treats an unknown
178/// layout as no index, so a later layout (partition-major, PERF-2) ships
179/// without a format bump.
180const V9_INDEX_LAYOUT: u8 = 1;
181
182/// FMT-9b: how many sparse vector pages one commit folds into its new
183/// pages (the vacuum). Bounded so a commit's cost stays bounded.
184const VACUUM_PAGES_PER_COMMIT: usize = 4;
185
186/// FMT-9c.2: and at most this many rows moved by the vacuum per commit (a
187/// moved row is a changed catalog row, so it lands in the commit's delta).
188/// Pages with more live rows than this stay as they are until deletes thin
189/// them out.
190const VACUUM_MAX_ROWS: usize = 64;
191
192/// FMT-9b: header flag: the file also keeps each record's float vector
193/// (`MnemoConfig::store_float_vectors`).
194const FLAG_FLOAT_VECTORS: u32 = 2;
195
196/// PERF-1: when the in-memory ANN index was last persisted, and whether the
197/// next flush must persist it.
198#[derive(Debug, Default, Clone, Copy)]
199struct IndexPersist {
200 /// Persist on the next flush (build, rebuild, drop, `flush_index`,
201 /// `close`, snapshot restore).
202 forced: bool,
203 /// Commits since the last persist that left the index dirty.
204 commits: u32,
205 /// Vectors added, re-assigned or removed since the last persist.
206 changes: usize,
207}
208
209/// Configuration for creating a new database.
210#[derive(Clone, Copy, Debug)]
211pub struct MnemoConfig {
212 /// Embedding dimensionality. Every stored vector must match this.
213 pub dimensions: usize,
214 /// Key-derivation parameters.
215 pub kdf: KdfParams,
216 /// Initial size of the WAL region in 8 KiB pages. Default is
217 /// [`DEFAULT_WAL_PAGES`] (8 pages = 64 KiB), which keeps fresh files
218 /// small; the region auto-grows when a transaction's control plane needs
219 /// more space, so raising this is only a hint for the expected steady-state
220 /// transaction size. Write-heavy databases that routinely flush large
221 /// catalogs or ANN indexes can set this higher (e.g. 64 = 512 KiB) to
222 /// avoid early grow events; tiny embedded uses can leave it at the
223 /// default. Clamped to a minimum of [`MIN_WAL_PAGES`] (2 pages).
224 pub wal_pages_initial: u64,
225 /// Maximum number of snapshot manifest entries to retain. Each `flush`
226 /// appends one entry; once the cap is hit, the *oldest* entry is dropped
227 /// from the in-memory manifest before the new one is added, so the
228 /// retained set is always the most-recent N. Defaults to
229 /// [`DEFAULT_MAX_SNAPSHOTS`] (256). Set to `0` to disable the cap and
230 /// retain every snapshot forever (the pre-v0.3 behavior).
231 ///
232 /// Pages referenced *only* by pruned snapshots stay on disk until the
233 /// next [`Mnemo::compact_file`], which reclaims them. Point-in-time
234 /// recovery via [`Mnemo::restore_to`] into a pruned `txn_id` returns
235 /// [`MnemoError::NotFound`].
236 ///
237 /// Apply to an already-open database with [`Mnemo::set_max_snapshots`].
238 pub max_snapshots: usize,
239 /// The on-disk format a new file is created in. `0` (the default)
240 /// means v9, the current format. `8` creates a v8 file, for tools that
241 /// still need to read it with v0.10 or earlier; it's kept for one
242 /// release (v0.12 makes v8 read-only). **Not a stable API.**
243 #[doc(hidden)]
244 pub format_version: u16,
245 /// FMT-9b (v9 files only; ignored for v8): also keep each memory's
246 /// full-precision vector in its record, so `get()` and `recall()`
247 /// return it exactly. Off by default: a v9 file stores vectors as
248 /// fp16 (about 1e-3 relative error) in the vector column, which recall
249 /// scores from either way. Costs `4 × dimensions` bytes per memory.
250 pub store_float_vectors: bool,
251}
252
253impl Default for MnemoConfig {
254 fn default() -> Self {
255 Self {
256 dimensions: 768,
257 kdf: KdfParams::secure(),
258 wal_pages_initial: DEFAULT_WAL_PAGES,
259 max_snapshots: DEFAULT_MAX_SNAPSHOTS,
260 format_version: 0,
261 store_float_vectors: false,
262 }
263 }
264}
265
266/// FMT-9: resolve [`MnemoConfig::format_version`] for a new file.
267fn resolve_format_version(requested: u16) -> Result<u16> {
268 match requested {
269 // FMT-9f: new files are v9; the `MNEMO_DEV_FORMAT` switch is gone.
270 0 => Ok(crate::format::DEFAULT_NEW_VERSION),
271 VERSION_V9 => Ok(requested),
272 // The v8 sunset (v0.13): v8 files open read-only and compact to v9;
273 // no new one is created.
274 v => Err(MnemoError::Invalid(format!(
275 "format_version {v} is not supported for new files: new files are v9 (pass 0 or 9)"
276 ))),
277 }
278}
279
280/// Catalog entry: maps a memory ID to its page run on disk.
281///
282/// **Schema (v5+):** carries `accessed_at` and `access_count` so `recall`
283/// can update access stats by mutating the catalog entry rather than
284/// rewriting the entire record (Phase 2.1 of the improvement plan). The
285/// values in a memory's serialized record body become a stale snapshot
286/// after the first recall; [`Mnemo::read_memory`] re-populates them from
287/// the catalog so consumers always see the live values.
288#[derive(Serialize, Deserialize, Clone, Debug)]
289struct CatalogEntry {
290 /// ULID as a raw `u128`.
291 id: u128,
292 start_page: u64,
293 page_count: u32,
294 /// Exact serialized byte length of the record.
295 len: u32,
296 deleted: bool,
297 /// Unix seconds of the most recent recall hit (or write, for fresh entries).
298 accessed_at: i64,
299 /// How many times `recall` has surfaced this memory.
300 access_count: u32,
301 /// FMT-9: the generation the record's pages were sealed under (v9 page
302 /// AAD). `0`, and left out of the encoding, on v8 files, so a v8
303 /// catalog is byte-for-byte what v0.10 writes.
304 #[serde(default, skip_serializing_if = "crate::format::is_zero_u64")]
305 gen: u64,
306 /// FMT-9b: the v9 row's tags, scoring inputs and vector location
307 /// (`None`, and left out of the encoding, on v8 files).
308 #[serde(default, skip_serializing_if = "Option::is_none")]
309 v9: Option<RowV9>,
310}
311
312/// FMT-9b: what a v9 catalog row carries beyond the v8 fields, so recall
313/// can filter and score a candidate without decrypting its record, and a
314/// cold handle can select records by kind or thread.
315#[derive(Serialize, Deserialize, Clone, Copy, Debug, Default)]
316struct RowV9 {
317 /// The vector column entry: page (`0` while it's waiting for the next
318 /// flush), slot, and the page's generation.
319 vec_page: u64,
320 vec_slot: u16,
321 vec_gen: u64,
322 /// FMT-9b.2: the record's slot on its packed page (`start_page`), or
323 /// [`REC_SPAN`] when the record owns a run of whole pages.
324 rec_slot: u16,
325 /// `ROW_KIND_*`.
326 kind: u8,
327 /// `ROW_SUPERSEDED | ROW_HAS_TTL | ROW_SHARED`.
328 flags: u8,
329 /// [`memory_type_code`].
330 memory_type: u8,
331 /// FNV-1a of `_mnemo.thread`, of the 12.1 key slot, and of `agent_id`
332 /// (`0` = none). A collision only lets a non-match through to the
333 /// decrypted check.
334 thread_hash: u32,
335 key_hash: u32,
336 agent_hash: u32,
337 created_at: i64,
338 importance: f32,
339 /// `created_at + ttl_secs` when `ROW_HAS_TTL` is set.
340 expires_at: i64,
341 /// FMT-9d: the row's BM25 document id (`0`: not keyword-indexed) and
342 /// its token count. Live rows define which documents are live, and
343 /// N and avgdl, so segments never hold lengths or tombstones.
344 doc: u32,
345 doc_len: u16,
346}
347
348/// FMT-9e: by default a thread turn is written plain and compressed once
349/// it's a week old (by its `created_at`), so a live session's recent turns
350/// read at full speed and archived history is small.
351pub const DEFAULT_TURN_COMPRESS_AFTER_SECS: i64 = 7 * 24 * 3600;
352/// Frozen v4 catalog entry shape, used only by the v4→v5 migration path in
353/// [`Mnemo::open`]. Its layout matches the catalog encoding written by
354/// pre-v5 builds (5 positional fields). Do not change this struct.
355#[derive(Serialize, Deserialize, Clone, Debug)]
356struct CatalogEntryV4 {
357 id: u128,
358 start_page: u64,
359 page_count: u32,
360 len: u32,
361 deleted: bool,
362}
363
364/// Returned by [`Mnemo::prepare_for_flush`] and consumed by [`Mnemo::flush`].
365/// Carries the already-serialized control-plane bytes through the prelude
366/// so we don't re-serialize after the lease has been persisted.
367struct FlushPrelude {
368 cat_bytes: Option<Vec<u8>>,
369 /// FMT-9c.2: `cat_bytes` is a delta run, not a base catalog.
370 cat_delta: bool,
371 /// FMT-9c.3: `idx_bytes` is an index delta run, not a whole index.
372 idx_delta: bool,
373 /// FMT-9d: this commit's BM25 segment, and the segments it replaces.
374 bm25_seg: Option<(Vec<u8>, Option<usize>)>,
375 idx_bytes: Option<Vec<u8>>,
376 /// Serialized result-cache directory bytes when `dirty_cache` is
377 /// set (Phase 10.1). `None` if the cache didn't change since the
378 /// last flush — in that case the header keeps its current
379 /// `cache_start` / `cache_pages` / `cache_len` and no fresh cache
380 /// run is written.
381 cache_bytes: Option<Vec<u8>>,
382}
383
384/// One entry in the append-only snapshot manifest. Because record, catalog,
385/// and index pages are only ever *appended*, the runs a past flush wrote are
386/// still on disk; a `Snapshot` is the set of pointers needed to reconstruct
387/// the database exactly as that flush left it.
388#[derive(Serialize, Deserialize, Clone, Debug)]
389struct Snapshot {
390 txn_id: u64,
391 created_at: i64,
392 catalog_start: u64,
393 catalog_pages: u64,
394 catalog_len: u64,
395 index_start: u64,
396 index_pages: u64,
397 index_len: u64,
398 memory_count: u64,
399 /// FMT-9: generations of the catalog and index runs (v9 only; `None`,
400 /// and left out of the encoding, on v8 files).
401 #[serde(default, skip_serializing_if = "Option::is_none")]
402 gens: Option<SnapshotGens>,
403}
404
405/// FMT-9: the generations a v9 snapshot's runs were sealed under.
406#[derive(Serialize, Deserialize, Clone, Copy, Debug, Default)]
407struct SnapshotGens {
408 catalog: u64,
409 index: u64,
410 /// FMT-9c.2: the catalog's delta-chain head at this snapshot.
411 #[serde(default)]
412 delta: (u64, u64, u64, u64),
413 /// FMT-9c.3: the index's delta-chain head at this snapshot.
414 #[serde(default)]
415 index_delta: (u64, u64, u64, u64),
416 /// FMT-9d: the BM25 manifest at this snapshot.
417 #[serde(default)]
418 bm25: (u64, u64, u64, u64),
419}
420
421impl Snapshot {
422 fn catalog_gen(&self) -> u64 {
423 self.gens.map_or(0, |g| g.catalog)
424 }
425 fn index_gen(&self) -> u64 {
426 self.gens.map_or(0, |g| g.index)
427 }
428 fn delta_head(&self) -> RunPtr {
429 self.gens.map_or(RunPtr::default(), |g| tuple_ptr(g.delta))
430 }
431 fn index_delta_head(&self) -> RunPtr {
432 self.gens
433 .map_or(RunPtr::default(), |g| tuple_ptr(g.index_delta))
434 }
435}
436
437/// A restorable point in a database's history — see [`Mnemo::snapshots`].
438#[derive(Clone, Copy, Debug)]
439pub struct SnapshotInfo {
440 /// Id of the transaction that produced this snapshot (monotonic from 1).
441 pub txn_id: u64,
442 /// When the snapshot was committed (unix seconds).
443 pub created_at: i64,
444 /// Live memory count captured in the snapshot.
445 pub memory_count: u64,
446}
447
448/// What [`Mnemo::stats`] and [`Mnemo::stats_summary`] report about restore
449/// points (INSP-1, RB-001.25).
450pub(super) struct RestorePoints {
451 pub(super) retained: usize,
452 pub(super) oldest_at: Option<i64>,
453 pub(super) pinned_bytes: u64,
454}
455
456/// A retrieval request for [`Mnemo::recall`].
457#[derive(Clone, Debug)]
458pub struct RecallRequest {
459 /// Query embedding.
460 pub query: Vec<f32>,
461 /// Maximum results to return.
462 pub top_k: usize,
463 /// Restrict to these memory types (`None` = all types).
464 pub memory_types: Option<Vec<MemoryType>>,
465 /// Restrict to a single agent's view: its own memories plus shared ones.
466 pub agent_id: Option<String>,
467 /// Similarity metric.
468 pub metric: Metric,
469 /// Multi-signal score weights.
470 pub weights: ScoreWeights,
471 /// Index override: partitions to probe (`None` = index default). Ignored
472 /// when no ANN index is present.
473 pub n_probe: Option<usize>,
474 /// Index override: candidates to rerank (`None` = index default). Ignored
475 /// when no ANN index is present.
476 pub n_rerank: Option<usize>,
477 /// Whether to update each result's `accessed_at` and `access_count` in
478 /// the catalog. Defaults to `true`, matching pre-v5 behavior.
479 ///
480 /// Set to `false` for **fully read-only recall** — useful for batch
481 /// scoring, dry-run scoring, or recalls run by introspection tooling
482 /// (e.g. `mnemo about` consumers) where you don't want the score's own
483 /// observation to perturb the database. With `false`, recall does not
484 /// dirty the catalog and the next `flush` is a no-op.
485 pub track_access: bool,
486 /// Phase 12.6 pre-scoring filter: `session_id` + AND-ed metadata
487 /// conditions applied before the candidate is scored. Default is
488 /// [`Filter::default`] (no constraints). When the ANN index is on
489 /// and this filter is selective enough to starve the shortlist
490 /// below `top_k`, Phase 12.1's widen-then-exact-scan logic kicks
491 /// in so the result still carries up to `top_k` correct hits.
492 pub filter: Filter,
493 /// Phase 12.8 post-scoring budget: stop adding hits once the UTF-8
494 /// bytes of their `content` fields (not the serialized record
495 /// body) would exceed this many bytes. `None` (default) means no
496 /// budget and every hit through `top_k` is returned. If the top-1
497 /// hit is already over budget it is still returned — callers that
498 /// need an absolute cap should also pre-size `top_k`.
499 ///
500 /// Counts only the UTF-8 `content` bytes so the number is stable
501 /// across the Rust / Python / CLI / MCP surfaces; the JSON or
502 /// MessagePack envelope is excluded. Roughly 4 bytes per BPE
503 /// token for English text — a 4 KB budget comfortably holds ~1K
504 /// tokens.
505 ///
506 /// Observable through [`RecallResponse::truncated`]
507 /// ([`Mnemo::recall_budgeted`]): `true` iff at least one scored
508 /// hit was dropped by this budget, `false` otherwise.
509 pub max_bytes: Option<usize>,
510 /// FMT-9d (Phase 2, v9 files): **identifiers or exact terms to match**
511 /// (a version, a PR number, a function name) for hybrid recall. BM25
512 /// scores, divided by this query's best, are added to each candidate's
513 /// similarity with weight [`RecallRequest::keyword_weight`] before the
514 /// usual scoring. With an empty `query` vector
515 /// ([`RecallRequest::keywords_only`]), recall is keyword-only.
516 ///
517 /// **Since v0.15 (12.3 step 4), a recall by text is hybrid by default:**
518 /// with `keywords` `None`, the request's [`RecallRequest::text`] is
519 /// used for BM25, so give keywords only for identifiers the question
520 /// doesn't contain. Keywords given replace the text. **Empty keywords
521 /// (`.keywords("")`) opt out:** vector-only recall. `None` on a request
522 /// with no text is plain vector recall.
523 pub keywords: Option<String>,
524 /// 12.3 step 4 (v0.15): the query text a recall by text was built from
525 /// ([`RecallRequest::from_text`] sets it). With `keywords` `None` it's
526 /// also scored with BM25 on a v9 file (hybrid by default); a v8 file,
527 /// which has no keyword index, ignores it.
528 pub text: Option<String>,
529 /// FMT-9d: weight ε of the normalised BM25 score in hybrid recall
530 /// (default [`DEFAULT_KEYWORD_WEIGHT`]), for keywords given.
531 pub keyword_weight: f32,
532 /// 12.3 step 4 (v0.15): the weight when BM25 scores the request's
533 /// [`RecallRequest::text`] (no keywords given); default
534 /// [`DEFAULT_TEXT_KEYWORD_WEIGHT`].
535 pub text_keyword_weight: f32,
536 /// FMT-9d: BM25 term-frequency saturation `k1` (default 1.2).
537 pub bm25_k1: f32,
538 /// FMT-9d: BM25 length normalisation `b` (default 0.75).
539 pub bm25_b: f32,
540}
541
542impl RecallRequest {
543 /// A request with sensible defaults for a query embedding.
544 pub fn new(query: Vec<f32>) -> Self {
545 Self {
546 query,
547 top_k: 10,
548 memory_types: None,
549 agent_id: None,
550 metric: Metric::Cosine,
551 weights: ScoreWeights::default(),
552 n_probe: None,
553 n_rerank: None,
554 track_access: true,
555 filter: Filter::default(),
556 max_bytes: None,
557 keywords: None,
558 text: None,
559 keyword_weight: DEFAULT_KEYWORD_WEIGHT,
560 text_keyword_weight: DEFAULT_TEXT_KEYWORD_WEIGHT,
561 bm25_k1: 1.2,
562 bm25_b: 0.75,
563 }
564 }
565
566 /// FMT-9d (v9 files): a keyword-only request: BM25 over `keywords`
567 /// (identifiers or exact terms), no query vector, so it works without
568 /// an embedder.
569 pub fn keywords_only(keywords: impl Into<String>) -> Self {
570 Self::new(Vec::new()).keywords(keywords)
571 }
572
573 /// FMT-9d (v9 files): add identifiers or exact terms to match (hybrid
574 /// recall). They replace the request's text for BM25; `""` opts out of
575 /// keyword scoring. See the `keywords` field.
576 pub fn keywords(mut self, text: impl Into<String>) -> Self {
577 self.keywords = Some(text.into());
578 self
579 }
580
581 /// 12.3 step 4: the weight of the text's keyword score when no keywords
582 /// are given (see [`RecallRequest::text_keyword_weight`]).
583 pub fn text_keyword_weight(mut self, w: f32) -> Self {
584 self.text_keyword_weight = w;
585 self
586 }
587
588 /// 12.3 step 4: the weight of this request's keyword score: the text's
589 /// when it's the text that's scored, the keywords' otherwise.
590 pub(crate) fn effective_keyword_weight(&self) -> f32 {
591 if self.keywords.is_none() {
592 self.text_keyword_weight
593 } else {
594 self.keyword_weight
595 }
596 }
597
598 /// 12.3 step 4: the text BM25 scores for this request: the keywords
599 /// given (none if they're empty), or else the query text on a v9 file.
600 pub(crate) fn keywords_for(&self, v9: bool) -> Option<&str> {
601 match self.keywords.as_deref() {
602 Some(k) if k.trim().is_empty() => None,
603 Some(k) => Some(k),
604 None if v9 => self.text.as_deref().filter(|t| !t.trim().is_empty()),
605 None => None,
606 }
607 }
608
609 /// FMT-9d: the weight ε of the keyword score in hybrid recall.
610 pub fn keyword_weight(mut self, w: f32) -> Self {
611 self.keyword_weight = w;
612 self
613 }
614
615 /// Phase 12.6: attach a pre-scoring filter. See [`Filter`] and
616 /// [`FilterTerm`] for term shapes.
617 pub fn filter(mut self, filter: Filter) -> Self {
618 self.filter = filter;
619 self
620 }
621
622 /// Phase 12.8: cap the total UTF-8 bytes of returned `content`
623 /// fields. See [`RecallRequest::max_bytes`].
624 pub fn max_bytes(mut self, n: usize) -> Self {
625 self.max_bytes = Some(n);
626 self
627 }
628
629 /// Build a request by embedding `query_text` with the supplied
630 /// embedder (Phase 3). Since v0.15 it embeds with
631 /// [`Embedder::embed_query`] and keeps the text in
632 /// [`RecallRequest::text`], so the recall is hybrid by default (see
633 /// [`RecallRequest::keywords`]; `.keywords("")` opts out). Otherwise the
634 /// same defaults as `new`. Fails if the embedder returns an empty vector
635 /// list or an embedding failure.
636 pub fn from_text(embedder: &dyn Embedder, query_text: &str) -> Result<Self> {
637 let mut vectors = embedder.embed_query(&[query_text])?;
638 let v = vectors.pop().ok_or_else(|| {
639 MnemoError::Invalid("embedder returned no vector for the query text".into())
640 })?;
641 Ok(Self::new(v).text(query_text))
642 }
643
644 /// 12.3 step 4: set the query text (see [`RecallRequest::text`]), for
645 /// a caller that embedded it itself.
646 pub fn text(mut self, text: impl Into<String>) -> Self {
647 self.text = Some(text.into());
648 self
649 }
650 /// Set the result cap.
651 pub fn top_k(mut self, k: usize) -> Self {
652 self.top_k = k;
653 self
654 }
655 /// Restrict to specific memory types.
656 pub fn types(mut self, t: Vec<MemoryType>) -> Self {
657 self.memory_types = Some(t);
658 self
659 }
660 /// Restrict to one agent's view.
661 pub fn agent(mut self, agent_id: impl Into<String>) -> Self {
662 self.agent_id = Some(agent_id.into());
663 self
664 }
665 /// Set the similarity metric (default: cosine).
666 pub fn metric(mut self, metric: Metric) -> Self {
667 self.metric = metric;
668 self
669 }
670 /// Replace the multi-signal score weights.
671 pub fn weights(mut self, weights: ScoreWeights) -> Self {
672 self.weights = weights;
673 self
674 }
675 /// Override the number of IVF partitions probed (accuracy/speed dial).
676 pub fn n_probe(mut self, n: usize) -> Self {
677 self.n_probe = Some(n);
678 self
679 }
680 /// Override the number of candidates reranked exactly (accuracy dial).
681 pub fn n_rerank(mut self, n: usize) -> Self {
682 self.n_rerank = Some(n);
683 self
684 }
685 /// Toggle whether recall updates `accessed_at` / `access_count` on
686 /// the returned memories' catalog entries (default `true`). Pass
687 /// `false` for a fully read-only recall — see the field doc.
688 pub fn track_access(mut self, track: bool) -> Self {
689 self.track_access = track;
690 self
691 }
692}
693
694/// One scored result from [`Mnemo::recall`].
695#[derive(Clone, Debug)]
696pub struct RecallResult {
697 /// The retrieved memory.
698 pub memory: Memory,
699 /// Combined multi-signal score.
700 pub score: f32,
701 /// The bare similarity component (before other signals).
702 pub similarity: f32,
703}
704
705/// Phase 12.8 budgeted-recall envelope returned by
706/// [`Mnemo::recall_budgeted`]. Wraps the `Vec<RecallResult>` the
707/// legacy [`Mnemo::recall`] returns so callers can tell whether
708/// [`RecallRequest::max_bytes`] cut anything.
709#[derive(Clone, Debug)]
710pub struct RecallResponse {
711 /// Scored hits, best first, truncated to at most `top_k` and then
712 /// to fit the `max_bytes` budget if set.
713 pub hits: Vec<RecallResult>,
714 /// `true` iff the `max_bytes` budget dropped at least one hit
715 /// that would otherwise have been returned (i.e. the result is
716 /// shorter than what `top_k` alone would produce).
717 pub truncated: bool,
718 /// Phase 12.1 + 12.6 observability: `true` iff recall fell
719 /// through to an exact scan (ANN shortlist too narrow after
720 /// filtering, and the widen pass also came up short, so the
721 /// index was skipped for one full-corpus pass). Monitoring on
722 /// this flag is how callers detect selective-filter regressions
723 /// or supersession chains outgrowing the ANN shortlist.
724 pub used_exact_scan: bool,
725}
726
727/// Where a file's bytes and an open handle's heap go (P-0 device budget,
728/// `examples/device_budget.rs`). **Unstable diagnostic**: fields may
729/// change in any release. File figures come from the header and the
730/// catalog. RAM figures are buffer capacities, with hash maps estimated
731/// from their capacity; they cover the engine's main structures, not
732/// every allocation, and not allocator overhead.
733#[doc(hidden)]
734#[derive(Clone, Debug, Default, serde::Serialize)]
735#[cfg(feature = "dev-hooks")]
736pub struct BudgetReport {
737 pub file_bytes: u64,
738 pub page_size: u64,
739 /// Page 0.
740 pub header_bytes: u64,
741 /// Whole pages holding live records (superseded versions included).
742 pub record_page_bytes: u64,
743 /// Serialized bytes of those records; the rest of their pages is
744 /// slack.
745 pub record_payload_bytes: u64,
746 /// Pages still holding soft-deleted records (reclaimed by compact).
747 pub deleted_record_page_bytes: u64,
748 pub catalog_run_bytes: u64,
749 pub catalog_payload_bytes: u64,
750 pub index_run_bytes: u64,
751 pub index_payload_bytes: u64,
752 /// First page of the persisted index run (0 = none).
753 pub index_start_page: u64,
754 pub wal_bytes: u64,
755 pub snapshot_manifest_bytes: u64,
756 pub cache_dir_run_bytes: u64,
757 /// Everything else: superseded catalog, index and directory runs from
758 /// earlier flushes, and freed pages, until the next compact.
759 pub unreferenced_bytes: u64,
760 pub live_records: u64,
761 pub ram_catalog: u64,
762 pub ram_id_map: u64,
763 pub ram_ann_centroids: u64,
764 pub ram_ann_codebook: u64,
765 pub ram_ann_posting_ids: u64,
766 pub ram_ann_posting_codes: u64,
767 pub ram_ann_assignment: u64,
768 pub ram_cache_dir: u64,
769 pub ram_key_caches: u64,
770 /// FMT-9b: the resident fp16 vector column as allocated (rows not yet
771 /// touched by recall cost no physical memory).
772 pub ram_vector_column: u64,
773 /// Sum of the `ram_*` fields.
774 pub ram_total: u64,
775}
776
777/// Summary statistics for a database.
778#[derive(Clone, Debug)]
779pub struct Stats {
780 /// Live (non-deleted) memory count.
781 pub memories: usize,
782 /// Tombstoned entries awaiting compaction.
783 pub deleted: usize,
784 /// Embedding dimensionality.
785 pub dimensions: usize,
786 /// File size in bytes.
787 pub file_bytes: u64,
788 /// Distinct agent IDs present.
789 pub agents: Vec<String>,
790 /// Whether pages are encrypted (always true in v1).
791 pub encrypted: bool,
792 /// Creation time (unix seconds).
793 pub created_at: i64,
794 /// ANN index shape, if an index has been built.
795 pub index: Option<IndexInfo>,
796 /// Current size of the write-ahead log region, in 8 KiB pages.
797 pub wal_pages: u64,
798 /// Fsyncs issued by the most recent successful [`Mnemo::flush`] on
799 /// this handle. `0` on a fresh handle before any flush, or when
800 /// `flush()` short-circuited (nothing dirty). Phase 6 instrumentation
801 /// for the Phase 11.1 write-latency work — the planner wants this
802 /// before deciding whether cutting fsync count is a viable
803 /// durability-preserving fix.
804 pub fsyncs_last_flush: u32,
805 /// FMT-9f: the file's on-disk format (`8` or `9`). Since v0.13 a v8 file
806 /// opens read-only; `mnemo compact` converts it to v9.
807 pub format_version: u16,
808 /// MOBILE-2d: how recall scores vectors on this handle right now.
809 pub recall_mode: RecallMode,
810 /// INSP-1 (RB-001.25): the snapshots retained right now, each a
811 /// restore point for [`Mnemo::restore_to`]. Under churn the pin cap can
812 /// keep fewer than the policy's 16-and-24-hours, so this, not the
813 /// policy, is what can be restored.
814 pub snapshots_retained: usize,
815 /// When the oldest retained snapshot was committed (unix seconds):
816 /// the furthest back a restore reaches. `None` with no snapshot.
817 pub oldest_restorable_at: Option<i64>,
818 /// The bytes the retained snapshots keep from reuse (pages freed after
819 /// the oldest one). `0` on v8, which never reuses pages.
820 pub snapshot_pinned_bytes: u64,
821 /// TOK-1 (v0.15): the keyword index's tokenizer: `V2` for a file v0.15
822 /// created or rebuilt, `V1` for an older file until a compaction or
823 /// `reembed` rebuilds it, `Mixed` after a build before v0.15 wrote to
824 /// a tokenizer 2 index. `None` on v8, which has no keyword index.
825 pub keyword_tokenizer: Option<crate::KeywordTokenizer>,
826}
827
828/// [`Mnemo::stats_summary`]: the cheap statistics, read from the catalog and
829/// the header (v0.12.2, RB-002.3).
830#[derive(Clone, Debug, PartialEq, Eq)]
831pub struct StatsSummary {
832 /// Live (non-deleted) memory count.
833 pub memories: usize,
834 /// Tombstoned entries awaiting compaction.
835 pub deleted: usize,
836 /// Embedding dimensionality.
837 pub dimensions: usize,
838 /// File size in bytes.
839 pub file_bytes: u64,
840 /// The on-disk format, `8` or `9`.
841 pub format_version: u16,
842 /// Current size of the write-ahead log region, in 8 KiB pages.
843 pub wal_pages: u64,
844 /// Whether an IVF+PQ index exists (loaded, or persisted in the file).
845 pub has_index: bool,
846 /// How recall scores vectors right now.
847 pub recall_mode: RecallMode,
848 /// The bytes the v9 vector column needs to stay in memory: the live
849 /// facts × (`2 × dimensions + 4`). Recall is `ExactResident` while the
850 /// vector cache budget is at least this; `0` on v8, which has no column.
851 pub vector_column_bytes: u64,
852 /// INSP-1 (RB-001.25): the snapshots retained right now, each a
853 /// restore point for [`Mnemo::restore_to`]. Under churn the pin cap can
854 /// keep fewer than the policy's 16-and-24-hours, so this, not the
855 /// policy, is what can be restored.
856 pub snapshots_retained: usize,
857 /// When the oldest retained snapshot was committed (unix seconds):
858 /// the furthest back a restore reaches. `None` with no snapshot.
859 pub oldest_restorable_at: Option<i64>,
860 /// The bytes the retained snapshots keep from reuse (pages freed after
861 /// the oldest one). `0` on v8, which never reuses pages.
862 pub snapshot_pinned_bytes: u64,
863}
864
865/// MOBILE-2d: how recall scores vectors, from [`Mnemo::stats`].
866#[derive(Clone, Copy, Debug, PartialEq, Eq)]
867pub enum RecallMode {
868 /// An exact scan over the fp16 vector column held in memory: a v9 file
869 /// whose live facts fit [`Mnemo::set_vector_cache_budget`]. The fast
870 /// path.
871 ExactResident,
872 /// An exact scan that reads vectors through the page cache: a v9 file
873 /// whose live facts are over the budget, or a v8 file. Slower, and
874 /// slower still as the file grows; raise the budget or build an index.
875 ExactPaged,
876 /// An IVF+PQ index shortlists the candidates
877 /// ([`Mnemo::build_index`]).
878 Indexed,
879}
880
881impl RecallMode {
882 /// `exact_resident`, `exact_paged` or `indexed`.
883 pub fn as_str(&self) -> &'static str {
884 match self {
885 RecallMode::ExactResident => "exact_resident",
886 RecallMode::ExactPaged => "exact_paged",
887 RecallMode::Indexed => "indexed",
888 }
889 }
890}
891
892/// The error from [`Mnemo::try_close`]: the final flush failed, and the
893/// handle comes back with it, still open and still holding every write that
894/// wasn't flushed.
895pub struct CloseError {
896 pub(super) handle: Box<Mnemo>,
897 pub(super) error: MnemoError,
898}
899
900impl CloseError {
901 /// Why the flush failed.
902 pub fn error(&self) -> &MnemoError {
903 &self.error
904 }
905
906 /// The handle, to retry [`Mnemo::flush`] or [`Mnemo::try_close`].
907 pub fn into_inner(self) -> Mnemo {
908 *self.handle
909 }
910
911 /// The handle and the error.
912 pub fn into_parts(self) -> (Mnemo, MnemoError) {
913 (*self.handle, self.error)
914 }
915}
916
917impl std::fmt::Debug for CloseError {
918 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
919 f.debug_struct("CloseError")
920 .field("error", &self.error)
921 .finish_non_exhaustive()
922 }
923}
924
925impl std::fmt::Display for CloseError {
926 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
927 write!(f, "close failed (the handle is kept): {}", self.error)
928 }
929}
930
931impl std::error::Error for CloseError {
932 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
933 Some(&self.error)
934 }
935}
936
937/// Result of a [`Mnemo::compact_file`] run.
938#[derive(Clone, Copy, Debug, Default)]
939pub struct CompactReport {
940 /// Live memories before compaction.
941 pub before: usize,
942 /// Live memories after compaction (expired ones dropped).
943 pub after: usize,
944 /// Live, non-expired cache entries before compaction. FIX-1
945 /// R-001.1: compaction now preserves the result cache instead of
946 /// silently dropping it.
947 pub cache_before: usize,
948 /// Live, non-expired cache entries after compaction (tombstoned
949 /// and TTL-expired ones dropped).
950 pub cache_after: usize,
951 /// Legacy onboarding or manifest memories that held an all-zero vector
952 /// (from before the zero-vector rule) and were given the sentinel unit
953 /// vector a current manifest has.
954 pub zero_vector_manifests: usize,
955 /// Other memories with an all-zero vector, carried unchanged: their
956 /// content and recall behaviour are the same as before.
957 pub zero_vector_memories: usize,
958}
959
960/// What [`Mnemo::reembed_file`] did (12.3 step 4, v0.15).
961#[derive(Clone, Debug, PartialEq, Eq)]
962pub struct ReembedReport {
963 /// Live memories embedded again: facts, superseded versions, essence
964 /// items and thread turns (expired ones are dropped, as by compaction).
965 pub memories: usize,
966 /// Manifests kept on the sentinel vector (resized to the new width).
967 pub manifests: usize,
968 /// Thread links (`_mnemo.kind = "thread_link"`) kept on the sentinel
969 /// vector (resized to the new width), R-008.3.
970 pub thread_links: usize,
971 /// Result-cache entries copied (the engine's own aren't counted).
972 pub cache_entries: usize,
973 /// Semantic cache entries dropped because their vector has the old
974 /// width (only when the width changed).
975 pub cache_dropped: usize,
976 /// The identity the file recorded before, if any.
977 pub from: Option<crate::EmbedderIdentity>,
978 /// The identity it records now.
979 pub to: crate::EmbedderIdentity,
980}
981
982/// What [`Mnemo::verify_report`] checked.
983#[derive(Clone, Debug, PartialEq, Eq)]
984pub struct VerifyReport {
985 /// Records decrypted and decoded: live memories and cache entries (the
986 /// engine's own entries aren't counted).
987 pub records: usize,
988 /// Live memories whose vector is all zeros (from before the zero-vector
989 /// rule). They score 0.0 on every vector query.
990 pub zero_vector_memories: usize,
991 /// TOK-1: the keyword index's tokenizer (see
992 /// [`Stats::keyword_tokenizer`]). `Mixed` is worth a compaction.
993 pub keyword_tokenizer: Option<crate::KeywordTokenizer>,
994}
995
996/// An encrypted, single-file agent memory database.
997pub struct Mnemo {
998 /// 12.4: the lock layer's note for a handle opened through it for a
999 /// long operation ([`Mnemo::open_exclusive`], compaction): its
1000 /// `lock-info` line, removed when the handle drops. Declared first so
1001 /// it drops before `pager`, whose file's unlock comes after it.
1002 lock_note: Option<crate::shared::Held>,
1003 /// 12.3: what this handle has to tell its owner once, such as a
1004 /// passphrase on raw-key KDF parameters ([`Mnemo::notices`]).
1005 notices: Vec<String>,
1006 pager: Pager,
1007 header: Header,
1008 catalog: Vec<CatalogEntry>,
1009 index: IdIndex,
1010 /// The path this handle opened, made absolute at open (so a later
1011 /// change of the process's directory doesn't change what it names).
1012 /// `ensure_not_replaced` checks that it still names the open file.
1013 path: PathBuf,
1014 dimensions: usize,
1015 kdf: KdfParams,
1016 /// Set whenever the catalog changes; drives whether `flush` rewrites it.
1017 dirty_catalog: bool,
1018 /// Optional IVF+PQ approximate-nearest-neighbour index.
1019 ann: Option<IvfPqIndex>,
1020 /// Set whenever the in-memory ANN index differs from the persisted one.
1021 /// PERF-1: `flush` persists it only per [`IndexPersist`]'s policy.
1022 dirty_index: bool,
1023 /// PERF-1: index persistence policy state.
1024 index_persist: IndexPersist,
1025 /// PERF-1 step 3: the header points at a persisted ANN index that
1026 /// hasn't been loaded yet. It loads on first use (`ensure_ann`).
1027 ann_unloaded: bool,
1028 /// Append-only manifest of committed snapshots, oldest first. Capped
1029 /// at [`Mnemo::max_snapshots`] entries on every flush — the oldest
1030 /// entries are pruned first.
1031 manifest: Vec<Snapshot>,
1032 /// Maximum manifest entries to retain across flushes. `0` disables
1033 /// the cap (retain forever). Defaults to [`DEFAULT_MAX_SNAPSHOTS`].
1034 max_snapshots: usize,
1035 /// If `true`, this handle was opened via [`Mnemo::open_read_only`] and
1036 /// every mutating API returns [`MnemoError::ReadOnly`]. The underlying
1037 /// file was opened without write permission and holds an OS shared
1038 /// lock; the OS would reject a write() anyway, but gating in Rust
1039 /// gives callers a clean, typed error.
1040 read_only: bool,
1041 /// Result-cache directory (Phase 10.1). See [`crate::result_cache`].
1042 /// Loaded from `header.cache_start` on open; persisted on `flush`
1043 /// via the same seal_run pipeline as catalog/index/manifest.
1044 cache_dir: Vec<CacheDirectoryEntry>,
1045 /// In-memory index over `cache_dir` for O(1) `(namespace, key_hash)`
1046 /// lookups. Rebuilt on open + kept in sync on `cache_put`/`delete`.
1047 cache_idx: DirectoryIndex,
1048 /// Set whenever `cache_dir` changes; drives whether `flush` rewrites
1049 /// the cache directory run.
1050 dirty_cache: bool,
1051 /// Per-namespace eviction budgets. Missing entries fall back to
1052 /// [`CacheBudget::default`]. Not persisted (per-handle policy).
1053 cache_budgets: std::collections::HashMap<String, CacheBudget>,
1054 /// Flush policy for cache mutations. Memory writes ignore this and
1055 /// always behave as `Strict`.
1056 cache_flush_policy: CacheFlushPolicy,
1057 /// Bookkeeping for `CacheFlushPolicy::Batched` — pending mutation
1058 /// count and first-dirty timestamp.
1059 cache_batch: BatchState,
1060 /// In-memory hit/miss/eviction counters (reset on reopen).
1061 cache_counters: CounterState,
1062 /// Optional handle-scoped embedder (Phase 3, PR 10a). Registered
1063 /// via [`Mnemo::set_embedder`]; consulted by [`Mnemo::remember_text`]
1064 /// and [`RecallRequest::from_text`]. `None` means text-side APIs
1065 /// return [`MnemoError::Invalid`] with a "no embedder" message.
1066 /// Not persisted — the handle is re-registered after every open.
1067 embedder: Option<std::sync::Arc<dyn Embedder>>,
1068 /// Fsyncs issued by the most recent `flush()` call. Snapshotted
1069 /// from the thread-local fsync counter in `lib.rs::fsync_counter`:
1070 /// `flush()` reads it on entry, does its work (each `sync_all` the
1071 /// pager / wal / recovery path makes bumps the counter), and
1072 /// stores the delta here. `0` on a fresh handle before any flush,
1073 /// or on a read-only handle where `flush()` short-circuits.
1074 /// Exposed through [`Stats::fsyncs_last_flush`] for diagnostics —
1075 /// the Phase 6 planner wants this before deciding whether cutting
1076 /// fsync count is a viable write-latency win.
1077 fsyncs_last_flush: u32,
1078 /// FIX-1 R-001.8 part 2: lazy cache of the distinct agent IDs
1079 /// across every live memory, built once on first `stats()` call
1080 /// per handle. `remember()` adds to it in O(1); `delete()` can't
1081 /// cheaply tell whether the removed memory was the last of its
1082 /// agent (the agent lives in the encrypted body, not the catalog
1083 /// — pre-v9 format), so it just invalidates the set and the next
1084 /// `stats()` call rebuilds. Pre-FIX-1 every `stats()` call
1085 /// decrypted every live memory to collect agents, turning an
1086 /// otherwise-cheap diagnostic into an O(N) decrypt.
1087 agent_set: Option<std::collections::BTreeSet<String>>,
1088 /// Phase 12.1 lazy caches, built together on the first keyed op this
1089 /// handle sees (`remember_keyed`, `update` that touches `_mnemo.key`,
1090 /// or any `history(...)` call). Both are maintained incrementally
1091 /// after that. `None` → not built yet; `Some(…)` → authoritative.
1092 ///
1093 /// * `key_index`: `(scope_owner, key) → ULID bytes` of the **live**
1094 /// record for each keyed slot. `scope_owner` is `Some(agent_id)`
1095 /// for a `Private` scope slot and `None` for a `Shared` one, so a
1096 /// private write never collides with a shared one.
1097 /// * `superseded`: the ULID bytes of every record that has been
1098 /// superseded (`_mnemo.superseded_by` set on it). `recall` and
1099 /// `about` skip these before any decrypt.
1100 ///
1101 /// Building both costs one scan over live records (~1s at 100K with
1102 /// hardware AES) and happens at most once per handle. A format bump
1103 /// to v9 moves the key into the catalog row so the scan goes away.
1104 key_index: Option<std::collections::HashMap<KeySlot, u128>>,
1105 superseded: Option<std::collections::HashSet<u128>>,
1106 /// R-004.2: thread layers + onboarding ids, built by the same lazy scan.
1107 layers: Option<LayerCache>,
1108 /// REKEY-1 (RB-004.2): what the last successful rekey couldn't scrub
1109 /// once the new secret was in force (see [`Mnemo::rekey_cleanup_error`]).
1110 rekey_cleanup: Option<String>,
1111 /// 12.4 shared mode: access statistics from reads made under the
1112 /// shared lock (recall hits, cache hits), applied with this handle's
1113 /// next commit. `None` on every other handle.
1114 access_delta: Option<shared::AccessDelta>,
1115 /// 12.4 shared mode: the transaction id of the commit `flush` had
1116 /// reached the WAL with, when it fails after that point. A shared write
1117 /// uses it to tell a lost write from one that may be in the file.
1118 commit_point: Option<u64>,
1119 /// 12.4 shared mode (RB-007.5): a `flush` since the window started
1120 /// committed. Set by every committing flush; a shared write window
1121 /// clears it first, and then knows that part of the window is in the
1122 /// file when a later step fails.
1123 window_committed: bool,
1124 /// 12.4 shared mode: this handle is a shared handle's state, so a
1125 /// `rekey` inside a window is refused (`SharedMnemo::rekey` does it and
1126 /// updates the kept secret).
1127 shared: bool,
1128 /// FMT-9e: thread turns are compressed once older than this many
1129 /// seconds (`0`: at write). Per handle, not persisted.
1130 turn_compress_after: i64,
1131 /// FMT-9 (a): the committed free list (v9; always empty on v8). Pages
1132 /// allocated from it since the last commit are already removed.
1133 free: FreeList,
1134 /// FMT-9 (a): runs this transaction stopped referencing (overwritten
1135 /// or deleted records, tombstoned cache entries, a relocated WAL
1136 /// region). The next commit adds them to the free list, freed at its
1137 /// own transaction id.
1138 pending_free: Vec<(u64, u64)>,
1139 /// FMT-9 (a): the free list changed (an allocation took pages from it)
1140 /// and must be rewritten by the next commit.
1141 free_dirty: bool,
1142 /// FMT-9 (b): the key-slot run (v9; empty until Phase 13.2 adds slots).
1143 key_slots: KeySlotRun,
1144 /// FMT-9 (b): `key_slots` changed since the last commit.
1145 dirty_keys: bool,
1146 /// FMT-9: this writable session has burned a transaction id with a
1147 /// durable header-only commit (`ensure_gen_lease`), so the generations
1148 /// its pages carry can't repeat ones a crashed earlier session used.
1149 gen_leased: bool,
1150 /// FMT-9b: the fp16 vector column (v9; unused on v8).
1151 col: VecColumn,
1152 /// FMT-9b.2: packed record pages (v9; unused on v8).
1153 recs: RecPages,
1154 /// FMT-9d: the BM25 keyword index (v9; unused on v8).
1155 bm25: Bm25State,
1156 /// FMT-9d: test hook: write this layout byte instead of the current
1157 /// one (to exercise the unknown-layout path).
1158 index_layout_override: Option<u8>,
1159 /// FMT-9d: during one recall, each keyword match's normalised BM25
1160 /// score, by id.
1161 kw: Option<std::collections::HashMap<u128, f32>>,
1162 /// FMT-9c.2: catalog rows changed since the last commit (v9 writes
1163 /// them as a delta run instead of the whole catalog).
1164 dirty_rows: std::collections::BTreeSet<usize>,
1165 /// FMT-9c.2: the delta runs on top of the base catalog, oldest first,
1166 /// and how many rows they hold in all.
1167 delta_chain: Vec<RunPtr>,
1168 delta_rows: usize,
1169 /// FMT-9c.3: the ANN index's delta runs on top of its base run, oldest
1170 /// first, and how many changes they hold in all.
1171 index_chain: Vec<RunPtr>,
1172 index_chain_ops: usize,
1173 /// FMT-9c.3: the next commit writes the whole index (after a build,
1174 /// rebuild or restore).
1175 index_rebase: bool,
1176 /// FMT-9c.3: this flush's index changes, when it writes them as a
1177 /// delta run.
1178 index_delta_ops: Option<Vec<IndexOp>>,
1179 /// FMT-9c.2: the next commit writes a whole base catalog (after a
1180 /// restore, or when the chain has grown too long).
1181 catalog_rewrite: bool,
1182 /// FMT-9c: the snapshot count was set explicitly (config or
1183 /// `set_max_snapshots`), which replaces v9's default retention policy.
1184 snapshot_cap_explicit: bool,
1185 /// FMT-9c: this flush wrote big runs straight to their home pages,
1186 /// which must be fsynced before the commit.
1187 direct_writes: bool,
1188 /// FMT-9b: keep the column resident while it fits this many bytes.
1189 vector_cache_budget: usize,
1190}
1191
1192/// Composite key for the lazy `key_index` on `Mnemo`. A slot is identified
1193/// by `(scope_owner, key)`:
1194/// * `Scope::Private` writes carry the owning agent → `Some(agent_id)`.
1195/// * `Scope::Shared` writes are per-file → `None`.
1196///
1197/// A private write never supersedes a shared one, and the reverse is also
1198/// true. Scope lives on `Memory.scope`, agent on `Memory.agent_id`.
1199#[derive(Debug, Clone, PartialEq, Eq, Hash)]
1200pub(crate) struct KeySlot {
1201 /// `Some(agent_id)` for `Scope::Private`, `None` for `Scope::Shared`.
1202 pub(crate) scope_owner: Option<String>,
1203 /// The caller-supplied key string, exactly as given (no case-fold).
1204 pub(crate) key: String,
1205}
1206
1207/// True if a memory's metadata marks it as the canonical onboarding manifest
1208/// (`metadata.topic == "manifest"`). Used by [`Mnemo::about`] to hoist the
1209/// manifest to the top of the briefing regardless of importance ordering.
1210fn is_manifest(m: &Memory) -> bool {
1211 m.metadata
1212 .get("topic")
1213 .and_then(|v| v.as_str())
1214 .map(|s| s.eq_ignore_ascii_case("manifest"))
1215 .unwrap_or(false)
1216}
1217
1218/// PERF-1 step 4: ULID → catalog row, as an open-addressing table of `u32`
1219/// row numbers: 4 bytes a slot, about 5 bytes an entry, against about 43
1220/// for the `HashMap<u128, usize>` it replaces. A probe compares against the
1221/// catalog's own id at that row, so the ids aren't stored twice. Rows are
1222/// never removed (a delete only tombstones the catalog entry), so there's
1223/// no delete path.
1224#[derive(Debug, Clone, Default)]
1225struct IdIndex {
1226 slots: Vec<u32>,
1227 len: usize,
1228}
1229
1230const NO_ROW: u32 = u32::MAX;
1231
1232impl IdIndex {
1233 fn build(catalog: &[CatalogEntry]) -> IdIndex {
1234 let mut t = IdIndex {
1235 slots: vec![NO_ROW; crate::index::table_capacity_for(catalog.len())],
1236 len: 0,
1237 };
1238 for (row, e) in catalog.iter().enumerate() {
1239 t.insert(e.id, row, catalog);
1240 }
1241 t
1242 }
1243
1244 /// The catalog row holding `id`, if any.
1245 fn get(&self, id: u128, catalog: &[CatalogEntry]) -> Option<usize> {
1246 if self.slots.is_empty() {
1247 return None;
1248 }
1249 let cap = self.slots.len();
1250 let mut i = crate::index::slot_home(id, cap);
1251 loop {
1252 let row = self.slots[i];
1253 if row == NO_ROW {
1254 return None;
1255 }
1256 if catalog[row as usize].id == id {
1257 return Some(row as usize);
1258 }
1259 i = crate::index::next_slot(i, cap);
1260 }
1261 }
1262
1263 /// Map `id` to `row`. `catalog` must hold every row already in the
1264 /// table (the new row may not be pushed yet).
1265 fn insert(&mut self, id: u128, row: usize, catalog: &[CatalogEntry]) {
1266 if (self.len + 1) * 4 > self.slots.len() * 3 {
1267 let cap = (self.slots.len() * 2).max(crate::index::table_capacity_for(self.len + 1));
1268 let old = std::mem::replace(&mut self.slots, vec![NO_ROW; cap]);
1269 self.len = 0;
1270 for r in old.into_iter().filter(|&r| r != NO_ROW) {
1271 self.insert(catalog[r as usize].id, r as usize, catalog);
1272 }
1273 }
1274 let cap = self.slots.len();
1275 let mut i = crate::index::slot_home(id, cap);
1276 loop {
1277 let r = self.slots[i];
1278 if r == NO_ROW {
1279 self.slots[i] = row as u32;
1280 self.len += 1;
1281 return;
1282 }
1283 if catalog[r as usize].id == id {
1284 self.slots[i] = row as u32;
1285 return;
1286 }
1287 i = crate::index::next_slot(i, cap);
1288 }
1289 }
1290
1291 #[cfg(feature = "dev-hooks")]
1292 fn heap_bytes(&self) -> usize {
1293 self.slots.capacity() * std::mem::size_of::<u32>()
1294 }
1295}
1296
1297/// Build the ULID → catalog-row lookup.
1298fn build_id_index(catalog: &[CatalogEntry]) -> IdIndex {
1299 IdIndex::build(catalog)
1300}
1301
1302// ---------------------------------------------------------------------------
1303// Phase 12.7a helpers used by `ingest_thread`.
1304// ---------------------------------------------------------------------------
1305
1306/// PERF-1 / FMT-9: was this catalog row written after the persisted index
1307/// run? v8 allocates pages monotonically, so a record past the run's first
1308/// page is newer. v9 reuses pages, so it compares generations instead.
1309fn written_after_index(e: &CatalogEntry, v9: bool, index_start: u64, index_gen: u64) -> bool {
1310 if v9 {
1311 // `start_page` 0: packed at the next flush, so certainly newer.
1312 e.start_page == 0 || e.gen > index_gen
1313 } else {
1314 e.start_page > index_start
1315 }
1316}
1317
1318/// Whether a record belongs in the ANN index: facts only. Thread-archive
1319/// turns, essence items and thread links are read by kind and scope, never
1320/// by similarity, so they stay out (R-004.2).
1321fn is_ann_kind(m: &Memory) -> bool {
1322 !matches!(
1323 m.metadata.get(MNEMO_META_KIND).and_then(|v| v.as_str()),
1324 Some(MNEMO_META_KIND_TURN)
1325 | Some(MNEMO_META_KIND_ESSENCE)
1326 | Some(MNEMO_META_KIND_THREAD_LINK)
1327 )
1328}