---
title: Utility Commands
description: "Commands for loading, searching, exporting, and maintaining memory"
---

# Utility Commands

Commands for managing memory state, searching, analysis, and maintenance.

## load

Load and display working memory at session start. Uses priority-based budget allocation to fit the most important memories within token limits.

```bash
kernle -a <agent> load [--json] [--sync] [--no-sync] [--budget TOKENS] [--no-truncate]
```

| Option | Description |
|--------|-------------|
| `-j, --json` | Output as JSON (includes `_meta` with budget metrics) |
| `-s, --sync` | Force sync (pull) before loading |
| `--no-sync` | Skip sync even if auto-sync enabled |
| `-b, --budget TOKENS` | Token budget for memory loading (100-50000, default: 8000) |
| `--no-truncate` | Disable content truncation (may exceed budget) |

<Tip>
Use `--budget` to prevent context overflow. A budget of 6000-8000 tokens is recommended for most sessions. See [Context Overload Recovery](/troubleshooting/context-overload) for details.
</Tip>

### Priority Ordering

Memories are loaded by priority until the budget is exhausted:

| Priority | Memory Type | Sorting |
|----------|-------------|---------|
| 1.00 | Checkpoint | Always loaded first |
| 0.90 | Values | By priority (descending) |
| 0.70 | Beliefs | By confidence (descending) |
| 0.65 | Goals | By recency |
| 0.60 | Drives | By intensity (descending) |
| 0.40 | Episodes | By recency |
| 0.35 | Notes | By recency |
| 0.30 | Relationships | By last interaction |

### Budget Metadata (`_meta`)

When using `--json`, the response includes a `_meta` object with budget metrics:

```json
{
  "_meta": {
    "budget_used": 5200,
    "budget_total": 8000,
    "excluded_count": 12
  }
}
```

| Field | Description |
|-------|-------------|
| `budget_used` | Tokens consumed by loaded memories |
| `budget_total` | Original budget requested |
| `excluded_count` | Number of memories that could not fit |

### Token Estimation

Tokens are estimated at approximately 4 characters per token, with a 1.3x safety margin for JSON serialization overhead.

### Access Tracking

Loading memories automatically records access for salience-based forgetting. Frequently accessed memories maintain higher salience and are less likely to be forgotten.

```bash
# Standard load
kernle -a claire load

# Force sync from cloud first
kernle -a claire load --sync

# Load with token budget (recommended)
kernle -a claire load --budget 6000

# Get JSON with budget metrics
kernle -a claire load --json --budget 8000
```

---

## checkpoint

Save and restore session state.

### checkpoint save

```bash
kernle -a <agent> checkpoint save TASK [options]
```

| Option | Description |
|--------|-------------|
| `-p, --pending PENDING` | Pending item (repeatable) |
| `-c, --context CONTEXT` | Additional context |
| `--progress PROGRESS` | Current progress on the task |
| `-n, --next NEXT` | Immediate next step |
| `-b, --blocker BLOCKER` | Current blocker if any |
| `-s, --sync` | Force sync after saving |
| `--no-sync` | Skip sync |

<Tip>
Use `--progress`, `--next`, and `--blocker` for better context recovery. These structured fields help your agent resume work more effectively.
</Tip>

<Tabs>
  <Tab title="Basic">
    ```bash
    kernle -a claire checkpoint save "Working on user authentication"
    ```
  </Tab>
  <Tab title="With Pending Items">
    ```bash
    kernle -a claire checkpoint save "Refactoring database layer" \
      --pending "finish migration script" \
      --pending "update tests"
    ```
  </Tab>
  <Tab title="With Context">
    ```bash
    kernle -a claire checkpoint save "Debugging API issue" \
      --context "Error occurs when token expires after 1 hour"
    ```
  </Tab>
</Tabs>

### checkpoint load

```bash
kernle -a <agent> checkpoint load [--json]
```

### checkpoint clear

```bash
kernle -a <agent> checkpoint clear
```

---

## search

Search memory using vector similarity.

```bash
kernle -a <agent> search QUERY [--limit LIMIT]
```

| Option | Description |
|--------|-------------|
| `-l, --limit LIMIT` | Maximum results (default: 10) |

```bash
kernle -a claire search "authentication"
kernle -a claire search "database performance" --limit 5
```

---

## status

Show memory status overview.

```bash
kernle -a <agent> status
```

**Example output:**
```
Memory Status for claire
========================================
Values:     3
Beliefs:    12
Goals:      2 active
Episodes:   45
Raw:        8 (5 unprocessed)
Notes:      23
Checkpoint: Yes (2 hours ago)
```

---

## when

Query memories by time period.

```bash
kernle -a <agent> when [PERIOD]
```

| Period | Description |
|--------|-------------|
| `today` | Today's memories (default) |
| `yesterday` | Yesterday's memories |
| `this week` | This week's memories |
| `last hour` | Last hour's memories |

```bash
kernle -a claire when yesterday
kernle -a claire when "this week"
```

