mirror of
https://github.com/jjbrunton/Sauci.git
synced 2026-10-31 18:19:43 +00:00
jjbrunton
8d4d9d8750
Move swipe screen logic into hooks/services and extract state-specific UI components to keep files small while preserving existing behavior. Reference: US-002
127 lines
3.5 KiB
Markdown
127 lines
3.5 KiB
Markdown
# Context Engineering Reference
|
|
|
|
This document explains the malloc/free metaphor for LLM context management that underlies the Ralph technique.
|
|
|
|
## The malloc() Metaphor
|
|
|
|
In traditional programming:
|
|
- `malloc()` allocates memory
|
|
- `free()` releases memory
|
|
- Memory leaks occur when you allocate without freeing
|
|
|
|
In LLM context:
|
|
- Reading files, receiving responses, tool outputs = `malloc()`
|
|
- **There is no `free()`** - context cannot be released
|
|
- The only way to "free" is to start a new conversation
|
|
|
|
## Why This Matters
|
|
|
|
### Context Pollution
|
|
|
|
When you work on multiple unrelated tasks in the same context:
|
|
|
|
```
|
|
Task 1: Build authentication → context contains auth code, JWT docs, security patterns
|
|
Task 2: Build UI components → context now ALSO contains auth stuff
|
|
|
|
Result: LLM might suggest auth-related patterns when building UI
|
|
or mix concerns inappropriately
|
|
```
|
|
|
|
### Autoregressive Failure
|
|
|
|
LLMs predict the next token based on ALL context. When context contains:
|
|
- Unrelated information
|
|
- Failed attempts
|
|
- Mixed concerns
|
|
|
|
The model can "spiral" into wrong territory, generating increasingly off-base responses.
|
|
|
|
### The Gutter Metaphor
|
|
|
|
> "If the bowling ball is in the gutter, there's no saving it."
|
|
|
|
Once context is polluted with failed attempts or mixed concerns, the model will keep referencing that pollution. Starting fresh is often faster than trying to correct course.
|
|
|
|
## Context Health Indicators
|
|
|
|
### 🟢 Healthy Context
|
|
- Single focused task
|
|
- Relevant files only
|
|
- Clear progress
|
|
- Under 60% capacity
|
|
|
|
### 🟡 Warning Signs
|
|
- Multiple unrelated topics discussed
|
|
- Several failed attempts in history
|
|
- Approaching 80% capacity
|
|
- Repeated similar errors
|
|
|
|
### 🔴 Critical / Gutter
|
|
- Mixed concerns throughout
|
|
- Circular failure patterns
|
|
- Over 90% capacity
|
|
- Model suggesting irrelevant solutions
|
|
|
|
## Best Practices
|
|
|
|
### 1. One Task Per Context
|
|
|
|
Don't ask "fix the auth bug AND add the new feature". Do them in separate conversations.
|
|
|
|
### 2. Fresh Start on Topic Change
|
|
|
|
Finished auth? Start a new conversation for the next feature.
|
|
|
|
### 3. Don't Redline
|
|
|
|
Stay under 80% of context capacity. Quality degrades as you approach limits.
|
|
|
|
### 4. Recognize the Gutter
|
|
|
|
If you're seeing:
|
|
- Same error 3+ times
|
|
- Solutions that don't match the problem
|
|
- Circular suggestions
|
|
|
|
Start fresh. Your progress is in the files.
|
|
|
|
### 5. State in Files, Not Context
|
|
|
|
Write progress to files. The next conversation can read them. Context is ephemeral; files are permanent.
|
|
|
|
## Ralph's Approach
|
|
|
|
The original Ralph technique (`while :; do cat PROMPT.md | agent ; done`) naturally implements these principles:
|
|
|
|
1. **Each iteration is a fresh process** - Context is freed
|
|
2. **State persists in files** - Progress survives context resets
|
|
3. **Same prompt each time** - Focused, single-task context
|
|
4. **Failures inform guardrails** - Learning without context pollution
|
|
|
|
This Cursor implementation aims to bring these benefits while working within Cursor's session model.
|
|
|
|
## Measuring Context
|
|
|
|
Rough estimates:
|
|
- 1 token ≈ 4 characters
|
|
- Average code file: 500-2000 tokens
|
|
- Large file: 5000+ tokens
|
|
- Conversation history: 100-500 tokens per exchange
|
|
|
|
Track allocations in `.ralph/context-log.md` to stay aware.
|
|
|
|
## When to Start Fresh
|
|
|
|
**Definitely start fresh when:**
|
|
- Switching to unrelated task
|
|
- Context over 90% full
|
|
- Same error 3+ times
|
|
- Model suggestions are off-topic
|
|
|
|
**Consider starting fresh when:**
|
|
- Context over 70% full
|
|
- Significant topic shift within task
|
|
- Feeling "stuck"
|
|
- Multiple failed approaches in history
|