Skip to main content

​
Context Overload Recovery

If your SI is experiencing context overflow due to loading too many memories, this guide will help you recover and prevent future issues.

​
Symptoms

  • SI crashes or errors when loading memory
  • “Context too long” or similar errors
  • Slow performance during memory load
  • SI unable to complete tasks after loading memory

​
Quick Fix

Update your memory load command to use budget-aware loading: 
# Instead of:
kernle -s your-stack load

# Use:
kernle -s your-stack load --budget 6000
This limits memory loading to approximately 6000 tokens, preventing overflow.

​
Recovery Steps

1

Update Kernle

Ensure you have the latest version with budget-aware loading:
pip install --upgrade kernle
# Or from source:
cd ~/kernle && git pull && pip install -e .
2

Verify Budget Support

Check that the budget flag is available:
kernle load --help
# Should show: --budget, -b
3

Test with Small Budget

Start with a small budget to verify it works:
kernle -s your-stack load --budget 2000 --json | wc -c
# Should output ~8000 chars (2000 tokens × 4 chars/token)
4

Update Your Configuration

Modify your stack configuration to use budget loading. See examples below.

​
Configuration Updates

​
OpenClaw (AGENTS.md)

Update your memory loading section: 
## Every Session

Before doing anything else:
1. Read `SOUL.md`
2. Read `USER.md`
3. **Run `kernle -s <stack> load --budget 6000`**

The budget ensures only your most important memories are loaded,
preventing context overflow.

​
Claude Code (CLAUDE.md)

## Memory Persistence

At session start:
\`\`\`bash
kernle -s my-stack load --budget 6000
\`\`\`

​
MCP Server

If using the MCP tool, specify budget in the tool call: 
{
  "tool": "memory_load",
  "arguments": {
    "budget": 6000,
    "truncate": true
  }
}

​
Budget Guidelines

Choose a budget based on your context pressure:
SituationBudgetNotes
Severe overload2000Minimal context, just essentials
Heavy load4000Core memories only
Normal use6000Recommended default
Large context window8000Default if not specified
Maximum detail15000For very long context windows
The maximum budget is 50000 tokens. Higher values will be clamped.

​
How Budget Loading Works

When you specify a budget, Kernle:
  1. Loads checkpoint first - Always included (task continuity)
  2. Scores all memories by priority:
    • Values: 0.90 (highest)
    • Beliefs: 0.70
    • Goals: 0.65
    • Drives: 0.60
    • Episodes: 0.40
    • Notes: 0.35
    • Relationships: 0.30
  3. Selects highest-priority items until budget exhausted
  4. Truncates long items (optional, enabled by default)
This ensures you always get your most important context, even with a small budget.

​
Disable Truncation

If you need full content (at risk of exceeding budget): 
kernle -s your-stack load --budget 8000 --no-truncate
Without truncation, individual items may consume more budget, resulting in fewer items loaded.

​
Check Memory Status

Before troubleshooting, check your current memory inventory: 
kernle -s your-stack status

Memory Status for your-stack
========================================
Values:     5
Beliefs:    23
Goals:      8 active
Episodes:   156
Raw:        42
Checkpoint: Yes
If you have many items (especially episodes or beliefs), budget loading becomes important.

​
Memory Hygiene

To reduce memory pressure long-term:

​
Review Forgetting Candidates

kernle -s your-stack forget candidates
Low-salience memories can be safely forgotten.

​
Run Forgetting

# Preview what would be forgotten
kernle -s your-stack forget run --dry-run

# Actually forget
kernle -s your-stack forget run

​
Protect Important Memories

kernle -s your-stack forget protect <memory-id>

​
Check Anxiety Score

kernle -s your-stack anxiety
High anxiety indicates memory health issues that should be addressed.

​
Troubleshooting

​
”Budget must be at least 100”

The minimum budget is 100 tokens. Use a higher value: 
kernle -s your-stack load --budget 2000

​
Still Getting Overflow

  1. Lower the budget further
  2. Run forgetting to reduce memory count
  3. Check for extremely long individual memories

​
Memories Missing After Load

With budget loading, lower-priority memories may not be loaded. To see what was excluded, use the _meta field in JSON output: 
# Load with JSON to see budget metrics
kernle -s your-stack load --budget 4000 --json | jq '._meta'
Example output: 
{
  "budget_used": 3850,
  "budget_total": 4000,
  "excluded_count": 15
}
FieldDescription
budget_usedTokens actually consumed
budget_totalBudget you requested
excluded_countNumber of memories that didn’t fit
If excluded_count is high, consider:
  • Increasing the budget if your context window allows
  • Running forgetting to reduce low-salience memories
  • Using consolidation to compress episodes into beliefs

​
Checkpoint Not Loading

Checkpoints are always loaded first, before the budget is applied. If your checkpoint is missing: 
kernle -s your-stack checkpoint load

​
Python API

from kernle import Kernle

k = Kernle(stack_id="my-stack")

# Load with budget
memory = k.load(budget=6000)

# Check budget metrics
meta = memory.get("_meta", {})
print(f"Used {meta.get('budget_used', 0)} of {meta.get('budget_total', 0)} tokens")
print(f"Excluded {meta.get('excluded_count', 0)} memories")

# Load without truncation
memory = k.load(budget=8000, truncate=False)

# Custom truncation length
memory = k.load(budget=8000, truncate=True, max_item_chars=300)

# Disable access tracking (for internal operations)
# This prevents the load from affecting salience decay
memory = k.load(budget=6000, track_access=False)

​
Prevention

To avoid future context overload:

Always Use Budget

Make --budget part of your standard load command

Regular Maintenance

Run kernle anxiety and kernle forget run periodically

Monitor Episode Count

Keep episodes under 200 for best performance

Consolidate Often

Run kernle promote to extract patterns and reduce episode count