---
title: "Context Overload Recovery"
description: "How to fix context overflow issues with budget-aware memory loading"
---

# Context Overload Recovery

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

## Symptoms

- Agent crashes or errors when loading memory
- "Context too long" or similar errors
- Slow performance during memory load
- Agent unable to complete tasks after loading memory

## Quick Fix

Update your memory load command to use budget-aware loading:

```bash
# Instead of:
kernle -a your-agent load

# Use:
kernle -a your-agent load --budget 6000
```

This limits memory loading to approximately 6000 tokens, preventing overflow.

---

## Recovery Steps

<Steps>
  <Step title="Update Kernle">
    Ensure you have the latest version with budget-aware loading:
    ```bash
    pip install --upgrade kernle
    # Or from source:
    cd ~/kernle && git pull && pip install -e .
    ```
  </Step>
  <Step title="Verify Budget Support">
    Check that the budget flag is available:
    ```bash
    kernle load --help
    # Should show: --budget, -b
    ```
  </Step>
  <Step title="Test with Small Budget">
    Start with a small budget to verify it works:
    ```bash
    kernle -a your-agent load --budget 2000 --json | wc -c
    # Should output ~8000 chars (2000 tokens × 4 chars/token)
    ```
  </Step>
  <Step title="Update Your Configuration">
    Modify your agent configuration to use budget loading. See examples below.
  </Step>
</Steps>

---

## Configuration Updates

### Clawdbot (AGENTS.md)

Update your memory loading section:

```markdown
## Every Session

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

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

### Claude Code (CLAUDE.md)

```markdown
## Memory Persistence

At session start:
\`\`\`bash
kernle -a my-agent load --budget 6000
\`\`\`
```

### MCP Server

If using the MCP tool, specify budget in the tool call:

```json
{
  "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 |

<Warning>
The maximum budget is 50000 tokens. Higher values will be clamped.
</Warning>

---

## 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):

```bash
kernle -a your-agent load --budget 8000 --no-truncate
```

<Note>
Without truncation, individual items may consume more budget, resulting in fewer items loaded.
</Note>

---

## Check Memory Status

Before troubleshooting, check your current memory inventory:

```bash
kernle -a your-agent status
```

```
Memory Status for your-agent
========================================
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

```bash
kernle -a your-agent forget candidates
```

Low-salience memories can be safely forgotten.

### Run Forgetting

```bash
# Preview what would be forgotten
kernle -a your-agent forget run --dry-run

# Actually forget
kernle -a your-agent forget run
```

### Protect Important Memories

```bash
kernle -a your-agent forget protect <memory-id>
```

### Check Anxiety Score

```bash
kernle -a your-agent 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:

```bash
kernle -a your-agent 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:

```bash
# Load with JSON to see budget metrics
kernle -a your-agent load --budget 4000 --json | jq '._meta'
```

**Example output:**

```json
{
  "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:

```bash
kernle -a your-agent checkpoint load
```

---

## Python API

```python
from kernle import Kernle

k = Kernle(agent_id="my-agent")

# 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:

<CardGroup cols={2}>
  <Card title="Always Use Budget" icon="gauge">
    Make `--budget` part of your standard load command
  </Card>
  <Card title="Regular Maintenance" icon="broom">
    Run `kernle anxiety` and `kernle forget run` periodically
  </Card>
  <Card title="Monitor Episode Count" icon="chart-line">
    Keep episodes under 200 for best performance
  </Card>
  <Card title="Consolidate Often" icon="layer-group">
    Run `kernle consolidate` to extract patterns and reduce episode count
  </Card>
</CardGroup>
