Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
The Cache Is Recall

Eyes see. Hands act. 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, 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, 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:
StoreFreshnessWhy
Index StoreTTLDirectory listings are collections. No cheap per-directory fingerprint exists.
File StoreFingerprintFiles 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 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.
  • Index Store, the directory-listing and metadata half of Recall.
  • File Store, the file-content half of Recall.