Cache Memory | GitHub Agentic Workflows
Skip to main content Cache Memory Cache memory provides persistent file storage across workflow runs via GitHub Actions cache. GitHub Actions evicts unused caches after 7 days. 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). Enabling Cache Memory Section titled “Enabling Cache Memory” --- tools : cache-memory : true --- Files are stored at /tmp/gh-aw/cache-memory/ using a workflow-scoped cache key, via standard file operations.
Advanced Configuration Section titled “Advanced Configuration” --- tools : cache-memory : key : custom-memory-${{ github.repository_owner }} retention-days : 30 # 1-90 days; controls uploaded artifact retention only allowed-extensions : [ " .json " , " .txt " , " .md " ] # Restrict file types (default: .json, .jsonl, .txt, .md, .csv) validation : timeout-minutes : 1 json-schemas : - file : index.json schema : type : object required : [ entries ] additionalProperties : false properties : entries : type : array items : { type : string } script : | const index = JSON.parse(fs.readFileSync(path.join(memoryRoot, "index.json"), "utf8")); if (!Array.isArray(index.entries)) throw new Error("index.json entries must be an array"); --- File Type Restrictions Section titled “File Type Restrictions” The allowed-extensions field restricts which file types can be written to cache-memory (default: .json , .jsonl , .txt , .md , .csv ). --- tools : cache-memory : allowed-extensions : [ " .json " , " .jsonl " , " .txt " ] # Only these extensions allowed --- If files with disallowed extensions are found, the workflow will report validation failures.
When a cache is restored for agent execution, gh-aw also strips execute bits from restored working-tree files and removes disallowed file types before the agent can read them. See ADR-26587 for the pre-agent sanitization contract behind allowed-extensions . Custom validation Section titled “Custom validation” Use validation.json-schemas for required JSON/JSONL structure checks. Each declaration has an inline schema and may have a relative file path or glob ( * matches within a path segment; ** spans segments).
If file is omitted, the schema applies to every eligible .json and .jsonl file in the memory directory, excluding .git ; omit format too so the format is inferred for each file. Otherwise, paths must match the configured allowed-extensions policy and exist in the candidate; globs must match at least one file, and every match is validated. JSON must contain one non-empty document. JSONL validates each record independently, accepts LF/CRLF and an optional final newline, permits an existing empty file, and rejects blank physical lines or malformed records with a line number.
Validation does not rewrite data. Schemas run after filtering and configured normalization, before any optional validation.script , and before cache save; when threat detection is enabled, they also run in the update_cache_memory job before actions/cache/save . The file format is inferred from each matched file’s .json or .jsonl extension (case-insensitive), so a glob may match both formats. Optional format: json or format: jsonl overrides inference and is required for other extensions.
The supported vocabulary is limited to type (including type lists and null ), primitive enum , required , nested properties , additionalProperties: false , object-schema items , and standalone oneOf / anyOf , with a maximum nesting depth of 32 and no sibling constraints beside alternatives. Numeric enum integers must be exactly representable by JavaScript, and values checked against numeric enums must not lose precision during JSON parsing.
This is not full JSON Schema: $ref , const , schema format , pattern , numeric/string/array bounds, and uniqueItems are rejected. Use validation.script for domain-specific constraints such as cross-file uniqueness, positive-ID checks, or timestamp policies. The optional JavaScript body runs with Node.js over the whole cache-memory directory after the agent and before the cache is saved (again in update_cache_memory when threat detection is enabled).
Schemas always run first. Available globals are Node.js fs and path , plus memoryRoot / memoryDir , memoryId , and memoryKind ( "cache" ). The working directory is the cache root. Environment variables available to the validator are intentionally limited to basic runner paths plus GH_AW_MEMORY_ROOT , GH_AW_MEMORY_DIR , GH_AW_MEMORY_ID , and GH_AW_MEMORY_KIND ; GitHub tokens and write credentials are not passed to the validator subprocess.
Network access follows the workflow runner’s normal network policy. The default timeout is 1 minute and may be set with validation.timeout-minutes (1-5 minutes). Throw an exception, return false , time out, exit nonzero, or modify a memory file to reject persistence. Validator stdout and stderr are reported separately from built-in storage validation output. Multiple Configurations Section titled “Multiple Configurations” --- tools : cache-memory : - id : default key : memory-default - id : session key : memory-session-${{ github.run_id }} - id : logs retention-days : 7 --- 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. Using with MCP Servers Section titled “Using with MCP Servers” With tools.cache-memory enabled, MCP servers can persist temporary state under /tmp/gh-aw/cache-memory/ . Configure the server in the workflow and point it at a subdirectory such as /tmp/gh-aw/cache-memory/<server-name>/ . For QMD’s index/search pattern , a separate custom job restores prior memory and incrementally builds a documentation index.
Pass its current-run snapshot to the agent through an artifact, then let cache-memory persist that snapshot. jobs.<id>.restore-memory: true restores memory read-only; it does not publish custom-job changes or transfer files between runners. SQLite snapshots require an explicit .sqlite entry in allowed-extensions . Behavior Section titled “Behavior” GitHub Actions cache provides a 10GB per-repository limit with LRU eviction, and evicts unused entries after 7 days. retention-days controls only uploaded artifact retention (1-90 days); it does not extend cache lifetime.
The repository-wide artifact retention policy overrides this per-cache artifact setting when configured. Cache memory is branch-scoped: runs restore from the same branch first, then can fall back to the default branch. On a non-default branch, the first restore often comes from the default branch; later saves create a branch-local cache lineage. Caches saved by pull_request runs are isolated to the PR merge ref. A scheduled workflow on the default branch cannot restore those PR-local caches, even with the same key or scope: repo .
PR runs may restore eligible default-branch caches, but their updates do not flow back to the default branch. Scheduled cache-memory consolidation therefore applies only to default-branch history; use local cleanup inside PR workflows. Cross-workflow restores also require compatible key prefixes and cache versions. Absent cache files are expected on cold starts, after eviction, or when branch scoping prevents restoring another branch’s cache.
When the workflow defines initialization or a full-analysis fallback, the agent follows that path without reporting report_missing_data and saves updated state for future runs. Required cached inputs with no fallback still produce report_missing_data ; malformed or unreadable required state also remains a failure unless the workflow explicitly defines recovery. A cache restore miss alone cannot distinguish optional history from required input, so it does not suppress an explicit missing-data report.
The compiler strips ${{ github.run_id }} from
The rest of this page is on the live site.