# Immich Memories

> A self-hosted companion for Immich that turns a photo and video library into memory films. Pick a month, a year, a trip or a person, review the cut, then render an MP4 with titles and music.

Docs track: stable, version v1.0.0-rc.10, source commit 43568a6975cf.

It runs next to an existing Immich server and reads the library through an Immich API key. It never changes your originals, and with upload off (the default) it writes nothing to the library. It ships as Docker Compose files, a Kubernetes setup, and a Python package for Mac and Linux.

There are three tiers, and each one makes a complete film:

- Basic: CPU only, no model server. Dates, favourites, people and places guide the edit. A plain NAS can do the whole job.
- GPU: adds picture descriptions, document and sensitive-content checks, and a family-viewing pre-screen.
- Full: GPU, plus a text reader that refines the draft and writes titles.

Start with Basic when unsure. Every docs page also exists as Markdown: add `.md` to its address, without the trailing slash. The docs links below go to the Markdown; drop the `.md` for the HTML page.

## Understand the project

- [How it chooses](https://sam-dumont.github.io/immich-memories/docs/how-it-chooses/overview.md): how a library turns into a cut, in plain words: stories, moments, favourites and length
- [Architecture](https://sam-dumont.github.io/immich-memories/docs/contribute/architecture.md): what runs where, the pipeline, the store, the web app and the services
- [Can I run this?](https://sam-dumont.github.io/immich-memories/docs/run/tested-deployments.md): every install route with the release and hardware it was last tested on
- [Measure your setup](https://sam-dumont.github.io/immich-memories/docs/better/measured.md): measured times, memory and cost per stage, each on named hardware
- [One month, three tiers](https://sam-dumont.github.io/immich-memories/docs/better/tier-example.md): Basic, GPU and Full films of the same month, side by side

## Install

- [Quick start](https://sam-dumont.github.io/immich-memories/docs/get-started/quick-start.md): Docker Compose install for Basic, GPU or Full, connect Immich, open the app
- [Choose your setup](https://sam-dumont.github.io/immich-memories/docs/get-started/choose-your-setup.md): what each tier changes and what hardware it needs
- [Setup builder](https://sam-dumont.github.io/immich-memories/setup/): generates the Compose or Kubernetes files for a tier, in the browser
- [Requirements and tiers](https://sam-dumont.github.io/immich-memories/docs/run/requirements.md): CPU, memory, disk and GPU per tier
- [On a NAS](https://sam-dumont.github.io/immich-memories/docs/run/nas.md): Synology, Unraid, TrueNAS and Portainer
- [Kubernetes](https://sam-dumont.github.io/immich-memories/docs/run/kubernetes.md): all three tiers in an existing cluster
- [Native Mac or Linux](https://sam-dumont.github.io/immich-memories/docs/run/uv-pip.md): packaged releases with uv or pip, Apple Silicon included
- [Installation help](https://sam-dumont.github.io/immich-memories/docs/reference/installation-help.md): what to check when an install fails

## Make a film

- [Your first film](https://sam-dumont.github.io/immich-memories/docs/get-started/first-film.md): choose an album, review the cut, render
- [After install](https://sam-dumont.github.io/immich-memories/docs/get-started/after-install.md): home, people, film language, backups, schedules
- [Choose a film](https://sam-dumont.github.io/immich-memories/docs/make/memory-types.md): month, year, person, trip or occasion
- [Use the web UI](https://sam-dumont.github.io/immich-memories/docs/make/web-ui.md): the browser app
- [Generate a film](https://sam-dumont.github.io/immich-memories/docs/make/cli/generate.md): CLI recipes
- [Automatic films](https://sam-dumont.github.io/immich-memories/docs/make/automate.md): one film a day, chosen by the app
- [Improve a film](https://sam-dumont.github.io/immich-memories/docs/make/improve-a-film.md): fix the cut, the people, the length

## Configure and operate

- [Configuration](https://sam-dumont.github.io/immich-memories/docs/run/config-file.md): the config file
- [Environment variables](https://sam-dumont.github.io/immich-memories/docs/run/environment-variables.md): every variable the app reads
- [Privacy](https://sam-dumont.github.io/immich-memories/docs/run/privacy.md): everything that can leave your network, and how to turn it off
- [Hardware encoding](https://sam-dumont.github.io/immich-memories/docs/run/hardware.md): NVENC, VAAPI, Quick Sync and VideoToolbox
- [Upgrading](https://sam-dumont.github.io/immich-memories/docs/run/maintenance/upgrading.md): upgrade steps and deprecations

## Reference

- [CLI reference](https://sam-dumont.github.io/immich-memories/docs/reference/cli-reference.md): every command and flag, generated from the code
- [Config reference](https://sam-dumont.github.io/immich-memories/docs/reference/config-reference.md): every config key and its default
- [Automation decisions and trigger API](https://sam-dumont.github.io/immich-memories/docs/reference/automation-contract.md): the HTTP trigger and what it decides
- [Text reader and provider contracts](https://sam-dumont.github.io/immich-memories/docs/reference/llm-providers.md): how the Full tier talks to a model server
- [Troubleshooting](https://sam-dumont.github.io/immich-memories/docs/reference/troubleshooting.md): known symptoms and fixes
- [FAQ](https://sam-dumont.github.io/immich-memories/docs/reference/faq.md)

## Build from source

- [AGENTS.md](https://github.com/sam-dumont/immich-memories/blob/main/AGENTS.md): read this first if you are a coding agent. Rules for changes, tests, commits and safety
- [ARCHITECTURE.md](https://github.com/sam-dumont/immich-memories/blob/main/ARCHITECTURE.md): map of the codebase and its entry points
- [Development setup](https://sam-dumont.github.io/immich-memories/docs/contribute/development-setup.md): Python 3.11 to 3.13, FFmpeg, uv, Make and Node 22, then `make dev` in every clone
- [Testing](https://sam-dumont.github.io/immich-memories/docs/contribute/testing.md): unit, integration and end-to-end tests, and how to run them
- [CI and quality gates](https://sam-dumont.github.io/immich-memories/docs/contribute/ci.md): every gate a change has to pass; `make ci` runs them all
- [Writing the docs](https://sam-dumont.github.io/immich-memories/docs/contribute/writing-docs.md): what goes on which page
- [Makefile](https://github.com/sam-dumont/immich-memories/blob/main/Makefile): `make help` lists every target

## Optional

- [Choose an upgrade](https://sam-dumont.github.io/immich-memories/docs/better/overview.md): optional add-ons per tier
- [Releasing](https://sam-dumont.github.io/immich-memories/docs/contribute/releasing.md): versioning and the release process