Needle 2 Binary Size: A Lightweight 14 MB Engine Explained

The Needle 2 binary size is 14 MB, delivered as a single core inference engine that downloads once from Hugging Face and caches locally for all subsequent runs.

The cactus-compute/needle repository is built around a minimal footprint philosophy, and the Needle 2 binary size reflects that design. Weighing just 14 MB on disk, the engine runs a full inference session in approximately 28 MB of RAM. This compact profile is documented directly in the project's README and supporting source files.

Where the 14 MB Size Is Documented

Two key files in the repository explicitly state the exact dimensions of the engine.

• README.md — The project's main documentation notes that Needle 2 ships as a "single 14 MB binary" that handles core inference.
• llms.txt — This supplementary file repeats the specification, stating that "the inference engine is a 14 MB binary fetched once from Hugging Face."

Both sources confirm that the Needle 2 binary size is fixed at 14 MB for standard distributions.

How the Engine Is Fetched and Cached

The Python package handles acquisition automatically. When you instantiate the top-level Needle class exposed in needle/__init__.py, the library checks for the engine in your local cache. If it is missing, the download logic inside needle/model/run.py retrieves the file from Hugging Face.

The default cache directory is ~/.cache/cactus-needle/. After the first successful download, the binary remains on disk, eliminating redundant network requests across sessions. This behavior keeps the Needle 2 binary size constant at 14 MB regardless of how many times you run the model.

How to Verify the Needle 2 Binary Size Locally

You can confirm the exact footprint of the downloaded engine using either the internal API or direct filesystem inspection.

Check the Engine After First Use

Once you have initialized the model, the _engine_path attribute points to the cached binary on disk.

import pathlib, needle

# Initialise the model – the engine is downloaded on first use

agent = needle.Needle()

# The engine is stored in the cache directory (default: ~/.cache/cactus-needle/)

engine_path = pathlib.Path(agent._engine_path)       # internal attribute used by Needle

size_mb = engine_path.stat().st_size / 1e6

print(f"Needle 2 engine file: {engine_path}")
print(f"Size: {size_mb:.2f} MB")

Inspect the Cache Without Loading the Model

If you prefer not to instantiate the agent, you can locate the *.bin file directly in the cache folder.

import pathlib, os

# Default cache location used by `cactus-needle`

cache_dir = pathlib.Path(os.getenv("XDG_CACHE_HOME", "~/.cache")).expanduser() / "cactus-needle"

# Find the first *.bin file (the engine binary)

engine_file = next(cache_dir.rglob("*.bin"))
print(f"Engine binary: {engine_file}")
print(f"Size: {engine_file.stat().st_size / 1e6:.2f} MB")

Both methods will report a Needle 2 binary size of roughly 14 MB, assuming the engine has already been fetched.

Key Source Files Behind the Binary

Several files in the cactus-compute/needle repository govern how the binary is distributed, documented, and accessed:

• README.md — Describes the 14 MB binary and overall architecture.
• llms.txt — Mentions the binary size and download behavior.
• needle/model/run.py — Contains the logic that downloads and caches the engine binary from Hugging Face.
• needle/__init__.py — Exposes the top-level Needle class that triggers the engine download.
• doc/apis.md — Documents how the engine is retrieved and used by the Python API.

Summary

• The Needle 2 binary size is a single 14 MB file.
• It is fetched once from Hugging Face and stored in ~/.cache/cactus-needle/.
• A complete inference session consumes approximately 28 MB of RAM.
• Source documentation in README.md and llms.txt explicitly confirms these figures.
• needle/model/run.py and needle/__init__.py manage the download and caching lifecycle.

Frequently Asked Questions

What is the exact Needle 2 binary size?

The engine is a single file weighing exactly 14 MB. This is stated in both README.md and llms.txt within the cactus-compute/needle repository.

Where is the Needle 2 binary stored after download?

By default, the package caches the binary in ~/.cache/cactus-needle/. You can override this path by setting the XDG_CACHE_HOME environment variable before running Needle.

How much RAM does Needle 2 use during a session?

According to the repository documentation, a full session runs in about 28 MB of RAM. This makes the engine suitable for edge devices and low-resource environments.

Is the binary re-downloaded on every run?

No. The 14 MB engine is downloaded only on first use. Subsequent initializations load the binary directly from the local cache managed by needle/model/run.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}