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