Repo Memory | GitHub Agentic Workflows
Skip to main content Repo Memory Repo memory provides persistent file storage via Git branches with unlimited retention. The compiler auto-configures branch cloning/creation, file access at /tmp/gh-aw/repo-memory-{id}/ , commits/pushes, and merge conflict resolution (your changes win). Enabling Repo Memory Section titled “Enabling Repo Memory” --- tools : repo-memory : true --- Creates branch memory/default at /tmp/gh-aw/repo-memory-default/ .
Files are stored within the branch at the branch name path ( memory/default/ ). Files auto-commit/push after workflow completion. Work-queue workers Section titled “Work-queue workers” Workers using tools.work-queue.worker: true cannot use standalone tools.repo-memory persistence: its ordinary push job is not attributed to a Claim. Removing this restriction or adding a declaration alongside that push job does not make the writes Claim-scoped.
For persistent snapshots, use a matching safe-outputs.scripts or custom preparation job and safe-outputs.claim-adapters with effect-type: git_tree . Pin an existing native base commit, a fixed target repository and a separate branch prefix. Credential-free preparation emits declared file content; the trusted handler creates an immutable Claim branch and independently verifies its commit, complete tree and blobs. The installed Work must freeze a positive numeric repository target and permit the output, intersecting the approved profile, Subject and every worker-created ancestor.
Preparation and restored history are not authority or delivery proof. The repository’s ESLint Refiner workflow preserves its legacy memory/eslint-refiner JSON/JSONL history and publishes new eslint-refiner.json snapshots under memory/eslint-refiner-runs/claims/ . A read-only setup step restores both histories from exact native commit and blob identities. It rejects truncated trees, foreign repositories, malformed refs, altered bytes and exceeded bounds rather than silently dropping history.
Its limits are 128 snapshots, 1 MiB per file and 16 MiB total; archive older history through an approved operator before exceeding them. This migration preserves memory continuity but does not update the old canonical branch. The Claim adapter cannot overwrite an existing Claim branch, and memory/eslint-refiner-runs avoids conflicting with the existing memory/eslint-refiner ref. Do not retain the ordinary unscoped memory push job or use a moving branch name as the configured base revision.
Advanced Configuration Section titled “Advanced Configuration” --- tools : repo-memory : branch-name : memory/custom-agent-for-aw branch-prefix : tracking # Custom prefix instead of "memory" description : " Long-term insights " file-glob : [ " *.md " , " *.json " ] max-file-size : 1048576 # 1MB (default 100KB) max-file-count : 50 # default 100 max-patch-size : 1048576 # 1MB max (default 10KB) target-repo : " owner/repository " create-orphan : true # default allowed-extensions : [ " .json " , " .txt " , " .md " ] # Restrict file types (default: empty/all files allowed) format-json : true # Pretty-print .json files (default: false) validation : timeout-minutes : 1 json-schemas : - file : state.json schema : type : object required : [ version , items ] additionalProperties : false properties : version : { enum : [ 1 ] } items : type : array items : { type : string } script : | const data = JSON.parse(fs.readFileSync(path.join(memoryRoot, "state.json"), "utf8")); if (!Array.isArray(data.items)) throw new Error("state.json must contain an items array"); --- branch-prefix changes the default memory prefix and must be 4-32 alphanumeric, hyphen, or underscore characters; it cannot be copilot . allowed-extensions limits which file types can be stored, format-json: true pretty-prints .json files before commit, validation.json-schemas declares mandatory per-file JSON/JSONL validation, validation.script runs an optional custom JavaScript domain validator, and max-patch-size caps the total diff size for one push (default 10KB, max 1MB) to prevent oversized updates.
GitHub App authentication Section titled “GitHub App authentication” github-app is optional in the object form and in each array entry. Without it, memory operations use github.token . Configure an installed GitHub App to write memory branches protected by rulesets: tools: repo-memory: github-app: client-id: ${{ vars.MEMORY_APP_CLIENT_ID }} private-key: ${{ secrets.MEMORY_APP_PRIVATE_KEY }} The app must have Contents: read and write permission and be installed on the memory repository.
Push tokens request only contents: write . client-id (or legacy app-id ) and private-key are required. Optional owner and repositories override the installation owner and repository scope; by default, both are derived from target-repo , or the current repository when no target is configured. Each array entry mints its own token. Additional app permissions cannot be requested. For an explicit target-repo , restore steps mint a separate Contents-read token from the same app, allowing private cross-repository clones.
Restores without target-repo continue using github.token unless github-app-read is configured. Tokens are revoked by the token action’s cleanup step. Use github-app-read and github-app-write to select different apps for reads and writes. Both accept the same credential and scope fields as github-app , in object and array forms: tools: repo-memory: github-app-read: client-id: ${{ vars.MEMORY_READ_APP_CLIENT_ID }} private-key: ${{ secrets.MEMORY_READ_APP_PRIVATE_KEY }} github-app-write: client-id: ${{ vars.MEMORY_WRITE_APP_CLIENT_ID }} private-key: ${{ secrets.MEMORY_WRITE_APP_PRIVATE_KEY }} Each override replaces github-app only for its operation.
An omitted override uses github-app , or github.token when no shared app is configured. An override with ignore-if-missing: true falls back to github.token , not to the shared app. The read app needs Contents: read and handles restores (including the current repository) and daily-credit ledger clones. The write app needs Contents: read and write and handles pushes, including the Git and API reads needed to commit changes.
Only the write app needs the ruleset bypass. The repo-memory daily-credit backend also mints Contents-read tokens for its activation and hydration clones. App-authenticated push jobs inherit the workflow’s environment , making environment-scoped app credentials available. Literal target-repo values authorize that repository. For expression targets, the resolved repository must be the current repository or a literal name in the selected app’s repositories under its literal owner (default: the current owner).
Wildcards and expressions cannot define this allowlist. Read and write apps authorize targets independently before minting, and tokens are scoped to the selected repository only. ignore-if-missing: true skips minting when either credential is missing and falls back to github.token . This fallback cannot bypass an app-only ruleset or access another private repository. The push job needs only contents: read when all entries use write apps without this fallback; otherwise it retains contents: write .
Protect memory branches with a ruleset Section titled “Protect memory branches with a ruleset” Create an active branch ruleset targeting memory/** (or the configured branch prefix). Enable Restrict updates and Restrict creations . Add the installed memory app to the bypass list with Always allow ; optionally add an administrator team for recovery. The built-in GitHub Actions token is not the app bypass actor. Every workflow and array entry writing to that pattern needs a bypass-listed app.
Use a narrower pattern when other memories must continue using github.token . Keep the app’s private key available only to trusted workflows and environments. A branch ruleset controls writers, not the content an authorized workflow accepts. Restored memory is untrusted data, not agent instructions. Select repositor
The rest of this page is on the live site.