Skip to main content

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.

Once a day it checks what's due and makes one film at most.

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​

AttemptCounts as the day's run
made a film, or tried and failedyes
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=trueyes: 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 UIno: it's an extra film you asked for
a dry run (Check eligibility, auto run --dry-run), finished or still runningno
a cooldown active skip (what most HTTP triggers get back)no
a Run this suggestion whose candidate was gone by thenno
an attempt whose process diedno

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 install copies PATH and 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 (--force overrides);
  • --config goes before auto, 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.

DetectorProposesScore
Yearlypast years with content, after 15 January0.8, 10 % off per year of age, floor 0.24
Birthdaya person whose birthday was 2 to 60 days ago, with at least 50 pictures on 3 days in the film's windows0.75 × closeness × their pictures against the busiest person's (floor 0.5)
Monthlythe latest completed month, if not made yet0.7, and it never looks further back
Activity bursta month, once it has ended, with more than 2× the rolling 12-month average0.7 once over the threshold
Triptrips in the trailing year, 7 days after coming homeup to 0.75, by length (14 days) × pictures (200)
Person spotlightthe five most-pictured people0.6 × their share of the top person's count (floor 0.2) × closeness
Multi-personpairs who appear together on at least 10 pictures last year, the year the film reads0.55, by shared pictures up to 500, × the pair's average closeness
On this daytoday, when its month has content in 5+ prior years0.35 × prior years / 10, capped at 0.35; month counts do not prove pictures exist on this exact date
Special daya catalogued day whose anniversary is within 3 days0.8, ×1.0 for a decade, ×0.85 for a half-decade, ×0.6 otherwise
Saved grouplast year's film of each saved group, once0.65 × the group's average closeness, counted as multi-person
Seasonthe 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 film0.6
HolidayChristmas, 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 over0.6 × (0.5 + 0.5 × years the day stood out, up to 5 / 5)
Albumone 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_albums0.55
Backfilla month of this year or last with 20 pictures or more and no film, newest first. The latest completed month is the monthly detector's0.35
Person monththe last completed month of each close person, at least 15 pictures on 4 days. The two months before it are backfill0.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:

WhoWeight
inner tier, or a partner, child or parent you confirmed1.0
recurring0.6
episodic0.3
event0.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 bySkips the cooldownStarts the next one
the built-in timer, the installed job, auto run, POST /api/triggernoyes
auto run --force, POST /api/trigger?force=true, Run this suggestionyesno
generate, a web UI rendernot an automatic runno

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.

Every attempt ends one of four ways, and the lock always comes back.

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.enabledserver.trigger_tokenPOST /api/trigger
offunset404: the route is not enabled
offsettoken required
onunsetlogged-in session required (browsers only)
onsettoken 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.

StatusBodyMeans
202status: "accepted", attempt_id, status_url, forcedthe 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"