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.0Emotional 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-lifeAccess reinforcement : record_access() boosts strength (diminishing returns)Verification : verify_memory() boosts strength toward 1.0Emotional weight : High-arousal episodes decay slowerExplicit weakening : weaken_memory() reduces strength by a specified amountForgetting : 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.
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 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 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"
