Immich Memories

CI codecov OpenSSF Scorecard Release Python License Docs

Turn your Immich photo library into video memory compilations with music, title screens, and smart cuts.

Immich Memories connects to your self-hosted Immich server, selects the best moments from your videos and photos, and compiles them into shareable memory videos. Year-end recaps, trip highlights, person spotlights, seasonal compilations, monthly highlights, "on this day" flashbacks -- all from a single tool.

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)

# 1. Download the compose file
curl -O https://raw.githubusercontent.com/sam-dumont/immich-video-memory-generator/main/docker-compose.yml

# 2. Set your Immich connection
export IMMICH_URL="http://your-immich-server:2283"
export IMMICH_API_KEY="your-api-key"

# 3. Start
docker compose up -d

# 4. Open http://localhost:8080

Do not expose the default UI as-is. Authentication is disabled by default, and the container listens on 0.0.0.0. Anyone who can reach port 8080 can use it. Enable authentication before publishing the port. 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 on a CPU-only box, and analysis 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
Encoding 1080p 4GB 4 cores ~2 min per 5 min of output ~15 min for a 30-clip video
Encoding 4K 6-8GB 4+ cores ~5 min per 5 min of output not recommended

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). Details in the NAS guide.

Default Docker limits: 4GB RAM, 4 CPUs. A monthly memory (~30 clips) is a coffee break on a Mac or GPU box and up to an hour on a NAS; a full year is an overnight job on a NAS. On a CPU-only box set IMMICH_MEMORIES_PRESET=fast (or preset: fast in config.yaml): 1080p H.264, fast encoder, static titles, no speech pass, favorites-first analysis — one switch, explicit settings still win. See the NAS-only guide for a Celeron-class table and the settings that keep it usable.

Developed on Apple Silicon (macOS). CI runs the unit suite on Ubuntu + macOS, the integration suite on a Linux NVIDIA runner, and publishes amd64 + arm64 images. Field reports from Synology, Unraid, Proxmox and Raspberry Pi are welcome — please report your experience.

Supported Immich Versions

Immich Memories supports Immich v2 and v3. Automatic runtime detection is the default:

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.

The compatibility layer handles the actual v2-to-v3 breaks: v2 duration strings and v3 millisecond durations both become seconds internally, uploads use the fields accepted by the detected major, and asset search dates include the UTC offset required by v3.

Check the detected API contract and your credentials without generating or uploading anything:

immich-memories config test

Optional: LLM for smart clip analysis

