Skip to content
Get packs

Guide · Agent skill

How to use the hf-mem agent skill to estimate model memory

Updated · written with AI from the project's own documentation and checked against our catalogue data

hf-mem is an agent skill from the huggingface/skills repository that lets an AI agent look up a model on the Hugging Face Hub and report how much memory it needs for inference. It covers the model weights and, optionally, the KV cache for language models. This guide explains what the skill does, how to install it, how to ask for it in plain language, and what to watch for, so you can decide whether a model will fit on your GPU or cloud instance.

Hugging Face Model Memory Estimatorhuggingface/skills · Apache-2.0

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for all projects, or in a project's .claude/skills/ folder.
  2. 2Install uv. Install uv so the skill can run hf-mem with the uvx command.
  3. 3Set a token if needed. For gated or private models, set HF_TOKEN or pass --hf-token. Public models do not need one.
  4. 4Ask a natural question. Name a Hugging Face model and ask how much memory it needs or whether it fits your GPU.
  5. 5Add KV cache if relevant. For a language model and a context length question, ask for the KV cache estimate, which uses the --experimental flag.
  6. 6Target a GGUF file. For GGUF repositories with several quantizations, name the quantization or file so the estimate covers only the one you will run.

What an agent skill is and what hf-mem makes the agent do

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific task. When the task matches the skill, the agent follows those instructions and can run the commands they describe.

Once hf-mem is installed, the agent can take a Hugging Face model ID or URL and estimate the memory required to load it for inference. The estimate covers the model weights. For large language models it can also include the KV cache when you ask for it. The skill supports Safetensors and GGUF model formats.

  • Estimates VRAM or RAM needed for inference
  • Covers model weights, with optional KV cache estimation for language models
  • Reads only file sizes and headers over HTTP Range requests, so it does not download or load the full weights

Install the hf-mem skill with a ZIP file

Download the ZIP for the skill from this page and unzip it. The skill's only file is SKILL.md.

For a personal install that applies to all your projects, unzip it into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills

Install uv and set up a Hugging Face token

hf-mem is run with uvx, which comes with uv. Install uv first, since the skill needs it to run the tool.

You only need a token for gated or private models. Set the HF_TOKEN environment variable, or pass the token with the --hf-token flag. Without a token, the Hub will refuse access to those models.

  • uv must be installed (it provides the uvx command)
  • HF_TOKEN environment variable or --hf-token flag, only for gated or private models
  • Network access to the Hugging Face Hub is required

Ask for the memory estimate in natural language

You do not need to type commands yourself. The skill is meant to trigger when you ask how much VRAM or memory a model needs, ask whether a model fits on your GPU or a given instance, or mention a Hugging Face model ID or URL while asking about inference requirements.

Be specific about what you want. If you care about context length or KV cache, say so, because the KV cache estimate is an optional extra.

  • How much VRAM does MiniMaxAI/MiniMax-M2 need to run?
  • Will mistralai/Mistral-7B-v0.1 fit on a 24 GB GPU with a 4k context?
  • Compare the memory needs of the Q4_K_M and Q8_0 GGUF files for this model.
  • Estimate memory for this model at a 32k context length with an fp8 KV cache.

Run the commands the skill uses

The skill runs hf-mem through uvx. The basic call takes a model ID and returns JSON output. The repository must contain Safetensors weights (model.safetensors, model.safetensors.index.json if sharded, or model_index.json for Diffusers) or GGUF weights.

For GGUF repositories with several quantizations, estimates are per file. Use --gguf-file to target the file you plan to run. To include KV cache, add --experimental. You can set --max-model-len, --batch-size and --kv-cache-dtype to match the vLLM options of the same names.

  • --model-id: the Hub repository to check
  • --gguf-file: the GGUF file or path to estimate
  • --experimental: adds KV cache memory for LLMs (...ForCausalLM), VLMs (...ForConditionalGeneration) and GGUF models
  • --max-model-len: overrides the default context window
  • --kv-cache-dtype: sets KV cache precision, which otherwise defaults to the model precision
uvx hf-mem --model-id <model-id> --json-output

Examples of model memory checks

These examples come from the skill's documentation. They show a Transformers model with Safetensors, a Diffusers model, a Sentence Transformers model, a language model with KV cache, and a GGUF language model with a chosen quantization.

  • Transformers with Safetensors: MiniMaxAI/MiniMax-M2
  • Diffusers with Safetensors: Qwen/Qwen-Image
  • Sentence Transformers with Safetensors: google/embeddinggemma-300m
  • Language model with KV cache: mistralai/Mistral-7B-v0.1 (with --experimental)
  • GGUF language model: unsloth/Qwen3.5-397B-A17B-GGUF with --gguf-file Q4_K_M
uvx hf-mem --model-id mistralai/Mistral-7B-v0.1 --experimental --json-output

Safety notes: scripts and network access

hf-mem runs scripts and uses the network. It contacts the Hugging Face Hub to read file sizes and headers over HTTP Range requests. It does not download the full weights, according to the skill's description.

Review the skill and the tool before running it on a machine with sensitive data. If you use a token, keep HF_TOKEN private and only supply it for models that need it.

  • Runs scripts: yes
  • Uses network: yes, to reach the Hugging Face Hub
  • Only needs a token for gated or private models

What people use it for

  • Checking whether a large language model fits on a single GPU before renting an instance
  • Comparing quantizations of a GGUF model such as Q4_K_M and Q8_0 before downloading one
  • Planning context length and KV cache precision for a long-context chat deployment
  • Checking memory needs for a Diffusers image model or a Sentence Transformers embedding model

Frequently asked questions

Is the hf-mem agent skill free to use?

The skill is published under the Apache-2.0 licence in the huggingface/skills repository. The source for this page does not describe pricing, so check the repository for any terms that apply to your use.

How do I install hf-mem?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, upload it under Settings, Capabilities, Skills. You also need uv installed so the uvx command works.

What do I need to run hf-mem?

You need uv installed, which provides the uvx command, and network access to the Hugging Face Hub. An HF_TOKEN environment variable or the --hf-token flag is only needed for gated or private models.

Does hf-mem download the whole model?

No. According to the skill's description, it estimates memory using HTTP Range requests, so it reads file sizes and headers without downloading or loading the weights locally.

Which model formats does hf-mem support?

It supports Safetensors and GGUF. It does not cover other formats. Safetensors repositories need model.safetensors, model.safetensors.index.json if sharded, or model_index.json for Diffusers.

Can hf-mem predict speed or exact performance?

No. The skill only estimates memory from file metadata and formulas. It is not meant for exact performance or speed predictions, so use it to check whether a model fits, not how fast it will run.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

hf-mem suits developers and engineers who want a quick, low-cost memory check before downloading or renting hardware, especially for comparing GGUF quantizations and planning KV cache. It is a poor choice if you need exact speed or latency numbers, or if your models are in formats other than Safetensors or GGUF.

Download the skill