ADR 0035: Automatic Album Clustering Research Gate
Status: accepted Date: 2026-05-22
Context
Automatic album suggestions depend on finding coherent family-memory clusters from capture time and location. Poor clustering would be worse than no automation: it would create noisy suggestions, repeatedly annoy owners, or imply false trips/events.
The first implementation could use a simple deterministic heuristic, but Christian prefers to evaluate DBSCAN/HDBSCAN-like clustering before committing to the first production algorithm. This deliberately favors suggestion quality and long-term fit over the fastest implementation path.
The decision must still respect Memories' architecture:
- Core owns suggestion generation, provenance, fingerprints, acceptance/rejection, and authorization.
- The browser must not receive unrestricted media/location rows to cluster client-side.
- Clustering must be owner-scoped and location-visibility aware.
- Algorithm output must remain inspectable, deterministic enough for rejection fingerprints, and replaceable across versions.
- Original media bytes, coordinates, and accepted/manual albums are never modified silently.
Options Considered
| Option | Summary | Benefits | Costs / Risks |
|---|---|---|---|
| A. Implement deterministic heuristic first | Use simple temporal buckets plus spatial grid/geohash grouping | Fast, boring, inspectable, easy to ship | May split/merge real trips poorly; hardcoded thresholds may become throwaway work |
| B. Research DBSCAN/HDBSCAN-style clustering before implementation | Evaluate density-based algorithms and baselines against real/synthetic family-memory scenarios | Better chance of useful suggestions; avoids committing to weak algorithm too early | Slower first delivery; requires local evaluation harness and explicit criteria |
| C. Defer automatic albums entirely | Do not work on suggestions until more product demand exists | No immediate complexity | Leaves reverse lookup unused by its main motivating feature |
| D. Use external/ML event recognition | Rely on external services or broader AI models to infer events | Potentially richer event detection | Conflicts with local-first/privacy posture; hard to inspect; cloud dependency risk |
Decision
Choose Option B: research DBSCAN/HDBSCAN-style clustering before the first automatic-album implementation slice.
This ADR does not select DBSCAN, HDBSCAN, OPTICS, ST-DBSCAN, or a deterministic baseline as the production algorithm. It creates a research gate: implementation tasks for persisted album suggestions should wait until an empirical comparison identifies the first algorithm profile, thresholds, provenance shape, and failure/degradation behavior.
The research must compare at least:
- deterministic temporal bucket + geohash/grid baseline;
- two-phase temporal segmentation followed by spatial DBSCAN;
- spatio-temporal DBSCAN/ST-DBSCAN-style distance model;
- HDBSCAN or OPTICS-style variable-density candidate, if a maintainable local implementation exists.
The chosen algorithm profile must be versioned and stored with every AlbumSuggestionRun so future algorithm changes can coexist with old suggestions, rejected fingerprints, and accepted-album provenance.
Consequences
Positive
- Reduces risk of building a noisy suggestion generator that users stop trusting.
- Makes clustering quality, thresholds, and edge cases explicit before schema/API tasks assume them.
- Keeps the algorithm replaceable by requiring versioned run provenance from the start.
- Encourages real-family-library validation without weakening owner/privacy boundaries.
Negative / Costs
- Delays the first visible automatic-album feature.
- Requires a local-only evaluation harness and scenario fixtures before production implementation.
- May introduce dependency questions if HDBSCAN/OPTICS libraries are considered for Java/Core.
- Research may still conclude that a simple baseline is best for the first production slice.
Privacy / Security Impact
- Research data must remain local. Any exported comparison corpus must be anonymized and should avoid raw exact coordinates unless explicitly kept inside the local developer environment.
- Evaluation outputs should prefer media IDs, rounded/geohashed locations, cluster metrics, and human-readable local summaries over raw GPS dumps.
Revisit Triggers
Revisit this decision if:
- research shows deterministic heuristics clearly outperform density-based approaches for Christian's library;
- no maintainable local DBSCAN/HDBSCAN/OPTICS implementation fits the Core API operational model;
- clustering research blocks product progress for too long without improving expected suggestion quality;
- automatic albums shift from owner-private suggestions to collaborative/group-first generation;
- performance on large libraries makes the chosen algorithm impractical without a worker/offline batch boundary.
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