Configure workspace memory

Set up memory for a Workspace service group, so the operator runs a memory-api for it and publishes its URL in the group’s status.

Prerequisites

A PostgreSQL database for memory, and a Secret in the workspace namespace with a POSTGRES_CONN key holding its connection string.
A Provider with role: embedding in the workspace namespace. Without one, recall falls back to full-text search only.
A MemoryPolicy, if you want to set retention or recall behaviour.

Configure a managed service group

Add the memory block to a service group in the Workspace. Workspace is cluster-scoped, so the manifest has no metadata.namespace. The names below are illustrative.

apiVersion: omnia.altairalabs.ai/v1alpha1
kind: Workspace
metadata:
  name: support
spec:
  namespace:
    name: support-agents
  services:
    - name: default
      mode: managed
      session:
        database:
          secretRef:
            name: session-postgres
      memory:
        database:
          secretRef:
            name: memory-postgres
        providerRef:
          name: memory-embeddings
        policyRef:
          name: memory-policy

Redis and podOverrides also go inside memory when the group needs a dedicated cache or Pod identity. See Workspace for every field.

To rerank recall results, add a Provider with role: rerank to the same block:
```
memory:
  rerankProviderRef:
    name: memory-reranker
```
The MemoryPolicy must also set spec.recall.rerank.enabled: true (an Enterprise setting). See MemoryPolicy.
To tune the embedding backfill worker, add a reembed block:
```
memory:
  reembed:
    concurrency: 4
    batchSize: 500
```
concurrency defaults to 2, which is safe on a small managed Postgres. The right value depends on the database’s CPU, so measure it with POST /admin/reembed/calibrate as described in Operate embeddings. Changing either field rolls the memory-api Pod.
Apply the Workspace:
Terminal window
```
kubectl apply -f workspace.yaml
```

Use an external memory-api

If you run memory-api yourself, set the group to external instead of managed:

spec:
  services:
    - name: default
      mode: external
      external:
        sessionURL: https://session.example.com
        memoryURL: https://memory.example.com

memoryURL is required. sessionURL is optional. The operator copies both into the group’s status, and an AgentRuntime selects the group with spec.serviceGroup.

Verify

Check that the group reports a memoryURL and ready: true:
Terminal window
```
kubectl get workspace support -o jsonpath='{.status.services}'
```
For a managed group, check that the memory-api Deployment has a ready replica. The Deployment is named memory-<workspace>-<group> and runs in the workspace namespace:
Terminal window
```
kubectl -n support-agents get deployment memory-support-default
```

The Pod serves its readiness probe on port 8081 at /readyz. See the Memory API reference for ports and authentication.

Troubleshooting

The group has no memoryURL

The operator holds back that group’s memory-api when a referenced Provider fails validation. The group’s session-api is unaffected. Read the group’s conditions:

kubectl describe workspace support

EmbeddingProviderReady and RerankProviderReady appear under status.services[].conditions. The reason names the cause: ProviderNotFound, ProviderLookupFailed, ProviderRoleMismatch (the Provider’s role is not embedding or rerank), or ProviderNotReady (the Provider is in phase Error or Unavailable).