Move the Entity, replace the model

Separate inference routing from the portable state that carries continuity.

Inference portability and Entity portability solve different problems. You can change a model endpoint without moving state, or package Entity state for a different runtime host.

Replace inference

The provider protocol exposes chat completion, embeddings, catalog and health inspection, and cleanup. The runtime can route those calls to local Ollama, a private gateway, or a supported hosted endpoint.

The Entity still owns memory, tool execution policy, relationships, and presence. Changing the provider does not automatically migrate old embedding vectors or persist an in-memory credential after restart.

Use hosted inference or the private gateway for those routing choices.

Export a portable Entity

uv run ngram export rook exports/rook.ngram
uv run ngram verify exports/rook.ngram

An export packages Entity state with an integrity manifest. Treat it as private data. Verification checks structure and integrity; it does not encrypt the archive or establish that its content is safe to execute.

For a consistent production snapshot, pause inference and stop other writers before coordinating the export and any external storage backup.

Open and inspect

uv run ngram open exports/rook.ngram entities/rook
uv run ngram verify entities/rook
uv run ngram studio entities/rook

Choose a fresh destination. Studio inspects the verified Entity locally without loading a model and binds to loopback by design.

ngram init migrates an existing runtime Entity into an open portable directory. ngram import supports restore workflows, including explicit hybrid activation options. Read the exact CLI reference before an import or migration that changes authoritative state.

Canonical state and runtime cache

An opened portable Entity has a canonical representation and a derived runtime cache. Live-container mode uses its cache database rather than ordinary Postgres routing from DATABASE_URL.

After an interrupted local session, ngram recover reconciles the derived cache according to the container workflow. Preserve the canonical artifact and its integrity metadata; do not copy only a convenient cache file and assume it is complete.

Lease and lifecycle rules matter when changing the authoritative writer. Do not launch competing instances against the same state as an informal migration method.

Source: ngram/container and persistence.