An autonomous loop does not need one giant memory file. It needs several kinds of state with different owners, lifetimes, and validation rules. Mixing a current task status, a repository-wide convention, an unverified debugging note, and a dependency relationship into the same document turns convenience into ambiguity.
Ralph Loop memory is therefore better treated as a layered design problem. The original Ralph pattern emphasizes durable plans, repository changes, and executable feedback. Particular implementations add their own state surfaces. The job for a team is to decide what each surface means, who may update it, and when it expires.
What Ralph Loop Memory Includes
At least four layers usually matter:
The purpose of Ralph Loop memory is to preserve those layers without granting temporary task notes the authority of reviewed project rules or current source.
- Task state: what is being attempted, what is complete, what failed, and what remains.
- Project rules: stable commands, conventions, boundaries, and review requirements that apply beyond one task.
- Experience: observations from an iteration, including failed approaches and useful paths, which may or may not deserve promotion into a project rule.
- Code structure: current modules, symbols, dependencies, call paths, and test relationships derived from source.
These layers overlap, but they are not interchangeable. “Run the API tests after changing the schema” may become a durable rule. “Test 17 failed because my fixture was stale” is task history. “Package B imports interface A” is a structural claim that should be regenerated or verified when the code changes.
The names of the storage files are implementation details. Huntley’s original Ralph description discusses a plan file, repository work, and feedback from builds or tests. The snarktank implementation uses prd.json, progress.txt, Git history, and prompt guidance.
Task State vs Project Rules
Task state is scoped and mutable. It can record the selected story, acceptance criteria, incomplete checks, and a concise note for the next iteration. It should reset or archive when the task or branch changes. If task state accumulates indefinitely, the next loop must distinguish relevant evidence from historical noise.
A search for Ralph progress.txt is useful only after the team has confirmed that it is discussing the snarktank implementation rather than Ralph as a general pattern.
Project rules are broader and more stable. They include build commands, style constraints, package ownership, security requirements, and known repository-specific traps. They should change through review because a mistaken rule can misdirect every later task. The AGENTS.md specification supports scoped instruction files: instructions apply to a directory tree, and a more deeply nested file can refine or override them within its own scope.
That hierarchy is useful because many “global” rules are not global. A frontend package and a data migration directory may have different validation commands and write constraints. Putting both in a root note forces every loop to carry irrelevant instructions. Scoped project rules reduce context while making ownership visible.
The boundary is promotion. An iteration may discover a recurring repository fact, but it should not silently convert a one-off observation into a permanent rule. Promotion should require evidence, a clear scope, and an owner. Otherwise the memory layer becomes a collection of confident anecdotes.
Progress Files, AGENTS.md, and Git History
In snarktank’s loop, progress.txt is an append-oriented handoff between iterations. The prompt template tells the agent to read it, use Git history, work on one story, run quality checks, commit, and append useful information. The README says the file is archived and reset when a new branch starts. Those are properties of that implementation, not of every Ralph loop.
A team searching for a Ralph loop Codex workflow should design the memory layers first rather than copying those filenames without their semantics.
Git history serves a different purpose. It records durable changes and their sequence, but a commit message is not necessarily a complete task handoff. The next loop may need current test failures or a reason an attempted approach was abandoned. That short-lived operational context belongs in task state, while the code itself remains the primary record of implementation.
AGENTS.md should hold reusable instructions, not a transcript of the current story. A useful entry explains a command, invariant, or directory convention that future tasks will need. Story-specific steps should remain in the task plan or progress file. This division prevents a temporary workaround from becoming permanent policy.
No layer should be trusted merely because it persisted. Read the current source, inspect recent changes, and use tests or static checks as backpressure. Memory narrows where to look; it does not supersede the repository.
Where Code Graphs Store Structural Knowledge
Structural knowledge has a different update model from prose memory. Imports, calls, implementations, schema references, and test coverage can change with a single commit. A code graph can index those relationships and answer a task-scoped query, but the returned facts should include file, symbol, commit SHA, and index version.
For a Ralph loop, this creates a read-mostly orientation layer. The task can ask which modules depend on a changed interface or which tests touch a call path, then verify the cited source before editing. Graphify is one possible codebase graph layer for this use case. It should complement exact text search and source inspection, not replace them.
This is an extension to the Ralph pattern. The cited Huntley, snarktank, and Anthropic Ralph implementations do not define a native code graph. Claude Code supports external integrations through MCP, but a graph service still needs its own freshness, access, and provenance controls.
Structural facts should rarely be hand-edited as prose. If the graph disagrees with source at the active commit, source wins and the index should be repaired. Human annotations may explain an architectural intent, but they should be stored separately from derived edges so reviewers know which assertions were computed and which were authored.
Failure Modes and Cleanup Notes
The first failure mode is stale authority. An old note may describe a module that moved, a command that changed, or a task that was abandoned. Every layer needs an expiration policy: task state resets at a task boundary, project rules are reviewed when contradicted, and structural indexes invalidate on commit or schema drift.
The second is conflict. A root instruction, nested instruction, progress note, and current source may disagree. Resolve the conflict by scope and authority: current source and executable checks establish behavior; the most specific reviewed instruction governs process; task notes explain intent but do not override verified reality. Record the resolution so the next iteration does not repeat it.
The third is uncontrolled growth. Append-only logs are useful for audit, but poor as an active prompt once they become long. Archive completed episodes, summarize only verified lessons, and keep the active handoff small. Do not delete history that is required for review; remove it from the hot context.
Finally, prevent sensitive data from entering shared memory. Progress logs and graph indexes can outlive a session and reach more agents than the original prompt. Store secrets in approved secret systems, restrict indexed paths, and review access separately for task, policy, and structural layers.
FAQ
What memory should be read-only?
Treat derived structural indexes, approved project rules, and finalized task specifications as read-only to an implementation loop unless an explicit workflow authorizes updates. The loop can propose changes, but another check or owner should validate them. Active task status can be writable within its branch and scope.
When should progress files reset?
Reset or archive them when the branch, feature, or task identity changes, or when a completed episode no longer belongs in active context. Preserve an auditable copy if the work requires it. Snarktank documents a new-branch reset, but other implementations can choose a different boundary if they state it clearly.
Who resolves memory conflicts?
The owner of the affected scope should decide process or architecture disputes. Before escalation, the agent should gather current source, applicable instructions, commit history, and test evidence. Conflicts involving security, public APIs, or cross-team ownership should not be resolved by an autonomous loop alone.
What is the Ralph loop pattern?
It is a repeated agent-development cycle driven by a stable task or plan and constrained by feedback such as tests, builds, or static analysis. Some implementations start a new process per iteration; Anthropic’s official plugin continues through a Stop hook in the current Claude Code session. Memory surfaces therefore vary by implementation.
Conclusion
Good Ralph Loop memory is less about remembering everything and more about preserving the right evidence at the right layer. Task state should be small and resettable. Project rules should be scoped and reviewed. Experience should be promoted cautiously. Code structure should be derived from current source and carry provenance.
When those boundaries are explicit, a fresh iteration can recover what it needs without treating an old conversation as architecture. For the structural retrieval layer, see knowledge graphs for AI coding assistants. For the reset boundary that makes these layers necessary, see Ralph fresh context trade-offs.
Leave a Reply