Immich Memories

CI codecov OpenSSF Scorecard Release Python License Docs

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 and runs a real editor over your library: a vision model looks at the material and describes what is happening, selection and review judge those descriptions, and the keepers become a real edit — a year in review, a trip with its map, one person across the years. Always chronological, favourites treated as law, and when it can't name a day honestly it refuses rather than faking it. How it decides is documented in The Curator.

Full documentation: sam-dumont.github.io/immich-video-memory-generator

Immich Memories demo: clip review, title screens and a finished memory video
▶ 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.
  • 11 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), album, and special day — a day the library itself flagged, found by discover-days rather than asked for. The wizard shows 12 cards: those eleven 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 music extra, 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.

Project links

Data verified by PyPI on Aug 25, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.75.5)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for samueldumont from gravatar.com samueldumont

Credits

Author: Immich Memories Contributors

GitHub Statistics

Data verified by PyPI on Aug 25, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Provides Extra

all all-mac audio audio-ml auth demucs dev gpu mac music speech transcribe

Tags

compilation immich memories photo-management video

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

immich_memories-0.71.0.tar.gz (4.6 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

immich_memories-0.71.0-py3-none-any.whl (3.8 MB view details)

Uploaded Python 3

File details

Details for the file immich_memories-0.71.0.tar.gz.

File metadata

  • Download URL: immich_memories-0.71.0.tar.gz
  • Upload date:
  • Size: 4.6 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for immich_memories-0.71.0.tar.gz
Algorithm Hash digest
SHA256 e8b2699eeb6715d66fbc8eac46d146a0b357aef34d3e8e06b7dd82331fa1e186
MD5 a9c1285d8982e585b3b652600e78687b
BLAKE2b-256 3568b577d782de10bf25bcf081a39f57f138f3fd715b9e5691ef6a6021d0acbe

See more details on using hashes here.

Provenance

The following attestation bundles were made for immich_memories-0.71.0.tar.gz:

Publisher: release.yml on sam-dumont/immich-video-memory-generator

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file immich_memories-0.71.0-py3-none-any.whl.

File metadata

File hashes

Hashes for immich_memories-0.71.0-py3-none-any.whl
Algorithm Hash digest
SHA256 2a29e84747f6c657306dc1a4bd77d29d606fd257fb2c4b19303cbabe47b48ce5
MD5 2b41fb79de3f6db98482c602ea6e7eaf
BLAKE2b-256 aaa28eed1653a3886523119a4031a966652d403dffa87b8f56eff695f279ccdd

See more details on using hashes here.

Provenance

The following attestation bundles were made for immich_memories-0.71.0-py3-none-any.whl:

Publisher: release.yml on sam-dumont/immich-video-memory-generator

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.75.5

2 files

0.75.4

2 files

0.75.3

2 files

0.75.2

2 files

0.75.1

2 files

0.75.0

2 files

0.74.0

2 files

0.73.0

2 files

0.72.3

2 files

0.72.2

2 files

0.72.1

2 files

0.72.0

2 files

0.71.1

2 files

This release

0.71.0 This release

2 files

0.70.1

2 files

0.70.0

2 files

0.69.2

2 files

0.69.1

2 files

0.69.0

2 files

0.68.0

2 files

0.67.0

2 files

0.66.0

2 files

0.65.0

2 files

0.64.0

2 files

0.63.0

2 files

0.62.1

2 files

0.62.0

2 files

0.61.0

2 files

0.60.1

2 files

0.60.0

2 files

0.59.2

2 files

0.59.1

2 files

0.59.0

2 files

0.58.0

2 files

0.57.0

2 files

0.56.0

2 files

0.55.0

2 files

0.54.1

2 files

0.54.0

2 files

0.53.11

2 files

0.53.10

2 files

0.53.9

2 files

0.53.8

2 files

0.53.7

2 files

0.53.6

2 files

0.53.5

2 files

0.53.4

2 files

0.53.3

2 files

0.53.2

2 files

0.53.1

2 files

0.53.0

2 files

0.52.2

2 files

0.52.1

2 files

0.52.0

2 files

0.51.2

2 files

0.51.1

2 files

0.51.0

2 files

0.50.0

2 files

0.49.2

2 files

0.49.1

2 files

0.49.0

2 files

0.48.1

2 files

0.48.0

2 files

0.47.0

2 files

0.46.0

2 files

0.45.1

2 files

0.45.0

2 files

0.44.0

2 files

0.43.0

2 files

0.42.3

2 files

0.42.2

2 files

0.42.1

2 files

0.42.0

2 files

0.41.0

2 files

0.40.3

2 files

0.40.2

2 files

0.40.1

2 files

0.40.0

2 files

0.39.0

2 files

0.38.3

2 files

0.38.2

2 files

0.37.2

2 files

0.37.1

2 files

0.37.0

2 files

0.36.6

2 files

0.36.5

2 files

0.36.4

2 files

0.36.3

2 files

0.36.2

2 files

0.36.1

2 files

0.36.0

2 files

0.35.3

2 files

0.35.2

2 files

0.35.1

2 files

0.35.0

2 files

0.34.6

2 files

0.34.5

2 files

0.34.4

2 files

0.34.3

2 files

0.34.2

2 files

0.34.1

2 files

0.34.0

2 files

0.33.0

2 files

0.32.1

2 files

0.32.0

2 files

0.31.0

2 files

0.30.1

2 files

0.30.0

2 files

0.29.5

2 files

0.29.4

2 files

0.29.3

2 files

0.29.2

2 files

0.29.1

2 files

0.29.0

2 files

0.28.1

2 files

0.28.0

2 files

0.27.1

2 files

0.27.0

2 files

0.26.5

2 files

0.26.4

2 files

0.26.3

2 files

0.26.2

2 files

0.26.1

2 files

0.26.0

2 files

0.25.1

2 files

0.25.0

2 files

0.24.1

2 files

0.24.0

2 files

0.23.4

2 files

0.23.3

2 files

0.23.2

2 files

0.23.1

2 files

0.23.0

2 files

0.22.0

2 files

0.21.6

2 files

0.21.5

2 files

0.21.4

2 files

0.21.3

2 files

0.20.0

2 files

0.19.1

2 files

0.19.0

2 files

0.18.2

2 files

0.18.1

2 files

0.18.0

2 files

0.17.3

2 files

0.17.2

2 files

0.17.1

2 files

0.17.0

2 files

0.16.0

2 files

0.15.0

2 files

0.14.0

2 files

0.13.2

2 files

0.13.1

2 files

0.13.0

2 files

0.12.1

2 files

0.12.0

2 files

0.11.1

2 files

0.11.0

2 files

0.10.1

2 files

0.10.0

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.8.0

2 files

Pre-release

0.7.1.dev0

2 files

0.6.0

2 files

0.5.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page