mnemo-engine 0.5.2__tar.gz → 0.6.0__tar.gz

{mnemo_engine-0.5.2 → mnemo_engine-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mnemo-engine
-Version: 0.5.2
+Version: 0.6.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: Apache Software License
@@ -58,9 +58,28 @@ The scaffold tells the next agent what to do: replace it with one that
 records your real embedder and conventions. See the [main README](../mnemo/README.md#self-describing-databases)
 for the full pattern.
 
-## Build & install
+## Install
 
-The bindings build with [maturin](https://www.maturin.rs):
+The published wheel is the normal install path — nothing to build:
+
+```bash
+pip install mnemo-engine
+```
+
+Prebuilt wheels ship for CPython 3.8+ on macOS x86_64 + arm64, Linux
+x86_64 + aarch64 (manylinux), and Windows x86_64. If none fits (e.g. a
+BSD, aarch64 musl, or any other platform mnemo doesn't ship a wheel
+for), pip falls back to the sdist and compiles from source — that path
+needs a working Rust toolchain (`rustup`) and will take a few minutes.
+
+> ARM users building from source (sdist, or `cargo install mnemo-engine`
+> directly): set `RUSTFLAGS="--cfg aes_armv8 --cfg polyval_armv8"` before
+> install to enable hardware AES. The prebuilt wheels have this baked
+> in; your sdist build doesn't see our repo's `.cargo/config.toml`.
+> Verify afterwards with `mnemo.build_info()['aes_backend']`, which
+> should read `"armv8 hardware"` (not `"armv8 software"`).
+
+### From source (contributors)
 
 ```bash
 pip install maturin
@@ -138,7 +157,7 @@ its own agent.
 | Method | Purpose |
 |---|---|
 | `remember(content, memory_type, vector, *, agent_id, importance, session_id, ttl_secs, shared, metadata)` | Store a memory; returns its id |
-| `recall(query, top_k=10, memory_types=None, agent_id=None, track_access=True)` | Multi-signal ranked retrieval. `track_access=False` skips access-stat updates (fully read-only recall) |
+| `recall(query, top_k=10, memory_types=None, agent_id=None, track_access=True, n_probe=None, n_rerank=None)` | Multi-signal ranked retrieval. `track_access=False` skips access-stat updates (fully read-only recall). `n_probe` / `n_rerank` (PR ANN-1): per-query ANN tuning — `None` uses the index's build-time defaults (ANN-1 auto-formulas: `(partitions+1)/2` and `500`) |
 | `search(query, top_k=10)` | Exact nearest-neighbour search |
 | `get(id)` / `delete(id)` | Fetch / soft-delete by id |
 | `about()` | Self-describing onboarding briefing — memories tagged `metadata.area="onboarding"`, manifest first |
@@ -163,17 +182,18 @@ its own agent.
 | `rekey(new_passphrase, fast=False)` | Change the passphrase. Re-derives the KEK and re-wraps the DEK; encrypted pages are not rewritten (O(1) in db size). `fast=True` uses the cheap-Argon2 test params — omit for production |
 | `set_embedder(fn, *, name, dimensions, normalize=True)` | Register a Python callable `embed(texts: list[str]) -> list[list[float]]` as this handle's text embedder (Phase 3). Dimension-checks against the database's width; identity-checks against (and on first use upserts) the scaffold manifest's `embedder_name` / `embedder_dimensions` / `embedder_normalize` keys, so swapping embedders between opens fails loudly |
 | `remember_text(content, memory_type, **kwargs)` | Embed `content` via the registered embedder and `remember` the result. Accepts the same per-memory kwargs as `remember` (`agent_id`, `importance`, `session_id`, `ttl_secs`, `shared`, `metadata`) |
-| `recall_text(query, top_k=10, memory_types=None, agent_id=None, track_access=True)` | Embed `query` via the registered embedder and run `recall`. Same return shape as `recall` |
+| `recall_text(query, top_k=10, memory_types=None, agent_id=None, track_access=True, n_probe=None, n_rerank=None)` | Embed `query` via the registered embedder and run `recall`. Same return shape and ANN-tuning kwargs as `recall` |
 | `cache_get_semantic_text(namespace, text, threshold=0.97)` | Text-side semantic cache lookup; uses the embedder's `name` as the semantic cache's `model` component |
-| `stats()` | Summary statistics |
+| `stats()` | Summary statistics — includes `fsyncs_last_flush` (count of `sync_all` the most recent `flush()` on this handle issued; `0` on a fresh handle before any flush — Phase 6 instrumentation) |
 | `export_encrypted(dest)` | Copy the (already-encrypted) file elsewhere |
 | `len(db)` | Live memory count |
 
-Plus one module-level function:
+Plus two module-level functions:
 
 | Function | Purpose |
 |---|---|
 | `mnemo.compact_file(path, passphrase)` | Rewrite the file out-of-place, dropping tombstoned and expired memories and reclaiming stale pages. Caller's own handle must be closed first. Returns `{"before": int, "after": int}` |
+| `mnemo.build_info()` | Returns `{"version", "target", "aes_backend", "polyval_backend"}` for the installed wheel. Lets you verify an ARM wheel picked up the hardware AES path — `aes_backend` should read `"armv8 hardware"` on Apple Silicon / Graviton (anything else, like `"armv8 software (constant-time fallback)"`, means the compile missed the fix). PR 11.0, v0.5.1+ |
 
 `Session` methods: `add_turn(turn)`, `recall(query, top_k=10, memory_types=None)`,
 `close()`, `discard()`, `id()`, `agent()`, `turn_ids()`, `turn_count()`; also a

{mnemo_engine-0.5.2 → mnemo_engine-0.6.0}/README.md

@@ -44,9 +44,28 @@ The scaffold tells the next agent what to do: replace it with one that
 records your real embedder and conventions. See the [main README](../mnemo/README.md#self-describing-databases)
 for the full pattern.
 
-## Build & install
+## Install
 
-The bindings build with [maturin](https://www.maturin.rs):
+The published wheel is the normal install path — nothing to build:
+
+```bash
+pip install mnemo-engine
+```
+
+Prebuilt wheels ship for CPython 3.8+ on macOS x86_64 + arm64, Linux
+x86_64 + aarch64 (manylinux), and Windows x86_64. If none fits (e.g. a
+BSD, aarch64 musl, or any other platform mnemo doesn't ship a wheel
+for), pip falls back to the sdist and compiles from source — that path
+needs a working Rust toolchain (`rustup`) and will take a few minutes.
+
+> ARM users building from source (sdist, or `cargo install mnemo-engine`
+> directly): set `RUSTFLAGS="--cfg aes_armv8 --cfg polyval_armv8"` before
+> install to enable hardware AES. The prebuilt wheels have this baked
+> in; your sdist build doesn't see our repo's `.cargo/config.toml`.
+> Verify afterwards with `mnemo.build_info()['aes_backend']`, which
+> should read `"armv8 hardware"` (not `"armv8 software"`).
+
+### From source (contributors)
 
 ```bash
 pip install maturin
@@ -124,7 +143,7 @@ its own agent.
 | Method | Purpose |
 |---|---|
 | `remember(content, memory_type, vector, *, agent_id, importance, session_id, ttl_secs, shared, metadata)` | Store a memory; returns its id |
-| `recall(query, top_k=10, memory_types=None, agent_id=None, track_access=True)` | Multi-signal ranked retrieval. `track_access=False` skips access-stat updates (fully read-only recall) |
+| `recall(query, top_k=10, memory_types=None, agent_id=None, track_access=True, n_probe=None, n_rerank=None)` | Multi-signal ranked retrieval. `track_access=False` skips access-stat updates (fully read-only recall). `n_probe` / `n_rerank` (PR ANN-1): per-query ANN tuning — `None` uses the index's build-time defaults (ANN-1 auto-formulas: `(partitions+1)/2` and `500`) |
 | `search(query, top_k=10)` | Exact nearest-neighbour search |
 | `get(id)` / `delete(id)` | Fetch / soft-delete by id |
 | `about()` | Self-describing onboarding briefing — memories tagged `metadata.area="onboarding"`, manifest first |
@@ -149,17 +168,18 @@ its own agent.
 | `rekey(new_passphrase, fast=False)` | Change the passphrase. Re-derives the KEK and re-wraps the DEK; encrypted pages are not rewritten (O(1) in db size). `fast=True` uses the cheap-Argon2 test params — omit for production |
 | `set_embedder(fn, *, name, dimensions, normalize=True)` | Register a Python callable `embed(texts: list[str]) -> list[list[float]]` as this handle's text embedder (Phase 3). Dimension-checks against the database's width; identity-checks against (and on first use upserts) the scaffold manifest's `embedder_name` / `embedder_dimensions` / `embedder_normalize` keys, so swapping embedders between opens fails loudly |
 | `remember_text(content, memory_type, **kwargs)` | Embed `content` via the registered embedder and `remember` the result. Accepts the same per-memory kwargs as `remember` (`agent_id`, `importance`, `session_id`, `ttl_secs`, `shared`, `metadata`) |
-| `recall_text(query, top_k=10, memory_types=None, agent_id=None, track_access=True)` | Embed `query` via the registered embedder and run `recall`. Same return shape as `recall` |
+| `recall_text(query, top_k=10, memory_types=None, agent_id=None, track_access=True, n_probe=None, n_rerank=None)` | Embed `query` via the registered embedder and run `recall`. Same return shape and ANN-tuning kwargs as `recall` |
 | `cache_get_semantic_text(namespace, text, threshold=0.97)` | Text-side semantic cache lookup; uses the embedder's `name` as the semantic cache's `model` component |
-| `stats()` | Summary statistics |
+| `stats()` | Summary statistics — includes `fsyncs_last_flush` (count of `sync_all` the most recent `flush()` on this handle issued; `0` on a fresh handle before any flush — Phase 6 instrumentation) |
 | `export_encrypted(dest)` | Copy the (already-encrypted) file elsewhere |
 | `len(db)` | Live memory count |
 
-Plus one module-level function:
+Plus two module-level functions:
 
 | Function | Purpose |
 |---|---|
 | `mnemo.compact_file(path, passphrase)` | Rewrite the file out-of-place, dropping tombstoned and expired memories and reclaiming stale pages. Caller's own handle must be closed first. Returns `{"before": int, "after": int}` |
+| `mnemo.build_info()` | Returns `{"version", "target", "aes_backend", "polyval_backend"}` for the installed wheel. Lets you verify an ARM wheel picked up the hardware AES path — `aes_backend` should read `"armv8 hardware"` on Apple Silicon / Graviton (anything else, like `"armv8 software (constant-time fallback)"`, means the compile missed the fix). PR 11.0, v0.5.1+ |
 
 `Session` methods: `add_turn(turn)`, `recall(query, top_k=10, memory_types=None)`,
 `close()`, `discard()`, `id()`, `agent()`, `turn_ids()`, `turn_count()`; also a

{mnemo_engine-0.5.2 → mnemo_engine-0.6.0}/mnemo/Cargo.lock

@@ -610,7 +610,7 @@ checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
 
 [[package]]
 name = "mnemo-engine"
-version = "0.5.2"
+version = "0.6.0"
 dependencies = [
  "aes-gcm",
  "argon2",

{mnemo_engine-0.5.2 → mnemo_engine-0.6.0}/mnemo/Cargo.toml

@@ -6,7 +6,7 @@
 # below stay `mnemo`, so consumers still write `use mnemo::...` and invoke
 # `mnemo` on the command line after `cargo add mnemo-engine`.
 name = "mnemo-engine"
-version = "0.5.2"
+version = "0.6.0"
 edition = "2021"
 rust-version = "1.75"
 # `benches/corpus.rs` is a shared helper module pulled into real benches

{mnemo_engine-0.5.2 → mnemo_engine-0.6.0}/mnemo/README.md

@@ -350,6 +350,25 @@ region grows automatically when a transaction's control plane outgrows it.
 (`tests/integration.rs` exercises crash recovery, the torn-header heal, a
 discarded uncommitted log, and WAL growth.)
 
+**Torn-header recovery (DUR-1).** Every post-`create` page-0 change —
+WAL relocation when the control plane outgrows the current region, and
+`rekey` when the passphrase moves — now goes through the WAL first:
+commit a one-frame `(0, new_header)` transaction into the new region,
+checkpoint page 0, then invalidate the predecessor region's first
+frame header. Combined with a streaming file-wide scan on open, this
+means a torn page-0 write at *any* WAL location is recoverable: open
+walks every 8 KiB-aligned `MWAL` candidate in the file, picks the
+highest-`txn_id` committed header frame whose `wal_start` + `wal_seq`
+agree with the frame's region, whose DEK unwraps under the
+passphrase, and whose AES-GCM seal validates, then replays it. Only
+the initial `Mnemo::create` writes page 0 unlogged. **A header that
+fails its seal is reported as `HeaderTampered` and never auto-healed**
+— the entire 294-byte header lies inside one 512-byte sector that
+storage writes atomically, so a surviving CRC with a failing seal
+cannot be a torn write, and silently loading a stale authenticated
+header from the WAL would erase the tamper-evidence the seal exists
+to give.
+
 What this buys over a plain copy-on-write header swap: a single-fsync commit
 and an explicit, replayable transaction boundary.
 
@@ -466,6 +485,35 @@ accurate, lower is faster. The index is stored *inside* the encrypted file
 Internally the index ranks by squared-L2; the exact rerank uses the
 requested metric, so for cosine queries a generous `n_rerank` is advisable.
 
+**Default auto-formulas (PR ANN-1 + ANN-1.1, pending v0.6.0).**
+`IndexConfig::default()` now picks `pq_subspaces = dims/4` at build time
+(was `dims/8`), plus query-time formulas:
+
+- `n_probe = max(ceil(partitions / 2), min(partitions, 100))` (was fixed `8`)
+  — full probe up to ~10K-vector files (≤100 partitions), half probe above
+- `n_rerank = (n_vectors / 200).clamp(100, 1000)` (ANN-1 shipped a fixed
+  500; ANN-1.1 made it size-aware — see
+  `index::effective_auto_n_rerank`). Hits 100 at 10K, 500 at 100K, caps
+  at 1000.
+
+Measured on the Phase 6 synthetic corpus: 10K hits recall@10 ≈ 0.98 at
+~1.4 ms/query; 100K hits ~0.98 at ~10.6 ms/query. The old pre-ANN-1
+`n_probe=8, n_rerank=64` defaults capped 100K recall@10 at ~0.40.
+
+**Upgrade path for existing files.** The `n_probe` / `n_rerank` fix
+takes effect at query time (ANN-1.1), so a v0.5.x-built index gets the
+new defaults immediately on first open under v0.6.0+ — no rebuild
+needed. The `pq_subspaces` fix is build-time (baked into the PQ
+codebook), so you'll stay on the old 48-subspace codebook until you run
+`mnemo index --rebuild` (CLI) or `db.rebuild_index()` (Rust / Python).
+With `pq_subspaces=48` + new query-time formulas, 100K tops out at
+~0.92; rebuilding to 96 subspaces lifts it to ~0.98. See
+`test/scripts/perf_v0.5.0.json` keys `ann_recall_grid_v2` (grid) and
+`ann_defaults_v0_6_0` (measurements at the shipped defaults).
+
+Any explicit `n_probe` / `n_rerank` passed per call still overrides
+everything above.
+
 `Mnemo::search` always stays exact — it is the brute-force ground truth.
 
 ## Security model
@@ -705,7 +753,7 @@ cargo run --bin mnemo -- demo            # try it without any setup
 
 ```sh
 cargo build --release
-cargo test            # 34 integration + 12 CLI smoke + 2 doctests + unit tests
+cargo test            # 66 integration + 26 CLI smoke + proptest state machine + unit tests
 cargo run --example quickstart
 ```
 
@@ -873,6 +921,14 @@ append history dominate everything else). The README design targets
 (<5 ms recall at 100 K, <15 ms at 1 M, <4 KB/memory) are aspirational
 goals at scale, not yet measured here.
 
+> **Historical note (updated 2026-10).** The CLI timings in this
+> baseline were taken on a *debug* `cargo run --bin mnemo` build. The
+> v0.5.x Phase 6 harness re-measures the same operations with release
+> builds and reports them in the Performance history row + the
+> `test/scripts/perf_v0.5.0.json` artifact — on a release build with
+> production KDF the open latency settles at ~15 ms, not ~330 ms.
+> Keeping this row for history, not as a current baseline.
+
 **Knobs that should help small files.** Running `compact` collapses
 snapshot history back to a single page run; the default 64-page WAL
 reservation is fixed today and would need a config change to shrink. ANN
@@ -886,9 +942,17 @@ rows stay as-is so improvements (or regressions) are visible.
 | Version | Date     | Corpus     | File size | CLI `info` | Python recall | Notes                  |
 |---------|----------|------------|-----------|------------|---------------|------------------------|
 | v0.1.0  | 2026-05  | 31 mems, 384-dim, no index | 1.41 MB | ~330 ms | ~35 ms | Initial dogfood baseline |
-| v0.5.0  | 2026-10  | 10K mems, 384-dim, IVF+PQ  | 82.9 MB | — (open 14.9 ms secure KDF) | 374 µs (IVF+PQ) / 623 ms (exact) | Phase 6: criterion benches + ranking harness + ANN recall@10 grid + file-size breakdown. IVF+PQ ≈ 1,660× faster than exact at 10K; 10,400× at 100K. Default `IndexConfig` recovers only 40% of exact top-10 — scoring v2 candidate. Full numbers in `test/scripts/perf_v0.5.0.json`. |
+| v0.5.0  | 2026-10  | 10K mems, 384-dim, IVF+PQ  | 82.9 MB | — (open 14.9 ms secure KDF) | 374 µs (IVF+PQ†) / 623 ms (exact‡) | Phase 6: criterion benches + ranking harness + ANN recall@10 grid + file-size breakdown. IVF+PQ ≈ 1,660× faster than exact at 10K; 10,400× at 100K. Default `IndexConfig` recovers only 40% of exact top-10 — **index-quality defect, fixed in ANN-1 below** (originally mis-filed as a scoring issue). Full numbers in `test/scripts/perf_v0.5.0.json`. |
 | v0.5.1  | 2026-10  | same corpus, hardware AES on ARM | — | — | 105 ms (exact 10K) / 1.05 s (exact 100K); IVF+PQ unchanged | PR 11.0: enable `--cfg aes_armv8 --cfg polyval_armv8` so aarch64 builds use hardware AES + PMULL instead of the constant-time software fallback. **6.0×** faster exact scan at 10K, **6.1×** at 100K; 1.3× on cache_put; IVF+PQ and Argon2id-bound open unchanged. See `test/scripts/perf_v0.5.0.json`'s `speed_hw_aes` block for the full set. No API or format change. If you build from crates.io see the "ARM users" section above. |
 
+> † IVF+PQ speed at the old defaults; recall@10 was ~0.40 at those
+> defaults, not 1.0. PR ANN-1 raises the default to ≥0.95 recall@10 at
+> ~10 ms/query at 100K; see the `ann_recall_grid_v2` block in
+> `perf_v0.5.0.json`.
+> ‡ Both v0.5.0 timings were measured on software AES (the fix landed
+> in v0.5.1). On hardware AES, exact scan at 10K drops to 105 ms;
+> IVF+PQ was never AES-bound so it's unchanged.
+
 ## Scope: what is and isn't here
 
 This crate is a faithful build of the MNemo plan, built to actually compile,

mnemo_engine-0.6.0/mnemo/examples/ann_defaults_v0_6_0.rs

@@ -0,0 +1,315 @@
+//! PR ANN-1.1 measurement: recall@10 + latency at the exact shipped
+//! v0.6.0 defaults, on each cached corpus tier.
+//!
+//! Two scenarios per tier:
+//!
+//! 1. **Fresh install** — index built with `IndexConfig::default()`
+//!    on v0.6.0+: `pq_subspaces = dims/4` (96 for 384-dim), auto
+//!    `n_probe` + size-aware auto `n_rerank` recomputed per query.
+//!    This is what every new user experiences.
+//! 2. **Upgrade path** — index built on v0.5.x (so `pq_subspaces =
+//!    dims/8` = 48 on 384-dim; stored `n_probe = 8, n_rerank = 64`)
+//!    reopened under v0.6.0. The query-time auto formulas kick in
+//!    without a rebuild (see `IvfPqIndex::effective_defaults` — the
+//!    legacy sentinel `(8, 64)` triggers auto). Shows what a user
+//!    gets *before* running `mnemo index --rebuild`.
+//!
+//! Writes `test/scripts/perf_v0.5.0.json["ann_defaults_v0_6_0"]`
+//! with per-tier `{fresh_install, upgrade_path}` cells carrying
+//! `recall_at_10` + `mean_query_ms` + the exact `n_probe` / `n_rerank`
+//! values the formulas picked.
+//!
+//! Run:
+//! ```sh
+//! cargo run --release --example ann_defaults_v0_6_0
+//! ```
+
+use std::collections::HashSet;
+use std::fs;
+use std::path::PathBuf;
+use std::time::Instant;
+
+use mnemo::{
+    IndexConfig, KdfParams, Memory, MemoryType, Metric, Mnemo, MnemoConfig, RecallRequest,
+};
+use serde_json::{json, Value};
+
+const PASSPHRASE: &str = "bench-pw";
+const DIMENSIONS: usize = 384;
+const QUERY_COUNT: usize = 50;
+const TOP_K: usize = 10;
+
+// Deterministic clustered-vector gen — same as benches/corpus.rs so
+// the cached files from Phase 6 / ANN-1 are byte-identical to what
+// this harness would produce.
+fn gen_clustered_vectors(n: usize, dims: usize, k_clusters: usize, seed: u64) -> Vec<Vec<f32>> {
+    let mut state = seed.wrapping_mul(0x9E37_79B9_7F4A_7C15).wrapping_add(1);
+    let mut next_u64 = || -> u64 {
+        state = state.wrapping_add(0x9E37_79B9_7F4A_7C15);
+        let mut z = state;
+        z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
+        z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
+        z ^ (z >> 31)
+    };
+    let mut next_normal = || -> f32 {
+        let u1 = ((next_u64() >> 11) as f64 / (1u64 << 53) as f64).max(1e-12);
+        let u2 = (next_u64() >> 11) as f64 / (1u64 << 53) as f64;
+        let r = (-2.0 * u1.ln()).sqrt();
+        (r * (2.0 * std::f64::consts::PI * u2).cos()) as f32
+    };
+    let normalize = |v: &mut [f32]| {
+        let mut norm = 0.0f32;
+        for x in v.iter() {
+            norm += x * x;
+        }
+        norm = norm.sqrt();
+        if norm == 0.0 {
+            v[0] = 1.0;
+        } else {
+            for x in v.iter_mut() {
+                *x /= norm;
+            }
+        }
+    };
+    let mut centres: Vec<Vec<f32>> = Vec::with_capacity(k_clusters);
+    for _ in 0..k_clusters {
+        let mut c = (0..dims).map(|_| next_normal()).collect::<Vec<_>>();
+        normalize(&mut c);
+        centres.push(c);
+    }
+    const NOISE_SIGMA: f32 = 0.1;
+    let mut out = Vec::with_capacity(n);
+    for i in 0..n {
+        let cluster = i % k_clusters;
+        let mut v: Vec<f32> = centres[cluster]
+            .iter()
+            .map(|&c| c + NOISE_SIGMA * next_normal())
+            .collect();
+        normalize(&mut v);
+        out.push(v);
+    }
+    out
+}
+
+fn cached_corpus_path(n: usize) -> PathBuf {
+    let base = std::env::var("CARGO_TARGET_DIR").unwrap_or_else(|_| "target".to_string());
+    PathBuf::from(base)
+        .join("benches")
+        .join(format!("corpus_{n}_{DIMENSIONS}d.mnemo"))
+}
+
+fn ensure_corpus(n: usize) -> PathBuf {
+    let path = cached_corpus_path(n);
+    if path.exists() {
+        if let Ok(db) = Mnemo::open(&path, PASSPHRASE) {
+            if db.dimensions() == DIMENSIONS {
+                return path;
+            }
+        }
+        let _ = fs::remove_file(&path);
+    }
+    println!(
+        "[ann-defaults] building {n}-memory corpus at {}",
+        path.display()
+    );
+    fs::create_dir_all(path.parent().unwrap()).unwrap();
+    let cfg = MnemoConfig {
+        dimensions: DIMENSIONS,
+        kdf: KdfParams::fast(),
+        ..Default::default()
+    };
+    let mut db = Mnemo::create(&path, PASSPHRASE, cfg).unwrap();
+    let k_clusters = ((n as f64).sqrt().ceil() as usize).max(16);
+    let vectors = gen_clustered_vectors(n, DIMENSIONS, k_clusters, 0xBEEF_C0DE);
+    for (i, v) in vectors.into_iter().enumerate() {
+        db.remember(Memory::new(
+            format!("bench memory #{i}"),
+            MemoryType::Semantic,
+            v,
+        ))
+        .unwrap();
+    }
+    db.flush().unwrap();
+    db.build_index_with(IndexConfig::default()).unwrap();
+    db.flush().unwrap();
+    path
+}
+
+/// Measure one (pq_subspaces, scenario_label) config on a corpus.
+///
+/// Rebuilds the ANN index in memory with the given `pq_subspaces` and
+/// explicit `(n_probe, n_rerank)` cfg values (sentinels or auto, per
+/// scenario), *doesn't flush* (cached file on disk is unchanged), and
+/// runs 50 recall queries. Returns a JSON cell with recall@10, mean
+/// latency, and the n_probe/n_rerank the index actually used at
+/// query time.
+fn measure_scenario(
+    cached: &PathBuf,
+    scenario: &str,
+    pq_subspaces: usize,
+    cfg_n_probe: usize,
+    cfg_n_rerank: usize,
+) -> Value {
+    let mut db = Mnemo::open(cached, PASSPHRASE).unwrap();
+
+    // Ground truth via exact search. Done before the index rebuild so
+    // it uses whatever's on disk — the vectors themselves are what
+    // matter, not the ANN state.
+    let queries = gen_clustered_vectors(QUERY_COUNT, DIMENSIONS, 100, 0xDEAD_BEEF);
+    let truth: Vec<HashSet<String>> = queries
+        .iter()
+        .map(|q| {
+            db.search(q, TOP_K, Metric::Cosine)
+                .unwrap()
+                .into_iter()
+                .map(|(m, _)| m.id.to_string())
+                .collect()
+        })
+        .collect();
+
+    // Rebuild the index in memory with this scenario's config.
+    db.drop_index();
+    let cfg = IndexConfig {
+        pq_subspaces,
+        n_probe: cfg_n_probe,
+        n_rerank: cfg_n_rerank,
+        ..Default::default()
+    };
+    let t_build = Instant::now();
+    db.build_index_with(cfg).unwrap();
+    let build_secs = t_build.elapsed().as_secs_f64();
+
+    // Both scenarios end up on the auto formulas at query time —
+    // fresh_install because build() resolves `IndexConfig::default()`
+    // to those values, upgrade_path because the stored (8, 64)
+    // sentinel triggers them. ANN-1.1 made `IvfPqIndex::info()`
+    // report the effective (shim-applied) numbers directly, so just
+    // read them back from `Stats::index` instead of reimplementing
+    // the formula here (where it would silently drift).
+    let info = db.stats().unwrap().index.unwrap();
+    let partitions = info.partitions;
+    let effective_n_probe = info.n_probe;
+    let effective_n_rerank = info.n_rerank;
+
+    let mut recalls = Vec::with_capacity(QUERY_COUNT);
+    let t0 = Instant::now();
+    for (q, truth_ids) in queries.iter().zip(truth.iter()) {
+        let req = RecallRequest::new(q.clone())
+            .top_k(TOP_K)
+            .track_access(false);
+        // No .n_probe()/.n_rerank() — this is the whole point of the
+        // test: measure what users get when they don't tune.
+        let hits = db.recall(&req).unwrap();
+        let got: HashSet<String> = hits.into_iter().map(|h| h.memory.id.to_string()).collect();
+        let hit = truth_ids.intersection(&got).count();
+        recalls.push(hit as f32 / TOP_K as f32);
+    }
+    let mean_secs = t0.elapsed().as_secs_f64() / QUERY_COUNT as f64;
+    let mean_recall = recalls.iter().sum::<f32>() / QUERY_COUNT as f32;
+
+    println!(
+        "  {scenario:>14}  pq={pq_subspaces:>3}  partitions={partitions:>4}  \
+         n_probe={effective_n_probe:>4}  n_rerank={effective_n_rerank:>4}  \
+         recall@10={mean_recall:.3}  {:>7.2} ms/query  build={build_secs:.1}s",
+        mean_secs * 1000.0,
+    );
+
+    json!({
+        "scenario": scenario,
+        "pq_subspaces": pq_subspaces,
+        "partitions": partitions,
+        "n_vectors": info.vectors,
+        "n_probe_used": effective_n_probe,
+        "n_rerank_used": effective_n_rerank,
+        "recall_at_10": round4(mean_recall as f64),
+        "mean_query_ms": round4(mean_secs * 1000.0),
+        "build_secs": round4(build_secs),
+    })
+}
+
+fn main() {
+    // Tiers to measure. 1M is "if feasible" — the harness tries it if
+    // the cached corpus is already on disk; otherwise it's skipped
+    // with a note. Avoids the 20-minute first-build cost unless the
+    // user already paid it in an earlier phase.
+    let tiers_to_measure: Vec<usize> = [10_000usize, 100_000, 1_000_000]
+        .iter()
+        .filter(|&&n| {
+            if n <= 100_000 {
+                return true;
+            }
+            // 1M only if cached; otherwise skip + print.
+            let p = cached_corpus_path(n);
+            if p.exists() {
+                true
+            } else {
+                println!(
+                    "[ann-defaults] skipping 1M tier ({} not cached; label as unmeasured)",
+                    p.display()
+                );
+                false
+            }
+        })
+        .copied()
+        .collect();
+
+    let mut tiers_json: Vec<Value> = Vec::new();
+    for n in tiers_to_measure {
+        println!("\n[ann-defaults] tier={n}");
+        let cached = ensure_corpus(n);
+        let cells = vec![
+            // Fresh install: new build defaults everywhere (dims/4
+            // pq + auto probe + auto rerank).
+            measure_scenario(&cached, "fresh_install", DIMENSIONS / 4, 0, 0),
+            // Upgrade path: v0.5.x build left pq_subspaces = dims/8 =
+            // 48 and stamped (8, 64) into the index. Simulate with
+            // explicit (8, 64) — ANN-1.1's legacy sentinel detection
+            // treats those as "auto" at query time.
+            measure_scenario(&cached, "upgrade_path", DIMENSIONS / 8, 8, 64),
+        ];
+        tiers_json.push(json!({
+            "corpus_size": n,
+            "dimensions": DIMENSIONS,
+            "scenarios": cells,
+        }));
+    }
+
+    let perf_path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .unwrap()
+        .join("test/scripts/perf_v0.5.0.json");
+    let mut out: Value = if perf_path.exists() {
+        let txt = fs::read_to_string(&perf_path).unwrap();
+        let v: Value = serde_json::from_str(&txt).unwrap();
+        if v.is_array() {
+            json!({ "legacy_rows": v })
+        } else {
+            v
+        }
+    } else {
+        json!({})
+    };
+    out["ann_defaults_v0_6_0"] = json!({
+        "methodology":
+            "Per-tier (10K, 100K, 1M-if-cached): rebuild the ANN index in \
+             memory under two scenarios — 'fresh_install' = IndexConfig::default() \
+             with pq_subspaces=dims/4 and ANN-1.1 query-time auto formulas; \
+             'upgrade_path' = explicit (pq=dims/8, n_probe=8, n_rerank=64) to \
+             simulate a v0.5.x-built index; ANN-1.1's legacy-sentinel detection \
+             substitutes the new auto formulas at query time. 50 queries per \
+             scenario, recall@10 against exact search, mean latency per query. \
+             Index is rebuilt in memory only — cached corpus on disk is \
+             untouched. See CHANGELOG `## [Unreleased]` → ANN-1.1.",
+        "tiers": tiers_json,
+    });
+    fs::write(
+        &perf_path,
+        serde_json::to_string_pretty(&out).unwrap() + "\n",
+    )
+    .unwrap();
+    println!("\n[ann-defaults] wrote {}", perf_path.display());
+}
+
+fn round4(x: f64) -> Value {
+    Value::from((x * 10000.0).round() / 10000.0)
+}