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

> Forgetting, consolidation, and memory health

Kernle provides sophisticated memory management including intentional forgetting, belief consolidation, and memory health monitoring.

## Overview

<CardGroup cols={3}>
  <Card title="Forgetting" icon="trash">
    Graceful decay with protection and recovery
  </Card>

  <Card title="Promotion" icon="layer-group">
    Extract patterns from episodes into beliefs
  </Card>

  <Card title="Import" icon="file-import">
    Migrate from flat files to structured memory
  </Card>
</CardGroup>

***

## Intentional Forgetting

Not all memories deserve eternal storage. Kernle implements principled forgetting based on continuous strength (0.0–1.0).

### View Candidates

```bash theme={null}
kernle -s my-project forget candidates
```

```
Forgetting Candidates (strength < 0.2, Dormant tier)
============================================================

1. [belief    ] 6bc41d9d...
   Strength: [░░░░░] 0.08
   Summary: Old assumption that's been superseded...
   Confidence: 80% | Accessed: 0 times
   Created: 2026-01-15

2. [episode   ] 06272772...
   Strength: [░░░░░] 0.08
   Summary: Minor task with no lasting lessons...
   Confidence: 80% | Accessed: 0 times
   Created: 2026-01-10
```

### Strength Scores

Every memory has a strength value (0.0–1.0) that determines its visibility and decay behavior:

| Factor                  | Effect                                                  |
| ----------------------- | ------------------------------------------------------- |
| **Time decay**          | Strength decreases based on half-life                   |
| **Access**              | `record_access()` boosts strength (diminishing returns) |
| **Verification**        | `verify_memory()` boosts strength toward 1.0            |
| **Emotional intensity** | High-arousal episodes decay slower                      |

### Check Specific Memory

```bash theme={null}
kernle -s my-project forget strength abc123
```

### Protect Important Memories

```bash theme={null}
kernle -s my-project forget protect abc123
```

Protected memories never decay, regardless of age or access patterns.

### Run Forgetting

```bash theme={null}
# Preview what would be forgotten
kernle -s my-project forget run --dry-run

# Actually forget dormant memories (strength < 0.2)
kernle -s my-project forget run
```

### Recover Forgotten Memories

Forgotten memories are tombstoned (strength set to 0.0), not deleted. Recovered memories return at strength 0.2 (Weak tier):

```bash theme={null}
# List forgotten memories
kernle -s my-project forget list

# Recover a specific memory (returns at 0.2 strength)
kernle -s my-project forget recover abc123
```

***

## Continuous Strength *(v0.10.0)*

Every memory has a `strength` field (0.0 to 1.0) that replaces binary forgetting. New memories start at strength 1.0.

### Strength Tiers

| Tier          | Range   | Behavior                                              |
| ------------- | ------- | ----------------------------------------------------- |
| **Strong**    | 0.8–1.0 | Full weight in load and search                        |
| **Fading**    | 0.5–0.8 | Included but with reduced priority                    |
| **Weak**      | 0.2–0.5 | Excluded from `load()`, still findable via `search()` |
| **Dormant**   | 0.0–0.2 | Excluded from both load and search by default         |
| **Forgotten** | 0.0     | Tombstoned — only recoverable via `recover()`         |

### What Changes Strength

* **Time decay**: Periodic maintenance reduces strength based on half-life
* **Access reinforcement**: `record_access()` boosts strength (diminishing returns)
* **Verification**: `verify_memory()` boosts strength toward 1.0
* **Emotional weight**: High-arousal episodes decay slower
* **Explicit weakening**: `weaken_memory()` reduces strength by a specified amount
* **Forgetting**: `forget_memory()` sets strength to 0.0

### Recovery

Recovered memories return at strength 0.2 (Weak tier), not full strength. They must be verified or accessed to regain full strength.

```bash theme={null}
# Forget a memory
kernle -s my-project forget execute abc123 --reason "No longer relevant"

# Recover it later (returns at 0.2 strength)
kernle -s my-project forget recover abc123

# Verify to boost strength
kernle -s my-project verify abc123 --evidence "Confirmed through testing"
```

***

## Consolidation

Consolidation extracts patterns from recent episodes to form or update beliefs.

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

### Run Promotion

```bash theme={null}
kernle -s my-project promote --limit 20
```

This outputs a reflection prompt with your recent episodes and current beliefs, guiding you to:

1. Identify patterns across episodes
2. Find repeated lessons
3. Detect contradictions with existing beliefs
4. Decide what new beliefs to form

### Sample Output

