# Research: Multi-Vector (PinnerSage-Style) User Preference

## Question

Should tidalDB replace its single per-user EMA preference vector with a multi-vector
(PinnerSage-style) representation, and if so, which clustering regime —
**offline-batch medoid** (PinnerSage proper), **online-maintained centroids** (the
`ARCHITECTURE.md:252-254` variant), or a **hybrid** — fits an embeddable,
single-node-first, in-process database? This doc settles one design for
@tidal-engineer to build.

## TidalDB Context

### What exists today (verified against code, 2026-06)

- **Single preference vector per user.** `tidal/src/entities/preference.rs`:
  `DashMap<u64, Vec<f32>>`, L2-normalized, blended via an adaptive-LR EMA
  `alpha = base / (1 + ln_1p(count))` (`update`, lines 109-126). Checkpoint/restore
  under `Tag::Preference` (`= 0x16`, `storage/keys.rs:71`); value layout
  `[count:8 LE][dim:4 LE][f32*dim LE]`, one row per user keyed by `EntityId(0)`
  sentinel + `[user:8 BE]` suffix (lines 263-362).
- **Update trigger.** On a *positive engagement* signal, `signals.rs:547` calls
  `try_update_preference_vector` (lines 765-816): reads the engaged item's stored
  embedding and blends it via `preference_vectors.update`. **There is no decay,
  velocity, or recency weighting on this blend** — the forward-decay signal model
  does not touch the preference vector at all. The only "recency" is the EMA's
  implicit exponential forgetting via `alpha`.
- **Consumption — `for_you`.** `query_ops.rs:99-116`: when the profile's
  `CandidateStrategy::Ann` is set and `query.for_user` is present, the db resolves
  **exactly one** query vector (`preference_vectors.get(user)`) and threads it as
  `ann_query_vector`. `candidate_gen.rs::ann_candidates` (lines 104-130) then issues
  **one** `index.search(query_vector, k, ef=64)` (`ANN_DEFAULT_EF_SEARCH`). Stage 3
  re-scores this pool by signals; `compute_preference_boosts`
  (`personalization.rs:91-123`) additionally applies a per-candidate cosine boost
  against the *same single* preference vector.
- **The `filtered_search` at `pipeline.rs:431`** is the **SEARCH** executor
  (explicit query vector + scope bitmap), **not** the `for_you` preference path. A
  multi-vector preference query would issue `search`/`filtered_search` K times from
  the `ann_candidates`/`query_ops` path, not from `pipeline.rs`.

### Why this matters for tidalDB specifically

- **Averaging problem is live.** A user who engages with hiking, cooking, and cars
  collapses to one EMA centroid that, per PinnerSage (KDD 2020), can represent *none*
  of them. tidalDB's core promise is "given a user and a context, what content should
  they see" — a multi-modal user is exactly where a single vector fails hardest.
- **Latency budget.** <50ms p99 end-to-end. The single-query ANN path is measured at
  p99 1.22ms (100k/1536-D, ef=64; `candidate_gen.rs:81-89`). K queries multiply the
  ANN leg, but the ANN leg is a small fraction of the budget — headroom exists (see
  §4).
- **Embeddable, single-node, in-process.** PinnerSage runs Ward hierarchical
  clustering on a *Spark cluster, daily, offline*. tidalDB has no Spark, no offline
  batch tier, and must cluster **in the same process that serves queries**. This is
  the single most important constraint and it disqualifies PinnerSage's literal
  implementation. The clustering primitive must be O(interactions) incremental work
  on the write path or a bounded periodic in-process pass — never an O(n²) hierarchical
  pass per user.

---

## Approaches Surveyed

### Approach 1: Offline-batch medoid clustering (PinnerSage proper)