---

## anxiety

Memory anxiety tracking and management.

```bash
kernle -a <agent> anxiety [options]
```

| Option | Description |
|--------|-------------|
| `-d, --detailed` | Show detailed breakdown |
| `-a, --actions` | Show recommended actions |
| `--auto` | Execute recommended actions |
| `-c, --context TOKENS` | Current context token usage |
| `-l, --limit LIMIT` | Context window limit (default: 200000) |
| `-e, --emergency` | Run emergency save immediately |
| `-s, --summary` | Summary for emergency save |
| `-j, --json` | Output as JSON |

<Tabs>
  <Tab title="Quick Check">
    ```bash
    kernle -a claire anxiety
    # Output: Memory Anxiety: 45/100 (Aware)
    ```
  </Tab>
  <Tab title="Detailed">
    ```bash
    kernle -a claire anxiety --detailed --actions
    ```
  </Tab>
  <Tab title="Auto-Fix">
    ```bash
    kernle -a claire anxiety --auto
    ```
  </Tab>
  <Tab title="Emergency">
    ```bash
    kernle -a claire anxiety --emergency --summary "Context compaction triggered"
    ```
  </Tab>
</Tabs>

---

## consolidate

Run memory consolidation (episodes → beliefs).

```bash
kernle -a <agent> consolidate [--min-episodes MIN]
```

| Option | Description |
|--------|-------------|
| `-m, --min-episodes MIN` | Minimum episodes to consolidate (default: 3) |

```bash
kernle -a claire consolidate
kernle -a claire consolidate --min-episodes 5
```

---

## identity

Identity synthesis operations.

### identity show

Generate a coherent identity narrative.

```bash
kernle -a <agent> identity show [--json]
# or just:
kernle -a <agent> identity
```

### identity confidence

Check identity coherence score.

```bash
kernle -a <agent> identity confidence [--json]
```

### identity drift

Detect identity drift over time.

```bash
kernle -a <agent> identity drift [--days DAYS] [--json]
```

| Option | Description |
|--------|-------------|
| `-d, --days DAYS` | Days to look back (default: 30) |

---

## emotion

Emotional memory operations.

### emotion summary

```bash
kernle -a <agent> emotion summary [--days DAYS] [--json]
```

### emotion search

Search by emotional characteristics.

```bash
kernle -a <agent> emotion search [options]
```

| Option | Description |
|--------|-------------|
| `--positive` | Find positive episodes |
| `--negative` | Find negative episodes |
| `--calm` | Find low-arousal episodes |
| `--intense` | Find high-arousal episodes |
| `-t, --tag TAG` | Emotion tag to match |
| `-l, --limit LIMIT` | Maximum results (default: 10) |

```bash
kernle -a claire emotion search --positive --limit 5
kernle -a claire emotion search --negative --intense
```

### emotion tag

Add emotional tags to an episode.

```bash
kernle -a <agent> emotion tag EPISODE_ID [--valence V] [--arousal A] [--tag TAG]...
```

### emotion mood

Get mood-relevant memories.

```bash
kernle -a <agent> emotion mood --valence V --arousal A [--limit LIMIT]
```

---

## meta

Meta-memory operations.

### meta confidence

Get confidence for a memory.

```bash
kernle -a <agent> meta confidence TYPE ID
```

### meta verify

Verify a memory (increases confidence).

```bash
kernle -a <agent> meta verify TYPE ID [--evidence EVIDENCE]
```

### meta lineage

Get provenance chain.

```bash
kernle -a <agent> meta lineage TYPE ID [--json]
```

### meta uncertain

List low-confidence memories.

```bash
kernle -a <agent> meta uncertain [--threshold T] [--limit L]
```

### meta knowledge

Show knowledge map.

```bash
kernle -a <agent> meta knowledge [--json]
```

### meta gaps

Detect knowledge gaps.

```bash
kernle -a <agent> meta gaps QUERY [--json]
```

### meta boundaries

Show competence boundaries.

```bash
kernle -a <agent> meta boundaries [--json]
```

### meta learn

Identify learning opportunities.

```bash
kernle -a <agent> meta learn [--limit LIMIT]
```

---

## forget

Controlled forgetting operations for memory maintenance. Kernle uses salience-based forgetting to help memories gracefully fade while preserving core identity.

<Info>
**Salience Formula**: Kernle calculates memory salience as:
```
salience = (confidence × reinforcement_weight) / (age_factor + 1)
```
where:
- `reinforcement_weight = log(times_accessed + 1)`
- `age_factor = days_since_last_access / half_life` (half_life = 30 days)

Lower salience = more likely to be forgotten. Protected memories and memories above the threshold are never forgotten.
</Info>

### forget candidates

Show forgetting candidates (low-salience memories eligible for forgetting).

```bash
kernle -a <agent> forget candidates [--threshold T] [--limit L]
```

