Immich Memories
Cuts your Immich library into edited memory videos: title screens, music, and only the good five seconds of each clip.
It connects to your self-hosted Immich server, scores every video and photo, and assembles the keepers into a real edit: a year in review, a trip with its map, one person across the years.
Full documentation: sam-dumont.github.io/immich-video-memory-generator
▶ Watch the 60-second demo · Make your first memory
Why: you left Google Photos for Immich and lost the year-in-review / trip / "your kid's year" videos. This brings them back: on your hardware, with clips you can veto and music that isn't canned. LLM titles and AI music are optional extras; the core pipeline runs on CPU.
Docker (recommended for self-hosters)
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 # then open http://localhost:8080
The compose file publishes port 8080 on localhost only. Authentication is disabled by default, and the app holds an Immich API key to your whole library — anyone who can reach the port can use it. To get to the UI from another machine, enable authentication first, then change the mapping to
"8080:8080". The UI is single-user, single-replica; run one instance.
Resource Requirements
Time depends mostly on whether analysis runs on a GPU/Apple Silicon or a CPU-only box. Results are cached, so the first run of a library is the slow one.
| Phase | RAM | CPU | Apple Silicon / GPU | CPU-only (4-core NAS class) |
|---|---|---|---|---|
| Idle (UI) | ~100MB | minimal | — | — |
| Analyzing clips (first run) | 2-4GB | 2+ cores | ~1 min per 10 clips | ~1-2 min per clip |
| Assembling 1080p | 4GB | 4 cores | ~2 min per 5 min of output | ~10-16 min for a 14-clip monthly (measured) |
| Assembling 4K | 6-8GB | 4+ cores | ~5 min per 5 min of output | not recommended |
Most of that assembly time is the title screens, not the encode: measured at 2 CPUs, title rendering took ~263 s of a ~339 s assembly, so read CPU-Only Mode before you buy a GPU for the encoder.
Measured once for calibration (2026-08-18): a 14-clip monthly at 1080p, cold cache, in the Docker
image with --cpus=4 --memory=4g and no GPU took 10 min with preset: fast and 15.7 min with
the default profile (4 M5 Max cores; a Celeron-class NAS is 2-3× slower). preset: fast swaps in
1080p H.264, a fast encoder, static titles, no speech pass and favorites-first analysis; explicit
settings still win over it. The
NAS-only guide
has the Celeron-class table. Field reports from Synology, Unraid, Proxmox and Raspberry Pi are
welcome: open an issue.
Without Docker
uvx immich-memories --help # no clone needed
mkdir -p ~/.immich-memories
cat > ~/.immich-memories/config.yaml << EOF
immich:
url: "https://photos.example.com"
api_key: "your-api-key-here"
EOF
immich-memories ui # web wizard on http://localhost:8080
immich-memories generate --year 2024 --person "John" --output ~/Videos/john_2024.mp4
Supported Immich Versions
Immich Memories supports 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.
immich-memories config test reports the detected contract and checks your credentials without
generating or uploading anything.
Optional: an LLM for clip analysis
Everything runs on your own hardware by default: analysis, encoding, titles, music. The LLM below is the one piece you can point somewhere else, and it speaks any OpenAI-compatible endpoint. That path exists for people who don't have the hardware or the patience to run a local model, not because the tool needs a cloud.
Developed and tested against Qwen3.6-27B and Qwen3.6-35B-A3B (vision is built into the Qwen3.x
models — no -VL variant to find).
# In ~/.immich-memories/config.yaml
advanced:
llm:
provider: "openai-compatible"
base_url: "http://your-llm-server:8000/v1"
model: "mlx-community/Qwen3.6-27B-8bit"
What it does
- Scores every clip on faces (35% of the weight), motion, camera stability and audio, then keeps the best ~5 seconds of a 45-second recording instead of all 45. LLM scene understanding is an optional fifth signal.
- 10 memory types: year in review, monthly, person spotlight, multi-person, season, on this day, holiday, then-and-now, trip (GPS-detected, with an animated satellite map fly-over) and album. The wizard shows 11 cards: those ten plus Custom.
- Photos share one selection pool with videos: Ken Burns, face-aware pan, blurred fill behind anything that doesn't fill the frame. Live Photos are scored like any other clip.
- Title screens with satellite map fly-overs, month dividers and particles, GPU-rendered through Taichi (static PIL titles without it). This is what makes the output look edited, not concatenated.
- Music: bring your own file, use the 28 bundled tracks (the
musicextra, already in the Docker image), or generate with ACE-Step or MusicGen. Ducking drops the music when someone talks. - Runs as a 4-step web wizard (basic auth, OIDC/SSO, or a trusted header proxy) or a headless CLI, in Docker, Kubernetes or a plain venv. Privacy mode blurs and mutes everything for demos.
Daily automation
Schedule one daily immich-memories auto run. It retries the oldest pending Immich upload if a
finished video still needs delivering, otherwise it generates a single eligible memory: never
several in one invocation. It ends skipped, dry_run, completed or failed, only failed
exits non-zero, and --quiet gives a scheduler stable JSON to read. In Docker skip cron entirely:
IMMICH_MEMORIES_AUTOMATION__ENABLED=true (plus …__DAILY_AT=09:00) and the UI process runs that
same decision once a day. The variety rules that stop it repeating itself are in the
auto CLI docs.
Documentation
The full documentation covers installation (Docker, uv/pip, Kubernetes, Terraform), the web UI walkthrough, the CLI reference, every config key, hardware acceleration, audio and music and per-setup recipes.
How the maintainer runs it
graph LR
IM["Immich Memories<br/>Python + FFmpeg, Apple Silicon Mac"]
LLM["omlx / mlx-vlm<br/>local vision LLM, same Mac"]
ACE["ACE-Step 1.5<br/>in-process, or a GPU box / K8s"]
MG["MusicGen API<br/>fallback"]
Immich["Immich v2 or v3<br/>Synology NAS"]
IM -->|"download clips"| Immich
IM -->|"clip scoring"| LLM
IM -->|"background music"| ACE
ACE -.->|"fallback"| MG
IM -->|"upload back (optional)"| Immich
One example, not a requirement. Both the LLM (omlx) and the music generator are optional: without them you get template titles and your own music, or silence.
Development
make dev installs everything, make ci runs the full pipeline, make help lists the rest.
Guidelines in CONTRIBUTING.md.
Built with AI
This entire codebase was written with AI (Claude) as an experiment in building complex software cleanly with AI assistance. 5,600+ tests (5,000+ unit, 600+ integration/E2E), 20 static analysis gates in CI (15 quality, 5 security), 300+ source modules. See DISCLAIMER.md for the full story.
License
MIT License, see LICENSE for details.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file immich_memories-0.63.0.tar.gz.
File metadata
- Download URL: immich_memories-0.63.0.tar.gz
- Upload date:
- Size: 4.5 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f158f5f206d0ed5f2987cf464926a2e6275b57d90ca7540712724422e2dbb113
|
|
| MD5 |
a9e36e5247ffaaf2fe05fb23ee85331e
|
|
| BLAKE2b-256 |
15c32943d87d4697c592a6036a1146d4f6af6c70107076d667e18ea960aa3239
|
Provenance
The following attestation bundles were made for immich_memories-0.63.0.tar.gz:
Publisher:
release.yml on sam-dumont/immich-video-memory-generator
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
immich_memories-0.63.0.tar.gz -
Subject digest:
f158f5f206d0ed5f2987cf464926a2e6275b57d90ca7540712724422e2dbb113 - Sigstore transparency entry: 2581318777
- Sigstore integration time:
-
Permalink:
sam-dumont/immich-video-memory-generator@f61adc9431746d39be26f6403507709ff78607fc -
Branch / Tag:
refs/heads/main - Owner: https://github.com/sam-dumont
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@f61adc9431746d39be26f6403507709ff78607fc -
Trigger Event:
push
-
Statement type:
File details
Details for the file immich_memories-0.63.0-py3-none-any.whl.
File metadata
- Download URL: immich_memories-0.63.0-py3-none-any.whl
- Upload date:
- Size: 3.8 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
030cc27f421a4da7213f538682cee65736b5bb94f22578449bdf3f5c6bc10ee6
|
|
| MD5 |
bfdc6f7965a147d22dc80d3c71e0518a
|
|
| BLAKE2b-256 |
c72b4a17e2a9d1d0efc91709a65ecbedd14dc4bae7d8d3f1f1ebb1b34e9d2184
|
Provenance
The following attestation bundles were made for immich_memories-0.63.0-py3-none-any.whl:
Publisher:
release.yml on sam-dumont/immich-video-memory-generator
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
immich_memories-0.63.0-py3-none-any.whl -
Subject digest:
030cc27f421a4da7213f538682cee65736b5bb94f22578449bdf3f5c6bc10ee6 - Sigstore transparency entry: 2581318783
- Sigstore integration time:
-
Permalink:
sam-dumont/immich-video-memory-generator@f61adc9431746d39be26f6403507709ff78607fc -
Branch / Tag:
refs/heads/main - Owner: https://github.com/sam-dumont
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@f61adc9431746d39be26f6403507709ff78607fc -
Trigger Event:
push
-
Statement type:
