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

# Step caching

> Momentic caches locator data from successful runs so repeat runs execute in milliseconds without AI calls.

Most interactive steps (**Click**, **Type**, etc.) cache the resolved element
after a successful run. On the next run, Momentic replays from cache and only
falls back to AI when the cache misses (see
[auto-heal](/reliability/auto-heal)).

Module and auth-state caching are covered in
[Modules](/core-concepts/modules#caching).

## How the cache works

A cached step stores more than one way to find its target: where the element
sits on screen, what it looks like, what text it contains, and the accessibility
and structural attributes around it. Which of those signals matters for a given
step is inferred from the step's natural-language description. "The red Cancel
button below the Order Summary header" leans on visual and positional signals;
"the Sign in button" leans on accessibility and text.

On replay, the runner matches the stored signals against the live page or screen
and runs the action without invoking the LLM when there's a match. When the
signals no longer match, [auto-heal](/reliability/auto-heal) re-resolves the
description against the current UI and updates the entry in place.

For web runs, open a step in the run viewer to see its cache status in the step
detail pane. The **Cache** section tells you whether the step used a cache hit,
missed cache, busted cache before use, or had no cache, plus the reason or
resolution method when Momentic recorded one.

## Element checks with long timeouts

[Element checks](/reference/commands/check-element) (`checkElementVisible`,
`checkElementExists`, and the rest of the family) poll until their condition
holds or the `timeout` elapses. When the step has a cache, the poll replays from
cache on every attempt - cheap, and exactly what you want while a page is still
loading and the element hasn't appeared yet.

If the element *is* present but its cached locator has gone stale (the page was
restructured, the element moved, or its surrounding signals changed), the check
periodically re-resolves the description with AI during the wait instead of only
once after the timeout. As a result the step **finishes as soon as the element
is found** rather than burning the entire timeout on cache-only polling.

This AI fallback only fires when the cache actually misses, on a cadence that
scales with the timeout (more frequent for short checks, less frequent for long
ones) so cost stays bounded, and a final re-resolution always runs at the end as
a safety net. Checks whose cache still resolves never spend an AI call.

## Cache saving eligibility

A run only saves cache when it passes **and** the run is eligible. Cancelled or
timed-out runs discard caches by default; enable
[`advanced.saveCacheOnCancel`](/configuration/advanced#advanced-savecacheoncancel)
to preserve partial caches from steps that completed before the interruption.

* **CI runs** (`CI=true`) are always eligible.
* **Local runs** are eligible when the current branch is **not** the main branch
  or a [protected branch](/configuration/momentic-config#gitprotectedbranches).
* Pass `--save-cache` to force eligibility.

## Never cached

* AI-evaluated steps like **AI check** and **AI extract**
* Steps whose variables change every run (e.g. `{{ Date.now() }}`)
* Steps with caching explicitly disabled

## Disabling cache

Globally:

<CodeGroup>
  ```bash npm theme={null}
  npx momentic run --disable-cache
  ```

  ```bash yarn theme={null}
  yarn dlx momentic run --disable-cache
  ```

  ```bash pnpm theme={null}
  pnpm dlx momentic run --disable-cache
  ```
</CodeGroup>

Per step: toggle **Disable cache** in step options. Useful for inherently
dynamic targets like `last item in list`.

## Cache invalidation

Cache entries are scoped per step. Changing a step's natural-language
description or the variable values it depends on (e.g. a different
`{{ env.USERNAME }}`) re-keys the entry. Re-rendering siblings, mutating
unrelated attributes, or animating background content does not.

## Storage

* Stored per organization; only accessible to authenticated runs
* Expires after 90 days of inactivity

## Git-based isolation

Caches are scoped per branch so concurrent work doesn't collide:

* `main` keeps per-commit caches; new branches seed from the cache at their
  merge base.
* Non-main branches store only the latest cache.
* On merge, the merged branch's cache is combined with `main`'s previous commit
  so subsequent runs on `main` keep passing.

## Environment isolation

By default, branch-scoped caches are shared across environments in the same
project. To keep separate caches for `dev`, `staging`, `production`, or any
other environment selected with `--env`, enable
[`advanced.isolateCachesByEnvironment`](/configuration/advanced#advanced-isolatecachesbyenvironment).