Immich Memories
Beta, under heavy rework, not stable. The selection engine has just been replaced by a story-driven editor, and
mainand thelatestDocker tag move with the work that follows. Expect runs that fail, photos that go missing, and options that move between releases. Try it on one small album first, not your whole library, and file what breaks.
Your self-hosted Immich library, cut into films worth keeping: a year in review, a trip with its map, one person across the years.
▶ Watch the 47-second demo · Make your first memory · Full documentation
The editor reads the period as a story, keeps the pictures that carry it, and shows the storyboard before rendering: every shot in the order it was taken, each with the line that put it there. Nothing is scored. Untick what you disagree with and cut again; immich-memories runs why says which pass dropped a missing one.
What leaves your machine
Nothing, unless you point it somewhere. No telemetry, no cloud API: the app talks to your Immich server over your LAN. Two optional model endpoints can receive pictures, both localhost by default: a caption server gets a 400 px tile of every picture in the period, once, and a reader gets 800 px tiles of a few dozen candidates plus their annotation lines, which name people and places. Trip detection geocodes GPS clusters at nominatim.openstreetmap.org, and satellite title screens fetch map tiles. Every switch is on Network & Privacy.
Three ways to run it
The editor has two independent settings: who reads the period, and how much image analysis runs first.
| Setup | What you need | What you get |
|---|---|---|
Rules only (reader: rules, tier: metadata_only) |
The app alone. A 4-core NAS is enough | All ten memory types from dates, places, favourites and people. No model, $0 in API fees. Measured on a Celeron NAS: 279 s for a month cold, 11 s warm. Simpler cuts: it can skip an occasion or spend time on a mundane object |
Rules plus classifiers (tier: no_captions) |
Same box, plus the pinned models fetched with one command: an 88 MB encoder, a 22.5 MB detector export and a document classifier snapshot | The sensitive-content and document detectors, so the family-viewing gate has evidence. First pass over a library of about ten thousand pictures on a Celeron: 3 h 41 min, then banked |
Model reader (reader: model) |
A machine that holds a vision model with a 32k context. Graded on a 30B model at 4-bit, about 17 GB resident, on an Apple Silicon Mac with 32 GB | The full editor: it reads the period as a story, looks at the pictures it needs to, and argues for each one. Add the caption server for a description under every picture. What that first pass costs depends entirely on where it runs: 0.16 s a picture on an Apple Silicon Mac with the MLX server, 30.9 s on a four-core Celeron |
Title screens are GPU-rendered on Linux x86_64, Linux aarch64, macOS arm64 and Windows AMD64 (Python 3.11 to 3.13). On an Intel Mac or Python 3.14 there is no kernel wheel and titles fall back to the PIL renderer: same text and timing, static instead of animated. immich-memories preflight tells you which one you get.
The reader and the caption server can live on another machine than the app, which needs 2 to 4 GB and renders on CPU. Measured timings, what each degraded mode loses, and what a hosted reader costs are on Running modes.
Run it
curl -O https://raw.githubusercontent.com/sam-dumont/immich-video-memory-generator/main/docker-compose.yml
export IMMICH_URL="http://your-immich-server:2283"
export IMMICH_API_KEY="your-api-key"
docker compose up -d
docker compose exec immich-memories immich-memories models fetch # skip on metadata_only
docker compose exec immich-memories immich-memories preflight # Immich, models, reader
# then open http://localhost:8080
The compose file publishes port 8080 on localhost only, and authentication is disabled by default. The UI is single-user, single-replica: run one instance. The app holds an API key to your whole library, so turn on authentication before you expose the port.
Supported Immich Versions
Immich v2 and v3, detected at runtime:
immich:
api_version: auto # auto | v2 | v3
Leave this on auto. The app detects the server major version and uses the matching API contract;
you do not choose a version for each run. The explicit v2 and v3 values are manual
troubleshooting overrides: escape hatches for proxies or unusual deployments that hide or rewrite
the version endpoint. They force that contract, so don't use them as upgrade flags.
Without Docker, on Python 3.11 or later:
uv tool install "immich-memories[editorial]"
immich-memories models fetch
immich-memories prepare --year 2024 --month 6 # prepare one month, print what each producer cost
immich-memories generate --memory-type monthly_highlights --year 2024 --month 6
immich-memories ui # the web UI on :8080
Start with one month, not a year: preparation scales with the width of the date range and is paid once, so the second cut over the same period is mostly the render. The whole stand-up, in order, is the self-hosting guide.
What it does
- Ten memory types: year in review, monthly, person, multiple people (with
AND/ORbetween names), season, on this day, album, trip with an animated map, holiday, and a day the library itself flagged. The web UI adds a custom date range. - Photos and videos in one pool, Live Photos included. Title screens, month dividers, map fly-overs.
- Music: your own file, 28 bundled tracks, or a generated track through ACE-Step or MusicGen. Ducking under the clips' own audio.
- A four-page web UI (Memory, Media pool, Generation Options, Preview & Export) behind basic auth, OIDC or a trusted-header proxy, or a headless CLI.
- Daily automation: one scheduled
auto runeither retries a pending upload or generates one eligible memory, then notifies. In Docker setIMMICH_MEMORIES_AUTOMATION__ENABLED=true. - Privacy mode blurs every frame and moves the map to a fake city, for showing the app over your own library.
How the editor decides is written up in The Curator.
About the demo
The hero above is make demo-hero, a 15-second cut of the Remotion demo (make demo-ui), which recreates the UI in React over a CC0 fixture library: 136 stock pictures that tell one household's June, a birthday, a Saturday in the woods and a week by a lake. The CLI demo inside it is a VHS recording (make demo-cli). Docs screenshots come from a hermetic run over the same fixture library (make screenshots).
Development
make dev installs everything, make ci runs what CI runs, make help lists the rest.
Guidelines in CONTRIBUTING.md. The codebase was written with AI assistance as a deliberate experiment; DISCLAIMER.md says how and where it fell short.
License
MIT, see LICENSE.
1 maintainer
Release files for immich-memories 0.98.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| immich_memories-0.98.1.tar.gz | 8.2 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| immich_memories-0.98.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 14.8 MB
Release files / immich_memories-0.98.1.tar.gz
| Download URL | immich_memories-0.98.1.tar.gz |
|---|---|
| Size | 8.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cdd86ccf60dbf7f34f572fb043641e70bd680fb567d6e442cde4dd4c7af965d2
|
|
BLAKE2b-256 checksum How to use checksums |
5403887c977a4c461efc121bc67d9c780fc57c3c883505d63ce4076c3c581e84
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency logRelease files / immich_memories-0.98.1-py3-none-any.whl
| Download URL | immich_memories-0.98.1-py3-none-any.whl |
|---|---|
| Size | 6.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d9e0ad644c45fcf21df983254f2af021d705c6993d082f39a631170f536d3b64
|
|
BLAKE2b-256 checksum How to use checksums |
0cf2429ed133374a128ea81cb116c79905213acb86e33b70d8f0d1537c4c2d51
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency log
