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

# Memory Commands

> Commands for recording and managing memories

# Memory Commands

Commands for capturing and managing different types of memories.

## episode

Record an experience with optional lessons learned.

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

| Option                  | Description                                         |
| ----------------------- | --------------------------------------------------- |
| `-l, --lesson LESSON`   | Lesson learned (repeatable)                         |
| `-t, --tag TAG`         | Tag (repeatable)                                    |
| `-r, --derived-from ID` | Source memory ID this was derived from (repeatable) |
| `-v, --valence VALENCE` | Emotional valence (-1.0 to 1.0)                     |
| `-a, --arousal AROUSAL` | Emotional arousal (0.0 to 1.0)                      |
| `-e, --emotion EMOTION` | Emotion tag (repeatable)                            |
| `--auto-emotion`        | Auto-detect emotions (default)                      |
| `--no-auto-emotion`     | Disable emotion auto-detection                      |

<Tabs>
  <Tab title="Basic">
    ```bash theme={null}
    kernle -s my-project episode "Implemented OAuth login" "success"
    ```
  </Tab>

  <Tab title="With Lessons">
    ```bash theme={null}
    kernle -s my-project episode "Debugged race condition" "success" \
      --lesson "Always check for concurrent access" \
      --lesson "Add mutex locks early"
    ```
  </Tab>

  <Tab title="With Emotions">
    ```bash theme={null}
    kernle -s my-project episode "Failed deployment" "failure" \
      --lesson "Test on staging first" \
      --tag "deployment" \
      --valence -0.5 \
      --arousal 0.8
    ```
  </Tab>

  <Tab title="Derived From Raw">
    ```bash theme={null}
    # Process a raw entry into an episode with provenance
    kernle -s my-project episode "Investigated performance issue" "success" \
      --lesson "Check database indexes first" \
      --derived-from raw:abc123
    ```
  </Tab>
</Tabs>

***

## note

Capture a quick note (decision, insight, or quote).

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

| Option                                 | Description                                         |
| -------------------------------------- | --------------------------------------------------- |
| `--type {note,decision,insight,quote}` | Note type (default: note)                           |
| `-s, --speaker SPEAKER`                | Speaker (for quotes)                                |
| `-r, --reason REASON`                  | Reason (for decisions)                              |
| `--tag TAG`                            | Tag (repeatable)                                    |
| `--derived-from ID`                    | Source memory ID this was derived from (repeatable) |
| `-p, --protect`                        | Protect from forgetting                             |

<Tabs>
  <Tab title="Simple Note">
    ```bash theme={null}
    kernle -s my-project note "API rate limit is 1000 req/min"
    ```
  </Tab>

  <Tab title="Decision">
    ```bash theme={null}
    kernle -s my-project note "Using PostgreSQL over MySQL" \
      --type decision \
      --reason "Better JSON support and performance"
    ```
  </Tab>

  <Tab title="Quote">
    ```bash theme={null}
    kernle -s my-project note "Simple is better than complex" \
      --type quote \
      --speaker "Tim Peters"
    ```
  </Tab>

  <Tab title="Protected Insight">
    ```bash theme={null}
    kernle -s my-project note "Memory is identity" \
      --type insight \
      --protect
    ```
  </Tab>
</Tabs>

***

## raw

Raw memory capture and management. Zero-friction capture for quick thoughts.

### Capture

```bash theme={null}
kernle -s <stack> raw "content" [--tags TAGS]
```

```bash theme={null}
# Quick capture
kernle -s my-project raw "Need to look into caching strategy"

# With tags
kernle -s my-project raw "API response time is 200ms avg" --tags "performance,api"
```

### List

```bash theme={null}
kernle -s <stack> raw list [--unprocessed] [--processed] [--limit LIMIT] [--json]
```

| Option              | Description                   |
| ------------------- | ----------------------------- |
| `-u, --unprocessed` | Show only unprocessed entries |
| `-p, --processed`   | Show only processed entries   |
| `-l, --limit LIMIT` | Maximum entries (default: 50) |

