# People registry contracts

Markdown version of <https://sam-dumont.github.io/immich-memories/docs/reference/people-registry/>.

Inference, export format and identity rules. For normal scanning and editing, see [People commands](https://sam-dumont.github.io/immich-memories/docs/make/cli/people.md).

The one rule doing most of the work: volume is a burst, continuity is a relationship. 160 pictures over four
active months is four events; the same 160 over forty months is part of your life.

| tier | shape |
| - | - |
| `inner` | at least 24 active months across 3 years, present in at least 35% of the months between; or the child rule below |
| `recurring` | a dozen months or more, failing one of the `inner` conditions |
| `episodic` | everything that is not one of the other three |
| `event` | four active months or fewer, averaging at least 20 pictures per active month: a burst |

The burst rule runs first. Otherwise, a person with a known birth date, whose first photographed
month is no later than a year after birth, counts as `inner` when present in at least half the
months between their first and last appearance. This lets a child born into the library qualify
without waiting three years. These are suggestions; confirmed relationships remain yours.

The scan also flags tight pairs (two people who are each a quarter or more of each other's pictures), possible twins
(same family name and birth date, marked `counts_reliable: false` because face recognition merges them) and one
name on two person records. These come from metadata, so different surnames or missing dates can hide a
pair. You are behind the camera, so pairs with you are read from month curves, not shared frames. The owner comes from `--owner` or `IMMICH_MEMORIES_OWNER` (`identified: told`), else your Immich account
name (`account`), else the longest-running person (`inferred`: check it). Those are guesses, and every scan
rewrites them. What you say with `people owner` (or **Account owner** on the People page) is stored per account
under `owners:` as `identified: confirmed`, or `person_id: null` for "nobody in this library", and no scan touches
it. The order is confirmed, then told, then the account name, then inferred.

A pair the scan notices (`tight-dyad`, `twin`, `duplicate`) is a question, not a relationship. You answer it by
naming what the two are, which writes the relationship on both sides with the reverse kind, and the detected link
isn't shown again for that pair. A link confirmed without a name stays "linked, relationship not named" and never
counts as a relationship in titles or prompts.

The People page also suggests the relationships your confirmed ones imply: siblings who share a parent,
grandparents, aunts and uncles, cousins and in-laws, each with the chain it follows ("parent of Bob, who is a
parent of Riley"). Suggestions build on each other and refresh as soon as you add or remove a relationship, with
no scan. Nothing is written until you accept one; "No, they are not" declines it for good. A model's film prompt
reads the same chains, labelled as derived, and never a declined one.

**Diagram: A rescan redraws the guesses. Your answers stay.** [(image)](https://sam-dumont.github.io/immich-memories/diagrams/people-rescan.svg)

```text
┌─────────────────────────┐
│                         │
│         A rescan        │
│    reads Immich again   │
└────────────┬────────────┘
             │
             │
             │
             │
             ▼
┌─────────────────────────┐
│         Typed by        │
│           you?          │
│ role, notes, birth date │
└─────────────────────────┘
             │
             │
             ├────────────────────────┐
             │                        │
             ▼                        ▼
┌─────────────────────────┐  ┌─────────────────┐
│                         │  │     An owner    │
│           kept          │  │   you picked?   │
│    never overwritten    │  │   per account   │
└─────────────────────────┘  └─────────────────┘
                                      │
                                      │
             ┌────────────────────────┤
             │                        │
             ▼                        ▼
┌─────────────────────────┐  ┌─────────────────┐
│                         │  │     Someone     │
│           kept          │  │    you added?   │
│   a scan only guesses   │  │  not in Immich  │
└─────────────────────────┘  └─────────────────┘
                                      │
                                      │
             ┌────────────────────────┤
             │                        │
             ▼                        ▼
┌─────────────────────────┐  ┌─────────────────┐
│                         │  │                 │
│           kept          │  │    In a saved   │
│  stays in the registry  │  │      group?     │
└─────────────────────────┘  └─────────────────┘
                                      │
                                      │
             ┌────────────────────────┤
             │                        │
             ▼                        ▼
┌─────────────────────────┐  ┌─────────────────┐
│           kept          │  │                 │
│the group and its people,│  │    A link you   │
│   even under the floor  │  │      named?     │
└─────────────────────────┘  └─────────────────┘
                                      │
                                      │
             ┌────────────────────────┤
             │                        │
             ▼                        ▼
┌─────────────────────────┐  ┌─────────────────┐
│           kept          │  │                 │
│    one row per pair,    │  │    A link you   │
│        both sides       │  │    rejected?    │
└─────────────────────────┘  └─────────────────┘
                                      │
                                      │
             ┌────────────────────────┤
             │                        │
             ▼                        ▼
┌─────────────────────────┐  ┌─────────────────┐
│           kept          │  │     Redrawn     │
│     stays rejected,     │  │tiers, counts and│
│       no new flag       │  │   new guesses   │
└─────────────────────────┘  └─────────────────┘
```

Arrows:

- A rescan → Typed by you?
- Typed by you? → kept
- Typed by you? → An owner you picked?
- An owner you picked? → kept
- An owner you picked? → Someone you added?
- Someone you added? → kept
- Someone you added? → In a saved group?
- In a saved group? → kept
- In a saved group? → A link you named?
- A link you named? → kept
- A link you named? → A link you rejected?
- A link you rejected? → kept
- A link you rejected? → Redrawn

The registry lives in the [store](https://sam-dumont.github.io/immich-memories/docs/run/database.md), next to every other decision you made. Everything under
`inferred:` is recomputed on each scan; everything under `confirmed:` is yours and never overwritten, and wins
where the two disagree. `people export` writes it out in the shape below (to standard output, or to `--to FILE`
readable only by you):

```yaml
people:
  - ids: [5f2c…]
    name: Alex Example
    birth_date: '1988-04-02'
    inferred:
      tier: inner
      evidence: {count: 4210, active_months: 180, span_years: 17.2, onset: '2009-06', continuity: 0.87}
    confirmed:
      role: null
      links: []
```

`people import --from FILE` replaces the registry with an edited export. It checks the whole file first: a
person without valid `ids` (a primary list or per-account lists), or an id listed twice, is refused with its
position, and nothing changes. Ids
come back exactly as written, `manual:` ids included. A registry that already holds people is only overwritten
with `--replace`, so an import cannot silently replace confirmed answers. A scan never reads the file; only an
import does.

A second Immich account on the same server gives the same person a different id. You say which ids are the same
person, and `ids:` becomes one list per account, `primary` first:

```yaml
people:
  - ids:
      primary: [5f2c…]
      partner: [a91e…, 07bd…]
    name: Alex Example
```

A flat `ids: [...]` list means your main account only, which is what a one-account export writes. Account names follow the rule for `immich.accounts` (lowercase letters and digits joined by single
underscores), and the account doesn't have to be configured yet. An empty list, a name that breaks the rule, or an
id listed under two accounts or two people is refused, and nothing changes. A top-level `accounts:` map is refused
too, and the message shows the per-account shape.

The first id listed is the person's own id: the one links and saved references point at. Adding ids never
changes it. When the person's own id isn't first (someone who came in through the partner account and later got
a `primary` id), the export names it with a `person_id:` line next to `ids:`, and an import keeps it.

To add one id without editing the file:

```bash
immich-memories people bind "Alex Example" --account partner --id a91e…
```

The person is a store id or a name exactly one person carries; if two people share the name, the command lists
their ids and asks for one. `bind` only adds the id: the name, birth date and your answers stay put. An id somebody
else holds is refused, never merged, and binding the same id twice changes nothing. Two live ids are never matched
by name. A retired one is followed: when Immich no longer has any of a person's ids (two records merged, re-clustered
or deleted), or keeps an id with no pictures next to a same-name person that has some, the app links them to the one
Immich person that carries their name and no one else here holds, or folds in the second record a scan already wrote
for them. It does this whenever it reads Immich's people: opening the People page, starting a film, the nightly run
or `people scan`. They keep their id and every answer; the old id is listed under `retired` and never asked for
again. With no single match, the People page flags them, and a film naming them stops with the same advice instead of
coming back empty.
`declined_links:` holds the "not the same person" answers from the People page, so a suggestion you refused stays
refused. Taking an id back off a person is **Unlink** on that page.
A film reads the second account with `generate --accounts primary,partner`
([generate](https://sam-dumont.github.io/immich-memories/docs/make/cli/generate.md)), and a bound person counts as one person across both.

### Saved groups

A group is a label for a people condition, so `generate --group kids` reads the same as typing the expression
out. It saves nothing about the people themselves, just the condition:

```bash
immich-memories people group add kids '"5f2c…" OR "a91e…"'
immich-memories people group list
immich-memories people group rm kids
```

`add` takes the same grammar as `--people-expression`, but the leaves are ids (what `people show` lists), not
names: `people group list` prints them, `people group add` refuses a label already in use, and `people group rm`
never touches the people the group named. `generate --group kids` resolves the saved expression through the
people store exactly as `--people-expression` does, and it combines with `--accounts` the same way. Groups round-trip
with `people export`/`people import`, next to the people.

The scan also writes its measurements (every person's counts and the pairs seen together) to
`people-graph.json`, next to the store this run is using (`~/.immich-memories` by default, or
wherever `--config` or `database.url` point instead). That one stays a file: each scan
recomputes all of it from Immich and nothing reads it back.

It is the same registry as the **People** page in the web UI. The roles you confirm there decide who counts as close
family, and selection reads that on every tier: the family seat, the big-story rule, and the relations a model
sees. Setting it up is on [Home and people](https://sam-dumont.github.io/immich-memories/docs/get-started/who-is-who.md); how selection uses it is on
[Family, audience and duplicates](https://sam-dumont.github.io/immich-memories/docs/how-it-chooses/family-audience-duplicates.md).
