Model cache should respect XDG_CACHE_HOME environment variable

[jasikpark]

Problem

QMD's model downloads ignore the XDG_CACHE_HOME environment variable and always use ~/.cache/qmd/models/, even when XDG_CACHE_HOME is set to a different location.

This is inconsistent with:

• The collection config path, which correctly respects XDG_CONFIG_HOME (fixed in fix: respect XDG_CONFIG_HOME in collection config path #190)
• The XDG Base Directory Specification
• User expectations for containerized/multi-user environments

Current Behavior

src/llm.ts:212 hardcodes the model cache directory:

const MODEL_CACHE_DIR = join(homedir(), ".cache", "qmd", "models");

This means:

• Models always download to ~/.cache/qmd/models/
• Setting XDG_CACHE_HOME=/custom/path/.cache has no effect on model location
• Only the index database respects XDG_CACHE_HOME

Expected Behavior

Models should respect XDG_CACHE_HOME when set, following the same pattern as the collection config fix in commit 8c2282c:

const MODEL_CACHE_DIR = process.env.XDG_CACHE_HOME 
  ? join(process.env.XDG_CACHE_HOME, "qmd", "models")
  : join(homedir(), ".cache", "qmd", "models");

Use Case

In containerized environments (Docker, OpenClaw agents, etc.), we set XDG_CACHE_HOME to persistent storage locations so models survive container rebuilds. Currently we need workarounds like symlinking ~/.cache/qmd/models to the XDG location.

Impact

Models are 2.1GB total (query-expansion 1.2GB + embedding 314MB + reranker 610MB), so having them in the wrong location can mean:

• Lost models on container rebuild
• Duplicate storage when models exist in both locations
• Breaking established XDG patterns

Environment

• QMD version: 2.0.1 (latest on main as of 2026-03-17)
• Node.js: v22.22.0
• OS: Linux (container)

Related

• PR fix: respect XDG_CONFIG_HOME in collection config path #190 / commit 8c2282c - Fixed XDG_CONFIG_HOME for collection config
• XDG Base Directory Specification: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html