Caches and disk use

videre keeps three caches. All are derived, so all can be deleted, but they cost very different amounts to rebuild.

Cache	Where	Typical size	Cost to lose
Thumbnails and decodes	~/.cache/videre/thumbnails/	tens of GB	Seconds each, re-decoded on demand
Model weights	~/.cache/huggingface/hub/	~960 MB	A download
Geocoded place names	inside the database	tiny	One network lookup each

Embeddings are not a cache. They are hours of computation and are covered under backing up.

Thumbnail cache

The big one, and the only one that grows without limit.

~/.cache/videre/libraries/<library-key>/thumbnails/

Each library has its own thumbnail directory, keyed by a hash of its root path, so two libraries never share cached decodes. Files are named by content hash:

File	What
<hash>_240.jpg	QuickLook grid thumbnail for HEIC
<hash>_1200.jpg	QuickLook lightbox image for HEIC
<hash>_raster-v1_240.jpg	Orientation-correct grid thumbnail for JPEG and other browser-raster formats
<hash>_raster-v1_1200.jpg	Orientation-correct raster lightbox image
<hash>_original.jpg	Full-resolution decode
<hash>_face-<key>_<size>.jpg	Cropped face, keyed by its crop geometry

Raster filenames carry a renderer version. A change to raster decoding can therefore bypass incompatible previews without throwing away expensive HEIC conversions. The first request after such a change rebuilds that raster preview; later requests remain direct cache reads.

The full-resolution copies are what make it large. They exist because videre faces needs full resolution to place face boxes, and reusing one is roughly 70x faster than decoding again (~108 ms against ~7.6 s). Face crops on the People pages reuse the same decode rather than rendering the photo again for every face, and videre faces writes each HEIC it detects into the cache as it goes, so the copies exist even where watch --heic never ran.

Managing it

videre stats                                # how big, alongside everything else
rm -rf ~/.cache/videre/libraries/          # safe, regenerates on demand

videre stats has a Disk use section listing every store largest first and marking which are rebuildable, so you can see whether the cache is actually the thing worth clearing before clearing it. It also knows where this library’s cache is, which du needs telling.

Deleting it is genuinely safe. Every file is derived, and the only cost is re-conversion the next time something needs the image.

There is no size limit, age-based expiry, or eviction. The only automatic cleanup is videre prune, and it only removes entries for photos that are no longer in the database. Cache for photos you still own is never reclaimed.

It is private to each library

Each library’s thumbnails live under its own key, so videre prune reclaims only the entries for its own library and can never delete another’s. The same photo in two libraries is decoded once per library; that small duplication buys complete isolation, which matters because a wrong deletion across libraries would be silent. A thumbnail costs milliseconds to rebuild in any case. See keeping libraries separate.

Warming it deliberately

videre --library ~/Photos watch --heic     # decode and cache everything, then Ctrl-C
videre faces                     # now reads the cache instead of decoding

Worth doing before a long face-detection run on a HEIC-heavy library. Do not run both at once; see long-running jobs.

Model weights

Downloaded on first use, never at install:

~/.cache/huggingface/hub/
  models--google--siglip2-base-patch16-224/    ~1.5 GB
  models--WePrompt--buffalo_l/                 ~180 MB

Set HF_HOME to move it. It is the standard Hugging Face location, so other tools on your machine may share it.

du -sh ~/.cache/huggingface/hub/
rm -rf ~/.cache/huggingface/hub/models--google--siglip2-base-patch16-224

Deleting means the next embed or search downloads it again. Your embeddings are unaffected: they live elsewhere and stay queryable.

Selecting a larger model downloads it in addition, not instead. Unused ones sit there until removed by hand.

Geocode cache

A table inside the database, filled by videre search --location so a repeated place-name query never repeats the network request.

SELECT query, lat, lon, resolved_at FROM geocode_cache ORDER BY resolved_at DESC;
DELETE FROM geocode_cache;              -- safe; just re-looks-up next time

Tiny, and the only reason to clear it is if a place resolved to somewhere wrong.

Separate from the location_name column that watch --location fills, which is a reverse lookup done offline.

Where disk actually goes

du -sh <library>/.videre/            # database, config, embeddings
du -sh <library>/.videre/embeddings/ # ~130-190 MB per model per 70k photos
du -sh ~/.cache/videre/libraries/     # usually the largest
du -sh ~/.cache/huggingface/hub/      # ~960 MB with defaults
videre stats                          # per-model embedding sizes

On a large HEIC library the thumbnail cache usually dwarfs everything else, and it is also the safest thing to delete. Work through it in that order:

1. rm -rf the thumbnail cache. Free, regenerates.
2. Remove model weights you no longer use. Free, re-downloads.
3. videre prune to drop derived data for photos that are gone.
4. Delete an unused model’s embeddings directory, if you tried one and moved on.

Nothing in that list touches your photos.