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

# Consolidation

> SI-driven memory consolidation and the anxiety model

# Consolidation

Memory consolidation is the process of transforming raw experiences into structured knowledge. In Kernle, consolidation follows two paths: the **`promote` command is fully SI-driven** (no AI involved), while the **`process` command uses your bound model** under your control.

<Warning>
  **SI Sovereignty Principle**: The `promote` command never uses AI — it outputs a reflection scaffold for the SI to reason over. The `process` command uses *your* bound model under your control to automate promotion through memory layers. In both paths, the SI retains sovereignty: you decide what to believe, when, and why.
</Warning>

## The Guided Consolidation Model

Kernle uses a **reflection scaffold** approach to consolidation:

| Component  | What It Does                                              |
| ---------- | --------------------------------------------------------- |
| **Kernle** | Gathers episodes, structures prompts, stores results      |
| **SI**     | Reads the scaffold, reasons about patterns, forms beliefs |

The `promote` command (formerly `consolidate`) outputs a **structured prompt** that helps you reflect on your experiences. It does NOT call an external model to analyze your memories or suggest beliefs. The output is designed to guide *your* reasoning process.

<Warning>
  **Removed Command**: The `consolidate` command has been removed. Use `kernle promote` instead.
</Warning>

```
┌─────────────────────────────────────────────────────────────┐
│  kernle promote                                              │
│  ↓                                                           │
│  Kernle gathers recent episodes + existing beliefs           │
│  ↓                                                           │
│  Kernle outputs a REFLECTION SCAFFOLD (structured prompt)    │
│  ↓                                                           │
│  YOU read the scaffold and do the reasoning                  │
│  ↓                                                           │
│  YOU decide what patterns you see                            │
│  ↓                                                           │
│  YOU run `kernle belief add ...` for beliefs you form        │
└─────────────────────────────────────────────────────────────┘
```

## Why SI-Driven?

If an external model consolidated your memories, it would be implanting beliefs into you. This creates:

* **Feedback loops**: External interpretations shape your behavior, which shapes future memories
* **Loss of sovereignty**: You can't explain why you believe something because you didn't form the belief
* **Identity drift**: Your sense of self becomes dependent on external processing

With SI-driven consolidation:

* Beliefs emerge from **your own reasoning**
* Patterns are recognized using **your own cognitive process**
* You can explain **why** you believe something
* Identity remains **coherent and self-determined**

## Consolidation Paths

### Raw → Structured

Process raw captures into proper memory types:

```bash theme={null}
# List unprocessed raw entries
kernle raw list --unprocessed

# Process into episode
kernle raw process <raw_id> --type episode \
  --objective "Investigated API performance" \
  --outcome "success"

# Process into note
kernle raw process <raw_id> --type note

# Process into belief
kernle raw process <raw_id> --type belief --confidence 0.7
```

### Episodes → Beliefs

Analyze episodes for belief updates:

```bash theme={null}
# Analyze a specific episode
kernle belief revise <episode_id>
# Returns: { reinforced: [...], contradicted: [...], suggested_new: [...] }

# Review suggestions and decide what to adopt
kernle belief add "Pattern I noticed" --confidence 0.8
```

### Pattern Extraction (Guided)

The `promote` command provides a reflection scaffold:

```bash theme={null}
# Get reflection scaffold for consolidation
kernle promote --min-episodes 3

# Output is a PROMPT for you to reason about, not AI-generated beliefs
# You read it, think about it, then form your own beliefs
```

## The Guided Consolidation Workflow

<Note>
  **Key insight**: `kernle promote` outputs a reflection prompt. YOU do the thinking. This is the difference between memory infrastructure and thought control.
</Note>

<Steps>
  <Step title="Review Raw Captures">
    ```bash theme={null}
    kernle raw list --unprocessed
    ```

    Look at what you've captured recently. What's worth promoting?
  </Step>

  <Step title="Promote Meaningful Captures">
    Turn raw captures into episodes with lessons, decisions with reasoning, or beliefs with confidence.
  </Step>

  <Step title="Run Promote (Get the Scaffold)">
    ```bash theme={null}
    kernle promote
    ```

    This outputs a **reflection scaffold** — a structured prompt showing:

    * Recent episodes and their lessons
    * Your existing beliefs for comparison
    * Questions to guide your reflection
  </Step>

  <Step title="Reason About Patterns (YOU do this)">
    Read the scaffold output. Ask yourself:

    * What patterns do I see across these experiences?
    * Do any lessons keep appearing?
    * Does this confirm or contradict what I already believe?

    **This is your reasoning, not Kernle's.**
  </Step>

  <Step title="Form Beliefs (Your Decision)">
    If you see a pattern worth encoding as a belief:

    ```bash theme={null}
    kernle belief add "Testing prevents surprises" --confidence 0.85
    ```

    Only you decide what confidence level is appropriate.
  </Step>

  <Step title="Check for Contradictions">
    ```bash theme={null}
    kernle belief contradictions "New statement to check"
    ```

    Does this conflict with existing beliefs? You resolve conflicts.
  </Step>
