fix(vram): persist remote probe metadata (#11487)

* fix(vram): persist remote probe metadata

The startup warmer repeated remote size and GGUF metadata probes after every restart because both caches lived only in memory. Store successful HTTP probes for 24 hours so frequent restarts reuse the prior results.

Bound the cache, reject invalid records, and purge it when gallery data changes. Local model files continue to bypass persistence.

Assisted-by: Codex:gpt-5

* fix(vram): check temporary file cleanup

The lint gate rejects the unchecked cleanup call in the persistent cache writer.

Assisted-by: Codex:gpt-5.6 [golangci-lint]

* fix(vram): make persistent cache optional

Remote metadata probes can transfer enough data that operators need
control over disk reuse and startup warming. Gallery autoload now gates
both behaviors, and the runtime setting applies changes immediately.

Assisted-by: Codex:gpt-5

* fix(ui): expose gallery startup pre-warm

The existing gallery autoload setting also gates the startup metadata warmer. Name both effects in Settings so operators can find the requested boot control.

Assisted-by: Codex:gpt-5

---------

Co-authored-by: localai-org-maint-bot <306269227+localai-org-maint-bot@users.noreply.github.com>

core/application/startup.go

@@ -446,13 +446,20 @@ func New(opts ...config.AppOption) (*Application, error) {
 	// Wire gallery generation counter into VRAM caches so they invalidate
 	// when gallery data refreshes instead of using a fixed TTL.
 	vram.SetGalleryGenerationFunc(gallery.GalleryGeneration)
+	if options.AutoloadGalleries {
+		if options.VRAMPersistentCache {
+			// Remote GGUF probes can transfer substantial metadata. Keep successful
+			// results across restarts so the startup warmer does not repeat that work.
+			vram.ConfigurePersistentCache(filepath.Join(options.SystemState.Model.ModelsPath, "..", "cache", "vram"), 24*time.Hour)
+		}
 
-	// Fill those caches ahead of the first visitor. An estimate for an entry
-	// nobody has asked about yet costs a remote probe of its weight files, and
-	// the model gallery asks for one per row, so without this the first page
-	// spends seconds filling in its own sizes while somebody watches it.
-	// Non-blocking, and bounded: see DefaultEstimateWarmConfig.
-	gallery.WarmEstimateCache(options.Context, options.Galleries, options.SystemState, gallery.EstimateWarmConfigFromEnv())
+		// Fill those caches ahead of the first visitor. An estimate for an entry
+		// nobody has asked about yet costs a remote probe of its weight files, and
+		// the model gallery asks for one per row, so without this the first page
+		// spends seconds filling in its own sizes while somebody watches it.
+		// Non-blocking, and bounded: see DefaultEstimateWarmConfig.
+		gallery.WarmEstimateCache(options.Context, options.Galleries, options.SystemState, gallery.EstimateWarmConfigFromEnv())
+	}
 
 	if options.ConfigFile != "" {
 		if err := application.ModelConfigLoader().LoadMultipleModelConfigsSingleFile(options.ConfigFile, configLoaderOpts...); err != nil {

core/cli/run.go

@@ -53,6 +53,7 @@ type RunCMD struct {
 	BackendGalleries          string   `env:"LOCALAI_BACKEND_GALLERIES,BACKEND_GALLERIES" help:"JSON list of backend galleries" group:"backends" default:"${backends}"`
 	Galleries                 string   `env:"LOCALAI_GALLERIES,GALLERIES" help:"JSON list of galleries" group:"models" default:"${galleries}"`
 	AutoloadGalleries         bool     `env:"LOCALAI_AUTOLOAD_GALLERIES,AUTOLOAD_GALLERIES" group:"models" default:"true"`
+	VRAMPersistentCache       bool     `env:"LOCALAI_VRAM_PERSISTENT_CACHE,VRAM_PERSISTENT_CACHE" group:"models" default:"true" help:"Persist successful remote VRAM metadata probes across restarts"`
 	AutoloadBackendGalleries  bool     `env:"LOCALAI_AUTOLOAD_BACKEND_GALLERIES,AUTOLOAD_BACKEND_GALLERIES" group:"backends" default:"true"`
 	BackendImagesReleaseTag   string   `env:"LOCALAI_BACKEND_IMAGES_RELEASE_TAG,BACKEND_IMAGES_RELEASE_TAG" help:"Fallback release tag for backend images" group:"backends" default:"latest"`
 	BackendImagesBranchTag    string   `env:"LOCALAI_BACKEND_IMAGES_BRANCH_TAG,BACKEND_IMAGES_BRANCH_TAG" help:"Fallback branch tag for backend images" group:"backends" default:"master"`
@@ -302,6 +303,7 @@ func (r *RunCMD) Run(ctx *cliContext.Context) error {
 		config.WithF16(r.F16),
 		config.WithStringGalleries(r.Galleries),
 		config.WithBackendGalleries(r.BackendGalleries),
+		config.WithVRAMPersistentCache(r.VRAMPersistentCache),
 		config.WithCors(r.CORS),
 		config.WithCorsAllowOrigins(r.CORSAllowOrigins),
 		config.WithDisableCSRF(r.DisableCSRF),

core/config/application_config.go

@@ -125,6 +125,7 @@ type ApplicationConfig struct {
 	ExternalGRPCBackends map[string]string
 
 	AutoloadGalleries, AutoloadBackendGalleries bool
+	VRAMPersistentCache                         bool
 	AutoUpgradeBackends                         bool
 	PreferDevelopmentBackends                   bool
 
@@ -284,6 +285,7 @@ func NewApplicationConfig(o ...AppOption) *ApplicationConfig {
 		// toggle can still turn it off (a persisted false wins - see
 		// loadRuntimeSettingsFromFile).
 		EnableBackendLogging:        true,
+		VRAMPersistentCache:         true,
 		ArtifactDownloadConcurrency: modelartifacts.DefaultDownloadConcurrency,
 		AgentJobRetentionDays:       30,               // Default: 30 days
 		LRUEvictionMaxRetries:       30,               // Default: 30 retries
@@ -596,6 +598,10 @@ func WithAutoUpgradeBackends(v bool) AppOption {
 	return func(o *ApplicationConfig) { o.AutoUpgradeBackends = v }
 }
 
+func WithVRAMPersistentCache(v bool) AppOption {
+	return func(o *ApplicationConfig) { o.VRAMPersistentCache = v }
+}
+
 func WithRequireBackendIntegrity(v bool) AppOption {
 	return func(o *ApplicationConfig) { o.RequireBackendIntegrity = v }
 }

core/config/application_config_test.go

@@ -1,6 +1,7 @@
 package config
 
 import (
+	"encoding/json"
 	"time"
 
 	. "github.com/onsi/ginkgo/v2"
@@ -9,6 +10,15 @@ import (
 
 var _ = Describe("ApplicationConfig RuntimeSettings Conversion", func() {
 	Describe("ToRuntimeSettings", func() {
+		It("includes the persistent VRAM cache toggle", func() {
+			encoded, err := json.Marshal(NewApplicationConfig().ToRuntimeSettings())
+			Expect(err).NotTo(HaveOccurred())
+
+			var settings map[string]any
+			Expect(json.Unmarshal(encoded, &settings)).To(Succeed())
+			Expect(settings).To(HaveKeyWithValue("vram_persistent_cache", true))
+		})
+
 		It("should convert all fields correctly", func() {
 			appConfig := &ApplicationConfig{
 				WatchDog:                 true,

core/config/runtime_settings.go

@@ -59,6 +59,7 @@ type RuntimeSettings struct {
 	BackendGalleries         *[]Gallery `json:"backend_galleries,omitempty"`
 	AutoloadGalleries        *bool      `json:"autoload_galleries,omitempty"`
 	AutoloadBackendGalleries *bool      `json:"autoload_backend_galleries,omitempty"`
+	VRAMPersistentCache      *bool      `json:"vram_persistent_cache,omitempty"`
 
 	// API keys - No omitempty as we need to save empty arrays to clear keys
 	ApiKeys *[]string `json:"api_keys"`

core/config/runtime_settings_registry.go

@@ -328,6 +328,10 @@ var runtimeSettingsFields = []fieldSpec{
 		func(s *RuntimeSettings) **bool { return &s.AutoloadBackendGalleries },
 		func(o *ApplicationConfig) bool { return o.AutoloadBackendGalleries },
 		func(o *ApplicationConfig, v bool) { o.AutoloadBackendGalleries = v }),
+	field("vram_persistent_cache",
+		func(s *RuntimeSettings) **bool { return &s.VRAMPersistentCache },
+		func(o *ApplicationConfig) bool { return o.VRAMPersistentCache },
+		func(o *ApplicationConfig, v bool) { o.VRAMPersistentCache = v }),
 
 	// API keys: echoed for the UI, but the apply loops never touch them.
 	// The settings endpoint and the file watcher own the env+runtime merge

core/config/runtime_settings_startup.go

@@ -45,6 +45,7 @@ func DefaultRuntimeBaseline() *ApplicationConfig {
 	o.BackendGalleries = mustGalleries(DefaultBackendGalleriesJSON)
 	o.AutoloadGalleries = true
 	o.AutoloadBackendGalleries = true
+	o.VRAMPersistentCache = true
 	// core/cli/run.go injects WithMemoryReclaimer(enabled, threshold)
 	// unconditionally, so the kong threshold default (0.95) reaches the
 	// config even when the reclaimer flag is off - this overlay must match

core/gallery/gallery.go

@@ -16,6 +16,7 @@ import (
 	"github.com/mudler/LocalAI/pkg/downloader"
 	"github.com/mudler/LocalAI/pkg/system"
 	"github.com/mudler/LocalAI/pkg/utils"
+	"github.com/mudler/LocalAI/pkg/vram"
 	"github.com/mudler/LocalAI/pkg/xsync"
 	"github.com/mudler/xlog"
 
@@ -457,6 +458,9 @@ func triggerGalleryRefresh(galleries []config.Gallery, systemState *system.Syste
 			galleryGeneration.Add(1)
 		}
 		availableModelsMu.Unlock()
+		if changed {
+			vram.InvalidatePersistentCache()
+		}
 	}()
 }
 

core/http/endpoints/localai/settings.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"io"
 	"net/http"
+	"path/filepath"
 	"time"
 
 	"github.com/labstack/echo/v4"
@@ -12,6 +13,7 @@ import (
 	"github.com/mudler/LocalAI/core/http/endpoints/openresponses"
 	"github.com/mudler/LocalAI/core/p2p"
 	"github.com/mudler/LocalAI/core/schema"
+	"github.com/mudler/LocalAI/pkg/vram"
 	"github.com/mudler/LocalAI/pkg/vrambudget"
 	"github.com/mudler/xlog"
 )
@@ -185,6 +187,13 @@ func UpdateSettingsEndpoint(app *application.Application) echo.HandlerFunc {
 
 		// Apply settings using centralized method
 		watchdogChanged := appConfig.ApplyRuntimeSettings(&settings)
+		if settings.VRAMPersistentCache != nil || settings.AutoloadGalleries != nil {
+			if appConfig.VRAMPersistentCache && appConfig.AutoloadGalleries {
+				vram.ConfigurePersistentCache(filepath.Join(appConfig.SystemState.Model.ModelsPath, "..", "cache", "vram"), 24*time.Hour)
+			} else {
+				vram.DisablePersistentCache()
+			}
+		}
 
 		// Handle API keys specially (merge with startup keys)
 		if settings.ApiKeys != nil {

core/http/react-ui/e2e/settings-backend-logging.spec.js

@@ -18,6 +18,34 @@ test.describe('Settings - Backend Logging', () => {
     await expect(input).toHaveValue('4')
   })
 
+  test('persistent VRAM cache can be toggled', async ({ page }) => {
+    const row = page.locator('.form-row', { hasText: 'Persist remote VRAM estimates' })
+    await expect(row).toBeVisible()
+
+    const checkbox = row.locator('input[type="checkbox"]')
+    const wasChecked = await checkbox.isChecked()
+    await checkbox.locator('..').click()
+    if (wasChecked) {
+      await expect(checkbox).not.toBeChecked()
+    } else {
+      await expect(checkbox).toBeChecked()
+    }
+  })
+
+  test('gallery startup loading and pre-warming can be toggled together', async ({ page }) => {
+    const row = page.locator('.form-row', { hasText: 'Load and pre-warm galleries on boot' })
+    await expect(row).toBeVisible()
+
+    const checkbox = row.locator('input[type="checkbox"]')
+    const wasChecked = await checkbox.isChecked()
+    await checkbox.locator('..').click()
+    if (wasChecked) {
+      await expect(checkbox).not.toBeChecked()
+    } else {
+      await expect(checkbox).toBeChecked()
+    }
+  })
+
   test('backend logging toggle can be toggled', async ({ page }) => {
     // Find the checkbox associated with backend logging
     const section = page.locator('div', { has: page.locator('text=Enable Backend Logging') })

core/http/react-ui/src/pages/Settings.jsx

@@ -482,12 +482,15 @@ export default function Settings() {
               <i className="fas fa-images text-accent" /> Galleries
             </h3>
             <div className="card">
-              <SettingRow label="Autoload Galleries" description="Automatically load model galleries on startup">
+              <SettingRow label="Load and pre-warm galleries on boot" description="Load model galleries and pre-warm their remote size and VRAM estimates when LocalAI starts">
                 <Toggle checked={settings.autoload_galleries} onChange={(v) => update('autoload_galleries', v)} />
               </SettingRow>
               <SettingRow label="Autoload Backend Galleries" description="Automatically load backend galleries on startup">
                 <Toggle checked={settings.autoload_backend_galleries} onChange={(v) => update('autoload_backend_galleries', v)} />
               </SettingRow>
+              <SettingRow label="Persist remote VRAM estimates" description="Reuse successful remote model metadata probes across restarts; disabled when gallery autoload is off">
+                <Toggle checked={settings.vram_persistent_cache} onChange={(v) => update('vram_persistent_cache', v)} />
+              </SettingRow>
               <div className="mt-sm">
                 <label className="form-label">Model Galleries (JSON)</label>
                 <textarea

docs/content/advanced/vram-management.md

@@ -460,8 +460,16 @@ context lengths, so you can see whether something will run before installing it.
 Working that out means reading the metadata of a model's weight files, which for
 a model you have not installed is a request to the host that serves them. It
 takes a second or two the first time, and the gallery needs one per row. LocalAI
-caches the result, and warms that cache in the background at startup so the
-gallery reads instantly rather than filling in its own numbers while you watch.
+caches successful remote probes for 24 hours under the LocalAI data directory,
+and warms that cache in the background at startup so the gallery reads instantly
+rather than filling in its own numbers while you watch. The on-disk cache is
+reused after a restart, so frequent restarts do not download the same metadata
+again. Local model files are always inspected directly. The cache keeps at most
+4,096 entries and removes the oldest entries when it reaches that limit.
+Disable **Persist remote VRAM estimates** under **Settings > Galleries**, or set
+`LOCALAI_VRAM_PERSISTENT_CACHE=false`, to keep estimates in memory only. Setting
+`LOCALAI_AUTOLOAD_GALLERIES=false` also disables the startup warmer and the
+persistent cache.
 
 The same warm-up also describes each entry's **variants** - the alternative
 builds of the same weights that the picker offers - because that costs the same

docs/content/features/runtime-settings.md

@@ -82,7 +82,7 @@ Manage model and backend galleries:
 
 - **Model Galleries**: JSON array of gallery objects with `url` and `name` fields, plus an optional `mirrors` list of fallback URLs (see [Gallery mirrors]({{%relref "features/model-gallery#gallery-mirrors" %}}))
 - **Backend Galleries**: JSON array of backend gallery objects, which accept the same `mirrors` key
-- **Autoload Galleries**: Automatically load model galleries on startup
+- **Load and pre-warm galleries on boot**: Load model galleries and pre-warm their remote size and VRAM estimates when LocalAI starts. Disable this setting to skip both startup operations.
 - **Autoload Backend Galleries**: Automatically load backend galleries on startup
 
 ### Agent Pool Settings
@@ -164,6 +164,7 @@ The `runtime_settings.json` file follows this structure:
   ],
   "autoload_galleries": true,
   "autoload_backend_galleries": true,
+  "vram_persistent_cache": true,
   "api_keys": []
 }
 ```

docs/content/reference/cli-reference.md

@@ -61,6 +61,7 @@ For more information on VRAM management, see [VRAM and Memory Management]({{%rel
 |-----------|---------|-------------|----------------------|
 | `--galleries` | | JSON list of galleries | `$LOCALAI_GALLERIES`, `$GALLERIES` |
 | `--autoload-galleries` | `true` | Automatically load galleries on startup | `$LOCALAI_AUTOLOAD_GALLERIES`, `$AUTOLOAD_GALLERIES` |
+| `--vram-persistent-cache` | `true` | Persist successful remote VRAM metadata probes across restarts | `$LOCALAI_VRAM_PERSISTENT_CACHE`, `$VRAM_PERSISTENT_CACHE` |
 | `--preload-models` | | A list of models to apply in JSON at start | `$LOCALAI_PRELOAD_MODELS`, `$PRELOAD_MODELS` |
 | `--models` | | A list of model configuration URLs to load | `$LOCALAI_MODELS`, `$MODELS` |
 | `--preload-models-config` | | A list of models to apply at startup. Path to a YAML config file | `$LOCALAI_PRELOAD_MODELS_CONFIG`, `$PRELOAD_MODELS_CONFIG` |

pkg/vram/cache.go

@@ -2,9 +2,24 @@ package vram
 
 import (
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"net/url"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
 	"sync"
+	"time"
 )
 
+const persistentCacheEntryLimit = 4096
+const persistentCacheVersion = 1
+
+var defaultPersistentGuard = &persistentGenerationGuard{}
+var defaultCacheMu sync.RWMutex
+
 // galleryGenFunc returns the current gallery generation counter.
 // When set, cache entries are invalidated when the generation changes.
 // When nil (e.g., in tests or non-gallery contexts), entries never expire.
@@ -23,6 +38,149 @@ func currentGeneration() uint64 {
 	return 0
 }
 
+// ConfigurePersistentCache replaces the process-wide estimator caches with
+// instances that reuse successful remote probes across server restarts.
+func ConfigurePersistentCache(dir string, ttl time.Duration) {
+	defaultCacheMu.Lock()
+	defer defaultCacheMu.Unlock()
+	removeAbandonedPersistentTemps(dir)
+	prunePersistentEntries(dir, ttl, persistentCacheEntryLimit)
+	guard := &persistentGenerationGuard{dir: dir}
+	defaultPersistentGuard = guard
+	defaultCachedSizeResolver = newCachedSizeResolverWithGuard(defaultSizeResolver{}, dir, ttl, guard)
+	defaultCachedGGUFReader = newCachedGGUFReaderWithGuard(defaultGGUFReader{}, dir, ttl, guard)
+}
+
+// DisablePersistentCache keeps process-local caching but stops disk reads and writes.
+func DisablePersistentCache() {
+	defaultCacheMu.Lock()
+	defer defaultCacheMu.Unlock()
+	defaultPersistentGuard = &persistentGenerationGuard{}
+	defaultCachedSizeResolver = newCachedSizeResolver(defaultSizeResolver{}, "", 0)
+	defaultCachedGGUFReader = newCachedGGUFReader(defaultGGUFReader{}, "", 0)
+}
+
+// InvalidatePersistentCache removes remote probe results after the gallery
+// changes, including when no estimate is requested before the next restart.
+func InvalidatePersistentCache() {
+	defaultCacheMu.RLock()
+	guard := defaultPersistentGuard
+	defaultCacheMu.RUnlock()
+	guard.invalidate(currentGeneration())
+}
+
+func removeAbandonedPersistentTemps(dir string) {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return
+	}
+	for _, entry := range entries {
+		if entry.Type().IsRegular() && strings.HasPrefix(entry.Name(), ".vram-") {
+			_ = os.Remove(filepath.Join(dir, entry.Name()))
+		}
+	}
+}
+
+func removePersistentEntries(dir string) {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return
+	}
+	for _, entry := range entries {
+		name := entry.Name()
+		if entry.Type().IsRegular() && (strings.HasPrefix(name, "size-") || strings.HasPrefix(name, "gguf-")) {
+			_ = os.Remove(filepath.Join(dir, name))
+		}
+	}
+}
+
+type persistentGenerationGuard struct {
+	mu         sync.Mutex
+	dir        string
+	generation uint64
+	set        bool
+}
+
+func (g *persistentGenerationGuard) invalidate(generation uint64) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	removePersistentEntries(g.dir)
+	g.generation = generation
+	g.set = true
+}
+
+func (g *persistentGenerationGuard) canRead(generation uint64) bool {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if !g.set {
+		g.generation = generation
+		g.set = true
+		return true
+	}
+	if g.generation == generation {
+		return true
+	}
+	removePersistentEntries(g.dir)
+	g.generation = generation
+	return false
+}
+
+func (g *persistentGenerationGuard) persist(generation uint64, write func()) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if !g.set {
+		g.generation = generation
+		g.set = true
+	}
+	if g.generation == generation {
+		write()
+	}
+}
+
+func prunePersistentEntries(dir string, ttl time.Duration, limit int) {
+	if dir == "" || ttl <= 0 {
+		return
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return
+	}
+	type cacheFile struct {
+		path    string
+		modTime time.Time
+	}
+	files := make([]cacheFile, 0, len(entries))
+	for _, entry := range entries {
+		name := entry.Name()
+		if entry.Type().IsRegular() && (strings.HasPrefix(name, "size-") || strings.HasPrefix(name, "gguf-")) {
+			if info, err := entry.Info(); err == nil {
+				path := filepath.Join(dir, name)
+				if time.Since(info.ModTime()) > ttl {
+					_ = os.Remove(path)
+					continue
+				}
+				files = append(files, cacheFile{path: path, modTime: info.ModTime()})
+			}
+		}
+	}
+	if limit <= 0 || len(files) <= limit {
+		return
+	}
+	sort.Slice(files, func(i, j int) bool { return files[i].modTime.Before(files[j].modTime) })
+	for _, file := range files[:len(files)-limit] {
+		_ = os.Remove(file.path)
+	}
+}
+
+func persistentRemoteURI(uri string) bool {
+	parsed, err := url.Parse(uri)
+	if err != nil {
+		return false
+	}
+	scheme := strings.ToLower(parsed.Scheme)
+	return (scheme == "http" || scheme == "https") && parsed.Host != ""
+}
+
 type sizeCacheEntry struct {
 	size       int64
 	err        error
@@ -33,6 +191,28 @@ type cachedSizeResolver struct {
 	underlying SizeResolver
 	mu         sync.Mutex
 	cache      map[string]sizeCacheEntry
+	diskDir    string
+	diskTTL    time.Duration
+	diskGuard  *persistentGenerationGuard
+}
+
+type persistentSizeEntry struct {
+	Version int   `json:"version"`
+	Size    int64 `json:"size"`
+}
+
+func newCachedSizeResolver(underlying SizeResolver, diskDir string, diskTTL time.Duration) *cachedSizeResolver {
+	return newCachedSizeResolverWithGuard(underlying, diskDir, diskTTL, &persistentGenerationGuard{dir: diskDir})
+}
+
+func newCachedSizeResolverWithGuard(underlying SizeResolver, diskDir string, diskTTL time.Duration, guard *persistentGenerationGuard) *cachedSizeResolver {
+	return &cachedSizeResolver{
+		underlying: underlying,
+		cache:      make(map[string]sizeCacheEntry),
+		diskDir:    diskDir,
+		diskTTL:    diskTTL,
+		diskGuard:  guard,
+	}
 }
 
 func (c *cachedSizeResolver) ContentLength(ctx context.Context, uri string) (int64, error) {
@@ -43,13 +223,62 @@ func (c *cachedSizeResolver) ContentLength(ctx context.Context, uri string) (int
 	if ok && e.generation == gen {
 		return e.size, e.err
 	}
+	if persistentRemoteURI(uri) && c.canReadPersistent(gen) {
+		if size, ok := c.readPersistent(uri); ok {
+			c.mu.Lock()
+			c.cache[uri] = sizeCacheEntry{size: size, generation: gen}
+			c.mu.Unlock()
+			return size, nil
+		}
+	}
 	size, err := c.underlying.ContentLength(ctx, uri)
 	c.mu.Lock()
 	c.cache[uri] = sizeCacheEntry{size: size, err: err, generation: gen}
 	c.mu.Unlock()
+	if err == nil && persistentRemoteURI(uri) {
+		c.writePersistent(uri, size, gen)
+	}
 	return size, err
 }
 
+func (c *cachedSizeResolver) canReadPersistent(generation uint64) bool {
+	return c.diskGuard.canRead(generation)
+}
+
+func (c *cachedSizeResolver) persistentPath(uri string) string {
+	digest := sha256.Sum256([]byte(uri))
+	return filepath.Join(c.diskDir, "size-"+hex.EncodeToString(digest[:])+".json")
+}
+
+func (c *cachedSizeResolver) readPersistent(uri string) (int64, bool) {
+	if c.diskDir == "" || c.diskTTL <= 0 {
+		return 0, false
+	}
+	path := c.persistentPath(uri)
+	info, err := os.Stat(path)
+	if err != nil || time.Since(info.ModTime()) > c.diskTTL {
+		return 0, false
+	}
+	data, err := os.ReadFile(path) // #nosec G304 -- path is a hash under the configured cache directory.
+	if err != nil {
+		return 0, false
+	}
+	var entry persistentSizeEntry
+	if json.Unmarshal(data, &entry) != nil || entry.Version != persistentCacheVersion || entry.Size <= 0 {
+		return 0, false
+	}
+	return entry.Size, true
+}
+
+func (c *cachedSizeResolver) writePersistent(uri string, size int64, generation uint64) {
+	if c.diskDir == "" || c.diskTTL <= 0 || os.MkdirAll(c.diskDir, 0o750) != nil {
+		return
+	}
+	c.diskGuard.persist(generation, func() {
+		writePersistentJSON(c.persistentPath(uri), persistentSizeEntry{Version: persistentCacheVersion, Size: size}, c.diskTTL)
+	})
+}
+
 type ggufCacheEntry struct {
 	meta       *GGUFMeta
 	err        error
@@ -60,6 +289,28 @@ type cachedGGUFReader struct {
 	underlying GGUFMetadataReader
 	mu         sync.Mutex
 	cache      map[string]ggufCacheEntry
+	diskDir    string
+	diskTTL    time.Duration
+	diskGuard  *persistentGenerationGuard
+}
+
+type persistentGGUFEntry struct {
+	Version int       `json:"version"`
+	Meta    *GGUFMeta `json:"meta"`
+}
+
+func newCachedGGUFReader(underlying GGUFMetadataReader, diskDir string, diskTTL time.Duration) *cachedGGUFReader {
+	return newCachedGGUFReaderWithGuard(underlying, diskDir, diskTTL, &persistentGenerationGuard{dir: diskDir})
+}
+
+func newCachedGGUFReaderWithGuard(underlying GGUFMetadataReader, diskDir string, diskTTL time.Duration, guard *persistentGenerationGuard) *cachedGGUFReader {
+	return &cachedGGUFReader{
+		underlying: underlying,
+		cache:      make(map[string]ggufCacheEntry),
+		diskDir:    diskDir,
+		diskTTL:    diskTTL,
+		diskGuard:  guard,
+	}
 }
 
 func (c *cachedGGUFReader) ReadMetadata(ctx context.Context, uri string) (*GGUFMeta, error) {
@@ -70,26 +321,106 @@ func (c *cachedGGUFReader) ReadMetadata(ctx context.Context, uri string) (*GGUFM
 	if ok && e.generation == gen {
 		return e.meta, e.err
 	}
+	if persistentRemoteURI(uri) && c.canReadPersistent(gen) {
+		if meta, ok := c.readPersistent(uri); ok {
+			c.mu.Lock()
+			c.cache[uri] = ggufCacheEntry{meta: meta, generation: gen}
+			c.mu.Unlock()
+			return meta, nil
+		}
+	}
 	meta, err := c.underlying.ReadMetadata(ctx, uri)
 	c.mu.Lock()
 	c.cache[uri] = ggufCacheEntry{meta: meta, err: err, generation: gen}
 	c.mu.Unlock()
+	if err == nil && meta != nil && persistentRemoteURI(uri) {
+		c.writePersistent(uri, meta, gen)
+	}
 	return meta, err
 }
 
+func (c *cachedGGUFReader) canReadPersistent(generation uint64) bool {
+	return c.diskGuard.canRead(generation)
+}
+
+func (c *cachedGGUFReader) persistentPath(uri string) string {
+	digest := sha256.Sum256([]byte(uri))
+	return filepath.Join(c.diskDir, "gguf-"+hex.EncodeToString(digest[:])+".json")
+}
+
+func (c *cachedGGUFReader) readPersistent(uri string) (*GGUFMeta, bool) {
+	if c.diskDir == "" || c.diskTTL <= 0 {
+		return nil, false
+	}
+	path := c.persistentPath(uri)
+	info, err := os.Stat(path)
+	if err != nil || time.Since(info.ModTime()) > c.diskTTL {
+		return nil, false
+	}
+	data, err := os.ReadFile(path) // #nosec G304 -- path is a hash under the configured cache directory.
+	if err != nil {
+		return nil, false
+	}
+	var entry persistentGGUFEntry
+	if json.Unmarshal(data, &entry) != nil || entry.Version != persistentCacheVersion || !validPersistentGGUFMeta(entry.Meta) {
+		return nil, false
+	}
+	return entry.Meta, true
+}
+
+func (c *cachedGGUFReader) writePersistent(uri string, meta *GGUFMeta, generation uint64) {
+	if c.diskDir == "" || c.diskTTL <= 0 || os.MkdirAll(c.diskDir, 0o750) != nil {
+		return
+	}
+	c.diskGuard.persist(generation, func() {
+		writePersistentJSON(c.persistentPath(uri), persistentGGUFEntry{Version: persistentCacheVersion, Meta: meta}, c.diskTTL)
+	})
+}
+
+func validPersistentGGUFMeta(meta *GGUFMeta) bool {
+	return meta != nil && meta.BlockCount > 0 && meta.EmbeddingLength > 0 && meta.HeadCount > 0 && meta.HeadCountKV > 0
+}
+
+func writePersistentJSON(path string, value any, ttl time.Duration) {
+	data, err := json.Marshal(value)
+	if err != nil {
+		return
+	}
+	tmp, err := os.CreateTemp(filepath.Dir(path), ".vram-*.tmp")
+	if err != nil {
+		return
+	}
+	tmpPath := tmp.Name()
+	defer func() { _ = os.Remove(tmpPath) }()
+	if _, err = tmp.Write(data); err != nil {
+		_ = tmp.Close()
+		return
+	}
+	if err = tmp.Close(); err != nil {
+		return
+	}
+	if os.Rename(tmpPath, path) == nil {
+		prunePersistentEntries(filepath.Dir(path), ttl, persistentCacheEntryLimit)
+	}
+}
+
 // DefaultCachedSizeResolver returns a cached SizeResolver using the default implementation.
 // Entries are invalidated when the gallery generation changes.
 func DefaultCachedSizeResolver() SizeResolver {
+	defaultCacheMu.RLock()
+	defer defaultCacheMu.RUnlock()
 	return defaultCachedSizeResolver
 }
 
 // DefaultCachedGGUFReader returns a cached GGUFMetadataReader using the default implementation.
 // Entries are invalidated when the gallery generation changes.
 func DefaultCachedGGUFReader() GGUFMetadataReader {
+	defaultCacheMu.RLock()
+	defer defaultCacheMu.RUnlock()
 	return defaultCachedGGUFReader
 }
 
 var (
-	defaultCachedSizeResolver = &cachedSizeResolver{underlying: defaultSizeResolver{}, cache: make(map[string]sizeCacheEntry)}
-	defaultCachedGGUFReader   = &cachedGGUFReader{underlying: defaultGGUFReader{}, cache: make(map[string]ggufCacheEntry)}
+	defaultCachedSizeResolver = newCachedSizeResolver(defaultSizeResolver{}, "", 0)
+	defaultCachedGGUFReader   = newCachedGGUFReader(defaultGGUFReader{}, "", 0)
 )

pkg/vram/cache_persistent_test.go

@@ -0,0 +1,228 @@
+package vram
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+type countingSizeResolver struct {
+	size  int64
+	err   error
+	calls int
+}
+
+type countingGGUFReader struct {
+	meta  *GGUFMeta
+	err   error
+	calls int
+}
+
+type blockingSizeResolver struct {
+	started chan struct{}
+	release chan struct{}
+}
+
+func (r *blockingSizeResolver) ContentLength(context.Context, string) (int64, error) {
+	close(r.started)
+	<-r.release
+	return 42, nil
+}
+
+func (r *countingGGUFReader) ReadMetadata(context.Context, string) (*GGUFMeta, error) {
+	r.calls++
+	return r.meta, r.err
+}
+
+func (r *countingSizeResolver) ContentLength(context.Context, string) (int64, error) {
+	r.calls++
+	return r.size, r.err
+}
+
+var _ = Describe("persistent VRAM metadata cache", func() {
+	AfterEach(func() {
+		ConfigurePersistentCache("", 0)
+		SetGalleryGenerationFunc(nil)
+	})
+
+	It("reuses a successful size probe after the in-memory cache is replaced", func() {
+		cacheDir := filepath.Join(GinkgoT().TempDir(), "vram")
+		firstSource := &countingSizeResolver{size: 42}
+		first := newCachedSizeResolver(firstSource, cacheDir, time.Hour)
+
+		size, err := first.ContentLength(context.Background(), "https://example.com/model.gguf")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(size).To(Equal(int64(42)))
+		Expect(firstSource.calls).To(Equal(1))
+
+		secondSource := &countingSizeResolver{err: errors.New("unexpected remote probe")}
+		second := newCachedSizeResolver(secondSource, cacheDir, time.Hour)
+		size, err = second.ContentLength(context.Background(), "https://example.com/model.gguf")
+
+		Expect(err).NotTo(HaveOccurred())
+		Expect(size).To(Equal(int64(42)))
+		Expect(secondSource.calls).To(BeZero())
+	})
+
+	It("reuses successful GGUF metadata after the in-memory cache is replaced", func() {
+		cacheDir := filepath.Join(GinkgoT().TempDir(), "vram")
+		want := &GGUFMeta{BlockCount: 32, EmbeddingLength: 4096, HeadCount: 32, HeadCountKV: 8, MaximumContextLength: 131072}
+		firstSource := &countingGGUFReader{meta: want}
+		first := newCachedGGUFReader(firstSource, cacheDir, time.Hour)
+
+		meta, err := first.ReadMetadata(context.Background(), "https://example.com/model.gguf")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(meta).To(Equal(want))
+		Expect(firstSource.calls).To(Equal(1))
+
+		secondSource := &countingGGUFReader{err: errors.New("unexpected remote probe")}
+		second := newCachedGGUFReader(secondSource, cacheDir, time.Hour)
+		meta, err = second.ReadMetadata(context.Background(), "https://example.com/model.gguf")
+
+		Expect(err).NotTo(HaveOccurred())
+		Expect(meta).To(Equal(want))
+		Expect(secondSource.calls).To(BeZero())
+	})
+
+	It("configures the default caches used by model estimates", func() {
+		cacheDir := filepath.Join(GinkgoT().TempDir(), "vram")
+		ConfigurePersistentCache(cacheDir, time.Hour)
+
+		Expect(defaultCachedSizeResolver.diskDir).To(Equal(cacheDir))
+		Expect(defaultCachedGGUFReader.diskDir).To(Equal(cacheDir))
+		Expect(defaultCachedSizeResolver.diskTTL).To(Equal(time.Hour))
+		Expect(defaultCachedGGUFReader.diskTTL).To(Equal(time.Hour))
+		Expect(defaultCachedSizeResolver.diskGuard).To(BeIdenticalTo(defaultCachedGGUFReader.diskGuard))
+	})
+
+	It("removes expired VRAM entries when the persistent cache is configured", func() {
+		cacheDir := GinkgoT().TempDir()
+		stale := filepath.Join(cacheDir, "size-stale.json")
+		abandoned := filepath.Join(cacheDir, ".vram-abandoned.tmp")
+		unrelated := filepath.Join(cacheDir, "keep.txt")
+		Expect(os.WriteFile(stale, []byte("{}"), 0o600)).To(Succeed())
+		Expect(os.WriteFile(abandoned, []byte("partial"), 0o600)).To(Succeed())
+		Expect(os.WriteFile(unrelated, []byte("keep"), 0o600)).To(Succeed())
+		old := time.Now().Add(-2 * time.Hour)
+		Expect(os.Chtimes(stale, old, old)).To(Succeed())
+
+		ConfigurePersistentCache(cacheDir, time.Hour)
+
+		Expect(stale).NotTo(BeAnExistingFile())
+		Expect(abandoned).NotTo(BeAnExistingFile())
+		Expect(unrelated).To(BeAnExistingFile())
+	})
+
+	It("does not reuse a persistent entry after the gallery generation changes", func() {
+		var generation uint64 = 1
+		SetGalleryGenerationFunc(func() uint64 { return generation })
+		cacheDir := GinkgoT().TempDir()
+		first := newCachedSizeResolver(&countingSizeResolver{size: 42}, cacheDir, time.Hour)
+		_, err := first.ContentLength(context.Background(), "https://example.com/model.gguf")
+		Expect(err).NotTo(HaveOccurred())
+
+		freshSource := &countingSizeResolver{size: 84}
+		second := newCachedSizeResolver(freshSource, cacheDir, time.Hour)
+		size, err := second.ContentLength(context.Background(), "https://example.com/model.gguf")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(size).To(Equal(int64(42)))
+
+		generation = 2
+		size, err = second.ContentLength(context.Background(), "https://example.com/model.gguf")
+
+		Expect(err).NotTo(HaveOccurred())
+		Expect(size).To(Equal(int64(84)))
+		Expect(freshSource.calls).To(Equal(1))
+	})
+
+	It("does not persist probes for local model files", func() {
+		cacheDir := GinkgoT().TempDir()
+		first := newCachedSizeResolver(&countingSizeResolver{size: 42}, cacheDir, time.Hour)
+		_, err := first.ContentLength(context.Background(), "file:///models/model.gguf")
+		Expect(err).NotTo(HaveOccurred())
+
+		freshSource := &countingSizeResolver{size: 84}
+		second := newCachedSizeResolver(freshSource, cacheDir, time.Hour)
+		size, err := second.ContentLength(context.Background(), "file:///models/model.gguf")
+
+		Expect(err).NotTo(HaveOccurred())
+		Expect(size).To(Equal(int64(84)))
+		Expect(freshSource.calls).To(Equal(1))
+	})
+
+	It("falls back to the remote probe for an invalid persisted size", func() {
+		cacheDir := GinkgoT().TempDir()
+		resolver := newCachedSizeResolver(&countingSizeResolver{size: 42}, cacheDir, time.Hour)
+		Expect(os.WriteFile(resolver.persistentPath("https://example.com/model.gguf"), []byte(`{"size":-1}`), 0o600)).To(Succeed())
+
+		size, err := resolver.ContentLength(context.Background(), "https://example.com/model.gguf")
+
+		Expect(err).NotTo(HaveOccurred())
+		Expect(size).To(Equal(int64(42)))
+	})
+
+	It("falls back to the remote probe for empty persisted GGUF metadata", func() {
+		cacheDir := GinkgoT().TempDir()
+		want := &GGUFMeta{BlockCount: 32, EmbeddingLength: 4096, HeadCount: 32, HeadCountKV: 8}
+		reader := newCachedGGUFReader(&countingGGUFReader{meta: want}, cacheDir, time.Hour)
+		Expect(os.WriteFile(reader.persistentPath("https://example.com/model.gguf"), []byte(`{"meta":{}}`), 0o600)).To(Succeed())
+
+		meta, err := reader.ReadMetadata(context.Background(), "https://example.com/model.gguf")
+
+		Expect(err).NotTo(HaveOccurred())
+		Expect(meta).To(Equal(want))
+	})
+
+	It("keeps the persistent cache within its entry limit", func() {
+		cacheDir := GinkgoT().TempDir()
+		for _, name := range []string{"size-a.json", "size-b.json", "gguf-c.json"} {
+			Expect(os.WriteFile(filepath.Join(cacheDir, name), []byte("{}"), 0o600)).To(Succeed())
+			time.Sleep(time.Millisecond)
+		}
+
+		prunePersistentEntries(cacheDir, time.Hour, 2)
+
+		entries, err := os.ReadDir(cacheDir)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(entries).To(HaveLen(2))
+		Expect(filepath.Join(cacheDir, "size-a.json")).NotTo(BeAnExistingFile())
+	})
+
+	It("removes persistent entries when gallery data is invalidated", func() {
+		cacheDir := GinkgoT().TempDir()
+		ConfigurePersistentCache(cacheDir, time.Hour)
+		stale := filepath.Join(cacheDir, "size-stale.json")
+		Expect(os.WriteFile(stale, []byte(`{"version":1,"size":42}`), 0o600)).To(Succeed())
+
+		InvalidatePersistentCache()
+
+		Expect(stale).NotTo(BeAnExistingFile())
+	})
+
+	It("does not persist a probe that finishes after invalidation", func() {
+		var generation uint64 = 1
+		SetGalleryGenerationFunc(func() uint64 { return generation })
+		cacheDir := GinkgoT().TempDir()
+		guard := &persistentGenerationGuard{dir: cacheDir}
+		source := &blockingSizeResolver{started: make(chan struct{}), release: make(chan struct{})}
+		resolver := newCachedSizeResolverWithGuard(source, cacheDir, time.Hour, guard)
+		done := make(chan error, 1)
+		go func() {
+			_, err := resolver.ContentLength(context.Background(), "https://example.com/model.gguf")
+			done <- err
+		}()
+		Eventually(source.started).Should(BeClosed())
+
+		generation = 2
+		guard.invalidate(generation)
+		close(source.release)
+
+		Eventually(done).Should(Receive(BeNil()))
+		Expect(resolver.persistentPath("https://example.com/model.gguf")).NotTo(BeAnExistingFile())
+	})
+})