# 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](/explanation/agents/memory/#embedding-providers) for how memory-api resolves it.
- Access to memory-api's admin routes. Forward the port and set `MEMORY_API`:

  ```bash
  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](/reference/platform/memory-api/#authentication-and-scope).

## Steps

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

   ```yaml
   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
   ```

2. Name it as the service group's next embedding Provider:

   ```yaml
   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:

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

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

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

4. Start the change:

   ```bash
   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.

5. Drop the old vectors and indexes once the phase reads `swapped`:

   ```bash
   curl -fsS -X POST "$MEMORY_API/admin/brain/model-change/finish"
   ```

6. Point the service group at the new Provider and remove `nextProviderRef`:

   ```yaml
   memory:
     providerRef:
       name: memory-embeddings-v2
   ```

   Until you do, memory-api serves with the new Provider, because the database names its model.

## Verify

```bash
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:

```bash
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](/reference/platform/memory-api/#embedding-dimension-limits).

## Related pages

- [Embedding providers](/explanation/agents/memory/#embedding-providers)
- [Workspace `memory.nextProviderRef`](/reference/core/workspace/)
- [Operate memory embeddings](/how-to/memory/operate-embeddings/)
- [Memory API reference](/reference/platform/memory-api/)
- [Provider reference](/reference/core/provider/)