Skip to main content
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). Module and auth-state caching are covered in Modules.

​
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 re-resolves the description against the current UI and updates the entry in place.

​
Element checks with long timeouts

Element checks (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.
  • CI runs (CI=true) are always eligible.
  • Local runs are eligible when the current branch is not the main branch or a protected branch.
  • 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: 
npx momentic run --disable-cache
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.