Memory Persistence

Since each Ralph iteration starts with a fresh context, the agent has no memory of previous iterations. All memory must be explicitly persisted to disk. Ralph uses four mechanisms to maintain state across iterations.

The Four Persistence Layers

Git History

The source of truth for what code has been implemented.

progress.txt

An append-only log of learnings and context from each iteration.

prd.json

The task list with completion status for each user story.

AGENTS.md Files

Distributed knowledge files throughout the codebase that AI tools automatically read.

Let’s explore each layer in detail.

1. Git History

What It Stores

Every completed user story is committed to git:

git log --oneline
feat: US-005 - Add user profile page
feat: US-004 - Implement password reset
feat: US-003 - Add JWT authentication
feat: US-002 - Create user database schema
feat: US-001 - Initialize project structure

How It’s Used

The next iteration sees all code changes from previous stories
Commit messages provide high-level context
git diff shows exactly what changed
Branches keep Ralph work isolated from main

Commit Format

Ralph uses a consistent commit message format:

feat: [Story ID] - [Story Title]

All changes from an iteration (implementation + prd.json update + progress.txt update + AGENTS.md updates) are committed together in a single commit.

Branch Strategy

The PRD specifies a branchName:

{
  "branchName": "ralph/user-authentication",
  "userStories": [...]
}

Ralph will:

Check if the branch exists
Create it from main if it doesn’t
Check it out
Make all commits on this branch

Using the ralph/ prefix helps distinguish Ralph branches from human-created feature branches.

2. progress.txt

What It Stores

An append-only log where each iteration records:

What was implemented
Which files were changed
Learnings for future iterations (most important!)

Structure

# Ralph Progress Log
Started: 2025-03-11 10:00:00
---

## Codebase Patterns
- Use `sql<number>` template tag for database queries
- Always use `IF NOT EXISTS` in migrations
- Export types from actions.ts for UI components

---

## 2025-03-11 10:15 - US-001
Thread: https://ampcode.com/threads/abc123
- Initialized Next.js project with TypeScript
- Files changed: package.json, tsconfig.json, next.config.js
- **Learnings for future iterations:**
  - This project uses the App Router (not Pages)
  - Environment variables are in .env.local
  - Prettier config requires trailing commas
---

## 2025-03-11 11:30 - US-002
- Created users table migration
- Files changed: migrations/001_create_users.sql, src/db/schema.ts
- **Learnings for future iterations:**
  - Migrations are in migrations/ directory
  - Use `npm run db:migrate` to run migrations
  - Schema types are auto-generated from migrations
---

Codebase Patterns Section

The Codebase Patterns section at the top is critical:

It’s the FIRST thing each iteration reads
Contains the most important, reusable patterns
Gets updated when iterations discover general patterns

Only add patterns that are general and reusable. Don’t clutter this section with story-specific details.

Per-Iteration Sections

Each iteration appends its own section with:

Timestamp and Story ID - When it ran and what it worked on
Thread URL (for Amp) - Link to the full conversation for deep dives
Implementation summary - High-level what was done
Files changed - Which files to look at
Learnings - Patterns, gotchas, and useful context

The “Learnings for future iterations” section is the most valuable part. Be specific and actionable:

✅ “Auth middleware must be imported BEFORE route handlers”
❌ “Fixed auth stuff”

How It’s Used

Each fresh iteration:

Reads progress.txt immediately after reading the PRD
Looks at the Codebase Patterns section first
Scans recent iterations to understand what’s been done
Uses learnings to avoid repeating mistakes
Appends its own learnings at the end

3. prd.json

What It Stores

The structured task list with completion status:

{
  "projectName": "User Authentication",
  "branchName": "ralph/user-authentication",
  "userStories": [
    {
      "id": "US-001",
      "title": "Initialize project structure",
      "priority": 1,
      "passes": true,
      "description": "Set up Next.js with TypeScript",
      "acceptanceCriteria": [
        "TypeScript configured",
        "ESLint and Prettier set up",
        "Project builds successfully"
      ]
    },
    {
      "id": "US-002",
      "title": "Create user database schema",
      "priority": 2,
      "passes": true,
      "description": "Define users table with migrations",
      "acceptanceCriteria": [
        "Migration creates users table",
        "Schema types are generated",
        "Migration runs without errors"
      ]
    },
    {
      "id": "US-003",
      "title": "Implement JWT authentication",
      "priority": 3,
      "passes": false,
      "description": "Add login/logout with JWT tokens",
      "acceptanceCriteria": [
        "POST /api/login issues JWT tokens",
        "Auth middleware validates tokens",
        "Tests verify token validation"
      ]
    }
  ]
}

The `passes` Field

The passes boolean is the key to Ralph’s state machine:

passes: false - Story is not yet complete
passes: true - Story is complete and quality checks passed

How It’s Used

Task Selection - Each iteration picks the highest priority story where passes: false
Completion Tracking - After successful implementation, the agent updates passes: true
Stop Condition - When ALL stories have passes: true, Ralph outputs <promise>COMPLETE</promise>

The PRD is both read (to pick the next task) and written (to mark tasks complete) during each iteration.

Story Structure

Each story includes:

id - Unique identifier (used in commit messages)
title - Short description (used in commit messages)
priority - Order of execution (lowest number = highest priority)
passes - Completion status
description - Detailed explanation of what to build
acceptanceCriteria - Specific requirements that must be met

