MemoryOps | GitHub Agentic Workflows
Skip to main content MemoryOps MemoryOps is a set of patterns for using Cache Memory and Repo Memory to persist state across runs: record progress, resume after interruptions, share data between workflows, and analyze trends. flowchart LR r1([Run 1]) --> s1[memory\nstate 1] s1 --> r2([Run 2]) r2 --> s2[memory\nstate 2] s2 --> r3([Run 3]) High-level prompts are usually enough: no schema is needed up front, since the first run can write a practical structure that later runs read and evolve.
Memory Types Section titled “Memory Types” Three memory stores are available: Type Best for Example Default path Cache Memory Temporary state, session data, short-term caching tools.cache-memory.key: my-workflow-state /tmp/gh-aw/cache-memory/ Repo Memory Historical data, trend tracking, long-lived state tools.repo-memory.branch-name: memory/my-workflow /tmp/gh-aw/repo-memory/default/ Comment Memory PR or issue follow-up context, review history, iterative updates tools.comment-memory.target: triggering /tmp/gh-aw/comment-memory/ Cache Memory uses GitHub Actions cache with 7-day retention.
Repo Memory stores files in a dedicated Git branch. Comment Memory stores state in a managed issue or PR comment and updates it over time. tools : cache-memory : key : my-workflow-state repo-memory : branch-name : memory/my-workflow file-glob : [ " *.json " , " *.jsonl " ] comment-memory : target : triggering # Use the issue/PR that triggered this workflow run Pattern 1: Exhaustive Processing Section titled “Pattern 1: Exhaustive Processing” Track progress through large datasets with todo/done lists for complete coverage across runs.
Analyze all open issues in the repository. Track your progress in cache-memory so you can resume if the workflow times out. Mark each issue as done after processing it. Generate a final report with statistics. The agent updates a state file after each item so the workflow can resume if interrupted: { "todo" : [ 123 , 456 , 789 ], "done" : [ 101 , 102 ], "errors" : [], "last_run" : 1705334400 } Real examples: .github/workflows/repository-quality-improver.md , .github/workflows/copilot-agent-analysis.md Pattern 2: State Persistence Section titled “Pattern 2: State Persistence” Save checkpoints to resume long-running tasks that may time out.
Migrate 10,000 records from the old format to the new format. Process 500 records per run and save a checkpoint. Each run should resume from the last checkpoint until all records are migrated. The agent stores the last processed position and resumes from it: { "last_processed_id" : 1250 , "batch_number" : 13 , "total_migrated" : 1250 , "status" : " in_progress " } Real examples: .github/workflows/daily-news.md , .github/workflows/cli-consistency-checker.md Pattern 3: Shared Information Section titled “Pattern 3: Shared Information” Share data between workflows using repo-memory branches.
A producer workflow stores data; consumers read it using the same branch name. Producer workflow: Every 6 hours, collect repository metrics (issues, PRs, stars) and store them in repo-memory so other workflows can analyze the data later. Consumer workflow: Load the historical metrics from repo-memory and compute weekly trends. Generate a trend report with visualizations. Both workflows reference the same branch: tools : repo-memory : branch-name : memory/shared-data Real examples: .github/workflows/metrics-collector.md (producer), trend analysis workflows (consumers) Pattern 4: Data Caching Section titled “Pattern 4: Data Caching” Cache API responses to avoid rate limits and reduce run time.
Suggested freshness: repository metadata 24h, contributor lists 12h, issues and PRs 1h, workflow runs 30m. Fetch repository metadata and contributor lists. Cache the data for 24 hours to avoid repeated API calls. If the cache is fresh, use it. Otherwise, fetch new data and update the cache. Real examples: .github/workflows/daily-news.md Pattern 5: Trend Computation Section titled “Pattern 5: Trend Computation” Append data points to a JSON Lines history file and compute trends and moving averages with Python.
Collect daily build times and test times. Store them in repo-memory as time-series data. Compute 7-day and 30-day moving averages. Generate trend charts showing whether performance is improving or declining over time. Real examples: .github/workflows/daily-code-metrics.md , .github/workflows/shared/charts-with-trending.md Pattern 6: Multiple Memory Stores Section titled “Pattern 6: Multiple Memory Stores” Use separate stores for different lifecycles: cache-memory for session data, repo-memory branches for metrics, configuration, and archives.
Use cache-memory for temporary API responses during this run. Store daily metrics in one repo-memory branch for trend analysis. Keep data schemas in another branch. Archive full snapshots in a third branch with compression. tools : cache-memory : key : session-data # Fast, temporary repo-memory : - id : metrics branch-name : memory/metrics # Time-series data - id : config branch-name : memory/config # Schema and metadata - id : archive branch-name : memory/archive # Compressed backups Pattern 7: PR Comment Memory Section titled “Pattern 7: PR Comment Memory” Keep task state in the PR discussion so each run continues from the latest context.
Review this pull request in passes. Store the running checklist, unresolved questions, and follow-up tasks in comment memory so each new run continues from the previous review state. tools : comment-memory : target : triggering memory-id : pr-review-state # Separate state bucket in the managed comment Use a stable memory-id : runs update the state file at /tmp/gh-aw/comment-memory/<memory-id>.md , and changing the ID writes to a different file.
The managed comment includes a collapsible History section linking to each workflow run that wrote the memory. Updates and clears preserve these links and deduplicate repeated run URLs, even when the generated footer is disabled. History stays outside the editable memory file. Older comments seed history from their most recent recorded attribution; earlier writers cannot be recovered. If the saved memory and accumulated history exceed the comment size limit, the update fails without changing the existing comment or dropping history.
Reduce the saved memory size or use a new memory-id . Best Practices Section titled “Best Practices” Use JSON Lines for append-only logs and time-series data. Include lightweight metadata so later runs can understand the structure. Rotate old data to prevent unbounded growth. Terminal window # Append without reading entire file echo ' {"date": "2024-01-15", "value": 42} ' >> data.jsonl # Keep only last 90 entries tail -n 90 history.jsonl > history-trimmed.jsonl mv history-trimmed.jsonl history.jsonl Security Considerations Section titled “Security Considerations” Memory stores are visible to anyone with repository access.
Never store credentials, API tokens, PII, or secrets — only aggregate statistics and anonymized data. Terminal window # ✓ GOOD - Aggregate statistics echo ' {"open_issues": 42} ' > metrics.json # ✗ BAD - Individual user data echo ' {"user": "alice", "email": "alice@example.com"} ' > users.json Troubleshooting Section titled “Troubleshooting” Cache not persisting : Verify the cache key is consistent across runs.
Repo memory not updating : Check that file-glob matches your files and that they stay within the max-file-size limit. Out of memory errors : Process data in chunks instead of loading everything at once, and rotate old data. Merge conflicts : Prefer append-only JSON Lines, separate branches per workflow, or include the run ID in filenames. Learn More Section titled “Learn More” Cache Memory — Full cache-memory reference Repository Memory — Full repo-memory reference MCP Servers - Memory MCP server configuration DeterministicOps - Data preprocessing and extraction Safe Outputs - Storing workflow outputs Frontmatter Refe
The rest of this page is on the live site.