> ## Documentation Index
> Fetch the complete documentation index at: https://internal.september.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration guides

> Step-by-step upgrades across Engine versions.

Every breaking change in the Engine gets a migration guide. Each guide
explains what changed, what the new behavior is, and what code you need
to update.

For all changes (breaking and non-breaking), see the
[Changelog](./changelog).

## Active migrations

### v2.2 → v2.3 — orchestrator extraction + super\_thinking

**Status:** required if you're using the orchestrator or the legacy
effort parameter.

#### What changed

1. **Orchestrator removed.** `orchestrator.py` is no longer in the
   Engine. It moved to [`bap-engine`](https://github.com/septemberai/bap-engine).
   If your deployment used the in-process orchestrator, switch to
   running bap-engine alongside the Engine.

2. **`super_thinking` replaces `effort`.** The 4-level effort
   parameter (none/low/medium/high) was a poorly-calibrated knob. It's
   replaced by a boolean `super_thinking` that turns extended thinking
   on or off explicitly.

3. **`scripts/deploy.sh` and `scripts/pg-backup.sh` removed.** Postgres
   support is gone; the deploy script moved to bap-engine.

4. **`src/infra/pg.py` removed.** SQLite is the only durable store.

#### Migration steps

**If you used the in-process orchestrator:**

1. Set up bap-engine alongside the Engine. See
   [bap-engine deployment docs](https://github.com/septemberai/bap-engine).
2. Point the upstream router (BAP) at the bap-engine orchestrator URL
   instead of the Engine's orchestrator endpoint.
3. The Engine continues to serve `/execute` and friends as before.

**If you used the `effort` parameter:**

Before:

```json theme={null}
{
  "message": "...",
  "task_id": "...",
  "effort": "high"
}
```

After:

```json theme={null}
{
  "message": "...",
  "task_id": "...",
  "super_thinking": true
}
```

The mapping is `effort: "high"` → `super_thinking: true`; everything
else → `super_thinking: false`.

**If you used the Postgres adapter:**

Postgres is no longer supported. The Engine is SQLite-only. Migrate
your data to SQLite or run multiple Engines (one per user, each with
its own SQLite brain).

#### Validation

After migration:

* `curl /health` — should return `ok`.
* Run a test `/execute` with `super_thinking: true`. Stream should
  include `thinking_delta` events.
* Run regression evals — see [Regression](../test-and-evaluate/regression).

***

### v1.x → v2.0 — pip package distribution

**Status:** required if you used a git-submodule install.

#### What changed

The Engine moved from git-submodule distribution to a pip package via
private GitHub.

#### Migration steps

**Before** (Dockerfile snippet):

```Dockerfile theme={null}
ADD .gitmodules .
RUN git submodule update --init --recursive
RUN cp -r submodules/engine/migrations migrations
RUN cp -r submodules/engine/catalog catalog
```

**After:**

```Dockerfile theme={null}
RUN pip install git+https://github.com/septemberai/engine.git@v2.1.1
# migrations and catalog now ship inside the package
```

The Engine reads its bundled migrations and catalog automatically.
Don't bind-mount over them unless you're customizing.

#### Validation

After migration:

* `python -c "import src; print(src.__version__)"` should print the
  Engine version.
* `curl /health` should return `ok`, with the migrations subsystem
  reporting all applied.

***

## Migration playbook

For any upgrade, regardless of size:

1. **Read the changelog.** Identify breaking changes.
2. **Read the relevant migration guides.** This page.
3. **Back up the brain.** Snapshot the volume or run
   `/memory/export`.
4. **Bring up the new Engine in a staging environment** with a copy
   of the brain. Confirm `/health` returns `ok`.
5. **Run regression evals.** Compare against the pre-upgrade baseline.
6. **Spot-check critical workflows.** A coding agent run; a research
   agent run; a support tier-2 run with HITL.
7. **Roll out to production** when the staging signal is green.

For high-stakes deployments, do a canary rollout: a small percentage
of traffic on the new version for a few hours before flipping the
rest.

## When migration goes wrong

If the new Engine fails to start:

* Check logs for migration errors. A failed migration leaves the brain
  in an inconsistent state.
* Roll back to the previous version (the brain remains compatible
  with prior versions if no breaking schema changes happened).
* Restore from snapshot if the brain is in a bad state.

If the new Engine starts but behaves oddly:

* Run a regression eval to identify which behaviors regressed.
* Check the [Changelog](./changelog) for `Changed` entries that match
  the symptoms.
* Roll back if the regressions are unacceptable.

## Versioning

The Engine follows [Semantic Versioning](https://semver.org/):

* **Major (X.0.0)** — breaking changes. Always has a migration guide.
* **Minor (X.Y.0)** — new features, no breaking changes.
* **Patch (X.Y.Z)** — bug fixes, no new features.

Migration guides are required for major bumps; optional for minor
bumps when behavior shifts non-breakingly.

## See also

* [Changelog](./changelog) — every release.
* [Regression](../test-and-evaluate/regression) — checking behavior
  across versions.
* [Upgrade](../../operations/deploy/upgrade) — operational steps for
  the deploy itself.