Automation decisions and trigger API
immich-memories auto run is the single daily entry point. It looks at your library, decides which one memory
is worth making today (a trip that ended last week, a birthday two days ago, last month's highlights, a year
nobody cut yet), makes it, and exits. Schedule it once a day and the films arrive on their own.
immich-memories auto suggest # what would it make today, and why
immich-memories auto run --dry-run # the decision, without the render
immich-memories auto run # decide and do it
It works on a plain NAS, and makes the same cuts you would get by hand there; a GPU or a model makes them better.
Docker: switch on the built-in timer
In Docker the container's only process is the web UI, so the timer lives there. One setting:
advanced:
automation:
enabled: true # default false
daily_at: "09:00" # the container's local time (set TZ=)
Or put IMMICH_MEMORIES_AUTOMATION__ENABLED: "true" and IMMICH_MEMORIES_AUTOMATION__DAILY_AT: "09:00"
in the app's Compose environment: block. A line in .env alone does not reach the container. Recreate
with docker compose up -d. While those Compose lines are absent, Settings > Automation shows
enabled and daily_at too.
upload.enabled: true delivers manual and automatic films to Immich, into upload.album_name. The film
gets the same description and tags a manual upload gets, a retry included
(What Immich sees). Confirmed delivery removes the local copy.
The UI process then runs the same auto run decision once a day, with the same lock, history, upload
retry and notifications as the CLI. A container that was down at daily_at catches up when it starts.
If the day's run already happened, it waits for tomorrow.
What counts as the day's run
| Attempt | Counts as the day's run |
|---|---|
| made a film, or tried and failed | yes |
decided nothing is worth a film (skipped, reason no eligible candidates or nothing worth a film: …) | yes |
an unforced auto run from the shell, the installed job or an HTTP trigger without ?force=true | yes: they can't be told apart from the timer |
a forced one: auto run --force, POST /api/trigger?force=true, Run this suggestion in the web UI | no: it's an extra film you asked for |
a dry run (Check eligibility, auto run --dry-run), finished or still running | no |
a cooldown active skip (what most HTTP triggers get back) | no |
| a Run this suggestion whose candidate was gone by then | no |
| an attempt whose process died | no |
When the timer waits, the log says which run it counted. A period the child read and judged empty ends
as one skipped attempt with no completed run behind it: the 24 h cooldown is untouched, and that
candidate sits out for 7 days.
A manual auto run in progress holds the automation lock: the timer's attempt comes back skipped
("automation already running") before it records anything, so auto history and auto status never show
it, and the timer tries again at its next poll (every 30 seconds). When the timer's own run is skipped for
the cooldown (it caught up at 14:00 yesterday, say), it tries again once the cooldown ends, the same day.
A manual generate in progress holds a different lock, the pipeline lock. The timer's attempt does start,
its child generate can't get the pipeline lock, and the attempt ends failed, not skipped.
An attempt whose process died mid-run (a killed container, a reboot) reads failed, reason
interrupted: …, everywhere status is shown. The next run, the web server's timer or
immich-memories auto status ends it for good, with one failure notification. A status read such as
/health/ready only reports it and changes nothing.
/health/ready shows the timer under in_process_scheduler. After a restart it starts from the last
attempt in the store, so last_fired_at, last_outcome and last_reason are filled in.
Bare metal: auto install
immich-memories auto install --hour 9
This writes a launcher at ~/.immich-memories/bin/immich-memories-auto and the scheduler files: a launchd
plist on macOS, a systemd user timer on Linux, or a crontab line to paste elsewhere. It prints
Activate: and Deactivate: commands and runs neither: run the activation command to start the
schedule. The launcher looks immich-memories up on every fire, so an upgrade in place needs no
reinstall.
The installed job reads automation.cooldown_hours on every run; --cooldown N pins a number into the
scheduler command instead. An older install: Upgrading.
There is one managed launcher per operating-system user, and one launchd job or systemd timer.
Installing with another --config replaces that user's existing schedule; it does not add a
second one. Use separate operating-system users or containers for independent schedules.
The launcher stays under ~/.immich-memories/bin even with an explicit config.
On headless Linux, enable lingering so the user timer survives logout:
loginctl enable-linger "$USER"
Uninstall deletes the launcher and scheduler files without unloading a running schedule, so run the
printed deactivation command first: launchctl unload on macOS, systemctl --user disable --now immich-memories-auto.timer on Linux. Then immich-memories auto install --uninstall, and on Linux
systemctl --user daemon-reload. For cron, remove the pasted line before deleting its launcher.
Three things a scheduled job does differently from your shell:
- it does not inherit your environment.
auto installcopiesPATHand the ACE-Step and torch variables it knows, nothing else, so credentials belong in the config file; - it refuses a git worktree or a checkout behind its upstream, because a nightly job on stale code looks fine
in the logs (
--forceoverrides); --configgoes beforeauto, and the installed job keeps the resolved path.
On macOS a missed job runs when the Mac wakes; launchd does not wake it.
The launchd job writes its wrapper output to auto.log and auto-error.log in ~/.immich-memories/logs/
(next to the config file when you installed with --config). The systemd unit sets no StandardOutput,
so its output goes to the user journal, which a user outside systemd-journal may not be allowed to read.
The per-attempt transcript under the cache is always readable by its owner: see where a scheduled run's logs go.
How it picks one memory
Fifteen detectors propose candidates, hard rotation rules reject some, the rest are scored, and the top one is made. The score ranks memories against each other and never touches which pictures go in a film. That is the editor's job: see How it chooses.
| Detector | Proposes | Score |
|---|---|---|
| Yearly | past years with content, after 15 January | 0.8, 10 % off per year of age, floor 0.24 |
| Birthday | a person whose birthday was 2 to 60 days ago, with at least 50 pictures on 3 days in the film's windows | 0.75 × closeness × their pictures against the busiest person's (floor 0.5) |
| Monthly | the latest completed month, if not made yet | 0.7, and it never looks further back |
| Activity burst | a month, once it has ended, with more than 2× the rolling 12-month average | 0.7 once over the threshold |
| Trip | trips in the trailing year, 7 days after coming home | up to 0.75, by length (14 days) × pictures (200) |
| Person spotlight | the five most-pictured people | 0.6 × their share of the top person's count (floor 0.2) × closeness |
| Multi-person | pairs who appear together on at least 10 pictures last year, the year the film reads | 0.55, by shared pictures up to 500, × the pair's average closeness |
| On this day | today, when its month has content in 5+ prior years | 0.35 × prior years / 10, capped at 0.35; month counts do not prove pictures exist on this exact date |
| Special day | a catalogued day whose anniversary is within 3 days | 0.8, ×1.0 for a decade, ×0.85 for a half-decade, ×0.6 otherwise |
| Saved group | last year's film of each saved group, once | 0.65 × the group's average closeness, counted as multi-person |
| Season | the season that just ended, from 3 to 30 days after its end, once per season-year. At least 40 pictures on 6 days. Needs the home base: without one there is no hemisphere and no season film | 0.6 |
| Holiday | Christmas, New Year's Day, Easter, a holiday of the home base's country, or one you list in extra_holidays, from 3 days after it, up to a year back, and only when your pictures show you kept it: in at least 3 years, the day holds 10 pictures or more and at least twice the median of the 4 days around it. The date alone never qualifies. The film reads every year back to 30. Once per holiday-year, however many years a film of it was made over | 0.6 × (0.5 + 0.5 × years the day stood out, up to 5 / 5) |
| Album | one of your albums never filmed (20 pictures or more), or one that grew by 30 pictures and to 1.5× the size it had at its last film. Albums spanning more than six months (a phone's Recents, Favorites, Live Photos) are left out. Shared albums only with include_shared_albums | 0.55 |
| Backfill | a month of this year or last with 20 pictures or more and no film, newest first. The latest completed month is the monthly detector's | 0.35 |
| Person month | the last completed month of each close person, at least 15 pictures on 4 days. The two months before it are backfill | 0.6, and 0.35 for the two earlier months |
Then, in order: a 1.2× boost for a memory that does not exist yet, recency (linear decay over 365 days from when the memory is timely, floor 0.5), content richness (up to 30 % of the score, log scale), and a same-type cooldown (0.3× for 7 days, 0.7× for 30 days). Per-type caps: 3 per type, 1 for on-this-day, special day, season, holiday, album, backfill and person month, 2 for multi-person. Backfill and person months render as a monthly film, but each has a category, a cap and a cooldown of its own, so they never use up the monthly's.
The rotation rules are hard. If every candidate is rejected the run is skipped; nothing relaxes a rule to get another video out:
- a monthly review cannot run twice in the same calendar month (backfill and person months are not monthly reviews, so a month film of either does not count); the monthly detector proposes only the latest completed month, while activity bursts can propose months from the trailing year;
- the previous category cannot repeat, except backfill, which fills quiet nights and may follow itself (anything fresher still outscores it);
- a category cannot appear more than twice in the last six completed automatic runs, except backfill, which runs every quiet night;
- a person cannot come back if they were in either of the last two person runs.
Birthdays fire 2 days after the date and trips 7 days after coming home, so the phone has uploaded.
Trips need trips.homebase_latitude and trips.homebase_longitude (see
Home and people). Special days come from the catalogue discover-days
writes. A birth date you gave the people store wins over the one Immich holds. Automation passes that resolved month and day explicitly to generate --birthday, including a leap-day birthday.
auto suggest prints eligible candidates in rank order with their reasons, then why a detector proposed
nothing where it could have: no home base for a season, a birthday under 50 pictures, a close person with
too little last month, albums left out for spanning more than six months. It also names failure-backoff
skips. It does not list candidates the rotation rules rejected: auto status shows those.
A candidate that failed twice in a row waits before it comes back: 24 hours, then 3 days after a third failure, then 7 days. One failure never counts, and a success clears the streak.
Closeness
A birthday film of a child is worth more than one of someone you met twice, however many pictures each has. Birthdays, spotlights, pairs and saved groups are scored by how close the people list says each person is:
| Who | Weight |
|---|---|
| inner tier, or a partner, child or parent you confirmed | 1.0 |
| recurring | 0.6 |
| episodic | 0.3 |
| event | 0.15 |
A pair or a group takes the average of its people. Someone the list says nothing about keeps the full weight, so a library that never ran the people scan scores everyone at 1.0. The same list decides who gets a monthly film: inner tier or a confirmed partner, child or parent.
Hand-made films count. A season, holiday, month or per-person month you made yourself with generate is the
same memory as the one auto would propose, so it is not proposed again. An album film made by hand is matched
by the album's dates, and an automatic one carries the album's picture count, so the album comes back only after it
grows again.
advanced:
automation:
detect_seasons: true # all five on by default
detect_holidays: true
detect_albums: true
detect_person_monthly: true
backfill_months: true
extra_holidays: # your own days, "MM-DD: name"
- "12-06: Saint Nicholas"
include_shared_albums: false # albums other people shared with you
The thresholds above are fixed. Holidays come from the country the home base is in, as Immich's own
geodata names it. With no known country, the detector proposes Christmas, New Year's Day, Easter and
your extra_holidays.
Across accounts, and saved groups
With a second Immich account connected, name the accounts automation reads:
advanced:
automation:
accounts: ["primary", "partner"] # empty reads the primary alone
detect_groups: true # the default
The list is exactly what is read: ["partner"] alone leaves the primary library out, and trips with it. Every
candidate but a trip or an album carries that scope to its generate --accounts run; trips always come from
the primary account, and an album film reads that one album.
detect_groups proposes one multi_person film of last year for each saved group (people group add). A
group's film is not proposed again once made, and a group none of whose people is among the most-pictured
people discovery counts is skipped. It shares the multi-person cap and rotation rules. The whole walkthrough:
A second Immich account.
What auto run does, exactly
One action per run, one memory per invocation: retry the oldest pending upload if there is one, otherwise make the top candidate.
The cooldown (--cooldown, default advanced.automation.cooldown_hours, 24) runs from the start of the last
completed automatic film that wasn't forced, with 30 minutes of slack so a daily timer fires every day.
auto status, the built-in timer and the HTTP trigger read the same cooldown.
| Started by | Skips the cooldown | Starts the next one |
|---|---|---|
the built-in timer, the installed job, auto run, POST /api/trigger | no | yes |
auto run --force, POST /api/trigger?force=true, Run this suggestion | yes | no |
generate, a web UI render | not an automatic run | no |
A forced film still counts for the rotation rules; it just never pushes back the next scheduled film.
--candidate KEY runs one exact memory_key from auto suggest --json. The rotation rules still apply,
--force skips only the cooldown, and a key that isn't eligible any more fails rather than making something
else.
The outcomes are skipped, dry_run, completed and failed. The first three exit 0, failed exits 1.
Quiet output is a stable JSON object with runtime as its first key: auto run --quiet turns
logging off and prints it as one line. Key a wrapper on outcome; action is generation or
delivery_retry.
An attempt killed mid-run reads failed, reason interrupted: …, as described
above.
{"runtime": {"version": "<running version>", "checkout": null, "commit": null, "upstream": null, "commits_behind": null, "stale": false}, "outcome": "dry_run", "action": "generation", "reason": "dry run", "candidate_key": "trip:2026-07-02:2026-07-09:", "category": "trip", "run_id": null, "error": null, "output_path": null, "recent_categories": ["monthly_review", "birthday"], "rejections": []}
An upload that keeps failing is dropped after automation.max_delivery_attempts (5) tries, with a
notification carrying the error; the video stays on disk.
When the output or cache volume runs low (output.min_free_space_gb, 5 GB by default), a completed run's
notification carries the warning, and a film that would not fit fails the attempt with the same message
before anything renders. On a headless cron deployment, that notification is the only place you see it.
Every attempt writes its full output to automation-output/<attempt-id>.private.log under the cache:
owner-readable, credentials redacted, downloadable from the Runs page.
auto status shows the running code's version and commit, the scheduler in use, the last attempt, the
cooldown, notification health and pending deliveries. It refreshes discovery and puts the outcome and
error under suggestion without naming the next candidate: auto suggest does that.
Check on it
immich-memories auto status # timer state, last attempt, cooldown and delivery health
immich-memories auto status --json # the same, for a script or jq
immich-memories auto history --limit 5 # the last five films it made on its own
The Scheduler: line lists everything that wakes automation: built-in timer (enabled, daily at 07:45 CEST, next firing 2026-10-08 07:45), an installed launchd, systemd or cron unit, and
external trigger (POST /api/trigger), last trigger 2026-10-07 07:45 once a trigger token is set or the
trigger API has been called. With none of them it starts with none. --json carries the same under
scheduler.in_use and scheduler.summary. The last trigger time is kept per host, beside the
automation lock.
While a run works, its log carries a Phase … line for each step, and at least one every 30 seconds or so.
Counted steps (preparation, the family-viewing check, the render) show n/N; a step that has gone quiet
repeats itself with process alive; no new progress (Nm in this step).
auto history lists only completed automatic runs; a film you made with generate or the web UI is in
runs list (runs). In Docker, prefix each with docker compose exec immich-memories.
Get told when it runs
Notifications go through Apprise, so one URL per target covers ntfy,
Discord, Telegram, email and more than a hundred others. They are off by default. Use ntfys for HTTPS,
and a private, authenticated topic: anyone can read a public ntfy topic.
advanced:
notifications:
enabled: true
urls:
- "ntfys://ntfy.sh/my-topic"
on_success: true
on_failure: true
immich-memories auto test-notification
auto test-notification sends one message to every URL and says whether it went through. It ignores the
pause that follows a failed delivery (notifications.cooldown_hours, 24), and a test that succeeds ends it.
Every rendered film sends a completion message: auto run, the Docker timer, plain generate, the web
UI's Render and runs render. Saving a cut without rendering sends none. The message carries the
memory type, the outcome, the duration, the output path and, once the film is uploaded, a direct Immich
link. A failure adds the last 300 characters of the redacted output, which is the error itself. No picture
unless you set attach_thumbnail: true. The URLs hold credentials, so config show masks them and the
database stores them encrypted.
Every key is in the config reference.
Trigger it over HTTP
One POST starts the decision auto run would have made, with the same detectors, rules, cooldown and
history. You choose when, the app chooses what: an Immich workflow when an album fills up, a cron on
another box, a phone shortcut, Home Assistant.
This process holds your Immich API key, so the app serves the route only when something can authenticate the caller.
auth.enabled | server.trigger_token | POST /api/trigger |
|---|---|---|
| off | unset | 404: the route is not enabled |
| off | set | token required |
| on | unset | logged-in session required (browsers only) |
| on | set | token or session |
export IMMICH_MEMORIES_SERVER__TRIGGER_TOKEN="$(openssl rand -hex 32)"
curl -X POST https://memories.example.com/api/trigger \
-H "x-api-key: $IMMICH_MEMORIES_SERVER__TRIGGER_TOKEN"
The token goes in x-api-key or in Authorization: Bearer <token>. For Docker, put
IMMICH_MEMORIES_SERVER__TRIGGER_TOKEN=your-generated-token in .env and run docker compose up -d: the
shipped Compose file forwards it.
Keep the token in the environment. server doesn't expand ${VAR}, so "${SOMETHING}" in config.yaml
is those literal characters. The token needs 32 random characters or more and no placeholder words like
change-me; a weaker one stops the app at startup. It is compared in constant time and redacted from
logs, /health and the config viewer. Send it only over HTTPS, behind the same reverse proxy as the web UI.
A caller that sends no Origin header (curl, a CronJob, Home Assistant) needs no change. One that sends an
Origin naming another site gets 403. With auth off, the app answers only a local host or one in
server.allowed_hosts; the shipped Kubernetes CronJobs send Host: localhost for that reason. See
Allowed hosts.
| Status | Body | Means |
|---|---|---|
| 202 | status: "accepted", attempt_id, status_url, forced | the run has started |
| 401 | {"detail": "invalid trigger token"} | authentication failed |
| 404 | {"detail": "trigger API is not enabled"} | neither auth nor a token is set |
| 409 | {"detail": "a run is already active", "attempt_id": …} | a run is already going |
GET the status_url (/api/trigger/<attempt_id>, same authentication) for attempt_id, state,
reason, started_at, finished_at, phase, memory_type, error and run. state is running
until it ends completed, failed, skipped or dry_run. run is null until the attempt has a run,
then holds run_id, status, created_at, completed_at, last_phase, output_duration_seconds,
delivery_status and immich_asset_id. An unknown id gets 404.
Add ?force=true for a film you're asking for by hand:
curl -X POST "https://memories.example.com/api/trigger?force=true" \
-H "x-api-key: $IMMICH_MEMORIES_SERVER__TRIGGER_TOKEN"
That call is auto run --force over HTTP: it skips the cooldown, and the film it makes doesn't start
one, so the next scheduled film still comes on time. The rotation rules still apply, and a run already
going still gets 409. Only true, 1 or yes count (any case); anything else, a typo included, is a
normal call, and forced in the 202 body says which one it got. Anyone holding the token can force a
film this way. Leave the parameter off a schedule: a scheduled call that forced would make a film every
time it fired.
skipped is a normal answer: a workflow that fires on every upload mostly gets it back. One that fires on
a trip album asks for the best candidate right now, not for that album. For a specific film, use the CLI
or the web UI.
Kubernetes
deploy/kubernetes/base/cronjobs.yaml holds two CronJobs that call POST /api/trigger on the running
Deployment: immich-memories-auto daily at 09:00 and immich-memories-monthly at 02:00 on the 1st. They
read only the trigger token from immich-memories-secrets and mount no application PVCs. Both make the
normal auto run decision: the monthly one does not force a monthly film.
Set the trigger token and add - cronjobs.yaml to base/kustomization.yaml (the setup builder does both
when you tick Scheduled films (CronJobs)), then render and apply:
kubectl kustomize deploy/kubernetes/base
kubectl apply -k deploy/kubernetes/base
A Complete Job only means the trigger was accepted (202); the running app makes the film. Follow it
with GET /api/trigger/<attempt_id> and the token, as shown under
Batch jobs. concurrencyPolicy: Forbid does not
stop overlapping runs; the run lease does, by answering a second trigger with 409. The base
NetworkPolicy lets the CronJobs reach the app pod on 8080, the Service's port 80 after translation.
base/job.yaml is different: it runs a one-off generate and mounts the app's PVCs, so include it only
with the Deployment scaled to zero. For a fixed recipe while the app runs, use
kubectl exec ... -- immich-memories generate ..., so there is never a second writer on the store.
A named memory on a named date
auto can't say "a year in review every 15 January". A cron line that runs generate can. Replace
/absolute/path/to/immich-memories with the installed executable, and set cron’s PATH so it finds
FFmpeg:
# 15 January, 09:00: last year's review, uploaded to an album
0 9 15 1 * /absolute/path/to/immich-memories generate --memory-type year_in_review --year $(( $(date +\%Y) - 1 )) --upload-to-immich --album "Memories"