> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kernle.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Overload Recovery

> How to fix context overflow issues with budget-aware memory loading

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

```bash theme={null}
# 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

<Steps>
  <Step title="Update Kernle">
    Ensure you have the latest version with budget-aware loading:

    ```bash theme={null}
    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 theme={null}
    kernle load --help
    # Should show: --budget, -b
    ```
  </Step>

  <Step title="Test with Small Budget">
    Start with a small budget to verify it works:

    ```bash theme={null}
    kernle -s your-stack load --budget 2000 --json | wc -c
    # Should output ~8000 chars (2000 tokens × 4 chars/token)
    ```
  </Step>

  <Step title="Update Your Configuration">
    Modify your stack configuration to use budget loading. See examples below.
  </Step>
</Steps>

***

## Configuration Updates

### OpenClaw (AGENTS.md)

Update your memory loading section:

```markdown theme={null}
## 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)

```markdown theme={null}
## 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:

```json theme={null}
{
  "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 theme={null}
kernle -s your-stack 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 theme={null}
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

```bash theme={null}
kernle -s your-stack forget candidates
```

Low-salience memories can be safely forgotten.

### Run Forgetting

```bash theme={null}
# Preview what would be forgotten
kernle -s your-stack forget run --dry-run

# Actually forget
kernle -s your-stack forget run
```

### Protect Important Memories

```bash theme={null}
kernle -s your-stack forget protect <memory-id>
```

### Check Anxiety Score

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# Load with JSON to see budget metrics
kernle -s your-stack load --budget 4000 --json | jq '._meta'
```

**Example output:**

```json theme={null}
{
  "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 theme={null}
kernle -s your-stack checkpoint load
```

***

## Python API

```python theme={null}
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:

<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 promote` to extract patterns and reduce episode count
  </Card>
</CardGroup>