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 Index Store is one half of Mirage’s Recall layer (the other is the File Store). It remembers directory listings and metadata that the Eyes have already seen, so ls, stat, and glob expansion don’t trigger network calls on every use.

​
What It Does

The index cache stores directory listings and file metadata from remote resources. Without it, every ls, glob expansion, or stat call triggers a network request.

​
What It Caches

  • Directory listings, children of a directory with metadata
  • File metadata, name, type, size, timestamps
This enables fast stat lookups. If the parent directory is cached, mirage knows instantly whether a file exists without a network call.

​
TTL Per Resource

ResourceTTLReason
RAM0sIn-process, always fresh
Disk60sLocal changes are fast to detect
S3/GCS/R2600sAPI calls are slow and costly
GitHub600sRepo tree rarely changes within a session
After TTL expires, the next directory read re-fetches from the resource.

​
Why TTL, Not Fingerprints

A directory listing is a collection, not a single blob, and resources do not expose a cheap “did this directory change?” fingerprint. The only way to verify staleness is to re-run list_objects_v2, which is the call you were trying to cache in the first place. TTL is a time-based bet instead: assume nothing changed for N seconds. The cost of being wrong is bounded. A newly-created file is invisible for at most N seconds, then the listing re-fetches.

​
Invalidation

Writes invalidate the parent directory listing only:

​
Storage Backends

BackendUse case
RAMDefault, in-process
RedisMulti-process