Upgrading Kernle

Upgrade Process

Kernle handles database migrations automatically when you upgrade. However, there are a few things to be aware of.

Basic Upgrade

pip install --upgrade kernle

pyenv Users

If you use pyenv to manage Python versions, you must rehash after upgrading:

pip install --upgrade kernle
pyenv rehash

Without pyenv rehash, your shell will continue using stale console script shims that point to the old version. You’ll see symptoms like:

New CLI flags not being recognized (e.g., --budget)
kernle --version showing the old version even after upgrade
python -c "import kernle; print(kernle.__version__)" showing the correct version

Verifying the Upgrade

After upgrading, verify both the module and CLI are updated:

# Check module version
python -c "import kernle; print(kernle.__version__)"

# Check CLI version
kernle --version

# Both should show the same version

CLI Breaking Changes

0.10.0: `-a/--agent` renamed to `-s/--stack`

In v0.10.0, the global -a/--agent flag was renamed to -s/--stack to better reflect the architecture. The old flag is no longer recognized. What changed:

Old syntax (pre-0.10)	New syntax (0.10+)
`kernle -a my-project load`	`kernle -s my-project load`
`kernle -a ash episode ...`	`kernle -s ash episode ...`
`kernle --agent my-project status`	`kernle --stack my-project status`

What to update:

Shell scripts and aliases — find-and-replace -a with -s and --agent with --stack :

# Before
alias kl="kernle -a my-project load"
# After
alias kl="kernle -s my-project load"

CLAUDE.md / AGENTS.md — update any CLI examples:

# Search project docs for old syntax
grep -rn "kernle -a\|kernle --agent" .

OpenClaw plugin config — if you have custom hook commands referencing -a, update them. The bundled plugin was updated automatically.

Claude Code hooks — re-run setup to regenerate hooks with the new flag:

kernle setup claude-code
# or
kernle setup claude-code --global

Environment variable — KERNLE_STACK_ID is unchanged and still works as before.

The environment variable KERNLE_STACK_ID was not renamed. Only the CLI flag changed. If you rely on the env var for stack resolution, no changes are needed.

Database Migrations

Kernle automatically migrates your local SQLite database when you run any command after upgrading. Migrations are non-destructive and preserve all existing data.

0.2.x → 0.9.0 Migration

The 0.9.0 release introduces continuous strength and removes binary forgetting fields:

Change	Details
`strength` column added	All memory tables gain a `strength REAL DEFAULT 1.0` column. Existing memories are backfilled to 1.0.
`is_forgotten` removed	Replaced by `strength = 0.0`.
`forgotten_at` removed	Forgetting timestamp is now tracked in `memory_audit`.
`forgotten_reason` removed	Forgetting reason is now tracked in `memory_audit`.
`memory_audit` table	New table tracking all strength changes with timestamps and reasons.
`stack_settings` table	New table for per-stack configuration (e.g., `enforce_provenance`).

What happens automatically:

The strength column is added to all memory tables with default 1.0
Memories previously marked is_forgotten=1 are migrated to strength = 0.0
The memory_audit and stack_settings tables are created

0.1.x → 0.2.0 Migration

The 0.2.0 release includes a significant raw layer refactor that changes how raw entries are stored:

Old Schema (0.1.x)	New Schema (0.2.0)
`content` field	`blob` field (primary)
`timestamp` field	`captured_at` field
`tags` JSON array	Included in `blob` text

What happens automatically:

The blob and captured_at columns are added to raw_entries
Existing content is migrated to blob with natural language formatting
Tags are appended to the blob text (e.g., [tags: work, planning])
FTS5 full-text search index is created for fast keyword search

Migration warning you might see:

WARNING:kernle.storage.sqlite:Raw blob migration check failed: no such column: blob

This warning appears when the migration is in progress or needs to be triggered. It’s non-blocking - Kernle will continue to work, but you should run a command to complete the migration.

Triggering Migrations Manually

Migrations run automatically on any Kernle command. To explicitly trigger them:

# Any command will trigger migrations
kernle status

# Or check your stack's memory
kernle -s your_stack load

Verifying Migration Success

After migration, the warning should disappear. You can also verify the raw layer is working:

# Test raw capture
kernle raw capture "test entry after migration"

# Test FTS5 search (new in 0.2.0)
kernle raw search "test"

Troubleshooting Migration Issues

”no such column: blob” Warning Persists

If the warning persists after running commands:

Check SQLite version: FTS5 requires SQLite 3.9.0+

python -c "import sqlite3; print(sqlite3.sqlite_version)"

Force schema recreation (safe - won’t delete data):

# Backup first
cp ~/.kernle/your_stack/memory.db ~/.kernle/your_stack/memory.db.backup

# Run any command to re-trigger migrations
kernle -s your_stack status

Check file permissions: Ensure the database file is writable
ls -la ~/.kernle/your_stack/memory.db

FTS5 Search Not Working

If kernle raw search returns no results but you have raw entries:

The FTS5 index may need rebuilding. This happens automatically, but you can force it:
kernle -s your_stack raw search "." # Any search triggers index check
On older SQLite versions without FTS5, search falls back to LIKE queries (slower but functional).

Rollback (Emergency Only)

If you need to rollback to a previous version:

pip install kernle==0.1.0
pyenv rehash  # if using pyenv

Rollback is safe for data but new features won’t be available. The database schema is backwards-compatible - old versions can read data created by new versions.

Version History

Version	Key Migration Changes
0.11.0	Hook CLI commands, Claude Code setup, OpenClaw plugin
0.10.0	Strength cascade, memory processing, export-full, provenance on MCP tools, `-a` → `-s` CLI rename
0.9.0	Continuous strength field, `memory_audit` table, `stack_settings` table, provenance enforcement, strict mode
0.2.0	Raw layer blob refactor, FTS5 search, budget-aware loading
0.1.0	Initial release

Getting Started

Core Concepts

Protocol System

Advanced Features

Developer Tools

CLI Reference

Integration

Design

Troubleshooting

Upgrading Kernle

Upgrade Process

Basic Upgrade

pyenv Users

Verifying the Upgrade

CLI Breaking Changes

0.10.0: `-a/--agent` renamed to `-s/--stack`

Database Migrations

0.2.x → 0.9.0 Migration

0.1.x → 0.2.0 Migration

Triggering Migrations Manually

Verifying Migration Success

Troubleshooting Migration Issues

”no such column: blob” Warning Persists

FTS5 Search Not Working

Rollback (Emergency Only)

Version History

​Upgrade Process

​Basic Upgrade

​pyenv Users

​Verifying the Upgrade

​CLI Breaking Changes

​0.10.0: -a/--agent renamed to -s/--stack

​Database Migrations

​0.2.x → 0.9.0 Migration

​0.1.x → 0.2.0 Migration

​Triggering Migrations Manually

​Verifying Migration Success

​Troubleshooting Migration Issues

​”no such column: blob” Warning Persists

​FTS5 Search Not Working

​Rollback (Emergency Only)

​Version History

Upgrade Process

Basic Upgrade

pyenv Users

Verifying the Upgrade

CLI Breaking Changes

0.10.0: `-a/--agent` renamed to `-s/--stack`

Database Migrations

0.2.x → 0.9.0 Migration

0.1.x → 0.2.0 Migration

Triggering Migrations Manually

Verifying Migration Success

Troubleshooting Migration Issues

”no such column: blob” Warning Persists

FTS5 Search Not Working

Rollback (Emergency Only)

Version History