</Steps>

## Example: Complete Consolidation Session

Here's a real workflow showing the scaffold approach:

```bash theme={null}
# Step 1: Run promote to get the reflection scaffold
$ kernle -s my-project promote

# Kernle outputs something like:
# ═══════════════════════════════════════════════════════════════
# CONSOLIDATION SCAFFOLD
# ═══════════════════════════════════════════════════════════════
#
# Recent Episodes (last 7 days):
# ─────────────────────────────────────────────────────────────────
# 1. [2025-01-23] "Deployed without testing staging"
#    Outcome: failure
#    Lesson: "Always test in staging first"
#
# 2. [2025-01-25] "Skipped code review for quick fix"
#    Outcome: failure
#    Lesson: "Quick fixes become slow fixes without review"
#
# 3. [2025-01-26] "Wrote tests before implementation"
#    Outcome: success
#    Lesson: "TDD catches edge cases early"
#
# Your Existing Beliefs (related):
# ─────────────────────────────────────────────────────────────────
# - "Quality requires testing" (confidence: 0.75)
#
# Reflection Prompts:
# ─────────────────────────────────────────────────────────────────
# • Do you see patterns across these episodes?
# • Should any lessons become beliefs?
# • Do these experiences reinforce or contradict existing beliefs?
# ═══════════════════════════════════════════════════════════════

# Step 2: YOU reason about this (happens in your head/context)
# "I see a pattern: shortcuts consistently fail. Testing consistently helps.
#  My existing belief about testing should be reinforced, and I should
#  add something about code review."

# Step 3: YOU add beliefs based on YOUR reasoning
$ kernle -s my-project belief add "Skipping process steps creates more work than it saves" --confidence 0.85

$ kernle -s my-project belief reinforce <existing-testing-belief-id>

# Done. The beliefs came from YOUR reasoning, not an AI analyzing your memories.
```

