Cache Memory

Cache memory provides persistent file storage across workflow runs via GitHub Actions cache with 7-day retention. The compiler automatically configures the cache directory, restore/save operations, and progressive fallback keys at /tmp/gh-aw/cache-memory/ (default) or /tmp/gh-aw/cache-memory-{id}/ (additional caches).

Stores files at /tmp/gh-aw/cache-memory/ using a workflow-scoped cache key. Use standard file operations to store/retrieve JSON/YAML, text files, or subdirectories.

Note

The allowed-extensions field restricts which file types can be written to cache-memory. By default, all file types are allowed (empty array). When specified, only files with listed extensions can be stored.

If files with disallowed extensions are found, the workflow will report validation failures.

Mounts at /tmp/gh-aw/cache-memory/ (default) or /tmp/gh-aw/cache-memory-{id}/. The id determines the folder name; key defaults to a workflow-scoped prefix derived from the sanitized workflow name.

Merge rules: Single→Single (local overrides), Single→Multiple (local converts to array), Multiple→Multiple (merge by id, local wins).

GitHub Actions cache provides 7-day retention, a 10GB per-repository limit, and LRU eviction. Add retention-days to upload artifacts (1-90 days) when you need access beyond normal cache expiration.

Cache memory is branch-scoped. Runs restore from caches on the same branch and can also fall back to the default branch. On a non-default branch, the first restore often comes from the default branch; later saves then create a branch-local cache lineage.

The compiler strips ${{ github.run_id }} from restore keys so each run can fall back to earlier runs, and for scope: repo it adds a broader restore key for cross-workflow sharing within the same branch scope. Custom user-supplied keys automatically append -${{ github.run_id }} when needed.

Use cache-memory for short-lived, branch-local state. Prefer scheduled runs on the default branch when a workflow depends on warmed caches, and use descriptive file names, hierarchical keys such as project-${{ github.repository_owner }}-${{ github.workflow }}, and the narrowest practical scope. Monitor total cache growth within the 10GB repository limit.

For unlimited retention with version control, see Repo Memory.

The agentic maintenance workflow automatically removes outdated cache-memory entries on a schedule by grouping caches by key prefix (everything before the run ID) and keeping only the latest entry in each group. You can also trigger the same cleanup manually from the GitHub Actions UI by running the Agentic Maintenance workflow with the clean_cache_memories operation.

If files are not persisting, check cache key consistency and the restore/save log messages. For file access issues, create subdirectories first, verify permissions, and use absolute paths. If cache growth becomes a problem, clear old entries periodically or use time-based keys for auto-expiration.

When an agent calls missing_data with reason: cache_memory_miss“, the conclusion handler automatically opens a failure issue that points to a likely cache path problem. Verify that the prompt uses the correct path (/tmp/gh-aw/cache-memory/ by default or /tmp/gh-aw/cache-memory-{id}/ for named caches) and that the cache key stays consistent across runs.

When a workflow uses tools.github.min-integrity, cache-memory automatically applies integrity-level isolation. Cache keys include the workflow’s integrity level and a hash of the guard policy so that changing any policy field forces a cache miss.

The compiler generates git-backed branching steps around the agent. Before the agent runs, it checks out the matching integrity branch and merges down from all higher-integrity branches (higher integrity always wins conflicts). After the agent runs, changes are committed to that branch. The agent itself sees only plain files — the .git/ directory rides along transparently in the Actions cache tarball.

This prevents a lower-integrity agent from poisoning data that a higher-integrity run would later read.

Note

Do not store sensitive data in cache memory. It follows repository permissions, and with threat detection enabled, caches save only after validation succeeds (restore → modify → upload artifact → validate → save).

See Grumpy Code Reviewer for tracking PR review history.

• Repo Memory - Git branch-based persistent storage with unlimited retention
• Frontmatter - Complete frontmatter configuration guide
• Safe Outputs - Output processing and automation
• GitHub Actions Cache Documentation - Official GitHub cache documentation