For AI-powered content analysis (identifies what's happening in each clip), point to any OpenAI-compatible vision model:

# In ~/.immich-memories/config.yaml
advanced:
  llm:
    provider: "openai-compatible"
    base_url: "http://your-llm-server:8080/v1"
    model: "qwen2.5-vl"

Quick Install

# One-liner (no clone needed)
uvx immich-memories --help

# Or clone and install
git clone https://github.com/sam-dumont/immich-video-memory-generator.git
cd immich-video-memory-generator
uv sync

Quick Start

# 1. Configure
mkdir -p ~/.immich-memories
cat > ~/.immich-memories/config.yaml << EOF
immich:
  url: "https://photos.example.com"
  api_key: "your-api-key-here"
  api_version: auto  # auto | v2 | v3
EOF

# 2. Launch the UI
immich-memories ui
# Opens at http://localhost:8080

# 3. Or use the CLI
immich-memories generate --year 2024 --person "John" --output ~/Videos/john_2024.mp4

Key Features

  • Videos + Photos — Unified selection pool: videos, photos (Ken Burns / face-aware pan), and Live Photos
  • 7 Memory Types — Year in Review, Season, Person Spotlight, Multi-Person, Monthly Highlights, On This Day, Trip
  • Smart Clip Selection — Scene detection, interest scoring, duplicate filtering, temporal coverage
  • Cinematic Titles — GPU-rendered title screens with satellite map fly-overs, month dividers
  • Face-Aware Cropping — Keeps faces centered when converting aspect ratios
  • Hardware Acceleration — NVIDIA NVENC, Apple VideoToolbox, Intel QSV, AMD VAAPI
  • AI Music Generation — ACE-Step or MusicGen with automatic mood detection and audio ducking
  • Privacy Mode — Blur all video, muffle audio, anonymize GPS/names for demos
  • Smart Automation — one daily auto run decides what deserves to run, then performs one action
  • Authentication — Basic auth, OIDC/SSO (Auth0, Authelia, Keycloak), or trusted header proxy
  • Web UI + CLI — 4-step wizard or headless automation
  • Docker & Kubernetes — Containerized deployment with GPU support

Daily automation

Schedule one daily invocation of immich-memories auto run. It first retries the oldest pending Immich delivery when a completed output still needs uploading; otherwise it selects and generates one eligible memory. It never tries to catch up by doing several things in one invocation.

The terminal outcome is skipped, dry_run, completed, or failed. The first three exit 0; failed exits 1. Use --quiet when a scheduler needs the stable JSON result.

Docker: no cron needed — set IMMICH_MEMORIES_AUTOMATION__ENABLED=true (and …__DAILY_AT=09:00) and the web UI process runs that same decision once a day itself.

The selector keeps variety on purpose: latest completed month only, at most one monthly review per calendar month, no category twice in a row, and no category more than twice in the last six completed automatic runs. See the auto CLI docs.

Documentation

See the full documentation for:

How the maintainer runs it

graph LR
    subgraph "Apple Silicon Mac"
        IM["Immich Memories<br/>Python + FFmpeg"]
        LLM["omlx (mlx-vlm)<br/>local vision LLM"]
    end

    subgraph "Optional GPU box / K8s"
        ACE["ACE-Step 1.5<br/>(or in-process on the Mac)"]
        MG["MusicGen API<br/>(fallback)"]
    end

    subgraph "Synology NAS"
        Immich["Immich v2 or v3<br/>Photos + Videos"]
    end

    IM -->|"API reads<br/>(download clips)"| Immich
    IM -->|"Vision analysis<br/>(clip scoring)"| LLM
    IM -->|"Background music<br/>(AI-generated)"| ACE
    ACE -.->|"fallback"| MG
    IM -->|"Upload back<br/>(optional)"| Immich

One example, not a requirement. The LLM runs locally on the Mac via omlx (Apple Silicon MLX); music generation runs either in-process (ACE-Step on Apple Silicon) or on a remote GPU API. Both are optional — without them you get template titles and your own music (or silence), and everything else still works.

Development

make dev      # Install all dependencies
make check    # Run all checks (lint, format, typecheck, tests)
make ci       # Full CI pipeline
make help     # Show all available targets

See CONTRIBUTING.md for guidelines.

Built with AI

This entire codebase was written with AI (Claude) as an experiment in building complex software cleanly with AI assistance. 5,000+ tests (4,400+ unit, 600+ integration/E2E), ~20 CI quality gates, 250+ source modules. See DISCLAIMER.md for the full story.

License

MIT License — see LICENSE for details.

Made with ❤️ for the Immich community

Project links

Data verified by PyPI on Aug 23, 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 23, 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 face 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.53.9.tar.gz (4.4 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.53.9-py3-none-any.whl (3.8 MB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: immich_memories-0.53.9.tar.gz
  • Upload date:
  • Size: 4.4 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.53.9.tar.gz
Algorithm Hash digest
SHA256 8e5045197ec3869032500b808e4a083d13afadf3833b6fa3d16e07f43a4c79e8
MD5 fe4698acd92e2c22da7d2683e78be091
BLAKE2b-256 3d5dd6701632e559f3d31613f0cb450febd7ccf6b1705eec5e45596c4a7980f4

See more details on using hashes here.

Provenance

The following attestation bundles were made for immich_memories-0.53.9.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.53.9-py3-none-any.whl.

File metadata

File hashes

Hashes for immich_memories-0.53.9-py3-none-any.whl
Algorithm Hash digest
SHA256 45fad48cece7c75130b27a00ab94e41ba9222ce41e5d916a124577a6952b08c6
MD5 5ad044e74a71bf3129cded3768c6689b
BLAKE2b-256 93a3a83e09b614b6c690dee72c1b152dcbd6981040070ae35dded701cc83c129

See more details on using hashes here.

Provenance

The following attestation bundles were made for immich_memories-0.53.9-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

0.71.0

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

This release

0.53.9 This release

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