Query memory from your own service

Retrieve memories from memory-api in a service that runs outside an AgentRuntime.

Prerequisites

A Workspace with memory enabled.
Your service runs in the Workspace’s namespace. memory-api trusts that namespace and no other.
internalServiceAuth.enabled is true (the chart default). The steps below assume it is.

Find the endpoint

Read the memory-api URL from the Workspace service-group status.
Terminal window
```
kubectl get workspace support -o jsonpath='{.status.services[*].memoryURL}'
```
Use that value as MEMORY_API below. support is an example Workspace name.

Memory rows are keyed by the Workspace UID, so also read the UID:
Terminal window
```
export WORKSPACE_ID=$(kubectl get workspace support -o jsonpath='{.metadata.uid}')
```

Mount a token

Project a ServiceAccount token into your pod with the audience memory-api enforces. The operator does this for the pods it manages; for your own Deployment, add the volume yourself.
```
volumes:
  - name: session-api-token
    projected:
      sources:
        - serviceAccountToken:
            path: token
            audience: omnia-session-api
            expirationSeconds: 3600
```
omnia-session-api is the chart default for internalServiceAuth.audience. Mount the volume on your container, for example at /var/run/secrets/omnia/session-api, and set SESSION_API_TOKEN_PATH to the token file.

The default ServiceAccount token carries the cluster audience, and memory-api answers it with 401.

Retrieve memories

Send the token as a bearer token.

curl -fsS "$MEMORY_API/api/v1/memories/retrieve" \
  -H "Authorization: Bearer $(cat "$SESSION_API_TOKEN_PATH")" \
  -H 'Content-Type: application/json' \
  -d '{
    "workspace_id": "'"$WORKSPACE_ID"'",
    "query": "return policy",
    "limit": 10
  }'

workspace_id is required and must be the Workspace UID: a name returns 500. limit defaults to 15 and is capped at 100.

From Go, use pkg/memory/httpclient. It reads the token from SESSION_API_TOKEN_PATH and forwards a subject proof held in the request context.

import (
  "github.com/altairalabs/omnia/pkg/memory/httpclient"
  "github.com/go-logr/logr"
)

store := httpclient.NewStore(memoryURL, logr.Discard())
result, err := store.RetrieveMultiTier(ctx, httpclient.MultiTierRequest{
  WorkspaceID: workspaceID, // the Workspace UID
  Query:       "return policy",
  Limit:       10,
})

To read a user’s memory, add user_id with the user’s pseudonymised identity. Do not send raw personal identifiers.

A request that names a user needs a verified session token for that user, or a caller on memory-api’s exact subject allowlist. Your service is admitted by namespace only, so a request with user_id and no token gets 403. Leave user_id out to read agent and institutional memory.

Verify

The response is 200 with a memories array and a total. Each entry carries tier, score and access_count.

Troubleshooting

401 from memory-api

The token is missing, expired, or has the wrong audience. Check that the projected audience equals internalServiceAuth.audience and that SESSION_API_TOKEN_PATH names the projected file.

403 from memory-api

Your ServiceAccount is outside the Workspace namespace, or the request names a user without a verified session token. See Authentication and scope.

429 from memory-api

The per-client-IP limit is 100 requests per second with a burst of 200 (RATE_LIMIT_RPS and RATE_LIMIT_BURST on memory-api). Space out requests, or batch work through POST /api/v1/institutional/ingest/batch, which is exempt when service authentication is on. To raise the limit on a managed memory-api, set both variables under the service group’s memory.podOverrides.extraEnv in the Workspace:

spec:
  services:
    - name: default
      memory:
        podOverrides:
          extraEnv:
            - name: RATE_LIMIT_RPS
              value: "500"
            - name: RATE_LIMIT_BURST
              value: "1000"

Memory API reference: every route, request schema and Enterprise gate.
Memory: how tiers and recall work.