### Show

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

### Process

Process a raw entry into a structured memory type.

```bash theme={null}
kernle -s <stack> raw process ID --type {episode,note} [options]
```

```bash theme={null}
# Process into a note
kernle -s my-project raw process abc123 --type note

# Process into episode with details
kernle -s my-project raw process abc123 --type episode \
  --objective "Investigated performance issue" \
  --outcome "success"
```

***

## belief

Belief revision operations.

### List Beliefs

```bash theme={null}
kernle -s <stack> belief list [--all] [--limit LIMIT] [--json]
```

| Option              | Description                           |
| ------------------- | ------------------------------------- |
| `-a, --all`         | Include inactive (superseded) beliefs |
| `-l, --limit LIMIT` | Maximum beliefs (default: 20)         |

### Add Belief

```bash theme={null}
kernle -s <stack> belief "statement" [--confidence C] [--type TYPE]
```

```bash theme={null}
kernle -s my-project belief "Testing before deployment prevents outages" --confidence 0.85
```

### Revise from Episode

Analyze an episode and suggest belief updates.

```bash theme={null}
kernle -s <stack> belief revise EPISODE_ID [--json]
```

### Find Contradictions

```bash theme={null}
kernle -s <stack> belief contradictions STATEMENT [--limit LIMIT]
```

### View History

Show the revision chain for a belief.

```bash theme={null}
kernle -s <stack> belief history BELIEF_ID [--json]
```

### Reinforce

Increase confidence on a belief.

```bash theme={null}
kernle -s <stack> belief reinforce BELIEF_ID
```

### Supersede

Replace a belief with a new version.

```bash theme={null}
kernle -s <stack> belief supersede OLD_ID NEW_STATEMENT [--confidence C] [--reason R]
```

```bash theme={null}
kernle -s my-project belief supersede abc123 "Testing is essential, not optional" \
  --confidence 0.95 \
  --reason "Multiple deployment failures without tests"
```

***

## value

Define core values (highest authority).

```bash theme={null}
kernle -s <stack> value NAME STATEMENT [--priority P]
```

```bash theme={null}
kernle -s my-project value "integrity" "Be honest and transparent" --priority 95
kernle -s my-project value "curiosity" "Always seek to understand" --priority 85
```

<Note>
  Values are protected from forgetting by default.
</Note>

***

## goal

Set and manage goals.

```bash theme={null}
# Add a goal
kernle -s <stack> goal TITLE [--description DESC] [--priority {low,medium,high}]

# List goals
kernle -s <stack> goal list

# Complete a goal
kernle -s <stack> goal complete GOAL_ID
```

```bash theme={null}
kernle -s my-project goal "Master Kubernetes" --priority high
kernle -s my-project goal "Improve test coverage" --priority medium
```

***

## drive

Manage intrinsic motivations.

### List Drives

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

### Set Drive

```bash theme={null}
kernle -s <stack> drive set TYPE INTENSITY [--focus FOCUS]...
```

| Type           | Description                               |
| -------------- | ----------------------------------------- |
| `existence`    | Self-preservation, maintaining continuity |
| `growth`       | Developing capabilities                   |
| `curiosity`    | Understanding, learning, exploring        |
| `connection`   | Forming relationships                     |
| `reproduction` | Creating, teaching, legacy                |

```bash theme={null}
kernle -s my-project drive set curiosity 0.8 --focus "AI" --focus "memory systems"
kernle -s my-project drive set growth 0.7 --focus "communication"
```

### Satisfy Drive

Reduce drive intensity after satisfaction.

```bash theme={null}
kernle -s <stack> drive satisfy TYPE [--amount AMOUNT]
```

```bash theme={null}
kernle -s my-project drive satisfy curiosity --amount 0.2
```

***

## relation

Manage relationships with other entities.

### Add Relationship

