Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt

Use this file to discover all available pages before exploring further.

When you browse People in an Immich app connected to Gumnut, the faces and identities you see come from Gumnut’s face pipeline — a substantially more sophisticated system than the per-face matching the official Immich server uses. This page explains what each system does and why Gumnut’s approach produces a cleaner, more accurate People view without any configuration on your part.

​
How Immich Recognizes People

The official Immich server uses a straightforward approach. When it detects a new face, it generates an embedding and looks for the closest existing person within a configured distance. If a close-enough match exists, the face joins that person. If not, and there are enough nearby unassigned faces, a new person is created. Each face is assigned once based on its single nearest neighbor, and the result stands until you intervene manually. This is fast and predictable, but it has well-known limitations:
  • Every detected face becomes a candidate, including tiny faces from crowds, background figures, and far-away strangers.
  • Faces of close relatives — siblings, twins, parents and children — often collapse into one person because nearest-neighbor matching can’t reliably tell them apart.
  • Once a face is assigned, the decision is sticky. Even when later photos provide evidence that the original assignment was wrong, Immich won’t revisit it.
  • Accuracy depends on server-admin tuning of thresholds (minimum score, maximum distance, minimum face count) that an end user has to discover and adjust.

​
How Gumnut Recognizes People

Gumnut takes a layered approach designed to produce a clean People view without any user configuration. Each stage adds protection that simple per-face matching lacks.

​
Crowd-face filtering

Before any recognition runs, Gumnut filters out detections that aren’t actually subjects of the photo — tiny or blurry faces from crowds, distant figures, and background extras. The People view stays focused on the people you actually photographed, not every face that happened to be in frame.

​
Sibling-aware per-asset assignment

When Gumnut considers attaching a new face to a named Person, it doesn’t just check the single closest match. Multiple confidence checks must pass together: the face has to be a close match to that Person’s average appearance, the Person’s existing faces have to be internally consistent (so the Person isn’t already a polluted mix), and the closest match has to be clearly distinct from the next-closest match. If two named Persons are similar enough that Gumnut can’t safely tell them apart — siblings, twins, or just look-alikes — Gumnut refuses to guess and leaves the face unassigned rather than poisoning either Person.

​
Library-wide re-clustering

Gumnut doesn’t make permanent decisions from a single face in isolation. Periodically, it re-runs clustering across every face in your library that isn’t already part of a named Person, using a group-based algorithm rather than per-face matching. This lets earlier guesses be revisited as more evidence accumulates: faces that were unassigned can come together into a new Person; loose groups can split apart; over-eager early matches can be reorganized. Faces in Persons you’ve named are excluded from this process — your labels are never re-evaluated.

​
Auto-merge into named Persons

When library-wide clustering surfaces a group of unnamed faces that strongly matches someone you’ve already named, Gumnut can fold the group into that named Person automatically — but only when a strict set of conditions all hold: the average match is well below the assignment threshold, both the incoming group and the existing named Person are internally consistent, the closest named Person is clearly distinct from the next-closest, and the incoming group isn’t disproportionately large relative to the existing Person. If any condition fails, the unnamed cluster stays separate and waits for you to decide.

​
Named Persons are protected

Once you’ve named a Person, that’s a strong signal to Gumnut. Automated paths can add new faces to the Person when all the confidence checks pass, but they will never move a face out of a named Person, never delete a named Person, and never merge two named Persons together. Decisions to combine named Persons are always left to you.

​
What to Expect

If you’re coming from Immich, here’s what changes in practice:
  • A cleaner People view. Crowd-face filtering and conservative matching mean far fewer junk People built from a single distant face or background extra.
  • Better handling of siblings and look-alikes. Where Immich tends to collapse similar-looking people into one, Gumnut leaves ambiguous faces unassigned until clustering gathers enough evidence to separate them into distinct Persons.
  • Improvement over time. New unnamed People may appear, merge, or refine as your library grows. This isn’t drift — it’s Gumnut re-evaluating earlier guesses with more data. Named Persons are unaffected.
  • Your edits stick. Once you name a Person, automated recognition won’t undo your work. Renaming, merging, hiding, favoriting, picking thumbnails, and reassigning individual faces in the Immich app all work normally and are respected by the pipeline.
  • No configuration to learn. Gumnut manages models, thresholds, and clustering cadence centrally, so improvements roll out automatically. If something looks wrong, contact Gumnut support instead of hunting through admin settings.