**How it works:** Periodically (daily at Pinterest), collect each user's last ~N
interaction embeddings, run **Ward hierarchical agglomerative clustering** to produce
3-100 clusters, represent each cluster by its **medoid** (the actual interaction
embedding closest to the cluster's other members — *not* a synthetic centroid), and
assign each cluster an **importance** score (time-decayed engagement mass). At serve
time, sample 3 clusters by importance and issue one ANN query per sampled medoid.

**Used by:** Pinterest PinnerSage (KDD 2020, "PinnerSage: Multi-Modal User Embedding
Framework for Recommendations at Pinterest", Pal et al.), 400M+ MAU. The medoid
choice is load-bearing: Pinterest reports synthetic centroids degrade because the
centroid drifts into empty embedding-space regions ("energy boosting breakfast"
example).

**Evidence:** KDD 2020 paper; `docs/research/ann_for_tidaldb.md:102-116` already
endorses "PinnerSage-style multi-query with result merging — no special index
modifications required."

**Strengths for tidalDB:** Highest-quality clusters (Ward is the gold standard for
this exact problem). Medoid = an actual stored embedding, so it is always a valid,
in-distribution query vector. Importance sampling composes cleanly with engagement
mass.

**Weaknesses for tidalDB:** **Ward is O(n²) memory / O(n² log n) time** per user. It
requires holding the user's full interaction history (or a window) in memory and
re-clustering from scratch. There is **no offline tier in an embeddable DB** — running
this inline on the write path or on a checkpoint thread for every active user is a
non-starter at content-platform scale. Medoid maintenance requires storing the raw
interaction embeddings, not just K centroids — a large storage multiplier
(N interactions × dim vs K × dim).

### Approach 2: Online-maintained centroids (the ARCHITECTURE.md variant)

**How it works:** Maintain K running centroids per user directly on the write path.
On each positive engagement, assign the item embedding to the nearest existing
centroid (by cosine) and blend it in via an EMA; if no centroid is within a similarity
threshold τ and K is below the cap, spawn a new centroid seeded by the embedding. This
is **streaming/online k-means** (specifically *sequential k-means* / MacQueen's
online update) with a threshold-based split rule (a lightweight **DP-means**, Kulis &
Jordan, ICML 2012). `ARCHITECTURE.md:252-254` describes this: "3-10 interest cluster
centroids (PinnerSage-style), maintained by the database as signals arrive."

**Used by:** The *pattern* (streaming k-means / DP-means) is textbook and ships in
many online-learning systems; the *specific* "K running user-interest centroids
updated on engagement" is what large-scale rec systems approximate when they cannot
afford offline Ward. No single citable production system matches it exactly under this
name — this is a tidalDB-original synthesis, which has patent-conception relevance
(§7).

**Strengths for tidalDB:** O(K·dim) work per engagement — trivially cheap, fits the
write hot path, no batch tier, no Spark. Stores only K × dim floats per user, a near
zero storage delta over today's single vector. Reuses the existing EMA + adaptive-LR
machinery per centroid. Naturally incremental — no rebuild.

**Weaknesses for tidalDB:** **Re-introduces the averaging problem *within* a cluster.**
A centroid is by construction a synthetic mean — exactly what PinnerSage rejected. If
τ is too loose, two genuinely distinct interests merge into one drifting centroid and
you are back to the single-vector failure mode at finer granularity. **Order
sensitivity:** online assignment is greedy and non-revisable — an early
misassignment is permanent (no reclustering pass corrects it). **No medoid
guarantee** — a centroid can drift to an empty embedding-space region between its
members (the precise PinnerSage failure). **τ is a per-corpus magic number** that
governs cluster count and must be tuned/benchmarked.

### Approach 3: Hybrid — online assignment + bounded periodic in-process recluster

**How it works:** Run Approach 2 online for cheap, always-fresh, write-path
clustering. **Additionally**, on the existing periodic checkpoint thread (which
already walks every user for `Tag::Preference` checkpoint, `preference.rs:263`), run a
bounded **in-process micro-recluster** for users whose interaction count crossed a
threshold since their last recluster: pull that user's recent interaction-embedding
window (capped, e.g. last 256), run a *cheap* clustering pass (mini-batch k-means with
k-means++ seed, or single-linkage with a distance cutoff — both O(N·K·dim), not
O(N²)), and **snap each cluster's representative to the nearest actual interaction
embedding (a medoid)**, recovering PinnerSage's medoid property. Online centroids
serve queries between reclusters; the periodic pass corrects greedy misassignments and
prevents centroid drift.

**Used by:** This is the architectural pattern Qdrant/Tantivy/Lucene use for *segment
management* (cheap incremental writes + periodic compaction merge) applied to user
clustering. `ann_for_tidaldb.md:96` already cites this segment pattern as proven. No
rec system publishes this exact hybrid for *user clustering*, again giving it
conception novelty (§7).

**Strengths for tidalDB:** Gets online's write-path cheapness AND offline's quality
correction, with **no new background subsystem** — it rides the checkpoint thread that
already exists. Recovers the medoid property periodically. The recluster is bounded
(capped window, K small, mini-batch) so it is O(active_users × window × K × dim), not
O(n²) global.

**Weaknesses for tidalDB:** Most implementation surface of the three. Requires storing
a **bounded recent interaction-embedding window per user** (the recluster input) — a
storage cost between Approach 1 (full history) and Approach 2 (K centroids only).
Two code paths (online + periodic) that must agree on the centroid format. The medoid
snap requires the window to still hold the chosen embedding (it does, by construction).

---

## Comparison

| Criterion | A: Offline medoid (Ward) | B: Online centroids | C: Hybrid (online + periodic medoid recluster) |
|---|---|---|---|
| Clustering cost | O(n² log n) per user, batch | O(K·dim) per engagement | O(K·dim)/engagement + bounded periodic O(W·K·dim) |
| Needs offline/Spark tier | **Yes (disqualifying)** | No | No (rides checkpoint thread) |
| Avoids averaging *across* interests | Yes | Yes (if τ tuned) | Yes |
| Avoids averaging *within* a cluster | **Yes (medoid)** | **No (synthetic centroid)** | **Yes (periodic medoid snap)** |
| Order-sensitivity / corrects misassignment | Corrects (full recluster) | **No (greedy, permanent)** | Corrects periodically |
| Storage per user | N×dim (full window) | **K×dim (≈ today)** | bounded W×dim window + K×dim |
| Reuses existing EMA/adaptive-LR | Partially | **Fully** | Fully (online leg) |
| Write-path latency impact | n/a (offline) | Negligible (K cosine + 1 EMA) | Negligible (online leg) |
| New magic constants | linkage cutoff | **τ (split threshold), K cap** | τ, K cap, recluster window W, recluster cadence |
| Implementation surface | High (Ward, but offline) | **Low** | Medium |
| Patent-conception novelty | None (prior art) | Medium | **High** (no published equivalent) |

---

## Settling the Sub-Questions

### 1. Central fork — recommendation

**Build Approach B (online-maintained centroids) now, with the data layout designed
so Approach C (the periodic medoid recluster) drops in later without a format
migration.** Concretely: ship B; reserve the persistence fields and the
interaction-window storage hooks that C needs (§5), but gate the periodic recluster
behind a follow-up milestone.

Rationale:

- **A is disqualified by the in-process constraint.** Ward hierarchical clustering has
  no home in an embeddable single-node DB with no batch tier. The prompt's framing is
  correct: PinnerSage's offline-medoid approach assumes a Spark cluster tidalDB does
  not have.
- **B is the cheapest correct online primitive** and is already 80% built — it is N
  copies of the existing `preference.rs` EMA, one per centroid, plus a nearest-centroid
  assignment and a threshold split. It eliminates the *across-interest* averaging
  problem (the dominant failure) immediately.
- **Does online clustering reintroduce the averaging problem within a cluster?** Yes —
  honestly, it does. A centroid is a mean. But this is a *second-order* failure
  (averaging within one coherent interest is far less harmful than averaging across
  three unrelated ones), and it is exactly what the deferred Approach-C medoid snap
  fixes. Shipping B first captures the large win; C captures the residual.
- **Cheapest correct online clustering primitive:** **threshold-based sequential
  k-means with a DP-means-style split** (assign to nearest centroid if cosine ≥ τ,
  else open a new centroid up to K_max). This is strictly cheaper than online
  agglomerative (which needs a merge step) and needs no fixed-K commitment up front
  (unlike classic streaming k-means). Use cosine on unit vectors (consistent with the
  existing L2-normalized invariant).

### 2. Cluster count K — recommendation

- **Adaptive per user, capped.** K grows by the DP-means split rule up to **K_max = 10**
  (matches `ARCHITECTURE.md`'s "3-10"). Most users will have 1-3 active clusters; only
  multi-modal users reach the cap. A fixed K wastes vectors for single-interest users
  and starves multi-modal ones.
- **Cold-start rule:** **below N = 5 positive interactions, fall back to the existing
  single adaptive-LR vector** (the current code path, unchanged). This is exactly
  `ann_for_tidaldb.md:112` ("for users with <5 interactions: simple weighted average
  is acceptable"). The single vector *is* the K=1 case; cold-start is therefore not a
  separate code path but the natural K=1 floor — the multi-vector store seeds its
  first centroid from the existing single vector when it crosses N.
- When over the cap, the split rule must **not** open an 11th cluster; instead assign to
  the nearest existing centroid (the standard DP-means cap behavior). Do not evict —
  eviction loses an interest; merging is the periodic recluster's job (Approach C).

### 3. Cluster importance / time-decay — recommendation

- **Per-cluster importance = decayed engagement mass.** Each centroid carries a scalar
  `importance` that is incremented on assignment and **forward-decayed using tidalDB's
  existing signal-decay model** rather than wall-clock recomputation. This is the
  composition point with the forward-decay signal system: store
  `(importance_at_anchor, anchor_timestamp)` per cluster and compute
  `current_importance = importance_at_anchor × decay(now − anchor)` on read — the same
  O(1) forward-decay primitive the signal ledger already uses
  (`docs/research/tidaldb_signal_ledger.md`). This is the *correct* reconciliation of
  the ARCHITECTURE.md "maintained by the database as signals arrive with decay" claim,
  which today is unimplemented (the EMA has only implicit forgetting, no decay term).
- **Query-time cluster selection = importance sampling, deterministic top-M.** Rather
  than PinnerSage's stochastic sample, query the **top-M clusters by current
  importance** where M = min(K_active, 3). Deterministic top-M is reproducible (tidalDB
  values deterministic queries elsewhere, e.g. the exploration shuffle in
  `candidate_gen.rs:174`) and 3 is PinnerSage's serve-time count. Make M a profile
  parameter so a profile can widen exploration.
- This means a stale interest naturally falls out of the queried set as its importance
  decays below the 3rd-ranked cluster — without ever deleting it (a re-engagement
  re-boosts it).

### 4. Query-time mechanics — recommendation and latency budget

- **Issue M `search` calls** (one per selected cluster centroid), where M ≤ 3. **As
  shipped these run sequentially on the query thread** (the loop is embarrassingly
  parallel and reserved for parallelization). For the `for_you` path these are
  unfiltered `search` (today's call); when a scope bitmap is present they become
  `filtered_search` — identical to the existing `pipeline.rs:431` shape, just issued
  M times.
- **Merge + dedup:** union the M result lists, dedup by entity id keeping the **best
  (min) distance** across clusters, then take top-k by that distance. This is a
  k-way merge of sorted lists, O(M·k). Critically, **dedup-by-best-distance, not
  dedup-by-score** — the ANN distance is the cluster-relevance signal; the engagement
  *score* is applied afterward by Stage 3, which must remain the single authority on
  final ordering.
- **Interaction with Stage 3:** unchanged. Stage 3 re-ranks the merged pool by signals
  exactly as today. The only change `compute_preference_boosts`
  (`personalization.rs:91`) needs: compute the per-candidate cosine boost against the
  **nearest of the user's clusters** (max cosine over **all** the user's centroids, not
  only the M queried — a union candidate is then scored against its true best interest),
  not a single vector — otherwise a candidate retrieved via the "cars" cluster gets a
  near-zero boost measured against a "cooking"-dominated single vector.
- **Latency cost (quantitative):** the ANN leg at 100k/1536-D, ef=64 is **p99 1.22ms**
  per query (`candidate_gen.rs:81-89`). M=3 issued sequentially (as shipped) is ~3.7ms
  p99 — well inside the 50ms budget; parallelizing would adds only parallel-merge
  overhead, not 3× latency. The merge of 3×k lists (k≈200) is sub-microsecond. **Net:
  the multi-vector path costs <3ms additional p99 in the as-shipped serial case (<1.5ms
  if parallelized).** The dominant budget consumer remains Stage 3
  preference-boost recompute (per MEMORY: `for_you` ANN p99 ~24ms is Stage-3, not the
  ANN leg) — multi-vector does not move that needle except for the nearest-centroid
  cosine change, which is M cosines instead of 1 per candidate (negligible).
- **Throughput:** at 1K queries/sec × M=3 = 3K ANN searches/sec; USearch sustains this
  comfortably at this corpus (per m12p3 grid-search). No new throughput risk.

### 5. Persistence — recommendation

Extend the `Tag::Preference` format, do **not** add a new tag (keeps the single
prefix-scan restore). Today's value is `[count:8 LE][dim:4 LE][f32*dim LE]`. Make it
**self-describing and backward-compatible**:

```
[version:1][n_clusters:1][dim:4 LE]
  repeated n_clusters times:
    [update_count:8 LE]            # per-cluster adaptive-LR count
    [importance_at_anchor:4 LE f32]
    [anchor_ts:8 LE]               # for forward-decay importance
    [f32 * dim LE]                 # the centroid (unit-normalized)
```

- `version` byte distinguishes the new layout from the legacy one. **Restore must
  read legacy rows** (no version byte, starts with an 8-byte count then a 4-byte dim ≤
  some sane max) and load them as a single K=1 cluster — a zero-migration upgrade. A
  legacy detector: if `bytes[0]` is a plausible version (e.g. `2`) AND the implied
  length matches, parse new; else parse legacy. **As built:** the 1-byte version
  sentinel CAN collide with a legacy little-endian count's low byte (e.g. `update_count
  == 2`), so the discriminator is *structural*, not byte-value-based — a row is parsed
  as multi-cluster only if `bytes[0] == FORMAT_VERSION` AND it decodes into ≥1
  dimension-correct cluster; otherwise it falls through to the legacy decoder. This
  rescues a colliding legacy row instead of dropping it. (See `FORMAT_VERSION` in
  `entities/multi_preference.rs`.)
- **For Approach C (deferred):** a *second* tag `Tag::PreferenceWindow` (discriminant
  `0x1A` — `0x17`–`0x19` are already taken) stores the bounded recent
  interaction-embedding window per user, written ring-buffer style. **This tag is now
  reserved in `keys.rs`** (not yet populated); adding the window when C ships is an
  additive row, never a rewrite of existing `Tag::Preference` rows.
- The atomic-batch swap (`checkpoint`, lines 270-296) and the load-boundary
  re-normalization + NaN-neutralization (`restore`, lines 333-353) carry over
  per-cluster unchanged — re-normalize every centroid, drop torn clusters
  individually rather than the whole user.

### 6. Adaptive learning rate — recommendation

**Preserve it per-cluster.** Each centroid keeps its own `update_count` and computes
`alpha = base / (1 + ln_1p(count))` exactly as today — a cluster stabilizes as it
accumulates engagements, which is the correct behavior (a well-established interest
should resist drift). Do **not** replace the per-cluster EMA with re-clustering in
Approach B — there is no reclustering in B. When Approach C's periodic recluster
runs, it **resets** the per-cluster counts for any cluster whose membership it
recomputes (a reclustered centroid is effectively new), which is the only point where
"re-clustering replaces the LR." So: **B preserves per-cluster adaptive LR; C's
periodic pass resets the LR of reclustered clusters.** This is internally consistent —
the LR tracks "how settled is *this* centroid," and a recluster un-settles it.

### 7. Reduced-to-practice vs. conception boundary

Patent filing distinguishes what the shipped design **actually implements** (reduced
to practice) from what is **described but not built** (conception only). Be precise —
claiming reduction to practice for unbuilt aspirational features is a filing defect.

| Element | Status in the recommended design | RTP or Conception |
|---|---|---|
| Single adaptive-LR EMA preference vector | Shipped today (`preference.rs`) | **Reduced to practice** (prior, in-tree) |
| Cold-start fallback to K=1 single vector below N interactions | Built in Approach B | **Reduced to practice** (on ship) |
| Online sequential-k-means + DP-means threshold split, K_max cap | Built in Approach B | **Reduced to practice** (on ship) |
| Per-cluster adaptive learning rate | Built in Approach B | **Reduced to practice** (on ship) |
| Forward-decayed per-cluster importance composed with the signal-decay model | Built in Approach B | **Reduced to practice** (on ship) |
| Deterministic top-M importance-ranked cluster selection at query time | Built in Approach B | **Reduced to practice** (on ship) |
| M **sequential** ANN queries + dedup-by-best-distance merge feeding Stage 3 (parallelization reserved) | Built in Approach B | **Reduced to practice** (on ship) |
| Max-cosine-over-all-clusters preference boost in Stage 3 | Built in Approach B | **Reduced to practice** (on ship) |
| Version-tagged backward-compatible `Tag::Preference` multi-cluster layout | Built in Approach B | **Reduced to practice** (on ship) |
| Periodic in-process medoid recluster on the checkpoint thread (Approach C) | **Designed, not built** | **Conception only** |
| Medoid snap recovering an actual-interaction representative | **Designed, not built** | **Conception only** |
| Bounded per-user interaction-embedding window (`Tag::PreferenceWindow`) | Reserved, not populated | **Conception only** |
| LR reset on recluster | Designed for C, not built | **Conception only** |
| Offline Ward hierarchical clustering (Approach A) | Surveyed, rejected | **Neither** (not pursued) |

The novel-conception kernel for a filing is the **combination**: online DP-means user
clustering + forward-decay-composed cluster importance + deterministic top-M multi-ANN
merge, **with a deferred in-process medoid-recluster correction** — no surveyed
production system (PinnerSage included, which is offline+medoid) combines online
maintenance with a periodic in-process medoid correction on an embedded DB's
checkpoint thread.

---

## Recommendation (one design, chosen)

**Ship Approach B.** Implement multi-vector user preference as **online
sequential-k-means with a DP-means threshold split**, capped at K_max=10, with:

1. **Cold start:** below N=5 positive interactions, use the existing single
   adaptive-LR vector (the K=1 floor; seed the first centroid from it on crossover).
2. **Assignment:** on each positive engagement, find the nearest centroid by cosine;
   if cosine ≥ τ blend via the existing per-cluster adaptive-LR EMA, else open a new
   centroid (up to K_max; over the cap, assign to nearest — never evict).
3. **Importance:** per-cluster `(importance_at_anchor, anchor_ts)`, forward-decayed
   with tidalDB's existing signal-decay primitive on read.
4. **Query (`for_you`):** select top-M (M=min(K_active,3)) clusters by current
   importance; issue M sequential `search`/`filtered_search` calls (parallelizable,
   not yet parallelized); merge with dedup-by-best-distance; feed the unified pool to
   Stage 3 unchanged.
5. **Stage 3 boost:** `compute_preference_boosts` uses max cosine over **all** the
   user's cluster centroids (a union candidate is scored against its true best interest).
6. **Persistence:** version-tagged multi-cluster `Tag::Preference` value, backward-
   compatible with legacy K=1 rows (structural discriminator, no count-collision drop);
   `Tag::PreferenceWindow` (`0x1A`) reserved in `keys.rs` for Approach C.
7. **Design the centroid + window storage so Approach C (periodic in-process medoid
   recluster) drops in with no format migration** — but do not build C in this
   milestone.

τ, K_max, N, M, and the decay half-life are **benchmark-derived constants**, not
guesses (see Open Questions). Default τ around 0.5-0.6 cosine for OpenAI-1536-D
embeddings as a *starting* point for the grid search, not a shipped value.

---

## Doc / Roadmap Corrections Required

These are factual reconciliations the survey surfaced; @tidal-engineer should land
them alongside (or before) the implementation:

1. **`ARCHITECTURE.md:252-254`** currently asserts, as if shipped, that each user's
   preference "is represented as 3-10 interest cluster centroids (PinnerSage-style),
   maintained by the database as signals arrive." **This is not implemented** — the
   code maintains exactly one EMA vector with no decay term. Correct the doc to either
   (a) describe the *single-vector* reality with a forward-pointer to this research, or
   (b) keep the multi-vector description but explicitly mark it as the planned design
   (this doc) rather than current behavior. Also fix the implicit "with decay" claim:
   today's blend has no decay; the decay composition is the *new* work in §3 here.

2. **`ROADMAP.md:587`** claims Phase 1 delivered "the **adaptive filtered search
   planner**." The delivered artifact is the **selectivity-based query planner** (AC at
   line 594: <2% → pre-filter+brute-force; 2-100% → `filtered_search`). That is real
   and shipped. But "adaptive" here risks being read as the adaptive *preference*/
   multi-vector planner, which does **not** exist. Reword to "selectivity-based
   filtered-search planner" to remove the conflation, and do not let this line stand as
   evidence that multi-vector preference is delivered.

3. **`ann_for_tidaldb.md:106-116`** is consistent with this doc (PinnerSage multi-query
   merge) but says "pre-compute user interest clusters **offline**" — which contradicts
   the embeddable, no-batch-tier constraint. Add a cross-reference from
   `ann_for_tidaldb.md` to this doc noting that the *offline* framing is superseded by
   the *online* Approach B for tidalDB's in-process model.

---

## Open Questions (benchmarks tidalDB must run)

- **τ (split threshold):** the single most important constant. Grid-search τ ∈
  {0.4..0.7} on a real multi-modal interaction trace; measure cluster count
  distribution and feed-relevance vs. ground truth. Too loose → averaging within
  cluster returns; too tight → K_max saturates and fragments one interest.
- **Does online-only (B) measurably beat the single vector** on a multi-modal cohort,
  and **by how much does the deferred medoid recluster (C) add** on top? If C's lift
  over B is marginal, C may never need to ship — that decision must be data-driven, not
  assumed.
- **Order-sensitivity magnitude:** construct adversarial interaction orderings; measure
  how often greedy online assignment produces a materially worse clustering than a
  batch recluster of the same set. This quantifies the value of Approach C.
- **M (clusters queried) sweep:** M ∈ {2,3,5} — relevance lift vs. the linear ANN-leg
  latency cost. Confirm the <3ms p99 estimate holds at 1M/1536-D (currently k3s-pending,
  per the m12 memory entries).
- **Dedup-by-best-distance vs. round-robin interleave** for the merge: which yields
  better post-Stage-3 diversity? Interleaving may better surface minority interests.
- **Importance decay half-life:** how fast should a stale interest fall out of the
  top-M? Tie to the signal-decay half-life or make it independent? Needs a retention/
  freshness A/B.
- **Storage delta for Approach C's interaction window** at scale (W=256 × 1536 × 4B ≈
  1.5MB/user) — validate this is acceptable for the active-user set before committing to
  C's window.

## Sources

- Pal et al., "PinnerSage: Multi-Modal User Embedding Framework for Recommendations at
  Pinterest," KDD 2020. (Ward hierarchical clustering, medoid representation,
  importance sampling, averaging-failure example.)
- Kulis & Jordan, "Revisiting k-means: New Algorithms via Bayesian Nonparametrics,"
  ICML 2012. (DP-means — threshold-based adaptive cluster count, the online split rule.)
- MacQueen, "Some methods for classification and analysis of multivariate
  observations," 1967. (Sequential/online k-means update.)
- `docs/research/ann_for_tidaldb.md` §"Multi-vector retrieval needs no special
  indexing" (lines 102-135). (USearch multi-query merge endorsement; segment pattern.)
- `docs/research/tidaldb_signal_ledger.md`. (Forward-decay O(1) primitive composed with
  cluster importance.)
- In-tree code verified 2026-06: `tidal/src/entities/preference.rs`,
  `tidal/src/db/signals.rs:547,765-816`, `tidal/src/db/query_ops.rs:99-116`,
  `tidal/src/query/executor/candidate_gen.rs:64-130`,
  `tidal/src/query/executor/personalization.rs:91-123`,
  `tidal/src/query/search/executor/pipeline.rs:429-440`,
  `tidal/src/storage/keys.rs:71`, `ARCHITECTURE.md:252-254`, `ROADMAP.md:587-598`.