Photos and people

Grant Photos access, index local and iCloud assets, refresh people data, and open results in Apple Photos.

Memsearch uses Apple PhotoKit to enumerate image assets and request image data. It separately opens the Photos library database in read-only mode to associate Apple Photos person names with assets.

Grant Photos permission

Enable Photos during onboarding or select Index Photos on Status. If macOS has not asked before, the backend requests authorization and waits up to 60 seconds.

To review access manually:

Open System Settings.
Go to Privacy & Security → Photos.
Allow MemSearch access.
Return to Memsearch and start Photos indexing again.

The API returns 403 when authorization is not granted. Current code treats any authorization state other than fully authorized as denied.

Limited-library access is not handled as authorized

The current permission check accepts the PhotoKit “authorized” state. If indexing still reports denied after choosing limited access, grant full Photos access and retry.

How Photos indexing works

PhotoKit fetches image assets, newest first.
Memsearch skips assets already indexed after their latest modification date.
PhotoKit requests current, high-quality image data and allows network access.
Memsearch converts the image to JPEG, creates a 256 × 256 thumbnail, and downsizes the embedding copy when it exceeds 4 MB.
Up to 10 embedding workers send prepared photos to Gemini concurrently.
ChromaDB stores the vector with a photos:// asset identifier and result metadata.

The source image is not copied into the ChromaDB index. A derived thumbnail is cached locally.

iCloud-only assets

networkAccessAllowed is enabled for PhotoKit requests. If the original is only in iCloud, Photos may download it on demand before Memsearch can prepare and embed it.

Keep the Mac online during the first Photos run.
Large libraries can take time because assets are downloaded and embedded individually.
A failed download increments the Photos error count and the run continues.
Stop may not take effect while PhotoKit is blocked on a request; the desktop app restarts the backend for a reliable stop.

Limit or select favorites

The desktop Index Photos action currently starts an unrestricted image run. The CLI and API expose additional controls.

uv run memsearch index-photos --limit 100
uv run memsearch index-photos --favorites
uv run memsearch index-photos --limit 100 --favorites

The PhotoKit fetch limit is applied before the favorites filter. --limit 100 --favorites therefore checks the newest 100 image assets and indexes favorites among them; it does not guarantee 100 favorite results.

People discovery

Memsearch reads:

~/Pictures/Photos Library.photoslibrary/database/Photos.sqlite

The configured library path can be changed with MEMSEARCH_PHOTOS_LIBRARY_PATH. The database is opened with SQLite read-only mode and PRAGMA query_only = ON.

The people reader joins Photos face, person, and asset records to build:

a case-insensitive person-name lookup;
face counts for autocomplete ordering; and
asset UUID → person-name associations.

Only people with a non-empty display name appear. Name people in Photos first if they are missing.

Refresh people

The backend automatically refreshes the people cache at most once every 60 seconds when /people is requested. It also refreshes before a Photos indexing run.

Use Refresh People in the desktop interface, or call:

curl -X POST http://127.0.0.1:7242/people/refresh

Refresh reloads Photos.sqlite and backfills person-name metadata on already indexed photos:// entries without creating new embeddings.

From the CLI, the equivalent backfill is:

cd backend
uv run memsearch update-people

People filtering stays local

During search, @person mentions are removed from the text embedded by Gemini. The backend filters returned candidates against locally stored person-name metadata and requires all mentioned people.

Open a result in Photos

Desktop and Raycast recognize a photos:// result and run an AppleScript that activates Photos and spotlights the asset by its local identifier.

If opening fails:

confirm that the asset still exists in the current Photos library;
retry after Photos finishes syncing;
check that the result came from the same library now configured; and
re-index after moving to a different Photos library.

Privacy notes

PhotoKit and the face-name database are accessed locally, but prepared JPEG image data is sent to Gemini for the embedding request. Person names are appended to local result metadata after the image embedding is created. See Privacy and architecture for the complete data flow.

On this page