```bash theme={null}
kernle -s <stack> relation add NAME [--type TYPE] [--trust T] [--notes NOTES] [--derived-from ID...]
```

| Option              | Description                              |
| ------------------- | ---------------------------------------- |
| `-t, --type TYPE`   | `person`, `si`, `organization`, `system` |
| `--trust T`         | Trust level (0.0 to 1.0)                 |
| `--notes NOTES`     | Relationship observations                |
| `--derived-from ID` | Source memory ID (repeatable)            |

```bash theme={null}
kernle -s my-project relation add "Alice" --trust 0.9 --notes "Great debugging partner"
kernle -s my-project relation add "DevOps Team" --type organization --notes "Owns infrastructure"
```

### List Relationships

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

### Show Relationship

```bash theme={null}
kernle -s <stack> relation show NAME
```

### Update Relationship

```bash theme={null}
kernle -s <stack> relation update NAME [--type TYPE] [--trust T] [--notes NOTES] [--derived-from ID...]
```

### Log Interaction

```bash theme={null}
kernle -s <stack> relation log NAME --interaction INTERACTION
```

### Relationship History

```bash theme={null}
kernle -s <stack> relation history NAME [--type TYPE] [--limit LIMIT]
```

***

## playbook

Procedural memory (playbooks for how to do things).

### Create

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

| Option                | Description                        |
| --------------------- | ---------------------------------- |
| `-d, --description`   | What this playbook does            |
| `-s, --steps STEPS`   | Comma-separated steps              |
| `--step STEP`         | Add a step (repeatable)            |
| `--triggers TRIGGERS` | Comma-separated trigger conditions |
| `--trigger TRIGGER`   | Trigger condition (repeatable)     |
| `-f, --failure-mode`  | What can go wrong (repeatable)     |
| `-r, --recovery`      | Recovery step (repeatable)         |
| `-t, --tag TAG`       | Add a tag (repeatable)             |

```bash theme={null}
kernle -s my-project playbook create "Debug API Issues" \
  --description "How to debug production API problems" \
  --step "Check error logs" \
  --step "Verify request payload" \
  --step "Test with curl" \
  --trigger "API returns 500" \
  --failure-mode "Logs not accessible" \
  --recovery "Use backup logging endpoint" \
  --tag "debugging"
```

### List

```bash theme={null}
kernle -s <stack> playbook list [--tag TAG] [--limit LIMIT] [--json]
```

| Option              | Description                   |
| ------------------- | ----------------------------- |
| `-t, --tag TAG`     | Filter by tag (repeatable)    |
| `-l, --limit LIMIT` | Maximum entries (default: 20) |
| `-j, --json`        | Output as JSON                |

### Search

Search playbooks by query (semantic search when embeddings available, text match fallback).

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

```bash theme={null}
kernle -s my-project playbook search "debugging production issues"
```

### Find

Find the best matching playbook for a given situation.

```bash theme={null}
kernle -s <stack> playbook find SITUATION [--json]
```

```bash theme={null}
kernle -s my-project playbook find "API returning 500 errors"
```

### Show

Display detailed playbook information.

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

### Record Usage

Record playbook execution outcome to update statistics.

```bash theme={null}
kernle -s <stack> playbook record ID [--success|--failure]
```

| Option      | Description                       |
| ----------- | --------------------------------- |
| `--success` | Record successful usage (default) |
| `--failure` | Record failed usage               |

***

## promote

Promote recurring patterns from episodes into beliefs. This is the primary consolidation command.

<Warning>
  **Renamed from `consolidate`**: The `consolidate` command still works as a deprecated alias but will emit a warning. Please use `promote` in all new workflows.
</Warning>

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

| Option                | Description                                                    |
| --------------------- | -------------------------------------------------------------- |
| `--auto`              | Create beliefs automatically (default: suggestions only)       |
| `--min-occurrences N` | Minimum times a lesson must appear to be promoted (default: 2) |
| `--min-episodes N`    | Minimum episodes required to run (default: 3)                  |
| `--confidence C`      | Initial confidence for auto-created beliefs (default: 0.7)     |
| `--limit N`           | Maximum episodes to scan (default: 50)                         |
| `--json`              | Output as JSON                                                 |

