Migration Copilot: An AI That Runs on Your Machine, Not Someone Else’s Cloud

Your Database Is the Last Thing You Want to Send to a Cloud API

The current wave of "AI migration assistants" mostly works the same way: they ship your schema — table definitions, PL/SQL, sometimes sample data — to a third-party LLM API to get an answer back. For a hobby project, fine. For a regulated production database in finance, healthcare, or the public sector, it's a non-starter. The data-governance conversation ends before it begins.

So we built Migration Copilot the other way around. It runs on your machine. No API key to get started, no internet required, nothing about your database leaves the box. It's a conversational assistant that can assess a schema, plan a migration, convert PL/SQL, validate the result, and drive a cutover — and it does all of that locally.

What It Actually Is

Migration Copilot is not a chatbot bolted onto a docs page. It's an agent wired into the migration engine. You talk to it in plain language; it drives the real tools:

• discover — inventory tables, types, FKs, row counts
• assess — the 95/5 gap report for a table
• plan — a dependency-aware migration plan
• execute — run the migration (gated; see below)
• validate — row counts, checksums, Merkle proof

Crucially, the model doesn't generate SQL and hope. It proposes a tool call, the engine executes it, the engine returns a structured result, and the model narrates what happened. The LLM is the conversation and the judgement; the deterministic engine is the hands.

Local-First by Default

The default brain runs in-process — a quantized open-weights model loaded directly inside the app (via llama.cpp), no separate server, no daemon. When no model file is present yet, the Copilot falls back to a deterministic built-in knowledge engine, so it's useful out of the box and never simply dead.

For teams that want a frontier model and can send data out, there's an opt-in bring-your-own-key path (OpenAI, Anthropic, Groq, or a local Ollama endpoint). But that's a choice you make — not the default, and never a surprise network call in an environment that can't allow one.

The Safety Model: It Asks First

An AI that can run a migration is an AI that can do damage. So the trust model is explicit and enforced in code, not in a prompt:

• Confirmation gate. Every destructive action — running a migration, cancelling a run — requires explicit user approval, every time, even if you approved a similar one a minute ago.
• Hard-coded refusals. Shell commands, arbitrary file access, and credential or license changes are refused at the dispatch layer regardless of what the model emits. It's defense-in-depth: not something the prompt can talk its way around.
• Structured tool results. When a tool fails, the model gets a clean error it can recover from and explain — not a stack trace it hallucinates around.
• Verify before it claims success. After a migration runs, the Copilot validates the result — row counts, checksums, Merkle proof — before it tells you it worked. It can't declare victory on a run it hasn't verified.

Long Conversations That Don't Fall Over

Real migration work is a long conversation — assess this, explain that, plan the cutover, walk through the validation report. Most assistants degrade as that history grows: they hit the model's context limit and either error out or silently forget the start of the session. Migration Copilot handles it explicitly.

• Recent turns stay verbatim. The latest stretch of the exchange is always sent in full, so the model has the live thread exactly as you said it.
• Older turns are summarized, not dropped. Once the conversation outgrows the window, earlier turns are folded into a compact running summary — the gist survives, the bulk goes.
• Your transcript is never lost. Summarizing only affects the working copy sent to the model. The full conversation stays on disk, append-only — /save, scroll-back, and the audit log still see every word.
• Tool exchanges stay intact. The trim is careful never to split a tool call from its result, so the model never sees a half-finished action.

The practical effect: an hour-long planning session doesn't hit a wall, and on the local model the per-turn size stays bounded — which is why the running cost estimate holds at $0.00 no matter how long you talk. We even keep a regression test that fails the build if the offline path ever creeps over its token budget.

Becoming the DBMigrateAIPro Model

Out of the box the local model is a capable general open-weights base. What makes it ours is fine-tuning on migration-specific data we already own: real Oracle→PostgreSQL conversion pairs from our own transpiler, the type-mapping rules, the package/sequence/validation playbooks, and the self-healing error→fix catalog. The honest framing: we stand on an open-weights base and make it distinctly good at this job — we're not pretending to have trained a foundation model from scratch.

Local-First vs Cloud-API Assistants

This isn't a knock on cloud models — they're excellent, and we support them as an opt-in. It's about the default being right for database work: private, offline-capable, and free to start.

How to Use It

Two front doors, same engine — in the terminal:

# Conversational, offline, no key:
python main.py copilot

# One-shot:
python main.py copilot -m "how do I migrate an Oracle package to PostgreSQL?"

# Connect live databases to enable discover / assess / plan / execute:
python main.py copilot --source-type oracle --source-host db \
  --source-user hr --source-pass <pwd> --source-schema HR

…or the Copilot tab in the desktop app, which lights up its live tools the moment you connect a database. Both support slash commands (/clear, /retry, /cost, /save, /load, /sessions), and the running cost estimate stays at $0.00 on the local model.

The Honest Verdict

AI is genuinely useful for migration work — but only if it can be used on the databases that matter, which are exactly the ones you can't pipe to an external API. Local-first isn't a limitation here; it's the feature. An assistant that runs on your machine, drives the real engine, and asks before it acts is one you can actually point at production.