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

# Caching

> How Strata's persistent result cache works: what invalidates it, why it can never change diagnostics, and how custom rules stay cacheable.

`strata check` keeps a persistent result cache, on by default, so warm runs skip
re-evaluating files whose inputs have not changed. On a large repository this
turns a multi-second check into a fast one without changing a single output byte.

The cache lives in a SQLite database at `.strata/cache/v1.db` in the repository
root. Add `.strata/` to your `.gitignore`.

## The contract

The cache is a pure optimization with one contract: **a cached run produces
byte-identical output to an uncached run**. Two properties enforce it.

**Reuse requires proof.** A file's cached result is reused only when everything
that produced it is provably unchanged:

* the file's own content hash,
* the answer to every cross-file question evaluation asked while checking it
  (does this path exist, what does this directory contain, what is in this
  imported file), re-asked and compared on every run,
* the configuration, the selected ruleset, and the Strata implementation
  itself, all content-hashed into one cache identity.

There is no dependency graph to maintain and no timestamp heuristics. Each
result records the questions its rules actually asked; reuse replays those
questions against the current filesystem. A file that newly appears or
disappears changes an answer, so it invalidates exactly the results that
depended on it. Editing config, a rule, or upgrading Strata changes the cache
identity, so the whole cache is rebuilt.

**Failure degrades, never corrupts.** An unreadable, corrupt, or foreign cache
entry is a cache miss: the file is recomputed fresh. A broken cache database
degrades the run to fully uncached with a warning on stderr telling you to
delete `.strata/cache` if it persists. No cache failure mode can change an
exit code or a diagnostic.

## Configuration and flags

The [`[cache]` table](/concepts/configuration#cache) has two keys: `enabled`
(default `true`) and `require_cacheable` (default `false`). On `strata check`,
`--cache` and `--no-cache` override the config for one run, and `--cache-stats`
prints hit/miss/invalidation/write counts to stderr, or
`Cache: disabled (<reason>)` when caching was unavailable. See
[`strata check`](/cli/check#caching) for the flag reference.

## Custom rules

A custom rule body is arbitrary Python, so it cannot be assumed to only read
tracked inputs. By default, selecting any custom rule disables caching for the
whole run. Setting `require_cacheable = true` verifies every selected custom
rule at startup and keeps such runs cached; see
[Custom rules](/concepts/custom-rules#caching-and-hermetic-rules) for the
hermetic contract that verification enforces.

## When something looks wrong

`strata check --no-cache` runs with the cache fully bypassed. If cached and
uncached output ever differ, that is a Strata bug; please report it. Deleting
`.strata/cache/` is always safe - the next run rebuilds it.