Fresh Context

Why each Ralph iteration starts with a clean slate

Fresh Context

One of Ralph’s core design principles is that each iteration spawns a completely fresh AI instance with clean context. This is not just an implementation detail—it’s a fundamental feature that makes Ralph reliable and scalable.

What Does “Fresh Context” Mean?

Every time Ralph starts a new iteration, it:

1. Terminates the previous AI instance completely
2. Spawns a new AI process (Amp or Claude Code)
3. Starts with zero conversation history from the previous iteration
4. Reads the prompt template from scratch (prompt.md or CLAUDE.md)

Think of it like rebooting a computer between tasks. Each iteration is a completely new session.

Why Fresh Context?

1. Avoids Context Window Exhaustion

AI models have limited context windows. In a long-running conversation:

• The chat history grows with every message
• Code diffs and file contents accumulate
• Eventually, the model runs out of context
• Quality degrades or the session crashes

With fresh context:

• Each iteration starts at 0 tokens
• The AI can use its full context window for the current task
• No risk of hitting limits mid-implementation

If a single user story is too large to complete in one context window, the AI will run out of context before finishing and produce poor code. Keep stories small!

2. Prevents Context Pollution

In long conversations, the AI can:

• Accumulate incorrect assumptions
• Remember abandoned approaches
• Get confused by contradictory instructions
• Develop “bad habits” from trial-and-error

Fresh context means:

• Each iteration starts with a clean mental model
• No baggage from previous failed attempts
• Consistent behavior across iterations

3. Enables Parallel Development

Because iterations are independent:

• You could theoretically run multiple Ralph instances on different branches
• Each instance works on a different story
• No shared state to synchronize (except git)

4. Makes Debugging Easier

When something goes wrong:

• You can examine exactly one iteration in isolation
• The input is always the same: prompt template + persistent files
• No hidden conversation history to untangle
• Easy to reproduce issues

What Persists Between Iterations?

If each iteration is fresh, how does Ralph remember what it’s done?

1. Git History

   Every completed story is committed to git. The next iteration sees:

   • All code changes from previous stories
   • Commit messages describing what was done
   • The full git log

   git log --oneline -10
   feat: US-003 - Add user authentication
   feat: US-002 - Create database schema
   feat: US-001 - Set up project structure
   
2. progress.txt

   Each iteration appends to progress.txt with:

   • What was implemented
   • Files changed
   • Learnings and patterns discovered
   • Gotchas to avoid

   The next iteration reads this file to understand what happened and what patterns to follow.

3. prd.json

   The PRD tracks which stories are complete:

   {
     "userStories": [
       {"id": "US-001", "title": "Setup", "passes": true},
       {"id": "US-002", "title": "Schema", "passes": true},
       {"id": "US-003", "title": "Auth", "passes": false}
     ]
   }
   

   This tells the next iteration what to work on.

4. AGENTS.md Files

   Discovered patterns are written to AGENTS.md files throughout the codebase. AI tools automatically read these files, so learnings persist for all future work.

These four persistence mechanisms (git, progress.txt, prd.json, AGENTS.md) are the only memory between iterations. Everything else is fresh.

How Fresh Context Changes Your Workflow

Story Size Matters

Each user story must be completable in a single context window:

✅ Good story sizes:

• Add a database column and migration
• Add a UI component to an existing page
• Update a server action with new logic
• Add a filter dropdown to a list

❌ Too big (split these):

• “Build the entire dashboard”
• “Add authentication”
• “Refactor the API”

If you’re using Amp with auto-handoff enabled, larger stories become feasible because Amp can hand off to a fresh context mid-story. Configure this in ~/.config/amp/settings.json:

{
  "amp.experimental.autoHandoff": {"context": 90}
}

Write Good Progress Reports

Because the next iteration can’t see your conversation history, your progress report in progress.txt is critical:

Bad progress report:

## US-003
Added auth. It works now.

Good progress report:

## 2025-03-11 14:30 - US-003
- Implemented JWT authentication
- Files changed: src/auth.ts, src/middleware/auth.ts, src/routes/login.ts
- **Learnings for future iterations:**
  - This codebase stores JWT secret in env.JWT_SECRET
  - Auth middleware must be imported BEFORE route handlers
  - Tests require TEST_JWT_SECRET in test environment

Update AGENTS.md Files

Since AI tools automatically read AGENTS.md files, updating them is like giving permanent memory to all future iterations:

# Auth Module

## Patterns
- All auth routes must use `authMiddleware` from `src/middleware/auth.ts`
- JWT tokens expire after 24 hours (configured in env.JWT_EXPIRY)
- Refresh tokens are stored in Redis

## Gotchas
- Do NOT forget to add `authenticate()` to protected routes
- Password hashing uses bcrypt with cost factor 12

Debugging Fresh Context Issues

If an iteration seems to “forget” something:

1. Check progress.txt - Did the previous iteration document the learning?
2. Check AGENTS.md - Is the pattern documented in the relevant directory?
3. Check git log - Is the code change actually committed?
4. Check prd.json - Is the story marked as passes: true?

If critical information is missing from these files, the fresh iteration has no way to know about it.

Benefits vs. Stateful Agents

Compared to a single long-running AI conversation:

Fresh Context (Ralph)	Stateful Conversation
✅ Never runs out of context	❌ Eventually hits context limits
✅ Consistent behavior	❌ Can develop bad habits
✅ Easy to debug	❌ Hidden conversation history
✅ Can run in parallel	❌ Sequential only
❌ Requires good documentation	✅ Remembers everything
❌ Stories must be atomic	✅ Can handle messy, exploratory work

Fresh context is ideal for structured, well-defined work (like implementing a PRD). For exploratory coding or debugging, a stateful conversation may be more appropriate.

Summary

Fresh context is what allows Ralph to run indefinitely without degradation:

• Each iteration is independent and self-contained
• Memory persists through git, progress.txt, prd.json, and AGENTS.md
• Stories must be small enough for one context window
• Good documentation is essential for continuity

This architecture trades some convenience (the AI can’t remember your conversation) for reliability and scalability (the AI never gets confused or runs out of context).