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

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 .

Verify Budget Support

Check that the budget flag is available:

kernle load --help
# Should show: --budget, -b

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)

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:

Situation	Budget	Notes
Severe overload	`2000`	Minimal context, just essentials
Heavy load	`4000`	Core memories only
Normal use	`6000`	Recommended default
Large context window	`8000`	Default if not specified
Maximum detail	`15000`	For 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:

Loads checkpoint first - Always included (task continuity)
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
Selects highest-priority items until budget exhausted
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

Lower the budget further
Run forgetting to reduce memory count
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
}

Field	Description
`budget_used`	Tokens actually consumed
`budget_total`	Budget you requested
`excluded_count`	Number 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

Getting Started

Core Concepts

Protocol System

Advanced Features

Developer Tools

CLI Reference

Integration

Design

Troubleshooting

Context Overload Recovery

Context Overload Recovery

Symptoms

Quick Fix

Recovery Steps

Configuration Updates

OpenClaw (AGENTS.md)

Claude Code (CLAUDE.md)

MCP Server

Budget Guidelines

How Budget Loading Works

Disable Truncation

Check Memory Status

Memory Hygiene

Review Forgetting Candidates

Run Forgetting

Protect Important Memories

Check Anxiety Score

Troubleshooting

”Budget must be at least 100”

Still Getting Overflow

Memories Missing After Load

Checkpoint Not Loading

Python API

Prevention

Always Use Budget

Regular Maintenance

Monitor Episode Count

Consolidate Often

​Context Overload Recovery

​Symptoms

​Quick Fix

​Recovery Steps

​Configuration Updates

​OpenClaw (AGENTS.md)

​Claude Code (CLAUDE.md)

​MCP Server

​Budget Guidelines

​How Budget Loading Works

​Disable Truncation

​Check Memory Status

​Memory Hygiene

​Review Forgetting Candidates

​Run Forgetting

​Protect Important Memories

​Check Anxiety Score

​Troubleshooting

​”Budget must be at least 100”

​Still Getting Overflow

​Memories Missing After Load

​Checkpoint Not Loading

​Python API

​Prevention

Always Use Budget

Regular Maintenance

Monitor Episode Count

Consolidate Often

Context Overload Recovery

Symptoms

Quick Fix

Recovery Steps

Configuration Updates

OpenClaw (AGENTS.md)

Claude Code (CLAUDE.md)

MCP Server

Budget Guidelines

How Budget Loading Works

Disable Truncation

Check Memory Status

Memory Hygiene

Review Forgetting Candidates

Run Forgetting

Protect Important Memories

Check Anxiety Score

Troubleshooting

”Budget must be at least 100”

Still Getting Overflow

Memories Missing After Load

Checkpoint Not Loading

Python API

Prevention