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
  1. Platform admins create stores with the Control Plane and mint agent keys with the Identity Service.
  2. The Control Plane keeps store records in Metadata Redis. The Identity Service keeps agent-key records in its own Metadata Redis.
  3. Agents and applications call the Data Plane with a store ID and an agent key.
  4. The Data Plane checks each agent key by calling the Identity Service, then reads or writes memory in Store Redis.
  5. 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.

  1. Install the package:

    pip install 'redis-iris>=1.0.0'
    
  2. Create iris.toml with 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>"
    
  3. 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>
    
  4. 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
    
  5. Create the store. The CLI mints its agent key and writes IRIS_AGENT_MEMORY_URL, IRIS_AGENT_MEMORY_STORE_ID, and IRIS_AGENT_MEMORY_API_KEY to .env without printing the key:

    iris agent-memory service create --name support-memory --write-env .env
    
  6. 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.

RATE THIS PAGE
Back to top ↑