# Entities

**Last Updated:** 2026-02-19
**Confidence:** High

## Summary

Entities are the nodes of the system. Three types: Items (content), Users, and Creators. Every entity has metadata, a vector embedding slot, and an attached signal ledger.

**Key Facts:**
- Items have metadata, embeddings, and signals — signals are typed timestamped streams, not fields
- Users have preferences, histories, and relationships — living profiles that update continuously
- A user's taste is **two-tier**: cold-start users (`< 5` interactions) carry a single adaptive-LR **preference vector** (K=1); warm users carry **multiple preference clusters** (one centroid per coherent interest)
- Creators are linked to Items and have their own embeddings (aggregated from catalog)
- Relationships are first-class edges between entities (weighted, directional, traversable)

**File Pointer:** `VISION.md:36-43`

## How It Works

Items enter via the WRITE path with metadata + embedding. A signal ledger is initialized at zero. Cold start exploration budget is applied automatically. Items are immediately queryable after commit.

Users accumulate implicit taste from engagement history, updated on every positive-engagement signal write (like, completion, etc.). The model has two tiers, gated on the user's total positive interaction count (`COLD_START_N = 5`):

- **Cold start (`< 5` interactions):** a single **preference vector** (`entities/preference.rs`) blended via an adaptive learning rate (`alpha = base / (1 + ln(1 + count))`) and L2-normalized — the K=1 case.
- **Warm (≥ 5 interactions):** multiple **preference clusters** (`entities/multi_preference.rs`). Each positive engagement is assigned to its nearest centroid by cosine; a DP-means threshold (τ, default `0.55`) opens a new cluster when nothing is similar enough, capped at `K_MAX = 10` (over the cap, the engagement is assigned to the nearest centroid, never evicted). Each cluster carries its own adaptive LR and a forward-decayed importance (default half-life 30 days). On crossing the threshold the single vector seeds cluster 0, so the cold taste is never discarded.

This keeps a user who engages with hiking, cooking, and cars from collapsing into one averaged centroid that represents none of them.

Creators are entities with their own embeddings derived from their item catalog. Creator-level signals include engagement rate, posting frequency, and follower count.

## Related Topics
- [Signals](./signals.md)
- [Ranking Profiles](./ranking-profiles.md)