Enable agent memory

Enable cross-session memory on an AgentRuntime, choosing ambient retrieval, the memory tools, or both.

Prerequisites

A service group with a running memory-api. See Configure workspace memory.
An AgentRuntime that names that service group in spec.serviceGroup.
Callers who authenticate with a credential that identifies a user. Memory tools register only for a verified user (step 3).

Steps

Set spec.memory on the AgentRuntime. Memory is off until enabled is true.
```
apiVersion: omnia.altairalabs.ai/v1alpha1
kind: AgentRuntime
metadata:
  name: support-agent
  namespace: agents
spec:
  serviceGroup: default
  memory:
    enabled: true
    retrieval:
      enabled: true
      strategy: composite
      limit: 10
    tools:
      enabled: true
```
retrieval injects relevant memories into each turn. tools exposes memory__remember, memory__recall, memory__list and memory__forget to the model. The two switches are independent, and both default to enabled when memory.enabled is true.

Ambient memories reach the model through the {{memory_context}} variable, so the agent’s PromptPack decides where they go and whether they appear at all. A pack whose prompts never render {{memory_context}} has opted out: the runtime then does not retrieve for it, and only the tools read memory.
```
You are a support agent.

What you already know about this user:
{{memory_context}}
```
Choose what to switch off.
- For ambient context only, set tools.enabled: false.
- For tools without automatic injection, set retrieval.enabled: false.
retrieval.strategy is keyword, semantic or composite. Composite fuses keyword and semantic results, and falls back to keyword results alone when the semantic search is unavailable. retrieval.limit accepts 1 to 50 memories per turn.
Authenticate the caller. The runtime registers the memory tools only for a verified user, and retrieval reads only the agent and institutional tiers without one.
- The facade takes the user from the credential’s end user. A management-plane token carries a signed on-behalf-of end user, then falls back to the device_id query parameter.
- A device_id alone is not enough. The facade must also exchange the request’s Authorization bearer credential for a subject proof.
- Anonymous, API-key, scheduled and async-invoke callers have no subject proof, so they get no memory tools and memory-api refuses user-scoped writes with a 403.
Optional: drop restricted items from retrieval with a CEL deny expression over each item’s metadata.
```
spec:
  memory:
    retrieval:
      accessFilter:
        denyCEL: 'has(metadata.classification) && metadata.classification == "restricted"'
```
An empty expression disables filtering. The filter denies an item whose evaluation errors, so an expression that reads a missing key, such as metadata.classification on an item without one, drops that item. Guard with has(). A malformed expression makes the conversation fail to start.
Apply the manifest.
Terminal window
```
kubectl apply -f support-agent.yaml
```

Verify

Read the runtime logs. AgentRuntime status has no memory field.
Terminal window
```
kubectl logs deployment/support-agent -n agents -c runtime
```
Look for memory store wired, which shows the memory-api URL, the strategy and whether a deny filter is set. For an unverified caller the log instead says memory tools enabled but will not be registered: no verified user on this conversation.
Connect as an authenticated user, ask the agent to remember a fact, then start a new session as the same user and ask about it.

Troubleshooting

The model has no memory tools

The conversation has no verified user. Check the runtime log for the will not be registered message, then authenticate the caller as in step 3.

The log says memory is enabled but no memory-api URL is configured

The runtime received no memory-api URL, so it skips memory. See Configure workspace memory.

The model never sees ambient memories

The pack does not render {{memory_context}}. The runtime log at debug says ambient memory retrieval skipped with that reason, and memory scope wired reports retrievalAttached: false. Add the placeholder to the prompt where the memories belong.

Retrieval returns nothing

Find the memory retrieval returned no context line in the runtime log. Its reason field says whether the conversation had no subject key, the turn had no user text, or the query matched nothing.

Memory tools for tool arguments.
AgentRuntime reference for every spec.memory field.
Memory API to inspect the raw records.