Table of contents
ADR 0093: Generic Class Instance Occurrence Embeddings
Status: proposed Date: 2026-07-09
Context
People face recognition uses a face_embeddings table coupled to face_annotations. To support merge suggestions for all discovery domains (plants, future domains) we need a domain-agnostic embedding storage. The embedding storage must support variable dimensions (face embeddings differ from plant embeddings), per-domain model versioning, and efficient similarity search within a domain+class+owner scope.
Decision
Create a single generic table class_occurrence_embeddings that stores embeddings as JSONB float arrays. Domain+class+owner keying replaces the old face-specific FK. Each row links to a class_instance_occurrence, not directly to a class_instance, allowing multiple embeddings per occurrence (e.g., different models). Embedding dimensions are stored explicitly alongside model_name and model_version. The table uses a GIN index on the JSONB embedding column for potential pgvector migration later, and a B-tree index on (domain_key, class_key, owner_id) for efficient scoped queries. This replaces the face-only face_embeddings table path. Existing face_embeddings rows are NOT migrated — the table is dropped in Spec 034.
Consequences
['JSONB embedding storage is less efficient than dedicated vector columns — acceptable at current scale (<10K embeddings per domain per owner). Can migrate to pgvector extension if performance becomes an issue.', 'Generic table enables merge suggestions for any domain: plants, animals, objects — any domain with an embedding model can participate.', 'face_embeddings table remains live until Spec 034 drops it, but no new code writes to it.', 'Embedding model registry (model_name + model_version) enables per-domain model evolution without schema changes.', 'JSONB array allows variable-dimension embeddings across domains (e.g., 128-dim faces, 512-dim plants).']
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