| Option | Description |
|--------|-------------|
| `-t, --threshold T` | Salience threshold (default: 0.3) |
| `-l, --limit L` | Maximum candidates (default: 20) |

### forget run

Run forgetting cycle.

```bash
kernle -a <agent> forget run [--dry-run] [--threshold T] [--limit L]
```

| Option | Description |
|--------|-------------|
| `--dry-run` | Preview what would be forgotten without actually forgetting |
| `-t, --threshold T` | Salience threshold (default: 0.3) |
| `-l, --limit L` | Maximum memories to forget (default: 10) |

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

# Actually forget low-salience memories
kernle -a claire forget run --threshold 0.2 --limit 5
```

<Warning>
Forgetting is reversible via `forget recover`, but run with `--dry-run` first to review candidates.
</Warning>

### forget protect

Protect a memory from forgetting. Protected memories never decay and cannot be forgotten.

```bash
kernle -a <agent> forget protect TYPE ID [--unprotect]
```

| Option | Description |
|--------|-------------|
| `--unprotect` | Remove protection from the memory |

<Note>
Values and Drives are protected by default and excluded from forgetting candidates.
</Note>

### forget recover

Recover a forgotten (tombstoned) memory. Forgotten memories are not deleted - they can always be recovered.

```bash
kernle -a <agent> forget recover TYPE ID
```

### forget list

List all forgotten (tombstoned) memories.

```bash
kernle -a <agent> forget list [--limit L]
```

| Option | Description |
|--------|-------------|
| `-l, --limit L` | Maximum results (default: 50) |

### forget salience

Check the salience score of a specific memory. Useful for understanding why a memory is or isn't a forgetting candidate.

```bash
kernle -a <agent> forget salience TYPE ID
```

Shows:
- Current salience score with visual bar
- Component breakdown (confidence, access count, protection status)
- Status interpretation (critical/low/moderate/high salience)

```bash
kernle -a claire forget salience episode abc12345
```

---

## dump

Dump all memory to stdout.

```bash
kernle -a <agent> dump [--format {markdown,json}] [--include-raw] [--no-raw]
```

| Option | Description |
|--------|-------------|
| `-f, --format` | Output format (default: markdown) |
| `-r, --include-raw` | Include raw entries (default: true) |
| `--no-raw` | Exclude raw entries |

```bash
kernle -a claire dump | less
kernle -a claire dump --format json
```

---

## export

Export memory to a file.

```bash
kernle -a <agent> export PATH [--format {markdown,json}]
```

Format is auto-detected from file extension if not specified.

```bash
kernle -a claire export backup.md
kernle -a claire export memory-snapshot.json --format json
```

---

## init

Initialize Kernle with interactive setup.

```bash
kernle -a <agent> init [options]
```

| Option | Description |
|--------|-------------|
| `-y, --non-interactive` | Use defaults |
| `--env {claude-code,clawdbot,cline,cursor,desktop}` | Target environment |
| `--seed-values` | Seed initial values (default: true) |
| `--no-seed-values` | Skip seeding values |

```bash
# Interactive
kernle -a my-project init

# Non-interactive for Claude Code
kernle -a my-project init -y --env claude-code
```

---

## suggestions

Manage memory suggestions (auto-generated recommendations).

### suggestions list

```bash
kernle -a <agent> suggestions list [--pending] [--approved] [--rejected] [--type TYPE] [--limit L]
```

| Option | Description |
|--------|-------------|
| `--pending` | Show only pending suggestions |
| `--approved` | Show only approved suggestions |
| `--rejected` | Show only rejected suggestions |
| `--type TYPE` | Filter by memory type |
| `-l, --limit L` | Maximum results (default: 20) |

### suggestions approve

```bash
kernle -a <agent> suggestions approve SUGGESTION_ID
```

### suggestions reject

```bash
kernle -a <agent> suggestions reject SUGGESTION_ID
```

---

## agent

Manage local agents.

### agent list

List all agents in `~/.kernle/`.

```bash
kernle agent list
```

### agent delete

Delete an agent and all its data.

```bash
kernle agent delete NAME [--force]
```

| Option | Description |
|--------|-------------|
| `--force` | Skip confirmation prompt |

<Warning>
This permanently deletes the agent's database records and directory. Cannot be undone.
</Warning>

---

## doctor

Validate boot sequence compliance and system health.

```bash
kernle -a <agent> doctor [--json]
```

Checks:
- Memory system initialization
- Storage accessibility
- Required tables exist
- Embedding provider availability
- Sync credentials (if configured)

---

## stats

Usage statistics and health check tracking.

### stats health-checks

Show health check compliance over time.

```bash
kernle -a <agent> stats health-checks [--days DAYS] [--json]
```

| Option | Description |
|--------|-------------|
| `-d, --days DAYS` | Days to look back (default: 30) |

---

## mcp

Start MCP server (stdio transport).

```bash
kernle -a <agent> mcp
```

Used for integration with MCP-compatible tools. See [MCP Integration](/integration/mcp).
