# How the Agent Memory File Is Deterministically Loaded into the Actuator Context > Learn how the agent memory file is deterministically loaded into the actuator context via the --memory flag in GitHub Actions. Discover the process after the controller step. - Repository: [HumanLayer/skills](https://github.com/humanlayer/skills) - Tags: internals - Published: 2026-09-13 --- **The `.github/agent-memory/.md` file is deterministically loaded when the GitHub Actions workflow passes a `--memory` flag to [`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts), which reads the file content and injects it into the actuator's prompt context immediately after the controller step completes.** The `humanlayer/skills` repository implements an **iterated coding-agent loop** following classic control-theory architecture. Understanding how the memory/feedback file is deterministically loaded into the actuator's context ensures that persistent feedback—such as scope exclusions and reviewer notes—consistently influences agent behavior across every CI run. ## The Control Loop Architecture The repository models agent execution as a control loop: ``` sensor → controller → actuator │ │ └─ disturbance ─┘ ``` In this design, the **memory/feedback file** acts as persistent "standing feedback" that survives between iterations. The **deterministic loading** mechanism guarantees that this file's contents are injected after the controller completes its analysis but before the actuator executes modifications. This sequencing prevents memory from biasing the controller's sensing phase while ensuring the actuator respects accumulated feedback. ## Deterministic Loading Pipeline The deterministic loading relies on three tightly coupled components that enforce the same hard-coded path across every execution. ### Workflow Template Entry Point The [`workflow-template.yml`](https://github.com/humanlayer/skills/blob/main/workflow-template.yml) file serves as the deterministic entry point. It invokes the agent iteration script with the `--memory` flag, ensuring the same file path is supplied on every workflow run based on the task slug. Located at [`plugins/design-control-loop/skills/design-control-loop/references/workflow-template.yml`](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/references/workflow-template.yml), this workflow guarantees that the path `.github/agent-memory/.md` is consistently passed into the execution context regardless of repository state changes elsewhere. ### Agent Iteration Script The [`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts) script acts as the deterministic glue between the workflow and the actuator. It reads the markdown file into the `MEMORY_CONTENT` variable and forwards this string to the actuator. Located at [`plugins/design-control-loop/skills/design-control-loop/references/agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/references/agent-iteration.ts), the script always executes the file read operation before invoking the actuator. This ensures the actuator receives the exact same content on every run unless the memory file itself is version-controlled and modified. ### Actuator Context Injection After the controller determines *what* changes to make, the actuator receives the memory string and interpolates it into **Phase F** of the prompt generation. This allows the agent to honor permanent exclusions and known false-positives during the execution phase. Because the memory is supplied as an explicit argument after the controller step, the actuator's context is reproducibly enriched independent of transient repository state. ## Implementation Details The following code snippets demonstrate how the deterministic loading is implemented across the repository. ### CI Workflow Configuration The workflow definition passes the memory file path via command-line flag: ```yaml # plugins/design-control-loop/skills/design-control-loop/references/workflow-template.yml steps: - name: Run coding agent run: | bun ci-scripts/agent-iteration.ts \ --command actuator \ --workflow agent-design-control-loop \ --memory .github/agent-memory/.md \ >> "$PR_BODY_FILE" ``` This configuration ensures the `--memory` argument is always present and points to the deterministic path. ### Memory File Reading Logic The iteration script reads the file into memory before actuator invocation: ```typescript // plugins/design-control-loop/skills/design-control-loop/references/agent-iteration.ts const memoryPath = process.argv.includes('--memory') ? process.argv[process.argv.indexOf('--memory') + 1] : '.github/agent-memory/.md'; const MEMORY_CONTENT = require('fs').readFileSync(memoryPath, 'utf8'); // Later, when invoking the actuator: const cmd = `bun run actuator --prompt "${prompt}" --memory "${MEMORY_CONTENT}"`; ``` The script uses `readFileSync` to load the content synchronously, ensuring `MEMORY_CONTENT` is populated before the actuator subprocess begins. ### Memory File Structure The template defines the expected structure for the persistent feedback file: ```markdown # Agent Memory – ## Permanent Scope Exclusions - ... ## Known False-Positives - ... ## Reviewer Feedback - ... ``` This structure allows developers to maintain version-controlled feedback that the actuator references on every subsequent run. ## Summary - **Deterministic path enforcement**: The [`workflow-template.yml`](https://github.com/humanlayer/skills/blob/main/workflow-template.yml) hard-codes the `.github/agent-memory/.md` path via the `--memory` flag, ensuring consistency across CI runs. - **Synchronous file loading**: The [`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts) script reads the memory file into `MEMORY_CONTENT` before invoking the actuator, acting as a deterministic gate. - **Controller isolation**: The controller step executes without memory context, ensuring unbiased analysis of the current code state. - **Actuator enrichment**: The memory content is interpolated into Phase F of the actuator's prompt after the controller completes, allowing persistent feedback to influence execution without corrupting the sensing phase. ## Frequently Asked Questions ### What is the purpose of the `.github/agent-memory/.md` file? This file serves as persistent "standing feedback" that carries forward between agent iterations. It stores **permanent scope exclusions**, **known false-positives**, and **reviewer feedback** that should influence all future runs of the specific task agent. ### Why is the memory loaded after the controller step? Loading the memory after the controller ensures the controller performs an unbiased analysis of the current code state during its sensing phase. The actuator then applies the persistent feedback during the execution phase, maintaining separation between observation (controller) and action (actuator). ### How does deterministic loading ensure reproducible agent behavior? By enforcing a hard-coded path in the workflow template and always reading the file via [`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts) before actuator invocation, every CI run receives the exact same memory context. Reproducibility is guaranteed because the memory file is version-controlled, and the loading mechanism does not depend on runtime discovery or environment variables. ### Where must the memory file be located? The file must reside at `.github/agent-memory/.md` relative to the repository root, where `` corresponds to the specific agent task identifier defined in the workflow configuration. This convention ensures the workflow template and iteration script can locate the file without dynamic path resolution.