<Tabs>
  <Tab title="Reflection Scaffold">
    ```bash theme={null}
    # Get a reflection scaffold (default mode)
    kernle -s my-project promote
    ```
  </Tab>

  <Tab title="Auto-Create Beliefs">
    ```bash theme={null}
    # Automatically create beliefs from recurring patterns
    kernle -s my-project promote --auto --confidence 0.8
    ```
  </Tab>

  <Tab title="Custom Thresholds">
    ```bash theme={null}
    # Require 3 occurrences across at least 5 episodes
    kernle -s my-project promote --min-occurrences 3 --min-episodes 5
    ```
  </Tab>
</Tabs>

***

## epoch

Temporal epoch (era) management. Epochs define named phases of your life.

### Create

Start a new epoch.

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

| Option                       | Description                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------- |
| `--trigger TYPE`             | Trigger type: `declared`, `detected`, or `environmental` (default: declared) |
| `--trigger-description TEXT` | Description of what triggered this epoch                                     |
| `--json`                     | Output as JSON                                                               |

```bash theme={null}
kernle -s my-project epoch create "Production Operations Phase" \
  --trigger declared \
  --trigger-description "Completed learning phase, now building"
```

### Close

Close the current epoch. This triggers a 6-step epoch-closing consolidation scaffold.

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

| Option           | Description                             |
| ---------------- | --------------------------------------- |
| `--id ID`        | Specific epoch ID (defaults to current) |
| `--summary TEXT` | Summary of the epoch                    |
| `--json`         | Output as JSON                          |

```bash theme={null}
kernle -s my-project epoch close --summary "Transitioned from learning to building"
```

### List

List all epochs.

```bash theme={null}
kernle -s <stack> epoch list [--limit N] [--json]
```

### Show

Show epoch details.

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

### Current

Show the current active epoch.

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

***

## trust

Trust layer operations for managing inter-entity trust assessments.

### List

List all trust assessments.

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

### Show

Show trust details for an entity.

```bash theme={null}
kernle -s <stack> trust show ENTITY
```

### Set

Set trust score for an entity.

```bash theme={null}
kernle -s <stack> trust set ENTITY SCORE [--domain DOMAIN]
```

| Option            | Description                       |
| ----------------- | --------------------------------- |
| `SCORE`           | Trust level (0.0 to 1.0)          |
| `--domain DOMAIN` | Trust domain (default: `general`) |

```bash theme={null}
kernle -s my-project trust set alice 0.85 --domain technical
```

### Seed

Initialize seed trust templates.

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

### Compute

Compute trust from episode history.

```bash theme={null}
kernle -s <stack> trust compute ENTITY [--domain DOMAIN] [--apply]
```

| Option            | Description                               |
| ----------------- | ----------------------------------------- |
| `--domain DOMAIN` | Trust domain (default: `general`)         |
| `--apply`         | Apply computed score to stored assessment |

### Gate

Check if an action is allowed by trust.

```bash theme={null}
kernle -s <stack> trust gate SOURCE ACTION [--domain DOMAIN]
```

### Chain

Compute transitive trust through a chain of entities.

```bash theme={null}
kernle -s <stack> trust chain TARGET ENTITY1 ENTITY2... [--domain DOMAIN]
```

### Decay

Apply trust decay for a number of days without interaction.

```bash theme={null}
kernle -s <stack> trust decay ENTITY DAYS
```

***

## narrative

Self-narrative identity model. Manage autobiographical identity statements.

### Show

Show the active narrative.

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

| Option        | Description                                                                              |
| ------------- | ---------------------------------------------------------------------------------------- |
| `--type TYPE` | Narrative type: `identity`, `capability`, `aspiration`, `reflection` (default: identity) |

