What Belongs in .github/agent-memory/<task-slug>.md Versus the PR Conversation

Store durable, standing guidance in .github/agent-memory/<task-slug>.md and transient, per-run feedback in the PR conversation to maintain a clean two-stage feedback loop for coding agents.

The humanlayer/skills repository implements a sophisticated two-stage feedback loop for iterated coding-agent workflows that separates long-term policy from short-term course corrections. Understanding what belongs in the agent memory file versus the pull request conversation ensures your AI coding agents maintain context across runs without polluting version control with ephemeral instructions.

The Two-Stage Feedback Loop Architecture

According to the source code in humanlayer/skills, the system uses a strict separation between durable guidance and transient feedback. This design is documented in SKILL.md, which establishes distinct phases where memory is loaded and where per-run instructions are processed.

Durable Memory Files (.github/agent-memory/.md)

Files stored in .github/agent-memory/<task-slug>.md serve as the standing guidance channel. As implemented in references/agent-iteration.ts (lines 70-84), these files are loaded into the actuator on every workflow run after the controller phase. This ensures that constraints, preferences, and policies persist across iterations and survive beyond a single PR.

Place the following content in your agent memory file:

• Permanent scope constraints (e.g., "never touch src/vendor/")
• Known false-positive areas that the agent should consistently ignore
• Reviewer preferences that should apply to all future iterations
• High-level policy or "steering" that defines the workflow's boundaries

The memory template at references/memory-template.md specifies that these files should contain a required header and a single "Guidance" section, remaining concise and human-readable.

Transient PR Conversations

The PR conversation—including the PR body and comments—handles per-run feedback only. When a maintainer comments /iterate <feedback>, the agent reads this transient context, applies immediate changes, and optionally updates the memory file only if the guidance proves durable.

Place the following content in PR conversations:

• Specific change requests for this PR (e.g., "use fooBar instead of baz in this file")
• One-off debugging notes or logs
• Anything that does not need to persist for the next run
• Instructions that apply only to the current iteration's context

What to Store in Agent Memory Files

The agent memory file, created from the skeleton in references/memory-template.md, acts as version-controlled institutional memory. According to the skill definition in SKILL.md, you should keep "one source of truth for each rule" and avoid repeating guidance across the skill, prompt, and memory file.

Store durable constraints such as:

1. Directory exclusions that never change between runs
2. Linting rules that should always be respected or ignored
3. Architectural decisions about library preferences (e.g., "Prefer axios over request")
4. False-positive patterns the agent consistently encounters

What to Store in PR Conversations

PR conversations are ephemeral by design. The workflow appends a footer containing a hidden marker (codelayer-agent:workflow=…;memory=…) and a /iterate instruction that links back to the durable memory file.

Use PR comments for:

• Immediate code review feedback requiring specific line changes
• Contextual debugging information relevant only to the current error state
• Questions or clarifications about the current implementation
• Instructions that start with /iterate to trigger the next agent run

Technical Implementation: How the Workflow Connects Both Systems

The integration between memory files and PR conversations is handled by references/agent-iteration.ts. This script generates the PR footer and constructs the iteration prompt, explicitly loading the memory file using the --memory .github/agent-memory/<task-slug>.md argument while reminding the agent to keep memory updates concise.

As described in SKILL.md Phase F, the memory file is interpolated after the controller but before the actuator executes. This means the durable guidance shapes the agent's behavior while the PR conversation provides the immediate task context.

The hidden marker in the PR footer serves a critical function: it tells the agent which memory file to load for future runs of this specific workflow, creating a bidirectional link between the transient PR and the durable memory store.

Practical Examples

The following examples demonstrate the separation between durable memory and transient feedback.

Example Memory File Structure

Create your .github/agent-memory/<task-slug>.md following this pattern from references/memory-template.md:

# Agent Memory: Example Task

Standing feedback for future `Agent: Example Task` runs. This is the human-on-the-loop steering channel: it is loaded into the actuator on every run (after the controller), so edits here change future behavior, not just one PR. Keep durable guidance only — not one-off instructions or single-run logs.

## Guidance

- Do not modify files under `src/generated/`.
- Exclude lint rule `no-use-effect` from automatic fixes.
- Prefer `axios` over `request` for HTTP calls.

PR Footer Generated by the Workflow

When the workflow runs, references/agent-iteration.ts appends this footer to the PR:

---

### Iterating on this agent run

This PR was opened by a coding agent workflow. Maintainers can comment:

- `/iterate <feedback>` to ask the same workflow to update this PR and learn durable guidance for future runs.

The workflow stores durable feedback in its agent memory file and injects that memory into future runs.

<!-- codelayer-agent:workflow=example-workflow;memory=.github/agent-memory/example-task.md;version=1 -->

Using the /iterate Command

To provide transient feedback that may or may not become durable:

/iterate Please ensure the new helper respects the existing `no-use-effect` rule.

When processed, the agent applies the immediate code change and, recognizing this as durable policy, appends "Never disable the no-use-effect rule" to the memory file.

Summary

• Store durable guidance in .github/agent-memory/<task-slug>.md to persist constraints across all future workflow runs
• Place transient feedback in PR comments using /iterate for one-time changes and debugging
• The workflow loads memory files after the controller phase (Phase F) as implemented in references/agent-iteration.ts
• Keep memory files concise and human-readable following the template in references/memory-template.md
• Avoid duplicating guidance across memory files, prompts, and skill definitions per SKILL.md policy

Frequently Asked Questions

How does the agent know which memory file to load?

The agent locates the correct memory file through a hidden marker embedded in the PR footer. According to references/agent-iteration.ts, the marker format is <!-- codelayer-agent:workflow=example-workflow;memory=.github/agent-memory/example-task.md;version=1 -->. This marker persists in the PR body and tells subsequent workflow runs exactly which durable memory file to inject during Phase F.

When should I update the memory file versus just commenting?

Update the memory file directly when you identify standing policy that should affect all future runs, such as new architectural constraints or persistent false positives. Use PR comments with /iterate for transient corrections specific to the current implementation, such as variable naming choices or one-off debugging steps. The agent will automatically promote durable feedback from PR comments to the memory file when appropriate.

What happens to PR comments after the workflow runs?

PR comments remain in the conversation history but are treated as transient context. The workflow does not automatically preserve PR feedback across runs unless a maintainer or agent explicitly determines the guidance is durable and writes it to .github/agent-memory/<task-slug>.md. This prevents ephemeral debugging notes from polluting future agent contexts.

Can I have multiple memory files for different workflows?

Yes. The <task-slug> in .github/agent-memory/<task-slug>.md corresponds to specific workflow identifiers defined in the hidden PR marker. Each distinct workflow can maintain its own memory file, allowing different agents or tasks to operate with specialized guidance without interfering with one another.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}