Self-managed Redis Agent Memory
Deploy, configure, secure, and operate Redis Agent Memory on a self-managed Kubernetes cluster.
Redis Agent Memory provides persistent memory for AI agents and applications. Applications write conversation events and long-term memories to Redis Agent Memory, then query Redis Agent Memory for relevant context before calling an LLM.
This guide covers deployment, configuration, security, validation, API examples, and operations for self-managed Redis Agent Memory. To install, follow Install the Redis Iris suite, then Deploy.
The Redis Agent Memory API is the shared Data Plane API for Redis Cloud and self-managed deployments. The Control Plane API reference documents the self-managed admin endpoints for stores.
What you are deploying
The redis-iris chart 1.0.0 deploys the Agent Memory Data Plane, workers, and Control Plane,
with the Identity Service and the Iris console, under fixed names. Agent Memory's values go under
the memory: key, and the chart's examples/memory-only.yaml is a working values file to start
from. You provide the Redis databases.
| Component | Purpose | Default service |
|---|---|---|
| Redis Agent Memory Data Plane | Store-scoped runtime memory API. | redis-agent-memory:9000 |
| Redis Agent Memory worker | Background promotion, summarization, and forgetting work. | No public service |
| Redis Agent Memory Control Plane | Admin API for creating and managing stores. | redis-agent-memory-controlplane:9100 |
| Identity Service | Mints, rotates, revokes, and checks agent keys. Installed by the suite. | iris-identity-service:9200 |
| Store Redis | Holds session memory, long-term memory, indexes, and TTL data. | Customer-provided |
| Job Redis | Holds background work for Redis Agent Memory workers. | Customer-provided |
| Metadata Redis | Holds Control Plane store records. The Identity Service keeps agent-key records in the Metadata Redis named in its own metadata Secret. | Customer-provided |
How the components work together
The Data Plane handles runtime memory requests. The Control Plane handles store administration, and the Identity Service handles agent keys.
| Flow | Caller | Service | Backing Redis |
|---|---|---|---|
| Store administration | Platform admin | Redis Agent Memory Control Plane | Metadata Redis |
| Agent-key administration | Platform admin | Identity Service | Identity Service Metadata Redis |
| Runtime memory requests | Agent, app, or gateway | Redis Agent Memory Data Plane | Store Redis |
| Background memory processing | Redis Agent Memory worker | Redis Agent Memory Data Plane | Job Redis and Store Redis |
- Platform admins create stores with the Control Plane and mint agent keys with the Identity Service.
- The Control Plane keeps store records in Metadata Redis. The Identity Service keeps agent-key records in its own Metadata Redis.
- Agents and applications call the Data Plane with a store ID and an agent key.
- The Data Plane checks each agent key by calling the Identity Service, then reads or writes memory in Store Redis.
- Workers use Job Redis for background work and write generated memory to Store Redis.
API surfaces
Memory data APIs are scoped to a store, the logical isolation boundary for memory data. Service liveness and readiness endpoints are not store-scoped.
When agent-key authentication is enabled, the grants on each agent key determine which stores and actions the key can access.
| API surface | Endpoint prefix | Purpose |
|---|---|---|
| Session memory | /iris/data/v1/agent-memory/stores/{storeId}/sessions |
Ordered conversation events, session metadata, and session lifecycle operations. |
| Long-term memory | /iris/data/v1/agent-memory/stores/{storeId}/memories |
Searchable facts, preferences, summaries, and custom memory records. |
| Namespaces | /iris/data/v1/agent-memory/stores/{storeId}/namespaces |
Namespace resources within a store. |
| Model Context Protocol (MCP) | /iris/data/v1/agent-memory/stores/{storeId}/mcp |
The MCP streamable-HTTP endpoint for a store. |
| Store health | /iris/data/v1/agent-memory/stores/{storeId}/health |
Read-only health for store-scoped features. |
| Service health | /health/liveness, /health/readiness |
Process liveness and readiness to serve requests; neither requires an agent key. |
| Control Plane | /iris/v1/agent-memory/stores, /iris/v1/agent-memory/detectors |
Self-managed administration for stores, and the catalog of built-in sensitive-data detectors. |
| Identity Service | /v1/api-keys |
Self-managed administration for agent keys. |
Session memory keeps conversation continuity within a session. Long-term memory provides searchable context across sessions.
Long-term memory memoryType is an open identifier. When omitted on create,
Redis Agent Memory stores the record as semantic; built-in names include semantic,
episodic, and message.
Create a store with the CLI and SDK
After you deploy, the iris CLI in the redis-iris package creates a store, mints its agent key, and checks every hop. The Control Plane API examples show the same steps over HTTP.
-
Install the package:
pip install 'redis-iris>=1.0.0' -
Create
iris.tomlwith a profile for your deployment. It holds URLs only:[profiles.suite] kind = "self-managed" [profiles.suite.agent_memory] service_url = "<control-plane-url>" url = "<data-plane-url>" identity_url = "<identity-service-url>" -
Put the operator tokens in
.env.admin, separate from your application's.env:IRIS_CONFIG=./iris.toml IRIS_PROFILE=suite IRIS_AGENT_MEMORY_SERVICE_TOKEN=<control-plane-admin-token> IRIS_IDENTITY_TOKEN=<identity-service-control-token> -
Load the tokens and do a dry run. It sends nothing:
set -a; source .env.admin; set +a iris agent-memory service create --name support-memory --dry-run -
Create the store. The CLI mints its agent key and writes
IRIS_AGENT_MEMORY_URL,IRIS_AGENT_MEMORY_STORE_ID, andIRIS_AGENT_MEMORY_API_KEYto.envwithout printing the key:iris agent-memory service create --name support-memory --write-env .env -
Check every hop, from the Control Plane to a read with the agent key:
set -a; source .env; set +a iris agent-memory service check "$IRIS_AGENT_MEMORY_STORE_ID" --env-file .env
Your application reads the same .env. With the Python SDK:
from redis_iris import AgentMemory
memory = AgentMemory.from_env()
convo = memory.conversation(owner="user-1042", session_id="support-thread-1")
convo.user("Please send updates by email.")
print(memory.recall("How does this user want updates?", owner="user-1042").as_prompt())
See SDK and CLI setup for profiles and credentials.