> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Client caching

> How the Archil client caches data in memory, and the controls for warming, sizing, and refreshing it.

Archil caches your data at two distinct layers:

* The **Archil storage system cache** is a durable, multi-Availability-Zone caching layer that runs server-side, between your clients and your [data source](/concepts/data-sources). It's where your active data is durably stored (a successful `fsync()` commits to it) and where it's [metered](/concepts/metering), and it serves data with sub-millisecond latency. See [Architecture](/details/architecture) for how it fits in.
* The **client-side cache** is an in-memory cache inside each Archil client — one per mount. It holds recently used data so that repeated access is served locally, without even a round-trip to the storage system.

This page is about the **client-side cache**: what it holds, how it's sized and evicted, and the commands you use to warm, refresh, and tune it.

## What the client caches

The client maintains several in-memory caches, all populated on demand as your application reads and writes:

* **File data** — the contents of files. This is the bulk of the cache.
* **File and directory attributes** — metadata such as size, timestamps, and permissions (the result of a `stat`).
* **Directory listings** — the entries returned by `readdir` (i.e., `ls`), so repeated traversals of the same directory don't round-trip to the server.
* **Extended attributes** — when [xattrs](/reference/archil-cli#mount) are enabled.

When your application requests data that isn't in the client cache, the client fetches it from the Archil storage system — which serves it from its durable cache (sub-millisecond) or, on a miss there, from the backing data source (for Amazon S3, typically 10–30 ms) — and then caches the result in memory for future requests.

## Cache size and eviction

The client's in-memory data cache is bounded by two settings on [`archil mount`](/reference/archil-cli#mount):

* `--max-cache-mb` — the hard ceiling on the client cache size. Default: 1/4 of available RAM or 2048 MiB, whichever is smaller.
* `--target-cache-mb` — the size the client aims to keep the cache near, leaving headroom for bursts of new reads. Default: 75% of the maximum.

When the cache fills, the client evicts older entries to make room for new data. Two kinds of entries are never evicted:

* **Unflushed (dirty) writes** — data you've written that hasn't yet been committed to the storage system is always preserved locally, so eviction can never lose your writes.
* **Entries still in use** — anything an application currently has open is kept until it's released.

<Note>
  Because the client cache is bounded, reading or pre-fetching more data than `--max-cache-mb` can hold will evict earlier entries before you use them. Size the cache for your working set when you plan to keep a large data set hot on a client.
</Note>

For example, to give a read-heavy client a larger cache:

```bash theme={null}
archil mount <disk-name> /mnt/archil --region aws-us-east-1 \
    --max-cache-mb 16384 --target-cache-mb 12288
```

## Freshness and consistency

Serving reads from the client cache is what lets a client avoid contacting the storage system on every operation — which also means a client can briefly serve slightly stale data after another client changes a file. The client revalidates cached entries with the storage system so that changes become visible within seconds for file data and attributes. Directory listings are cached for longer; you can tune their lifetime per directory with [`archil set-cache-expiry`](/reference/archil-cli#set-cache-expiry).

For the full model — including how `fsync` and cache flushes provide strong read-after-write consistency between connected clients — see [Consistency](/details/consistency).

## Warming the client cache

By default the client cache fills lazily as data is read, so the first read of any file on a client pays the fetch latency. When you know which files you'll need — loading a model, starting a database, or running a batch job over a known set of inputs — you can warm them ahead of time so the first read is already local.

There are two ways to warm the client cache:

* **[`archil prefetch <MOUNTPOINT> <PATH>...`](/reference/archil-cli#prefetch)** — pre-fetch files or directories (recursively) into the cache of an already-mounted disk. The command queues the work and returns immediately; fetching continues in the background.
* **[`archil mount --pre-fetch <PATHS>`](/reference/archil-cli#mount)** — warm a comma-separated set of paths automatically as soon as the disk is mounted.

```bash theme={null}
# Warm a model directory on an already-mounted disk
archil prefetch /mnt/archil models/llama-3

# Or warm it as part of the mount
archil mount <disk-name> /mnt/archil --region aws-us-east-1 --pre-fetch models/llama-3
```

<Note>
  Pre-fetched data shares the client cache with normal reads, so it counts against `--max-cache-mb` and is subject to the same eviction described above.
</Note>

## Refreshing the client cache

To force a client to drop cached entries and re-read from the storage system — for example, when another client has updated files on a [`--shared`](/concepts/shared-disks) mount — use [`archil invalidate-cache`](/reference/archil-cli#invalidate-cache). Pass the mount root to refresh everything, or a single file path to refresh just that file. In-flight (dirty) writes are always preserved.

```bash theme={null}
# Refresh the whole mount
archil invalidate-cache /mnt/archil

# Refresh a single file (siblings keep their cache)
archil invalidate-cache /mnt/archil/shared-data/report.csv
```

## Controls at a glance

| Goal                                           | Control                                                      |
| ---------------------------------------------- | ------------------------------------------------------------ |
| Set the maximum client cache size              | [`mount --max-cache-mb`](/reference/archil-cli#mount)        |
| Set the target client cache size               | [`mount --target-cache-mb`](/reference/archil-cli#mount)     |
| Warm files into the client cache after mount   | [`prefetch`](/reference/archil-cli#prefetch)                 |
| Warm files into the client cache at mount time | [`mount --pre-fetch`](/reference/archil-cli#mount)           |
| Drop and re-read cached data                   | [`invalidate-cache`](/reference/archil-cli#invalidate-cache) |
| Tune directory-listing cache lifetime          | [`set-cache-expiry`](/reference/archil-cli#set-cache-expiry) |