ADR 0105: Quality score C-isolation uses an absolute floor on the shared cosine scale
Status: accepted Date: 2026-10-05
Context
ADR 0103 defined the new_person_cluster isolation feature as the group's relational margin clamp01((d_nearest_external_identity - mean_intra_cluster_distance) / 0.15). Owner evaluation on the real production library (26,619 faces, threshold 0.45, 2026-10-05) invalidated that design: because a dense group's internal spread is small, the relational margin saturated — median C isolation was 1.0 while 771 of 3418 emitted C groups sat CLOSER than 0.50 (the old 0.35 threshold + safety margin) to the nearest confirmed person's centroid, and 103 had effectively zero margin. In the shared weights (0.35 cohesion + 0.25 isolation + 0.25 ambiguity + 0.15 size) this handed coherent identity-adjacent splinter groups ~0.13 points over merge cards: the run's 381 cluster_person_match cards ranked behind 192 weaker new_person_cluster cards (best merge card at carousel rank 193), reproducing the exact 'only New person suggestions' complaint ADR 0103 was written to fix. The user's review raised the semantic objection that both card types must be graded by the SAME standard: a new-person proposal must demonstrably NOT belong to any existing cluster, on the same scale the merge proposal's confidence lives on.
Decision
Change ONLY the C isolation feature to an absolute margin on the shared cosine-distance scale: clamp01((d_nearest_external_identity - 0.50) / 0.35). A group within 0.50 of the nearest confirmed person's centroid earns ZERO isolation credit regardless of internal coherence; full credit from 0.85. The 0.50 floor sits one step above the production clustering_max_distance (0.45): a group the clustering itself could plausibly have attached to a person must not earn an isolation bonus for exactly that proximity. mean_intra no longer enters the feature (the helper signature keeps the parameter for call-site stability); ambiguity (0.10 runner-up margin), cohesion, size and all ADR 0103 weights are unchanged; grouping, outcome gates, card shapes and validators are untouched — the change affects ONLY the persisted ranking score. Offline measurement with the changed code on the same library: best merge card rank 193 → 1, top-30 composition 0/30 → 15/15 B/C, while genuinely distant stranger groups keep their isolation credit (their d_nearest exceeds the old effective bar too). Because existing pending cards carry scores from the old formula, a clustering reset + rerun is required after deploy to re-score the board.
Consequences
New-person cards adjacent to known people no longer outrank merge cards; the owner sees family merge suggestions at the top of the carousel. The relational-margin semantics (a group graded against its own spread) are gone — a future outcome-based refit (ADR 0103's planned Platt-style recalibration over the owner accept/reject log) supersedes both anchors. 0.50/0.35 are documented worker constants (C_ISOLATION_FLOOR / C_ISOLATION_RANGE) and revisitable without contract changes; the score remains optional in the envelope and does not bump the clustering contract version.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference