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 15, 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 15, 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

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.38.2.tar.gz (1.8 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.38.2-py3-none-any.whl (1.4 MB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: immich_memories-0.38.2.tar.gz
  • Upload date:
  • Size: 1.8 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.38.2.tar.gz
Algorithm Hash digest
SHA256 ba60e293f88935be05bd2ec2eb378a7753656d46f1eb81f42a941b235132e14a
MD5 a74807389ffbebd0c18466222afe9abe
BLAKE2b-256 ea31d369e4a0274ae5954e10f090137c312d107225a5ef3e393267cad253d023

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for immich_memories-0.38.2-py3-none-any.whl
Algorithm Hash digest
SHA256 13c55170d1efcf138ce77f1e70df9c459e709bd92c050dd0c0f8c773810bbbda
MD5 424bf514b461b194160373c131fb8c1c
BLAKE2b-256 1262cee851092ad45bec450216d9985228ce45155302aa4a0e2051a4564fab25

See more details on using hashes here.

Provenance

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

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

This release

0.38.2 This release

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