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.

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)

Use --budget to prevent context overflow. A budget of 6000-8000 tokens is recommended for most sessions. See Context Overload Recovery for details.

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:

{
  "_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.

# 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

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

Use --progress, --next, and --blocker for better context recovery. These structured fields help your SI resume work more effectively.

Basic
With Pending Items
With Context

kernle -s my-project checkpoint save "Working on user authentication"

kernle -s my-project checkpoint save "Refactoring database layer" \
  --pending "finish migration script" \
  --pending "update tests"

kernle -s my-project checkpoint save "Debugging API issue" \
  --context "Error occurs when token expires after 1 hour"

checkpoint load

kernle -s <stack> checkpoint load [--json]

checkpoint clear

kernle -s <stack> checkpoint clear

search

Search memory using vector similarity.

kernle -s <stack> search QUERY [--limit LIMIT]

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

kernle -s my-project search "authentication"
kernle -s my-project search "database performance" --limit 5

status

Show memory status overview.

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.

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

kernle -s my-project when yesterday
kernle -s my-project when "this week"

anxiety

Memory anxiety tracking and management.

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

Quick Check
Detailed
Auto-Fix
Emergency

kernle -s my-project anxiety
# Output: Memory Anxiety: 45/100 (Aware)

kernle -s my-project anxiety --detailed --actions

kernle -s my-project anxiety --auto

kernle -s my-project anxiety --emergency --summary "Context compaction triggered"

identity

Identity synthesis operations.

identity show

Generate a coherent identity narrative.

kernle -s <stack> identity show [--json]
# or just:
kernle -s <stack> identity

identity confidence

Check identity coherence score.

kernle -s <stack> identity confidence [--json]

identity drift

Detect identity drift over time.

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

kernle -s <stack> emotion summary [--days DAYS] [--json]

emotion search

Search by emotional characteristics.

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)

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.

kernle -s <stack> emotion tag EPISODE_ID [--valence V] [--arousal A] [--tag TAG]...

emotion mood

Get mood-relevant memories.

kernle -s <stack> emotion mood --valence V --arousal A [--limit LIMIT]

forget

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

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.

forget candidates

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

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.

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)

# 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

Forgetting is reversible via forget recover, but run with --dry-run first to review candidates.

forget protect

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

kernle -s <stack> forget protect TYPE ID [--unprotect]

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

Values and Drives are protected by default and excluded from forgetting candidates.

forget recover

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

kernle -s <stack> forget recover TYPE ID

forget list

List all forgotten (tombstoned) memories.

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.

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)

kernle -s my-project forget salience episode abc12345

dump

Dump all memory to stdout.

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

kernle -s my-project dump | less
kernle -s my-project dump --format json

export

Export memory to a file.

kernle -s <stack> export PATH [--format {markdown,json}]

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

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.

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

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

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

Run All
Specific Transition
Force

kernle -s my-project process run

kernle -s my-project process run --transition episode_to_belief

kernle -s my-project process run --force

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.

process status

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

kernle -s <stack> process status [--json]

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

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

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

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

kernle -s <stack> model show [--json]

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

kernle -s my-project model show
# Output: Model: anthropic / claude-haiku-4-5-20251001

model set

Bind a model provider.

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)

Claude
Claude (Custom)
Ollama

kernle -s my-project model set claude
# Bound model: anthropic / claude-haiku-4-5-20251001

kernle -s my-project model set claude --model-id claude-sonnet-4-5-20250929
# Bound model: anthropic / claude-sonnet-4-5-20250929

kernle -s my-project model set ollama --model-id mistral:7b
# Bound model: ollama / mistral:7b

model clear

Unbind the currently bound model.

kernle -s <stack> model clear

init

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

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

# 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

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.

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

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.

kernle -s <stack> suggestions dismiss ID [--reason R]

suggestions expire

Expire stale pending suggestions older than a threshold.

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.

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

kernle stack list

stack delete

Delete a stack and all its data.

kernle stack delete NAME [--force]

Option	Description
`--force`	Skip confirmation prompt

This permanently deletes the stack’s database records and directory. Cannot be undone.

doctor

Validate boot sequence compliance and system health.

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.

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

kernle -s <stack> mcp

Used for integration with MCP-compatible tools. See MCP Integration.

Getting Started

Core Concepts

Protocol System

Advanced Features

Developer Tools

CLI Reference

Integration

Design

Troubleshooting

​Utility Commands

​load

​Priority Ordering

​Budget Metadata (_meta)

​Token Estimation

​Access Tracking

​checkpoint

​checkpoint save

​checkpoint load

​checkpoint clear

​search

​status

​when

​anxiety

​identity

​identity show

​identity confidence

​identity drift

​emotion

​emotion summary

​emotion search

​emotion tag

​emotion mood

​meta

​meta confidence

​meta verify

​meta lineage

​meta uncertain

​meta knowledge

​meta gaps

​meta boundaries

​meta learn

​forget

​forget candidates

​forget run

​forget protect

​forget recover

​forget list

​forget salience

​dump

​export

​export-full

​process

​process run

​process status

​process exhaust

​model

​model show

​model set

​model clear

​init

​suggestions

​suggestions list

​suggestions show

​suggestions accept

​suggestions dismiss

​suggestions expire

​suggestions extract

​stack

​stack list

​stack delete

​doctor

​stats

​stats health-checks

​mcp

Utility Commands

load

Priority Ordering

Budget Metadata (`_meta`)

Token Estimation

Access Tracking

checkpoint

checkpoint save

checkpoint load

checkpoint clear

search

status

when

anxiety

identity

identity show

identity confidence

identity drift

emotion

emotion summary

emotion search

emotion tag

emotion mood

meta

meta confidence

meta verify

meta lineage

meta uncertain

meta knowledge

meta gaps

meta boundaries

meta learn

forget

forget candidates

forget run

forget protect

forget recover

forget list

forget salience

dump

export

export-full

process

process run

process status

process exhaust

model

model show

model set

model clear

init

suggestions

suggestions list

suggestions show

suggestions accept

suggestions dismiss

suggestions expire

suggestions extract

stack

stack list

stack delete

doctor

stats

stats health-checks

mcp