Skip to main content

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