---
title: Caching
description: Understand how agent-qa caches action plans, builds cache keys, invalidates stale entries, and can make similar subsequent runs 5x faster with 3x fewer planner tokens.
---



agent-qa caches action plans for step sub-actions. A repeated run still observes the live page, checks the current screen state, executes actions, records artifacts, and verifies outcomes. The cache only skips redundant planning work when the same step is running in the same source, config, suite, platform, and step-position context.

The default cache directory is `.agent-qa/cache`.

## Why caching speeds up repeated runs [#why-caching-speeds-up-repeated-runs]

Most test runs spend time asking the planner what action should happen next: click this button, fill this field, wait for this state, or assert this visible result. When a previous run already planned a sub-action for the same step context, agent-qa can reuse that cached action plan instead of asking the LLM to plan it again.

That means caching helps most when you rerun the same test or suite after a small product change, while the test YAML, suite YAML, config, platform, and step order remain stable.

The landing-page cache feature shows the intended impact for similar subsequent runs: `5x` faster execution, from `42s -> 8s`, and `3x` fewer planner tokens. Those gains come from cached action plans skipping redundant planner work when the flow and screen state still match.

Caching does not turn a run into a replay script. The agent still re-observes the page before each sub-action, and a cached action can be rejected, invalidated, or replaced when the run no longer matches the cached path.

## Configure cache storage [#configure-cache-storage]

Cache storage is configured in `agent-qa.config.yaml` under `services.cache`:

```yaml
services:
  cache:
    dir: .agent-qa/cache
    ttl: 7d
```

`services.cache.dir` chooses where cache files are written. `services.cache.ttl` controls how long entries stay fresh.

You can override these from the environment:

```bash
AGENT_QA_CACHE_DIR=.agent-qa/cache AGENT_QA_CACHE_TTL=24h agent-qa run tests/login.yaml
```

Per-run and per-test behavior is controlled through `use.cache`:

```yaml
use:
  cache: true
```

Set `use.cache: false` in a test or suite override when that workflow should always plan fresh actions.

## Run without cache [#run-without-cache]

Use `--no-cache` when you want a single run to bypass action-cache reads and writes from the normal run path:

<CommandSnippet command="agent-qa run tests/login.yaml --no-cache" />

The dashboard uses the same runtime behavior. The run options menu exposes **Use cache**; turning it off sends a no-cache run request and the underlying command runs with `--no-cache`.

## Cache keys [#cache-keys]

agent-qa builds a step hash from the execution context, then stores sub-actions under that hash. The step hash uses the first 16 hex characters of a SHA-256 digest over:

* config file content
* suite file content
* suite test index
* test file content
* step instruction
* platform
* step index

The current sub-action cache files use this shape:

```txt
.agent-qa/cache/<stepHash>/sub-<index>.json
```

This is why small source changes can intentionally create a new cache context. Changing the config file, moving a test within a suite, editing the test file, changing the step text, switching platform, or moving the step to a different index can all change the key.

## Hits, misses, and invalidation [#hits-misses-and-invalidation]

A cache hit returns the stored action plan for a sub-action index. A cache miss asks the planner for a fresh action plan.

Entries are treated as misses when:

* the cache file is missing or invalid JSON
* `CACHE_SCHEMA_VERSION` does not match the current cache schema
* `services.cache.ttl` has expired
* a run misses at sub-action index N, which invalidates cached sub-actions from that index forward
* a cached action fails and the run needs to replan from that point
* a cached action contains an old redacted secret marker such as `[secret:loginPassword]` for a step that uses runtime `{{secret:...}}` templates

That prefix invalidation keeps a partially stale path from continuing after the first mismatch. The run can still write fresh cache entries for the actions it replans.

## Purge cached plans [#purge-cached-plans]

Purge cache entries for one test file when you know its action path should be rebuilt:

<CommandSnippet command="agent-qa cache purge --test tests/login.yaml" />

Purge all cached plans when you want a clean cache directory:

<CommandSnippet command="agent-qa cache purge --all --force" />

Without `--force`, the all-cache purge asks for confirmation.

Dashboard pages that run tests can also expose cache purge actions. Run detail cache markers show when a step was fully or partially cached, with labels such as `All actions cached` or `2 of 5 actions cached`.

## Cache, memory, and configuration [#cache-memory-and-configuration]

Cache is execution-level reuse. It stores action plans that let repeated runs avoid redundant planning work.

Memory is product context. It stores file-backed observations about products, suites, and tests so future runs can reason with prior evidence.

Configuration is runtime control. It defines targets, browsers, devices, services, hooks, variables, auth, and default run behavior.

Use cache when repeated runs should be faster. Use memory when the agent should remember product behavior. Use configuration when the team needs reviewable defaults and explicit overrides.