docs: add .github/aw/memory.md — canonical guide for persistent memory strategies

[Copilot]

Agents were hallucinating repo-memory as a synonym for cache-memory. These are distinct tools with different backends, persistence models, and permission requirements.

Changes

.github/aw/memory.md (new)

Prompt loaded by the agentic-workflows authoring agent when designing persistence strategies. Covers:

• cache-memory — first choice; GitHub Actions cache backend, zero repo noise, works with all engines, up to 90-day retention. Includes a complete scheduled-workflow deduplication example and filename safety rules (no colons in artifact names).
• repo-memory — Git branch backend; indefinite persistence, auditable history, requires contents: write. For long-lived knowledge bases, not ephemeral state.
• repo-memory + wiki: true — GitHub Wiki backend; human-browsable pages, Markdown-only.
• Side-by-side comparison table across all three options.
• Explicit anti-patterns: repo-memory ≠ cache-memory, don't use repo-memory for per-run state.

.github/aw/create-agentic-workflow.md

Updated the caching hint to name cache-memory as the canonical persistence tool and link to the new memory.md comparison guide.

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

[github-actions]

Hey @Copilot 👋 — thanks for picking up the cache-memory documentation task! Documenting the canonical deduplication tool will help prevent agent hallucinations like the repo-memory issue surfaced in discussion #22071 — really valuable signal to bake into the project's reference material.

A couple of things to address before this is ready for review:

• No file changes yet — the PR currently contains only an "Initial plan" commit with an empty diff. The implementation still needs to land.
• Redirect from AGENTS.md — per @pelikhan's comment in the PR description, the content should not go into AGENTS.md. Instead, you should create a new file at .github/aw/memory.md that covers all memory/persistence options (cache-memory, repo-memory, repo-memory with wiki), their benefits, and tradeoffs. The AGENTS.md section at line 1053 ("Workflow Artifacts and Cache-Memory") can remain as a brief pointer but shouldn't be the primary home for this guidance.
• Update the acceptance criteria — the current checklist in the PR description targets AGENTS.md changes and skills/ updates; these should be revised to reflect the .github/aw/memory.md target.

If you'd like a hand, you can assign this prompt to your coding agent:

Create the file `.github/aw/memory.md` as a new agentic prompt file loaded by `.github/agents/agentic-workflows.agent.md`.

The file should help the workflow-authoring agent choose the right memory/persistence strategy. Cover the following:

1. **cache-memory** (first choice)
   - What it is: GitHub Actions artifact-backed cache scoped to the workflow run
   - How to use it for deduplication in scheduled workflows (e.g., skip already-processed items)
   - Concrete example: reading/writing a JSON state file at `/tmp/gh-aw/cache-memory/(filename).json`
   - Filename constraints (no colons — use dashes instead of ISO 8601 colons)

2. **repo-memory** (second option — note: does NOT exist as a built-in tool; clarify this explicitly to avoid hallucination)
   - Explain why `repo-memory` is NOT a supported tool in this project
   - Add a prominent warning: "⚠️ `repo-memory` does not exist. Do not use this in workflow frontmatter."

3. **repo-memory with wiki** (manual pattern)
   - Describe the manual pattern of storing state in a GitHub wiki page as an alternative
   - Benefits vs tradeoffs vs cache-memory

4. **Decision guide** — a short table or list helping the agent pick the right option:
   - Use `cache-memory` for per-run deduplication and transient state
   - Use wiki-based patterns only when long-term cross-run persistence across repos is needed
   - Never use `repo-memory` (invalid)

After creating the file, update the Workflow Artifacts and Cache-Memory section of `AGENTS.md` (around line 1053) to add a cross-reference to `.github/aw/memory.md` for full details.

Finally, run `make agent-finish` to validate all changes before marking the PR ready for review.

Note

🔒 Integrity filtering filtered 1 item

Integrity filtering activated and filtered the following item during workflow execution.
This happens when a tool call accesses a resource that does not meet the required integrity or secrecy level of the workflow.

• issue:#unknown (search_issues: has secrecy requirements that agent doesn't meet. The agent is not authorized to access private-scoped data.)

Generated by Contribution Check · ◷

[Copilot]

Pull request overview

Adds a canonical documentation guide clarifying persistent memory options for agentic workflows, aiming to prevent confusion between cache-memory and repo-memory.

Changes:

• Added .github/aw/memory.md as a detailed comparison/decision guide for cache-memory vs repo-memory (branch) vs repo-memory with wiki: true.
• Updated .github/aw/create-agentic-workflow.md to recommend cache-memory as the canonical persistence tool and point to the new guide.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
.github/aw/memory.md	New canonical reference doc explaining when/how to use each persistence option and their tradeoffs.
.github/aw/create-agentic-workflow.md	Updates workflow authoring guidance to explicitly recommend cache-memory and link to the new comparison doc.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.