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

Reference Setup

graph LR
    subgraph "Apple M2 Pro – 16GB RAM"
        IM["Immich Memories<br/>Python + FFmpeg"]
        LLM["omlx (mlx-vlm)<br/>Qwen2.5-VL local"]
    end

    subgraph "K8s Cluster (GPUs)"
        ACE["ACE-Step 1.5<br/>T1000 8GB"]
        MG["MusicGen API<br/>GTX 1070 8GB"]
    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

The LLM runs locally on the Mac via omlx (Apple Silicon MLX). Music generation runs on a K8s cluster with dedicated GPUs. Both are optional — the tool works without them, just without AI clip descriptions and generated music.

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

Phase RAM CPU Time estimate
Idle (UI) ~100MB minimal —
Analyzing clips 2-4GB 2+ cores ~1 min per 10 clips
Encoding (1080p) 4GB 4 cores ~2 min for 5 min video
Encoding (4K) 6-8GB 4+ cores ~5 min for 5 min video

Default Docker limits: 4GB RAM, 4 CPUs. This is not a NAS app — video analysis and encoding need real compute. Best run on a machine with 8GB+ RAM.

Developed and tested on: Apple M2 Pro, 16GB RAM, macOS. Not yet tested on other hardware. If you run it on Linux/x86, Synology, Unraid, or Raspberry Pi — 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 globe animations, satellite maps, 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.

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:

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. 3,900+ tests, 20+ CI quality gates, 225 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 18, 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 18, 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 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.40.2.tar.gz (4.2 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.40.2-py3-none-any.whl (3.6 MB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: immich_memories-0.40.2.tar.gz
  • Upload date:
  • Size: 4.2 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.40.2.tar.gz
Algorithm Hash digest
SHA256 1ab9cbd66ea131d69efb1dd3b34f197389355b61e15b86de5d82739d319589ce
MD5 7f70cdd96f0b594c1db009e814530315
BLAKE2b-256 d2186b66e33b7e7ca9b0c50021e071b5c06dbb75b05da3bf805aafa4e6b4cb49

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for immich_memories-0.40.2-py3-none-any.whl
Algorithm Hash digest
SHA256 0e0809d05225108a6a30076b583fa555c944a0aee1ac5d38871a89006b1d2ad1
MD5 bb04ece2e92c4822cb536fe1a5e56bcd
BLAKE2b-256 ca2ff0ee8d86fdb3a0b4fcaddf7418afe822b2293d16c821550e40ad29c60916

See more details on using hashes here.

Provenance

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

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

This release

0.40.2 This release

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