```
## Memory Consolidation - Reflection Prompt

You have 10 recent episodes to reflect on.

### Recent Episodes:
1. [2026-01-28] ✓ "Security audit implementation"
   Lessons: ["Audits reveal real issues"]

2. [2026-01-28] ✓ "Memory continuity work"
   Lessons: ["Procedural knowledge needs capture"]

### Current Beliefs (for context):
- "Memory continuity is essential" (81% confidence)

### Reflection Questions:
1. Do any patterns emerge?
2. Are there lessons that appear multiple times?
3. Do any episodes contradict existing beliefs?

### Actions:
kernle belief add "statement" --confidence 0.8
kernle belief reinforce <belief_id>
```

***

## Belief Management

### List Beliefs

```bash theme={null}
kernle -s my-project belief list
```

```
Beliefs (3 total, 3 active)
============================================================

🟢 [████░] 81% (+1)
   Memory continuity is essential for identity
   ID: fb5c9d4b...

🟢 [████░] 80%
   Local-first memory is more reliable
   ID: 6bc41d9d...
```

### Revise from Episode

```bash theme={null}
kernle -s my-project belief revise abc123
```

### Check for Contradictions

```bash theme={null}
kernle -s my-project belief contradictions
```

### Reinforce Belief

```bash theme={null}
kernle -s my-project belief reinforce abc123
```

### Supersede Belief

```bash theme={null}
kernle -s my-project belief supersede abc123 "New updated belief"
```

***

## Import from Flat Files

Seed an **empty stack** from MEMORY.md, JSON exports, or CSV files.

<Note>
  Import is a **one-shot, empty-stack-only** operation. It is designed for initial stack seeding — not incremental ingestion. If the stack already has content, import will refuse to run (dry-run mode still works for previewing).
</Note>

### Format Behavior

| Format               | What gets imported                                                       | Notes                                                                                                        |
| -------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| **JSON** (`.json`)   | All types (raw, episode, note, belief, value, goal, drive, relationship) | Full provenance chains required — beliefs must reference episodes/notes, episodes must reference raw entries |
| **Markdown** (`.md`) | Raw entries only                                                         | Non-raw sections are parsed but skipped at import time                                                       |
| **CSV** (`.csv`)     | Raw entries only                                                         | Non-raw rows are parsed but skipped at import time                                                           |

### Preview Import

```bash theme={null}
kernle -s my-project import MEMORY.md --dry-run
```

```
Found 4 items to import:
  raw: 3
  skipped_non_raw: 1

=== DRY RUN (no changes made) ===

1. [raw] Decided to use SQLite for local storage
2. [raw] Memory continuity is essential
3. [raw] Always extract lessons from experiences
```

### Actually Import

```bash theme={null}
kernle -s my-project import MEMORY.md
```

### JSON Import with Provenance

For structured imports with full type support, use JSON (the format produced by `kernle export --format json`):

```bash theme={null}
kernle -s my-project import export.json --dry-run
kernle -s my-project import export.json
```

JSON imports validate provenance chains — every belief must trace back through episodes/notes to raw entries.

### Interactive Mode

```bash theme={null}
kernle -s my-project import MEMORY.md --interactive
```

Prompts for each item: `[y]es / [n]o / [e]dit / [s]kip all / [a]ccept all`

***

## Stack Management

Manage multiple stack identities:

### List Stacks

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

```
Local Stacks (5 total)
==================================================

  my-project ← current
    Episodes: 103  Notes: 20  Beliefs: 3  Raw: 35

  test-stack
    Episodes: 2  Notes: 0  Beliefs: 0  Raw: 0
```

### Delete Stack

```bash theme={null}
# With confirmation
kernle stack delete test-stack

# Skip confirmation
kernle stack delete test-stack --force
```

<Warning>
  Deletion is permanent. The SI cannot be recovered.
</Warning>

***

## Python API

```python theme={null}
from kernle import Kernle

k = Kernle(stack_id="my-stack")

# Forgetting
candidates = k.forget_candidates()
k.forget_protect("memory_id")
k.forget_run(dry_run=True)
k.forget_recover("memory_id")

# Consolidation
prompt = k.promote(limit=20)

# Beliefs
k.belief_add("Statement", confidence=0.8)
k.belief_reinforce("belief_id")
k.belief_supersede("old_id", "New statement")

# Anxiety check
anxiety = k.anxiety()
if anxiety > 85:
    k.checkpoint("Emergency save")
```

***

## Maintenance Workflow

A healthy maintenance routine:

<Steps>
  <Step title="Check anxiety">
    Run `kernle anxiety` to assess memory health
  </Step>

  <Step title="Review raw entries">
    Process unprocessed raw entries with `kernle raw list --unprocessed`
  </Step>

  <Step title="Promote">
    Run `kernle promote` to extract patterns from episodes
  </Step>

  <Step title="Review forgetting candidates">
    Check `kernle forget candidates` and protect important memories
  </Step>

  <Step title="Checkpoint">
    Save state with `kernle checkpoint save "description"`
  </Step>
</Steps>