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

# Upgrading Kernle

> How to upgrade Kernle and handle database migrations

## Upgrade Process

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

### Basic Upgrade

```bash theme={null}
pip install --upgrade kernle
```

### pyenv Users

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

```bash theme={null}
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:

```bash theme={null}
# 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:**

1. **Shell scripts and aliases** — find-and-replace `-a ` with `-s ` and `--agent ` with `--stack `:
   ```bash theme={null}
   # Before
   alias kl="kernle -a my-project load"
   # After
   alias kl="kernle -s my-project load"
   ```

2. **CLAUDE.md / AGENTS.md** — update any CLI examples:
   ```bash theme={null}
   # Search project docs for old syntax
   grep -rn "kernle -a\|kernle --agent" .
   ```

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

4. **Claude Code hooks** — re-run setup to regenerate hooks with the new flag:
   ```bash theme={null}
   kernle setup claude-code
   # or
   kernle setup claude-code --global
   ```

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

<Note>
  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.
</Note>

***

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

1. The `strength` column is added to all memory tables with default 1.0
2. Memories previously marked `is_forgotten=1` are migrated to `strength = 0.0`
3. 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:**

1. The `blob` and `captured_at` columns are added to `raw_entries`
2. Existing `content` is migrated to `blob` with natural language formatting
3. Tags are appended to the blob text (e.g., `[tags: work, planning]`)
4. 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

1. **Check SQLite version**: FTS5 requires SQLite 3.9.0+
   ```bash theme={null}
   python -c "import sqlite3; print(sqlite3.sqlite_version)"
   ```

2. **Force schema recreation** (safe - won't delete data):
   ```bash theme={null}
   # 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
   ```

3. **Check file permissions**: Ensure the database file is writable
   ```bash theme={null}
   ls -la ~/.kernle/your_stack/memory.db
   ```

### FTS5 Search Not Working

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

1. The FTS5 index may need rebuilding. This happens automatically, but you can force it:
   ```bash theme={null}
   kernle -s your_stack raw search "."  # Any search triggers index check
   ```

2. 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:

```bash theme={null}
pip install kernle==0.1.0
pyenv rehash  # if using pyenv
```

<Note>
  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.
</Note>

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