Change the memory embedding model

Move a service group’s memory to a different embedding model. memory-api embeds every memory with the new model beside its current vector, swaps recall over in one step, and keeps serving throughout.

Prerequisites

A Workspace service group whose memory.providerRef names a Provider with spec.role: embedding.
Permission to create a Provider in the workspace namespace and to edit the Workspace.
The new model’s output dimension. See Embedding providers for how memory-api resolves it.

Access to memory-api’s admin routes. Forward the port and set MEMORY_API:

kubectl port-forward -n <namespace> svc/memory-<workspace>-<group> 8080:8080
export MEMORY_API=http://localhost:8080

internalServiceAuth.enabled is true by default. Add -H "Authorization: Bearer $TOKEN" to each curl below, with a ServiceAccount token as described in Authentication and scope.

Steps

Create a Provider for the new model. Leave the current Provider as it is. The values below are illustrative:

apiVersion: omnia.altairalabs.ai/v1alpha1
kind: Provider
metadata:
  name: memory-embeddings-v2
  namespace: agents
spec:
  role: embedding
  type: ollama
  model: nomic-embed-text
  embedding:
    dimensions: 768

Name it as the service group’s next embedding Provider:

spec:
  services:
    - name: default
      memory:
        providerRef:
          name: memory-embeddings
        nextProviderRef:
          name: memory-embeddings-v2

The operator passes it to memory-api as --next-embedding-provider and rolls the pod. Wait for the rollout:

kubectl rollout status deployment/memory-<workspace>-<group> -n <namespace>

Read the estimate. configuredNext names the new model, and estimate gives the vectors to embed again and the storage the change adds until you finish it:
Terminal window
```
curl -fsS "$MEMORY_API/admin/brain/model-change"
```
Start the change:
Terminal window
```
curl -fsS -X POST "$MEMORY_API/admin/brain/model-change"
```
status.phase moves through filling (new vectors are embedded), indexing (the new indexes are built) and ready. memory-api then swaps recall to the new model and the phase reads swapped. Recall and writes stay online in every phase.
Drop the old vectors and indexes once the phase reads swapped:
Terminal window
```
curl -fsS -X POST "$MEMORY_API/admin/brain/model-change/finish"
```
Point the service group at the new Provider and remove nextProviderRef:
```
memory:
  providerRef:
    name: memory-embeddings-v2
```
Until you do, memory-api serves with the new Provider, because the database names its model.

Verify

curl -fsS "$MEMORY_API/admin/brain/model-change"

status.phase is idle and status.current names the new model and dimension.

Cancel a change

Before the swap, abandon the change and drop the new vectors:

curl -fsS -X POST "$MEMORY_API/admin/brain/model-change/cancel"

Then remove nextProviderRef from the service group.

Troubleshooting

A model-change call returns 409

The change is in another state than the call needs. The message names it: no next model is configured (set nextProviderRef), a change is already in progress, the next model is the current one, no change is in progress, or the change is not ready to swap.

A model-change call returns 403

The routes accept service callers only. Send a ServiceAccount bearer token.

memory-api fails to start with `memory_meta does not match configuration`

The current Provider was edited in place to another model or dimension. Restore its previous model and spec.embedding.dimensions, then change models through nextProviderRef as above. A Provider edit between two declared dimensions also returns an admission warning that points at the model change.

memory-api fails with a maximum-dimension error

The model’s dimension is above the supported maximum. Choose a model within the limit, or set spec.embedding.dimensions to a value the model can shorten to. See Embedding dimension limits.