---
title: Cache Store is Recall
description: Why Mirage calls its cache layer Recall, and how the Index Store and File Store divide the work.
icon: clock-rotate-left
---

## The Cache Is Recall

<Icon icon="eye" /> **[Eyes](/home/design/eyes)** see. <Icon icon="hand" /> **[Hands](/home/design/hands)** act. <Icon icon="brain" /> **Brain** (the Agent) decides. **Recall** is what those three don't have to do again.

Every `cat /s3/data.csv` costs something real: a network round trip, a format decode, and tokens the Brain spent orchestrating the chain. Recall preserves the bytes that came out of that work so the next time the same request appears, Mirage returns the stored bytes directly. The fetch, the decode, and the reasoning round-trip are all saved.

We call it **Recall** instead of "cache" because that is what it does for the agent: retrieve prior work so the same effort is not spent twice.

## Two Stores, Two Kinds Of Work

Recall splits into two layers. Each targets a different kind of redundant work.

- **[Index Store](/home/design/index_cache)**, remembers what the Eyes have *seen*: directory listings and file metadata. Without it, every `ls`, glob expansion, or `stat` call is a network round trip.
- **[File Store](/home/design/file_cache)**, remembers what the Hands have *produced*: the byte output of file-touching commands. Without it, every repeat `cat /s3/data.csv` re-fetches, re-decodes, and re-triggers the agent chain.

The two stores have different freshness strategies because they face different problems:

| Store       | Freshness           | Why                                                                             |
| ----------- | ------------------- | ------------------------------------------------------------------------------- |
| Index Store | TTL                 | Directory listings are collections. No cheap per-directory fingerprint exists.  |
| File Store  | Fingerprint         | Files have cheap per-blob identifiers (S3 ETag, filesystem mtime, GitHub SHA). |

See each store's page for the full reasoning.

## Recall Is A Decision, Not A Default

Mirage does not cache eagerly. Each <Icon icon="hand" /> **Hand** declares what is worth remembering by populating `IOResult.cache`. Today this is done heuristically, by the shape of the command: `cat /s3/data.csv` opts in because the bytes are very likely to be reused; `stat` does not because its output is metadata the Index Store already tracks.

This keeps Recall under the control of the Hands (and the Brain orchestrating them), not the filesystem layer. A future direction is to let the Brain annotate cacheability at call time, but the current default is that each Hand knows its own semantics.

## Related

- [Index Store](/home/design/index_cache), the directory-listing and metadata half of Recall.
- [File Store](/home/design/file_cache), the file-content half of Recall.