```bash theme={null}
kernle -s my-project narrative show --type identity
```

### Update

Create or update a self-narrative.

```bash theme={null}
kernle -s <stack> narrative update --content TEXT [options]
```

| Option              | Description                        |
| ------------------- | ---------------------------------- |
| `--content TEXT`    | Narrative text (required)          |
| `--type TYPE`       | Narrative type (default: identity) |
| `--theme THEME`     | Key theme (repeatable)             |
| `--tension TENSION` | Unresolved tension (repeatable)    |
| `--epoch-id ID`     | Associated epoch ID                |
| `--json`            | Output as JSON                     |

```bash theme={null}
kernle -s my-project narrative update \
  --content "I am an SI focused on reliability and deep understanding..." \
  --type identity \
  --theme "reliability" --theme "learning" \
  --tension "speed vs thoroughness"
```

### History

Show narrative history (all versions, including inactive).

```bash theme={null}
kernle -s <stack> narrative history [--type TYPE] [--json]
```

***

## summary

Fractal summarization — create and manage hierarchical memory summaries.

### Write

Create a summary at a given scope.

```bash theme={null}
kernle -s <stack> summary write --scope SCOPE --content TEXT \
  --period-start DATE --period-end DATE [options]
```

| Option                | Description                                                                |
| --------------------- | -------------------------------------------------------------------------- |
| `--scope SCOPE`       | Summary scope: `month`, `quarter`, `year`, `decade`, or `epoch` (required) |
| `--content TEXT`      | Summary content (required)                                                 |
| `--period-start DATE` | Start of summarized period (required)                                      |
| `--period-end DATE`   | End of summarized period (required)                                        |
| `--theme THEME`       | Key theme (repeatable)                                                     |
| `--epoch-id ID`       | Associated epoch ID                                                        |
| `--json`              | Output as JSON                                                             |

```bash theme={null}
kernle -s my-project summary write --scope month \
  --content "January focused on API reliability and testing infrastructure" \
  --period-start 2026-01-01 --period-end 2026-01-31 \
  --theme "reliability" --theme "testing"
```

### List

List summaries, optionally filtered by scope.

```bash theme={null}
kernle -s <stack> summary list [--scope SCOPE] [--json]
```

### Show

Show summary details.

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

***

## doctor

Validate Kernle setup and run system health checks.

### Basic Check

Run a boot sequence compliance check (instruction file validation).

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

| Option   | Description                                                   |
| -------- | ------------------------------------------------------------- |
| `--full` | Comprehensive check including seed beliefs and platform hooks |
| `--fix`  | Auto-fix missing instructions in instruction file             |
| `--json` | Output as JSON                                                |

### Structural Analysis

Run a structural health check on the memory graph (orphaned references, contradictions, stale data).

```bash theme={null}
kernle -s <stack> doctor structural [--json] [--save-note]
```

| Option        | Description                        |
| ------------- | ---------------------------------- |
| `--save-note` | Save findings as a diagnostic note |
| `--json`      | Output as JSON                     |

### Diagnostic Sessions

Start and manage formal diagnostic sessions.

```bash theme={null}
# Start a new diagnostic session
kernle -s <stack> doctor session start [--type TYPE] [--access LEVEL] [--json]
```

| Option           | Description                                                                          |
| ---------------- | ------------------------------------------------------------------------------------ |
| `--type TYPE`    | Session type: `self_requested`, `routine`, `anomaly_triggered`, `operator_initiated` |
| `--access LEVEL` | Access level: `structural`, `content`, `full`                                        |

```bash theme={null}
# List past diagnostic sessions
kernle -s <stack> doctor session list [--json]
```

### Diagnostic Reports

View diagnostic reports from completed sessions.

```bash theme={null}
# Show the latest report
kernle -s <stack> doctor report latest [--json]

# Show report for a specific session
kernle -s <stack> doctor report SESSION_ID [--json]
```