Photos / Immich Connector

The Immich connector imports photos, albums, and facial recognition data from a self-hosted Immich instance.

Auth type: API Key Trust score: 0.85 Source types: photo, file

What It Syncs

• Photos -- image metadata, EXIF data, GPS coordinates, timestamps
• Albums -- album names and organization
• Facial recognition -- people identified by Immich's face detection, including names and person IDs
• Photo descriptions -- generated by Ollama's vision-language model during file processing

Setup

1. Get an Immich API Key

1. Open your Immich web UI
2. Go to User Settings > API Keys
3. Create a new API key
4. Copy the key

2. Configure in Botmem

Navigate to the Connectors page and click Add on the Photos / Immich connector. Enter:

Field	Value
Host	Your Immich server URL (e.g., http://192.168.1.50:2283)
API Key	Your Immich API key

How Sync Works

1. Lists all assets (photos) using the Immich API
2. For each photo, fetches metadata including:
   • EXIF data (camera, lens, ISO, etc.)
   • GPS coordinates (latitude, longitude)
   • Timestamps (taken date)
   • Album membership
   • People tags (from facial recognition)
3. Emits a ConnectorDataEvent with sourceType: 'file'
4. The embed processor creates a memory record and resolves contacts from people tags
5. The file processor downloads the image and generates a description using Ollama's vision-language model (qwen3-vl:4b)
6. The description becomes the memory's text content

Contact Resolution

Immich's facial recognition provides person names and IDs. The embed processor:

• Creates contacts with name and immich_person_id identifiers
• Downloads face thumbnails from the Immich API and stores them as base64 avatars
• Links contacts to the memory with role participant

Immich Person "John Smith" (id: abc-123)
  -> Contact: John Smith
     - Identifier: name = "John Smith" (photos)
     - Identifier: immich_person_id = "abc-123" (photos)
     - Avatar: data:image/jpeg;base64,... (source: immich)

Photo Description Pipeline

When a photo event reaches the file processor:

1. The image is downloaded from Immich using the API key
2. The image is converted to base64
3. Ollama's VL model generates a natural language description of the photo
4. The description is stored as the memory text
5. The memory is re-embedded with the new text
6. Entity extraction finds people, places, and objects in the description

This means you can search your photos with natural language: "beach sunset with palm trees" or "birthday party at the restaurant."

Limitations

• Immich required -- this connector requires a running Immich instance; it does not read local photo files
• Processing time -- photo description via the VL model takes 5-15 seconds per image
• No video -- video files are currently not processed
• Face recognition accuracy -- depends on Immich's face detection quality; untagged faces are not imported

Troubleshooting

"401 Unauthorized" error

The API key may be invalid or expired. Generate a new one from Immich's settings.

Photos not getting descriptions

Make sure the qwen3-vl:4b model is pulled on your Ollama host. The file processor needs this model to generate photo descriptions.

Missing face tags

Face tags only appear for people that Immich has identified and named. Go to Immich's People section and name any unidentified faces you want to import.