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