Good acceptance criteria are specific and testable:

✅ “Tests pass with > 80% coverage”
✅ “API returns 401 for invalid tokens”
❌ “Auth works well”

4. AGENTS.md Files

What They Store

Distributed knowledge files throughout the codebase that document:

Patterns and conventions for that module
Gotchas and non-obvious requirements
Dependencies between files
Testing approaches
Configuration requirements

Where They Live

AGENTS.md files can exist at any level of your project:

project/
  AGENTS.md              # Root-level patterns
  src/
    AGENTS.md            # Patterns for src/ directory
    auth/
      AGENTS.md          # Auth-specific patterns
      login.ts
      middleware.ts
    api/
      AGENTS.md          # API-specific patterns
      routes.ts

How They’re Used

AI coding tools (Amp, Claude Code, etc.) automatically read AGENTS.md files:

When viewing/editing files in a directory
When navigating the codebase
When the agent mentions the directory

This means learnings in AGENTS.md files are always available to future iterations, not just when they explicitly read progress.txt.

AGENTS.md is a convention supported by many AI coding tools. It’s like a README for AI agents.

What to Include

Add to AGENTS.md when you discover: ✅ Good additions:

“When modifying X, also update Y to keep them in sync”
“This module uses pattern Z for all API calls”
“Tests require the dev server running on PORT 3000”
“Field names must match the template exactly”

❌ Bad additions:

Story-specific implementation details
Temporary debugging notes
Information already in progress.txt

Example AGENTS.md

# Auth Module

## Overview
Handles user authentication with JWT tokens.

## Patterns
- All auth routes use `authMiddleware` from `src/middleware/auth.ts`
- JWT tokens expire after 24 hours (configured in env.JWT_EXPIRY)
- Refresh tokens are stored in Redis
- Password hashing uses bcrypt with cost factor 12

## Gotchas
- Do NOT forget to add `authenticate()` to protected routes
- Token validation happens in middleware, not in route handlers
- Tests use `TEST_JWT_SECRET` instead of production secret

## Dependencies
- Requires Redis running on localhost:6379
- Requires `JWT_SECRET` in environment variables

## Testing
- Run auth tests: `npm test -- auth`
- Integration tests require Redis (use `docker-compose up redis`)

How the Layers Work Together

Each layer serves a specific purpose:

Git - What code exists
progress.txt - Why it was built that way
prd.json - What still needs to be done
AGENTS.md - How to work with this code

Archiving

When starting a new feature (different branchName), Ralph archives the old state:

archive/
  2025-03-11-user-authentication/
    prd.json
    progress.txt
  2025-03-12-dashboard-refactor/
    prd.json
    progress.txt

This preserves the history of each Ralph run without cluttering the workspace.

AGENTS.md files are NOT archived—they stay in the codebase permanently as living documentation.

Debugging Memory Issues

If an iteration seems to “forget” something:

Check if it was committed to git
```
git log --oneline -10
git diff main
```
Check if it’s documented in progress.txt
```
grep -A 5 "US-003" progress.txt
```

Check if the story is marked complete

cat prd.json | jq '.userStories[] | {id, title, passes}'

Check if the pattern is in AGENTS.md

find . -name "AGENTS.md" -exec grep -l "pattern" {} \;

If critical information is missing from these four layers, the next iteration has no way to access it.

Best Practices

Commit Frequently

Each completed story should be committed immediately. Don’t accumulate multiple stories in one commit.

Write Detailed Progress Reports

The learnings section in progress.txt is future-you’s only memory. Be thorough.

Update Codebase Patterns

When you discover a reusable pattern, add it to the Codebase Patterns section at the top of progress.txt.

Maintain AGENTS.md Files

Update AGENTS.md files when you discover module-specific patterns that would help future iterations.

Keep PRD Updated

Always update passes: true after completing a story. This is how Ralph knows what to work on next.

Summary

Ralph’s memory is entirely explicit:

Git stores code and changes
progress.txt stores context and learnings
prd.json stores task status
AGENTS.md stores patterns and conventions

Together, these four layers provide everything a fresh AI instance needs to continue where the previous iteration left off.

​Memory Persistence

​The Four Persistence Layers

​1. Git History

​What It Stores

​How It’s Used

​Commit Format

​Branch Strategy

​2. progress.txt

​What It Stores

​Structure

​Codebase Patterns Section

​Per-Iteration Sections

​How It’s Used

​3. prd.json

​What It Stores

​The passes Field

​How It’s Used

​Story Structure

​4. AGENTS.md Files

​What They Store

​Where They Live

​How They’re Used

​What to Include

​Example AGENTS.md

​How the Layers Work Together

​Archiving

​Debugging Memory Issues

​Best Practices

​Summary

Memory Persistence

The Four Persistence Layers

1. Git History

What It Stores

How It’s Used

Commit Format

Branch Strategy

2. progress.txt

What It Stores

Structure

Codebase Patterns Section

Per-Iteration Sections

How It’s Used

3. prd.json

What It Stores

The `passes` Field

How It’s Used

Story Structure

4. AGENTS.md Files

What They Store

Where They Live

How They’re Used

What to Include

Example AGENTS.md

How the Layers Work Together

Archiving

Debugging Memory Issues

Best Practices

Summary