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

# Utility Commands

> 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 theme={null}
kernle -s <stack> 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 theme={null}
{
  "_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 theme={null}
# Standard load
kernle -s my-project load

# Force sync from cloud first
kernle -s my-project load --sync

# Load with token budget (recommended)
kernle -s my-project load --budget 6000

# Get JSON with budget metrics
kernle -s my-project load --json --budget 8000
```

***

## checkpoint

Save and restore session state.

### checkpoint save

```bash theme={null}
kernle -s <stack> 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 SI resume work more effectively.
</Tip>

<Tabs>
  <Tab title="Basic">
    ```bash theme={null}
    kernle -s my-project checkpoint save "Working on user authentication"
    ```
  </Tab>

  <Tab title="With Pending Items">
    ```bash theme={null}
    kernle -s my-project checkpoint save "Refactoring database layer" \
      --pending "finish migration script" \
      --pending "update tests"
    ```
  </Tab>

  <Tab title="With Context">
    ```bash theme={null}
    kernle -s my-project checkpoint save "Debugging API issue" \
      --context "Error occurs when token expires after 1 hour"
    ```
  </Tab>
</Tabs>

### checkpoint load

```bash theme={null}
kernle -s <stack> checkpoint load [--json]
```

### checkpoint clear

```bash theme={null}
kernle -s <stack> checkpoint clear
```

***

## search

Search memory using vector similarity.

```bash theme={null}
kernle -s <stack> search QUERY [--limit LIMIT]
```

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

```bash theme={null}
kernle -s my-project search "authentication"
kernle -s my-project search "database performance" --limit 5
```

***

## status

Show memory status overview.

```bash theme={null}
kernle -s <stack> status
```

**Example output:**

```
Memory Status for my-project
========================================
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 theme={null}
kernle -s <stack> 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 theme={null}
kernle -s my-project when yesterday
kernle -s my-project when "this week"
```

***

## anxiety

Memory anxiety tracking and management.

```bash theme={null}
kernle -s <stack> 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 theme={null}
    kernle -s my-project anxiety
    # Output: Memory Anxiety: 45/100 (Aware)
    ```
  </Tab>

  <Tab title="Detailed">
    ```bash theme={null}
    kernle -s my-project anxiety --detailed --actions
    ```
  </Tab>

  <Tab title="Auto-Fix">
    ```bash theme={null}
    kernle -s my-project anxiety --auto
    ```
  </Tab>

  <Tab title="Emergency">
    ```bash theme={null}
    kernle -s my-project anxiety --emergency --summary "Context compaction triggered"
    ```
  </Tab>
</Tabs>

***

## identity

Identity synthesis operations.

### identity show

Generate a coherent identity narrative.

```bash theme={null}
kernle -s <stack> identity show [--json]
# or just:
kernle -s <stack> identity
```

### identity confidence

Check identity coherence score.

```bash theme={null}
kernle -s <stack> identity confidence [--json]
```

### identity drift

Detect identity drift over time.

```bash theme={null}
kernle -s <stack> identity drift [--days DAYS] [--json]
```

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

***

## emotion

Emotional memory operations.

### emotion summary

```bash theme={null}
kernle -s <stack> emotion summary [--days DAYS] [--json]
```

### emotion search

Search by emotional characteristics.

```bash theme={null}
kernle -s <stack> 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 theme={null}
kernle -s my-project emotion search --positive --limit 5
kernle -s my-project emotion search --negative --intense
```

### emotion tag

Add emotional tags to an episode.

```bash theme={null}
kernle -s <stack> emotion tag EPISODE_ID [--valence V] [--arousal A] [--tag TAG]...
```

### emotion mood

Get mood-relevant memories.

```bash theme={null}
kernle -s <stack> emotion mood --valence V --arousal A [--limit LIMIT]
```

***

## meta

Meta-memory operations.

### meta confidence

Get confidence for a memory.

```bash theme={null}
kernle -s <stack> meta confidence TYPE ID
```

### meta verify

Verify a memory (increases confidence).

```bash theme={null}
kernle -s <stack> meta verify TYPE ID [--evidence EVIDENCE]
```

### meta lineage

Get provenance chain.

```bash theme={null}
kernle -s <stack> meta lineage TYPE ID [--json]
```

### meta uncertain

List low-confidence memories.

```bash theme={null}
kernle -s <stack> meta uncertain [--threshold T] [--limit L]
```

### meta knowledge

Show knowledge map.

```bash theme={null}
kernle -s <stack> meta knowledge [--json]
```

### meta gaps

Detect knowledge gaps.

```bash theme={null}
kernle -s <stack> meta gaps QUERY [--json]
```

### meta boundaries

Show competence boundaries.

```bash theme={null}
kernle -s <stack> meta boundaries [--json]
```

### meta learn

Identify learning opportunities.

```bash theme={null}
kernle -s <stack> 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 theme={null}
kernle -s <stack> 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 theme={null}
kernle -s <stack> 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 theme={null}
# Preview what would be forgotten
kernle -s my-project forget run --dry-run

# Actually forget low-salience memories
kernle -s my-project 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 theme={null}
kernle -s <stack> 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 theme={null}
kernle -s <stack> forget recover TYPE ID
```

### forget list

List all forgotten (tombstoned) memories.

```bash theme={null}
kernle -s <stack> 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 theme={null}
kernle -s <stack> 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 theme={null}
kernle -s my-project forget salience episode abc12345
```

***

## dump

Dump all memory to stdout.

```bash theme={null}
kernle -s <stack> 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 theme={null}
kernle -s my-project dump | less
kernle -s my-project dump --format json
```

***

## export

Export memory to a file.

```bash theme={null}
kernle -s <stack> export PATH [--format {markdown,json}]
```

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

```bash theme={null}
kernle -s my-project export backup.md
kernle -s my-project export memory-snapshot.json --format json
```

***

## export-full

Export complete agent context (all memory layers) to a single file. Unlike `export` (full memory dump), `export-full` assembles all memory layers -- boot config, values, beliefs, goals, episodes, notes, drives, relationships, self-narratives, trust assessments, playbooks, and checkpoint -- into one comprehensive file.

```bash theme={null}
kernle -s <stack> export-full [PATH] [--format {markdown,json}] [--include-raw] [--no-raw]
```

| Option              | Description                                                                      |
| ------------------- | -------------------------------------------------------------------------------- |
| `PATH`              | Output file path (default: stdout)                                               |
| `-f, --format`      | Output format (auto-detected from extension if not specified, default: markdown) |
| `-r, --include-raw` | Include raw entries (default: true)                                              |
| `--no-raw`          | Exclude raw entries                                                              |

```bash theme={null}
# Export to file
kernle -s my-project export-full context.md

# Export as JSON
kernle -s my-project export-full context.json --format json

# Print to stdout
kernle -s my-project export-full
```

***

## process

Run or check automated memory processing (model-driven layer promotion). Processing uses a bound model to automatically promote memories across layers (e.g., raw entries to episodes, episodes to beliefs).

### process run

Run memory processing transitions.

```bash theme={null}
kernle -s <stack> process run [--transition TRANSITION] [--force] [--json]
```

| Option                        | Description                                        |
| ----------------------------- | -------------------------------------------------- |
| `-t, --transition TRANSITION` | Specific transition to process (omit to check all) |
| `-f, --force`                 | Process even if quantity thresholds are not met    |
| `-j, --json`                  | Output as JSON                                     |

Available transitions:

| Transition                | Description                        |
| ------------------------- | ---------------------------------- |
| `raw_to_episode`          | Promote raw entries to episodes    |
| `raw_to_note`             | Promote raw entries to notes       |
| `episode_to_belief`       | Extract beliefs from episodes      |
| `episode_to_goal`         | Derive goals from episodes         |
| `episode_to_relationship` | Detect relationships from episodes |
| `episode_to_drive`        | Identify drives from episodes      |
| `belief_to_value`         | Promote beliefs to values          |

<Tabs>
  <Tab title="Run All">
    ```bash theme={null}
    kernle -s my-project process run
    ```
  </Tab>

  <Tab title="Specific Transition">
    ```bash theme={null}
    kernle -s my-project process run --transition episode_to_belief
    ```
  </Tab>

  <Tab title="Force">
    ```bash theme={null}
    kernle -s my-project process run --force
    ```
  </Tab>
</Tabs>

<Tip>
  `process run` and `process exhaust` auto-bind a model from environment variables (`CLAUDE_API_KEY` / `ANTHROPIC_API_KEY`) if none is already bound. You can also bind one explicitly with `kernle model set claude`.
</Tip>

### process status

Show unprocessed memory counts and whether each transition's quantity threshold has been met.

```bash theme={null}
kernle -s <stack> process status [--json]
```

| Option       | Description    |
| ------------ | -------------- |
| `-j, --json` | Output as JSON |

```bash theme={null}
kernle -s my-project process status
```

**Example output:**

```
Memory Processing Status
========================================
Unprocessed raw entries:  12
Unprocessed episodes:    8
Unprocessed beliefs:     3

Trigger Status:
  raw_to_episode: 12/5 (READY)
  raw_to_note: 12/5 (READY)
  episode_to_belief: 8/3 (READY)
  episode_to_goal: 8/10 (waiting)
  episode_to_relationship: 8/5 (READY)
  episode_to_drive: 8/10 (waiting)
  belief_to_value: 3/5 (waiting)
```

### process exhaust

Run processing cycles repeatedly until convergence (no more promotions possible).

```bash theme={null}
kernle -s <stack> process exhaust [--max-cycles N] [--no-auto-promote] [--dry-run] [--json] [--batch-size N] [--verbose]
```

| Option               | Description                                      |
| -------------------- | ------------------------------------------------ |
| `--max-cycles N`     | Maximum processing cycles (default: 20)          |
| `--no-auto-promote`  | Create suggestions instead of directly promoting |
| `-n, --dry-run`      | Preview what would run without making changes    |
| `-j, --json`         | Output as JSON                                   |
| `-b, --batch-size N` | Override batch size for processing               |
| `-v, --verbose`      | Enable verbose logging                           |

```bash theme={null}
# Run until convergence (auto-binds model from env vars)
kernle -s my-project process exhaust

# Preview only
kernle -s my-project process exhaust --dry-run

# With verbose logging
kernle -s my-project process exhaust --verbose
```

***

## model

Show, bind, or unbind inference models. Model binding is session-only (not persisted to disk). Process commands auto-bind from environment variables, but `model set` lets you bind explicitly.

### model show

Show the currently bound model.

```bash theme={null}
kernle -s <stack> model show [--json]
```

| Option       | Description    |
| ------------ | -------------- |
| `-j, --json` | Output as JSON |

```bash theme={null}
kernle -s my-project model show
# Output: Model: anthropic / claude-haiku-4-5-20251001
```

### model set

Bind a model provider.

```bash theme={null}
kernle -s <stack> model set <provider> [--model-id MODEL_ID]
```

| Argument / Option | Description                                      |
| ----------------- | ------------------------------------------------ |
| `provider`        | Provider to use: `claude`, `openai`, or `ollama` |
| `--model-id`      | Override the default model name                  |

Default models per provider:

| Provider | Default Model               | Env Var                                 |
| -------- | --------------------------- | --------------------------------------- |
| `claude` | `claude-haiku-4-5-20251001` | `CLAUDE_API_KEY` or `ANTHROPIC_API_KEY` |
| `openai` | `gpt-4o-mini`               | `OPENAI_API_KEY`                        |
| `ollama` | `llama3.2:latest`           | *(local server, no key)*                |

<Tabs>
  <Tab title="Claude">
    ```bash theme={null}
    kernle -s my-project model set claude
    # Bound model: anthropic / claude-haiku-4-5-20251001
    ```
  </Tab>

  <Tab title="Claude (Custom)">
    ```bash theme={null}
    kernle -s my-project model set claude --model-id claude-sonnet-4-5-20250929
    # Bound model: anthropic / claude-sonnet-4-5-20250929
    ```
  </Tab>

  <Tab title="Ollama">
    ```bash theme={null}
    kernle -s my-project model set ollama --model-id mistral:7b
    # Bound model: ollama / mistral:7b
    ```
  </Tab>
</Tabs>

### model clear

Unbind the currently bound model.

```bash theme={null}
kernle -s <stack> model clear
```

***

## init

Initialize Kernle by generating a `CLAUDE.md`/`AGENTS.md` health check section.

```bash theme={null}
kernle -s <stack> init [options]
```

| Option                                    | Description                                                  |
| ----------------------------------------- | ------------------------------------------------------------ |
| `-s, --style {standard,minimal,combined}` | Section style (default: standard)                            |
| `-o, --output PATH`                       | Output file path (auto-detects CLAUDE.md/AGENTS.md)          |
| `-p, --print`                             | Print to stdout instead of writing                           |
| `-f, --force`                             | Overwrite/append even if Kernle section already exists       |
| `--no-per-message`                        | Skip per-message health check section                        |
| `-y, --non-interactive`                   | Use defaults (no prompts)                                    |
| `--full-setup`                            | Full setup: instruction file + seed beliefs + platform hooks |

```bash theme={null}
# Interactive
kernle -s my-project init

# Non-interactive
kernle -s my-project init -y --style minimal
```

***

## suggestions

Manage memory suggestions (auto-generated recommendations from the processing pipeline).

### suggestions list

```bash theme={null}
kernle -s <stack> suggestions list [options]
```

| Option               | Description                               |
| -------------------- | ----------------------------------------- |
| `--pending`          | Show only pending suggestions             |
| `--approved`         | Show only approved (promoted) suggestions |
| `--rejected`         | Show only rejected suggestions            |
| `--dismissed`        | Show only dismissed suggestions           |
| `--expired`          | Show only expired suggestions             |
| `--type TYPE`        | Filter by memory type                     |
| `--min-confidence C` | Minimum confidence threshold              |
| `--max-age-hours H`  | Maximum age in hours                      |
| `--source SOURCE`    | Filter by source raw entry ID             |
| `-l, --limit L`      | Maximum results (default: 50)             |
| `-j, --json`         | Output as JSON                            |

### suggestions show

Show details for a specific suggestion. Supports partial ID matching.

```bash theme={null}
kernle -s <stack> suggestions show ID [--json]
```

### suggestions accept

Accept a suggestion and promote it to structured memory. Supports all 7 memory types (episode, belief, note, goal, value, relationship, drive).

```bash theme={null}
kernle -s <stack> suggestions accept ID [--objective O] [--outcome O] [--statement S] [--content C]
```

| Option          | Description                       |
| --------------- | --------------------------------- |
| `--objective O` | Override objective (for episodes) |
| `--outcome O`   | Override outcome (for episodes)   |
| `--statement S` | Override statement (for beliefs)  |
| `--content C`   | Override content (for notes)      |

### suggestions dismiss

Dismiss a suggestion with an optional reason.

```bash theme={null}
kernle -s <stack> suggestions dismiss ID [--reason R]
```

### suggestions expire

Expire stale pending suggestions older than a threshold.

```bash theme={null}
kernle -s <stack> suggestions expire [--max-age-hours H]
```

| Option              | Description                                    |
| ------------------- | ---------------------------------------------- |
| `--max-age-hours H` | Age threshold in hours (default: 168 / 7 days) |

### suggestions extract

Extract new suggestions from unprocessed raw entries.

```bash theme={null}
kernle -s <stack> suggestions extract [--limit L]
```

| Option          | Description                                  |
| --------------- | -------------------------------------------- |
| `-l, --limit L` | Maximum raw entries to process (default: 50) |

***

## stack

Manage local stacks.

### stack list

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

```bash theme={null}
kernle stack list
```

### stack delete

Delete a stack and all its data.

```bash theme={null}
kernle stack delete NAME [--force]
```

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

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

***

## doctor

Validate boot sequence compliance and system health.

```bash theme={null}
kernle -s <stack> 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 theme={null}
kernle -s <stack> stats health-checks [--days DAYS] [--json]
```

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

***

## mcp

Start MCP server (stdio transport).

```bash theme={null}
kernle -s <stack> mcp
```

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