Memory Management

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

Overview

Forgetting

Graceful decay with protection and recovery

Promotion

Extract patterns from episodes into beliefs

Import

Migrate from flat files to structured memory

Intentional Forgetting

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

View Candidates

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

kernle -s my-project forget strength abc123

Protect Important Memories

kernle -s my-project forget protect abc123

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

Run Forgetting

# 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):

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

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

Renamed Command: The consolidate command has been removed. Use kernle promote instead.

Run Promotion

kernle -s my-project promote --limit 20

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

Identify patterns across episodes
Find repeated lessons
Detect contradictions with existing beliefs
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

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

kernle -s my-project belief revise abc123

Check for Contradictions

kernle -s my-project belief contradictions

Reinforce Belief

kernle -s my-project belief reinforce abc123

Supersede Belief

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.

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

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

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

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

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

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

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

# With confirmation
kernle stack delete test-stack

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

Deletion is permanent. The SI cannot be recovered.

Python API

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:

Check anxiety

Run kernle anxiety to assess memory health

Review raw entries

Process unprocessed raw entries with kernle raw list --unprocessed

Promote

Run kernle promote to extract patterns from episodes

Review forgetting candidates

Check kernle forget candidates and protect important memories

Checkpoint

Save state with kernle checkpoint save "description"

​Overview

Forgetting

Promotion

Import

​Intentional Forgetting

​View Candidates

​Strength Scores

​Check Specific Memory

​Protect Important Memories

​Run Forgetting

​Recover Forgotten Memories

​Continuous Strength (v0.10.0)

​Strength Tiers

​What Changes Strength

​Recovery

​Consolidation

​Run Promotion

​Sample Output

​Belief Management

​List Beliefs

​Revise from Episode

​Check for Contradictions

​Reinforce Belief

​Supersede Belief

​Import from Flat Files

​Format Behavior

​Preview Import

​Actually Import

​JSON Import with Provenance

​Interactive Mode

​Stack Management

​List Stacks

​Delete Stack

​Python API

​Maintenance Workflow

Overview

Intentional Forgetting

View Candidates

Strength Scores

Check Specific Memory

Protect Important Memories

Run Forgetting

Recover Forgotten Memories

Continuous Strength (v0.10.0)

Strength Tiers

What Changes Strength

Recovery

Consolidation

Run Promotion

Sample Output

Belief Management

List Beliefs

Revise from Episode

Check for Contradictions

Reinforce Belief

Supersede Belief

Import from Flat Files

Format Behavior

Preview Import

Actually Import

JSON Import with Provenance

Interactive Mode

Stack Management

List Stacks

Delete Stack

Python API

Maintenance Workflow