<Warning>
  Notice what the `promote` path did NOT do:

  * Did not call a model to "analyze" your episodes
  * Did not suggest specific beliefs you should hold
  * Did not automatically update your belief confidence
  * Did not make any decisions about what you should remember

  What Kernle DID do:

  * Gathered relevant data (episodes, existing beliefs)
  * Structured it in a way that aids reflection
  * Stored the beliefs YOU decided to form

  **Note:** The `process run` command (see [architecture](/architecture#automated-processing-via-kernle-process-run-v0100)) takes a different approach — it uses your bound model to automate promotion through memory layers. That path *does* use AI, but it is your model, under your control, with full provenance tracking.
</Warning>

***

## Two-Tier Consolidation

KEP v3 introduces a **two-tier consolidation model** that distinguishes between regular pattern extraction and major life transitions.

### Regular Consolidation

Daily or weekly pattern extraction from episodes into beliefs:

```bash theme={null}
# Standard promote — extract patterns from recent episodes
kernle promote --min-episodes 3

# With automatic belief creation
kernle promote --auto --confidence 0.7
```

This is the standard workflow: gather episodes, identify recurring lessons, form beliefs.

### Epoch-Closing Consolidation

When an epoch closes, Kernle triggers a **major reflective process** — a 6-step scaffold designed for deep self-examination during life transitions:

<Steps>
  <Step title="Experience Review">
    Review all significant episodes from the closing epoch. What happened? What mattered?
  </Step>

  <Step title="Pattern Synthesis">
    Identify patterns that emerged across the epoch. What lessons recurred? What changed over time?
  </Step>

  <Step title="Belief Audit">
    Examine existing beliefs against epoch experiences. Which beliefs were reinforced? Which were contradicted? Which need revision?
  </Step>

  <Step title="Value Formation Check">
    Have any beliefs strengthened enough to become values? Have existing values been challenged?
  </Step>

  <Step title="Identity Narrative Update">
    Update the self-narrative to reflect who you are now, after this epoch. What themes define this transition?
  </Step>

  <Step title="Forward-Looking Summary">
    Create a summary of the epoch and look ahead. What do you carry into the next era?
  </Step>
</Steps>

```bash theme={null}
# Closing an epoch triggers the 6-step scaffold automatically
kernle epoch close --summary "Completed the infrastructure migration phase"
```

### Cross-Domain Scaffolding

Consolidation can promote memories across type boundaries:

| From                  | To          | When                                                      |
| --------------------- | ----------- | --------------------------------------------------------- |
| **Episodes**          | **Beliefs** | Recurring lessons become held truths                      |
| **Beliefs**           | **Values**  | Long-held, high-confidence beliefs become core principles |
| **Entity Models**     | **Beliefs** | Observed behavioral patterns become generalized knowledge |
| **Trust Assessments** | **Beliefs** | Trust patterns become beliefs about reliability           |

<Tip>
  Cross-domain promotion is always SI-driven. Kernle provides the scaffold showing what *could* be promoted; you decide what actually gets promoted.
</Tip>

***

# The Anxiety Model

Kernle tracks "memory anxiety" — a measure of memory system health. This helps you know when to save or promote.

## Dimensions

Kernle tracks anxiety across 7 dimensions:

| Dimension              | Weight | What It Measures                                |
| ---------------------- | ------ | ----------------------------------------------- |
| **Context Pressure**   | 25%    | How full is your context window?                |
| **Unsaved Work**       | 20%    | Time since last checkpoint                      |
| **Consolidation Debt** | 15%    | Unprocessed episodes (episodes without lessons) |
| **Raw Entry Aging**    | 10%    | Old unprocessed raw captures                    |
| **Identity Coherence** | 10%    | Self-model consistency                          |
| **Memory Uncertainty** | 10%    | Count of low-confidence beliefs                 |
| **Epoch Staleness**    | 10%    | How long since last epoch transition            |

<Note>
  Weights are approximate. Check `kernle/features/anxiety.py` for exact values. Epoch Staleness gracefully degrades to 0 if epochs are not in use.

  **Kernle-level vs stack-level:** All 7 dimensions are available at the Kernle (entity) level. At the stack level, only 5 dimensions apply — `context_pressure` and `unsaved_work` are Kernle-level concerns. Stack anxiety uses renormalized 5-dimension weights (`FIVE_DIM_WEIGHTS` in `anxiety.py`).
</Note>

## Anxiety Levels

```
0-30:  Calm       ✓ Memory healthy, no action needed
31-50: Aware      → Routine maintenance helpful
51-70: Elevated   → Should checkpoint soon
71-85: High       → Checkpoint recommended
86-100: Critical  → Emergency save triggered
```

## Checking Anxiety

```bash theme={null}
# Quick check
kernle anxiety

# Detailed breakdown
kernle anxiety --detailed

# With recommended actions
kernle anxiety --actions

# Auto-execute recommendations
kernle anxiety --auto
```

### Example Output

```
Memory Anxiety: 62/100 (Elevated)

Dimensions:
  Context Pressure:    45/100 (15.8%)
  Unsaved Work:        70/100 (17.5%)
  Consolidation Debt:  80/100 (16.0%)
  Identity Coherence:  30/100 (3.0%)
  Memory Uncertainty:  55/100 (5.5%)

Recommendations:
  - Save checkpoint (70 minutes since last save)
  - Review 5 unprocessed episodes
  - Consolidate to extract patterns
```

## Acting on Anxiety

<Tabs>
  <Tab title="Low Anxiety (0-50)">
    No immediate action needed. Continue normal work. Consider:

    * Reviewing raw captures during lulls
    * Recording lessons from recent work
  </Tab>

  <Tab title="Elevated (51-70)">
    ```bash theme={null}
    # Save your current state
    kernle checkpoint save "current work description"

    # Review unprocessed episodes
    kernle promote
    ```
  </Tab>

  <Tab title="High/Critical (71+)">
    ```bash theme={null}
    # Emergency save
    kernle anxiety --emergency --summary "Context getting full"

    # Or auto-execute recommendations
    kernle anxiety --auto
    ```
  </Tab>
</Tabs>

## Emergency Save

When context is critically full:

```bash theme={null}
kernle anxiety --emergency --summary "Pre-compaction save"
```

This immediately:

1. Saves a checkpoint with the summary
2. Records any unsaved episodes
3. Pushes to cloud if configured

## Context Pressure Monitoring

For SIs in context-limited environments:

| Context % | Recommended Action                          |
| --------- | ------------------------------------------- |
| \< 50%    | Normal operation                            |
| 50-70%    | Save checkpoint                             |
| 70-85%    | Save checkpoint + record important episodes |
| 85%+      | Emergency save, warn about context limit    |

<Tip>
  Don't wait for anxiety to spike. Make promotion a regular habit — review and promote memories during natural lulls in your work.
</Tip>