Vast-Studios/ralph-wiggum

Ralph Wiggum Method

An autonomous AI development technique that treats LLM context like memory, rotating to fresh context before pollution builds up.

Core Principle

The malloc/free Problem:

• Reading files, tool outputs, conversation = malloc() (allocates context)
• There is no free() - context cannot be selectively released
• Only way to free: start a new conversation

Ralph's Solution: Deliberately rotate to fresh context before pollution builds up. State lives in files and git, not in the LLM's memory.

When to Use

Use Ralph Wiggum when:

• Working on complex, multi-step tasks
• Context window is filling up (>60k tokens)
• Agent is repeating failed attempts
• You need autonomous iteration on a task
• Context pollution is causing confusion

Setup

1. Create State Files

mkdir -p .ralph

Create these files:

.ralph/progress.md - What's been accomplished:

# Progress

## Completed
- [x] Initial setup
- [x] Basic structure created

## In Progress
- [ ] Feature implementation

## Next Steps
- Complete feature tests

.ralph/guardrails.md - Lessons learned (Signs):

# Guardrails (Signs)

## Sign: Check imports before adding
- **Trigger**: Adding a new import statement
- **Instruction**: First check if import already exists in file
- **Added after**: Duplicate import caused build failure

RALPH_TASK.md - Task definition with checkboxes:

---
task: Build feature X
test_command: "npm test"
---

# Task: Feature X

## Success Criteria

1. [ ] Feature works correctly
2. [ ] Tests pass
3. [ ] Documentation updated

## Context
- Use framework Y
- Follow pattern Z

2. Initialize Git (if not already)

git init
git add .ralph/ RALPH_TASK.md
git commit -m "ralph: initialize task"

The Loop

Iteration Process

1. Read State (not from previous context):

   • Read RALPH_TASK.md for task definition
   • Read .ralph/progress.md for what's done
   • Read .ralph/guardrails.md for lessons learned
   • Check git history for recent changes

2. Work on Unchecked Criteria:

   • Focus on [ ] items in RALPH_TASK.md
   • Follow guardrails from .ralph/guardrails.md
   • Make incremental progress

3. Commit Progress:

   git add -A
   git commit -m "ralph: [criterion] - description"
   

4. Update State Files:

   • Update .ralph/progress.md with accomplishments
   • If errors occur, add to .ralph/guardrails.md

5. Monitor Context:

   • Track token usage (approximate)
   • At ~70k tokens: warn to wrap up current work
   • At ~80k tokens: ROTATE to fresh context

Context Rotation

When approaching token limits:

1. Commit all work:

   git add -A
   git commit -m "ralph: checkpoint before rotation"
   git push  # if remote exists
   

2. Signal rotation: Output <ralph>ROTATE</ralph>

3. Next iteration: Start fresh, read state from files/git

Guardrails (Signs)

When something fails, add a "Sign" to .ralph/guardrails.md:

### Sign: [Brief description]
- **Trigger**: When this situation occurs
- **Instruction**: What to do differently
- **Added after**: Iteration X - what went wrong

Future iterations read guardrails first and follow them.

Completion Detection

Task is complete when:

1. All [ ] in RALPH_TASK.md are [x]
2. Agent outputs <ralph>COMPLETE</ralph>
3. All tests pass (if test_command specified)

Gutter Detection

Detect when stuck:

• Same command failed 3+ times → GUTTER
• Same file written 5+ times in short period → GUTTER
• Agent outputs <ralph>GUTTER</ralph>

When gutter detected:

1. Check .ralph/guardrails.md for patterns
2. Fix issue manually or add guardrail
3. Re-run iteration

Token Tracking

Approximate tracking:

• File read: ~1KB per 100 lines
• File write: ~1KB per 100 lines
• Tool calls: ~500 bytes each
• Conversation: ~100 bytes per message

Monitor and rotate before 80k tokens.

Workflow Example

# Iteration 1
# Read RALPH_TASK.md, progress.md, guardrails.md
# Work on first [ ] item
# Commit: git commit -m "ralph: implement feature X"
# Update progress.md
# Token count: ~45k → continue

# Iteration 2 (after rotation)
# Read RALPH_TASK.md, progress.md, guardrails.md (fresh context)
# Read git history to see previous work
# Work on next [ ] item
# Commit: git commit -m "ralph: add tests"
# Update progress.md
# Token count: ~78k → ROTATE signal

# Iteration 3 (fresh context)
# Read state files again
# Continue from git history
# Complete remaining items
# All [x] → COMPLETE

Best Practices

1. Commit frequently: After each meaningful change
2. Update progress.md: After completing each criterion
3. Add guardrails: When errors occur, document the lesson
4. Be specific: Each criterion should be testable and achievable
5. Rotate proactively: Don't wait until context is completely full
6. Use git history: Next iteration learns from commits, not context

Key Files Reference

| File | Purpose | Who Uses It | |------|---------|-------------| | RALPH_TASK.md | Task definition + success criteria | You define, agent reads | | .ralph/progress.md | What's been accomplished | Agent writes after work | | .ralph/guardrails.md | Lessons learned (Signs) | Agent reads first, writes after failures | | .ralph/activity.log | Tool call log (optional) | For monitoring | | .ralph/errors.log | Failure log (optional) | For debugging |

Signals

Use these XML-like signals in your output:

• <ralph>ROTATE</ralph> - Request context rotation
• <ralph>COMPLETE</ralph> - Task is complete
• <ralph>GUTTER</ralph> - Agent is stuck, needs intervention
• <ralph>WARN</ralph> - Approaching token limit, wrap up current work

References

• Original Ralph technique - Geoffrey Huntley
• Context as memory - The malloc/free metaphor