尧图网页设计 
gh-aw 记忆机制完全指南cache-memory 与 repo-memory 持久化原理详解【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-awgh-awGitHub Agentic Workflows是一个让 AI Agent 在 GitHub Actions 中自动处理 Issue、PR 和维护任务的开源项目。它的记忆机制通过cache-memory缓存记忆与repo-memory仓库记忆两种存储方式让 Agent 在多次工作流运行之间记住进度、状态和历史数据从而把一次次孤立的运行串联成有记忆的持续任务。1. 为什么 AI Agent 需要记忆GitHub Actions 的每次运行都是全新环境Runner 执行完就销毁Agent 上一次记下的进度、读过的上下文全部丢失。没有记忆的 Agent 每次都要从零开始无法做到⏸️ 长任务断点续传比如批量处理 10000 条记录 跨运行积累历史数据、计算趋势 多个工作流之间共享数据gh-aw 的解法是在 Agent 运行期间挂载一个确定的记忆目录运行结束后由编译器自动生成的步骤把文件同步到持久化存储下次运行时再自动恢复。整个过程对 Agent 是透明的——它只需要正常读写文件即可。2. 三大记忆机制一览 ️gh-aw 提供三种记忆存储按生命周期从轻到重排列机制存储位置保留时长适合场景默认路径cache-memoryGitHub Actions 缓存7 天临时状态、会话数据/tmp/gh-aw/cache-memory/repo-memoryGit 专用分支永久历史数据、长期状态/tmp/gh-aw/repo-memory-{id}/comment-memoryIssue/PR 受管评论永久PR 跟进上下文/tmp/gh-aw/comment-memory/三者共用同一套设计哲学Agent 只操作普通文件持久化由 gh-aw 编译器生成的步骤在幕后完成。3. cache-memory7 天有效期的高速缓存记忆3.1 一键启用在 Markdown 工作流的 frontmatter 中只需一行tools: cache-memory: true编译后Agent 就能在/tmp/gh-aw/cache-memory/目录下自由读写.json、.jsonl、.txt、.md、.csv等文件。gh-aw 还会自动把这段记忆目录说明注入 Agent 的提示词见 pkg/workflow/prompts/cache_memory_prompt.md。3.2 持久化原理restore → 读写 → validate → savecache-memory 的每次运行都遵循一条自动生成的流水线Restore用actions/cache按缓存 key 恢复整个目录。gh-aw 会自动生成带降级链的 restore-keys自动剥离github.run_id本次运行没命中最新缓存时可以回落到更早的运行甚至回落到默认分支的缓存Agent 读写Agent 把文件当作简易文件共享随意组织比如notes.md记观察、history.jsonl记流水日志、state/存结构化状态Validate校验文件扩展名白名单、文件大小数量限制还允许用validation.script写一段自定义 JS 做业务级校验此时不传入任何 GitHub tokenSave校验通过后才把目录打包存回缓存仓库级 10GB 上限LRU 淘汰。核心生成逻辑在 pkg/workflow/cache_memory.go目录、缓存 key、restore-keys 的拼装都发生在编译期。3.3 完整性感知缓存防止低信任数据投毒这是 cache-memory 最有意思的设计。当工作流启用了tools.github.min-integrity时缓存目录内部会初始化一个git 仓库并建立merged / approved / unapproved / none四级完整性分支运行前脚本 actions/setup/sh/setup_cache_memory_git.sh 检出当前运行对应的完整性分支并从高完整性分支向下合并冲突时高完整性数据胜出效果是低信任运行能读到高信任数据但高信任运行永远看不到低信任数据从机制上阻断恶意/低质数据污染可信缓存的路径同时该脚本还会做预 Agent 消毒删除符号链接、剥离可执行位、按allowed-extensions清理不合规文件。3.4 自动清理gh-aw 的 Agentic Maintenance 工作流会定期按key 前缀分组清理 cache-memory每个组只保留最新一条避免缓存无限膨胀。4. repo-memory写入 Git 分支的永久记忆4.1 启用方式同样只需在 frontmatter 中声明例如把记忆写入自定义分支并限制文件类型tools: repo-memory: branch-name: memory/custom-agent-for-aw file-glob: [*.md, *.json] max-file-size: 1048576分支默认自动以orphan孤儿分支创建create-orphan: true无需预先存在。4.2 持久化原理五个阶段的数据流与 cache-memory 的缓存整目录不同repo-memory 走的是**缓存中转 Git 落地**的双阶段模型完整架构定义在 scratchpad/repo-memory.mdCloneAgent 作业开始时脚本 actions/setup/sh/clone_repo_memory_branch.sh 以--depth 1 --single-branch克隆memory/{id}分支到/tmp/gh-aw/repo-memory/{id}/分支不存在则创建孤儿分支ExecutionAgent 直接在目录里读写文件提示词中会明确告知这个记忆路径Upload作业结束时把目录上传为 GitHub Actions artifactrepo-memory-{id}且使用if: always()——即使作业失败记忆也会保存方便事后调试Download Validate独立的 Push 作业下载 artifact逐项校验file-glob、max-file-size默认 10KB、max-file-count默认 100和max-patch-size单次 diff 上限默认 10KBPushactions/setup/js/push_repo_memory.cjs 把文件提交到memory/{id}分支。提交通过 GitHub GraphQL 的createCommitOnBranch变更完成自动携带 GitHub GPG 签名满足提交必须已验证的分支保护规则并发推送时以-X ours合并策略重放你的文件变更永远胜出。4.3 多记忆分区支持一次声明多个记忆分区数组形式每个分区独立分支、独立限制例如一个metrics分支存时序数据、一个config分支存 schema。记忆 ID 遵循[a-zA-Z0-9-]命名规则Go 层与 JavaScript 层共用同一套路径推导规则repo_memory.go中的目录、artifact 名、分支名构建函数由专门的跨层一致性测试保证不漂移。5. 如何选择cache-memory vs repo-memory维度cache-memoryrepo-memory保留时长7 天LRU 淘汰永久版本控制❌✅每次运行 一次提交性能快整目录 tar 恢复稍慢clone commit上限10GB/仓库受仓库限制最佳用途会话状态、API 缓存、断点续传历史指标、趋势分析、跨工作流共享经验法则7 天内还会再用的状态放 cache-memory需要留档、审计、回溯的历史数据放 repo-memory。两者可以同时启用——用缓存做工作集用分支做档案库这是官方 MemoryOps 模式Pattern 6推荐的组合。6. 安全建议与安全机制 不要存敏感数据两种记忆都跟随仓库权限任何能访问仓库的人/流程都能读到凭据、token、PII 一律禁止收紧白名单用allowed-extensions/file-glob限制文件类型cache-memory 在恢复后还会做预消毒删符号链接、去可执行位、清 hooks威胁检测联动启用 threat detection 后cache-memory 的保存动作被推迟到独立校验作业restore → 修改 → 上传 artifact → 校验 → save校验不过则不落盘自定义校验validation.script以受限 Node 环境执行可用memoryRoot、memoryId等全局变量做 schema 级检查抛异常即拒绝持久化。7. 延伸阅读 官方参考文档docs/src/content/docs/reference/cache-memory.md、docs/src/content/docs/reference/repo-memory.md实战模式库docs/src/content/docs/patterns/memory-ops.md穷尽式处理、断点续传、趋势计算等 7 种模式设计决策记录docs/adr/28482-centralize-cache-memory-directory-path-computation.md缓存目录路径集中化、docs/adr/26587-pre-agent-cache-memory-working-tree-sanitization.md预 Agent 消毒、docs/adr/27479-comment-memory-file-based-agent-memory-with-github-persistence.mdcomment-memory核心源码pkg/workflow/cache_memory.go、pkg/workflow/repo_memory.go、actions/setup/js/push_repo_memory.cjs 一句话总结cache-memory 让 Agent 拥有短期记忆repo-memory 让它拥有档案记忆——而 Agent 本身始终只需要会读写文件。【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-aw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gh-aw 记忆机制完全指南：cache-memory 与 repo-memory 持久化原理详解
gh-aw 记忆机制完全指南cache-memory 与 repo-memory 持久化原理详解【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-awgh-awGitHub Agentic Workflows是一个让 AI Agent 在 GitHub Actions 中自动处理 Issue、PR 和维护任务的开源项目。它的记忆机制通过cache-memory缓存记忆与repo-memory仓库记忆两种存储方式让 Agent 在多次工作流运行之间记住进度、状态和历史数据从而把一次次孤立的运行串联成有记忆的持续任务。1. 为什么 AI Agent 需要记忆GitHub Actions 的每次运行都是全新环境Runner 执行完就销毁Agent 上一次记下的进度、读过的上下文全部丢失。没有记忆的 Agent 每次都要从零开始无法做到⏸️ 长任务断点续传比如批量处理 10000 条记录 跨运行积累历史数据、计算趋势 多个工作流之间共享数据gh-aw 的解法是在 Agent 运行期间挂载一个确定的记忆目录运行结束后由编译器自动生成的步骤把文件同步到持久化存储下次运行时再自动恢复。整个过程对 Agent 是透明的——它只需要正常读写文件即可。2. 三大记忆机制一览 ️gh-aw 提供三种记忆存储按生命周期从轻到重排列机制存储位置保留时长适合场景默认路径cache-memoryGitHub Actions 缓存7 天临时状态、会话数据/tmp/gh-aw/cache-memory/repo-memoryGit 专用分支永久历史数据、长期状态/tmp/gh-aw/repo-memory-{id}/comment-memoryIssue/PR 受管评论永久PR 跟进上下文/tmp/gh-aw/comment-memory/三者共用同一套设计哲学Agent 只操作普通文件持久化由 gh-aw 编译器生成的步骤在幕后完成。3. cache-memory7 天有效期的高速缓存记忆3.1 一键启用在 Markdown 工作流的 frontmatter 中只需一行tools: cache-memory: true编译后Agent 就能在/tmp/gh-aw/cache-memory/目录下自由读写.json、.jsonl、.txt、.md、.csv等文件。gh-aw 还会自动把这段记忆目录说明注入 Agent 的提示词见 pkg/workflow/prompts/cache_memory_prompt.md。3.2 持久化原理restore → 读写 → validate → savecache-memory 的每次运行都遵循一条自动生成的流水线Restore用actions/cache按缓存 key 恢复整个目录。gh-aw 会自动生成带降级链的 restore-keys自动剥离github.run_id本次运行没命中最新缓存时可以回落到更早的运行甚至回落到默认分支的缓存Agent 读写Agent 把文件当作简易文件共享随意组织比如notes.md记观察、history.jsonl记流水日志、state/存结构化状态Validate校验文件扩展名白名单、文件大小数量限制还允许用validation.script写一段自定义 JS 做业务级校验此时不传入任何 GitHub tokenSave校验通过后才把目录打包存回缓存仓库级 10GB 上限LRU 淘汰。核心生成逻辑在 pkg/workflow/cache_memory.go目录、缓存 key、restore-keys 的拼装都发生在编译期。3.3 完整性感知缓存防止低信任数据投毒这是 cache-memory 最有意思的设计。当工作流启用了tools.github.min-integrity时缓存目录内部会初始化一个git 仓库并建立merged / approved / unapproved / none四级完整性分支运行前脚本 actions/setup/sh/setup_cache_memory_git.sh 检出当前运行对应的完整性分支并从高完整性分支向下合并冲突时高完整性数据胜出效果是低信任运行能读到高信任数据但高信任运行永远看不到低信任数据从机制上阻断恶意/低质数据污染可信缓存的路径同时该脚本还会做预 Agent 消毒删除符号链接、剥离可执行位、按allowed-extensions清理不合规文件。3.4 自动清理gh-aw 的 Agentic Maintenance 工作流会定期按key 前缀分组清理 cache-memory每个组只保留最新一条避免缓存无限膨胀。4. repo-memory写入 Git 分支的永久记忆4.1 启用方式同样只需在 frontmatter 中声明例如把记忆写入自定义分支并限制文件类型tools: repo-memory: branch-name: memory/custom-agent-for-aw file-glob: [*.md, *.json] max-file-size: 1048576分支默认自动以orphan孤儿分支创建create-orphan: true无需预先存在。4.2 持久化原理五个阶段的数据流与 cache-memory 的缓存整目录不同repo-memory 走的是**缓存中转 Git 落地**的双阶段模型完整架构定义在 scratchpad/repo-memory.mdCloneAgent 作业开始时脚本 actions/setup/sh/clone_repo_memory_branch.sh 以--depth 1 --single-branch克隆memory/{id}分支到/tmp/gh-aw/repo-memory/{id}/分支不存在则创建孤儿分支ExecutionAgent 直接在目录里读写文件提示词中会明确告知这个记忆路径Upload作业结束时把目录上传为 GitHub Actions artifactrepo-memory-{id}且使用if: always()——即使作业失败记忆也会保存方便事后调试Download Validate独立的 Push 作业下载 artifact逐项校验file-glob、max-file-size默认 10KB、max-file-count默认 100和max-patch-size单次 diff 上限默认 10KBPushactions/setup/js/push_repo_memory.cjs 把文件提交到memory/{id}分支。提交通过 GitHub GraphQL 的createCommitOnBranch变更完成自动携带 GitHub GPG 签名满足提交必须已验证的分支保护规则并发推送时以-X ours合并策略重放你的文件变更永远胜出。4.3 多记忆分区支持一次声明多个记忆分区数组形式每个分区独立分支、独立限制例如一个metrics分支存时序数据、一个config分支存 schema。记忆 ID 遵循[a-zA-Z0-9-]命名规则Go 层与 JavaScript 层共用同一套路径推导规则repo_memory.go中的目录、artifact 名、分支名构建函数由专门的跨层一致性测试保证不漂移。5. 如何选择cache-memory vs repo-memory维度cache-memoryrepo-memory保留时长7 天LRU 淘汰永久版本控制❌✅每次运行 一次提交性能快整目录 tar 恢复稍慢clone commit上限10GB/仓库受仓库限制最佳用途会话状态、API 缓存、断点续传历史指标、趋势分析、跨工作流共享经验法则7 天内还会再用的状态放 cache-memory需要留档、审计、回溯的历史数据放 repo-memory。两者可以同时启用——用缓存做工作集用分支做档案库这是官方 MemoryOps 模式Pattern 6推荐的组合。6. 安全建议与安全机制 不要存敏感数据两种记忆都跟随仓库权限任何能访问仓库的人/流程都能读到凭据、token、PII 一律禁止收紧白名单用allowed-extensions/file-glob限制文件类型cache-memory 在恢复后还会做预消毒删符号链接、去可执行位、清 hooks威胁检测联动启用 threat detection 后cache-memory 的保存动作被推迟到独立校验作业restore → 修改 → 上传 artifact → 校验 → save校验不过则不落盘自定义校验validation.script以受限 Node 环境执行可用memoryRoot、memoryId等全局变量做 schema 级检查抛异常即拒绝持久化。7. 延伸阅读 官方参考文档docs/src/content/docs/reference/cache-memory.md、docs/src/content/docs/reference/repo-memory.md实战模式库docs/src/content/docs/patterns/memory-ops.md穷尽式处理、断点续传、趋势计算等 7 种模式设计决策记录docs/adr/28482-centralize-cache-memory-directory-path-computation.md缓存目录路径集中化、docs/adr/26587-pre-agent-cache-memory-working-tree-sanitization.md预 Agent 消毒、docs/adr/27479-comment-memory-file-based-agent-memory-with-github-persistence.mdcomment-memory核心源码pkg/workflow/cache_memory.go、pkg/workflow/repo_memory.go、actions/setup/js/push_repo_memory.cjs 一句话总结cache-memory 让 Agent 拥有短期记忆repo-memory 让它拥有档案记忆——而 Agent 本身始终只需要会读写文件。【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-aw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考