Configuration
Configure the Redis Agent Memory Data Plane and Control Plane from redis-iris suite values, or bring your own configuration files.
The redis-iris chart renders Agent Memory's Data Plane and Control Plane configuration from the
values under memory: in iris-values.yaml. Credentials stay in existing Secrets. For a complete
example, see Add the Agent Memory values.
To supply complete configuration files in your own Secrets instead, see Bring-your-own (BYO) configuration.
Where each setting goes
| Values | Configures |
|---|---|
memory.shared |
Settings common to the Data Plane and the Control Plane, such as databases. The chart merges them under memory.memory and memory.controlplane.configData. |
memory.memory |
The Data Plane and worker configuration file. |
memory.controlplane.configData |
The Control Plane configuration file. |
global.iris |
The tenant, license, Identity Service connection, and OIDC settings. The suite derives Memory's values from them. |
Overlay Secret (memory.secrets.secretName, key overlay.yaml) |
metadata.urls, metadata.namespace, databases."1".urls, background_jobs.redis.urls, and provider api_key values. The Data Plane, the workers, and the Control Plane all read it. |
Data Plane settings
Data Plane settings go under memory.memory, or at the top level of a BYO Data Plane configuration file.
| Setting | Purpose |
|---|---|
metadata.urls |
Required. Metadata Redis, which holds store records. metadata.namespace sets the key namespace (default iris:memory). |
databases |
Required. Store Redis, as databases."1".urls. |
embedding.models.default_embedding_model, embedding.models.dimensions |
Required. The embedding model and its vector size. The Control Plane's embedding.dimensions must match. |
auth |
Data Plane authentication. Defaults to agent_key. |
ownership.enabled |
Restricts personal records to their authenticated owner while allowing shared records. Defaults to false. When enabled, personal access requires a matching authenticated user ID, such as an agent key with a delegated user token. With it off, authorize requests in your backend. See Server-side ownership enforcement before enabling it. |
inference_providers |
Required when any llm block is set. Each entry holds a provider's endpoint. |
server |
Data Plane bind address and port. |
license.license_path |
Path where the license Secret is mounted. |
request_region |
Region used for background work routing. |
background_jobs.redis |
Job Redis connection used by background workers. |
background_jobs.idempotency |
Enable execution idempotency and extraction serialization for production workers. Requires enabled: true and urls; it can share Job Redis. |
embedders_connection_details |
Embedding provider endpoint and credentials. |
dataplane_client |
Worker callback client configuration. |
promote_session_memory |
Promotion strategy and LLM connection used by workers. |
An llm block names its provider with llm.provider, which must match an inference_providers
entry. The endpoint goes in inference_providers.<name>.endpoint, not in the llm block.
In the chart-rendered configuration, the suite writes the agent-key introspection settings for you,
pointing them at iris-identity-service: it owns auth.agent_keys.introspection.base_url,
credential, and allow_insecure_transport, and refuses hand-set values in either
memory.memory.auth or memory.shared.auth. Cache tuning under
auth.agent_keys.introspection.cache is still allowed. Set memory.memory.auth.method: agent_key
explicitly when combining agent keys with worker or other authentication methods.
For ownership enforcement, use memory.memory.ownership.enabled in Helm values or ownership.enabled in a BYO Data Plane configuration file. MEM_OWNERSHIP_ENABLED overrides the file setting. Enabling this option does not bind agent keys to users or rewrite existing owners.
Bring-your-own (BYO) configuration
With BYO configuration, you supply each complete configuration file in your own Secret, and the chart injects nothing into it. Add the keys the chart would otherwise write:
- Data Plane: the
auth.agent_keys.introspectionblock. - Control Plane:
auth.internal_token.token_file: /etc/controlplane-onprem/internal/tokenandauth.admin_tenant_idmatchingglobal.iris.tenantId.
The suite refuses BYO configuration Secrets when global.iris.extraction.enabled is true,
because the extraction trust settings land only in the configuration it renders.
With config.existingSecret, the chart does not inspect the supplied file. Rendering cannot
catch missing introspection settings or an invalid development profile in that file; startup
validation still applies. Connection Secrets must still be named in Helm values so they are mounted.
The Data Plane defaults to agent_key whenever no auth method is set. A BYO Data Plane configuration
without auth therefore needs the auth.agent_keys.introspection block. For development only,
auth.method: none requires exact profile: dev.
The MEM_AUTH_METHOD environment variable overrides the method.
Data Plane configuration file
Create memory-dataplane.config.yaml:
server:
host: 0.0.0.0
port: 9000
license:
license_path: /etc/redis-agent-memory/license
default_extraction_strategy: instruct
request_region:
default: eu1
background_jobs:
idempotency:
enabled: true
urls:
- redis://<job-redis-host>:6379
redis:
enabled: true
queue_prefix: ram
urls:
- redis://<job-redis-host>:6379
worker_regions:
- eu1
metadata:
urls:
- redis://<metadata-redis-host>:6379
namespace: iris:memory
databases:
"1":
urls:
- redis://<store-redis-host>:6379
auth:
method: agent_key
agent_keys:
introspection:
base_url: http://iris-identity-service:9200
allow_insecure_transport: true
product: memory
credential:
token_file: /etc/identity-service/runtime/memory-dp/token
worker_identity:
enabled: true
issuer: <service-account-issuer>
jwks_uri: https://kubernetes.default.svc/openid/v1/jwks
audience:
- redis-agent-memory
subjects:
- subject: "system:serviceaccount:<namespace-name>:redis-agent-memory-worker"
user_id: redis-agent-memory-worker
roles:
- operator
resources:
"mem-store:*":
permissions:
- write
embedding:
provider: openai
models:
default_embedding_model: text-embedding-3-large
dimensions: 3072
embedders_connection_details:
openai:
base_url: https://api.openai.com
credentials:
type: static
api_key: "<embedding-api-key>"
inference_providers:
openai:
endpoint:
base_url: https://api.openai.com/v1
timeout: 30s
auth_format: bearer
dataplane_client:
base_url: http://redis-agent-memory:9000
auth:
disabled: false
type: service_account_token
token_file: /var/run/secrets/redis-agent-memory-worker/token
promote_session_memory:
strategies:
instruct:
llm:
provider: openai
credentials:
type: static
api_key: "<promotion-llm-api-key>"
models:
default_chat_model: gpt-4o
The auth.worker_identity and dataplane_client.auth settings let workers call the Data Plane
under agent-key authentication. They need the platform setup in worker identity.
Create the Data Plane config Secret with the key memory-dataplane.config.yaml:
kubectl -n <namespace-name> create secret generic ram-config \
--from-file=memory-dataplane.config.yaml=./memory-dataplane.config.yaml
Control Plane configuration file
Create controlplane-onprem.config.yaml:
profile: prod
auth:
type: admin-token
admin_token:
token_file: /etc/controlplane-onprem/admin/token
internal_token:
token_file: /etc/controlplane-onprem/internal/token
admin_tenant_id: default
license:
license_path: /etc/redis-agent-memory/license
metadata:
urls:
- redis://<metadata-redis-host>:6379
namespace: iris:memory
databases:
"1":
urls:
- redis://<store-redis-host>:6379
embedding:
dimensions: 3072
The Control Plane only needs embedding.dimensions, to create each store's vector index. Configure
the embedding provider, model, and credentials in the Data Plane configuration.
Create the Control Plane config Secret:
kubectl -n <namespace-name> create secret generic ram-controlplane-config \
--from-file=controlplane-onprem.config.yaml=./controlplane-onprem.config.yaml
Helm values
In iris-values.yaml, replace memory.shared, memory.memory, and
memory.controlplane.configData with the two Secrets, and turn off rendering. The chart fails at
install time if both config.existingSecret and config.render are set.
memory:
config:
render: false
existingSecret: ram-config
controlplane:
config:
render: false
existingSecret: ram-controlplane-config
Optional Agent Playbooks extraction
Set global.iris.extraction.enabled: true. The suite configures Memory's Data Plane to trust the
Agent Playbooks extraction worker for reads, and its Control Plane to trust the Agent Playbooks
control plane as a viewer. A differing value under memory: fails the render. Both Memory planes
must reach the issuer's JWKS and trust its CA; see
worker identity.
For the Agent Playbooks side, see Extraction.
Configure document ingestion
Document ingestion is enabled in self-managed deployments. Configure the server and worker together through chart-rendered values. This example sets explicit processing limits:
memory:
memory:
document_ingestion:
enabled: true
max_decoded_bytes: 1048576
max_input_tokens: 8000
max_chunks: 32
max_output_records: 100
max_queued_bytes_per_store: 10485760
max_retries: 3
max_execution_seconds: 900
source_retention_seconds: 86400
checkpoint_retention_seconds: 86400
background_jobs:
redis:
enabled: true
jobs:
document-ingestion:
concurrency: 1
timeout: 15m
max_retry: 3
promote_session_memory:
strategies:
custom:
llm:
provider: openai
models:
default_chat_model: <chat-model-name>
credentials:
type: static
api_key: <model-api-key>
Use a model supported by your configured inference_providers.openai connection. Supply the credential through the existing overlay Secret. The custom extraction model is required even if built-in session extraction already has a model.
For a bring-your-own configuration, place these fields at the file root instead of under memory.memory. Keep the worker's queue retries and timeout consistent with the ingestion limits. All numeric ingestion limits must be positive. Byte, estimated token, and chunk limits apply together.
Roll out both the server and worker. Confirm store health, then create an extractor and submit a document. Setting enabled: false rejects new ingestions; it does not undo memories already written.
Configure Summary Views
Summary Views are enabled in self-managed deployments. Configure the server and worker with the same ownership setting, model provider, and explicit bounds. For chart-rendered configuration, merge these example values under memory.memory:
memory:
memory:
summary_views:
enabled: true
llm:
provider: openai
models:
default_chat_model: <chat-model-name>
credentials:
type: static
api_key: <model-api-key>
page_size: 10
max_definitions: 100
max_partitions: 100
max_concurrent_refreshes: 2
max_concurrent_refreshes_per_store: 1
max_input_tokens: 8000
max_source_records: 100
max_source_tokens: 100000
default_debounce: 1s
min_debounce: 1s
max_debounce: 1m
default_reconcile_interval: 1h
min_reconcile_interval: 1s
max_reconcile_interval: 24h
schedule_repair_interval: 1m
cleanup_batch_size: 100
cleanup_timeout: 5s
generation:
max_output_tokens: 2000
timeout: 30s
Use the deployment's configured model-provider connection and supply its credential through the overlay Secret. The selected provider must support the required text or structured generation; the OpenAI connection uses chat_completions for structured output. These numbers are examples. Required bounds have no defaults when Summary Views are enabled; set them explicitly and validate them under your expected load.
| Bounds | How to choose them |
|---|---|
max_input_tokens, generation.max_output_tokens |
Leave room for the prompt and output within the selected model’s context limit. |
max_source_records, max_source_tokens, max_partitions, max_definitions |
Bound the amount of data each store can summarize and retain. Test representative source sizes and grouping values. |
max_concurrent_refreshes, max_concurrent_refreshes_per_store |
Budget model-provider requests and Redis load. Both caps apply per worker replica; multiply by the replica count when sizing capacity. |
| Debounce and reconciliation intervals | Balance result freshness against repeated generation cost. |
generation.timeout, cleanup_timeout |
Allow measured generation and cleanup time while bounding stalled work. |
page_size, cleanup_batch_size, schedule_repair_interval |
Test scan and cleanup throughput against Redis capacity. |
With a bring-your-own file, place summary_views at the file root. Keep the Redis job backend, authenticated worker callbacks, and scheduling worker enabled. Roll out server and worker together, then create and refresh a view. A private view needs an authenticated user; an ordinary agent key alone does not supply one.
Each view retains its source-access policy. Replace existing definitions when changing ownership enforcement rather than expecting a flag change to rewrite them.
Enable ingestion webhooks
Start with the self-managed deployment. These are process settings; a client cannot enable them through a request header.
An operator must configure both Data Plane servers and workers:
- Enable
memory.memory.webhooks.enabledin chart-rendered configuration, orwebhooks.enabledat the root of a bring-your-own file. - Enable the Redis job backend and authenticated worker callbacks.
- Configure the same signing-secret backend and prefix in the Control Plane, Data Plane, and worker. Supported backends are Vault and AWS Secrets Manager. The Control Plane writes keys; Data Plane processes read them.
- Serve the receiver over HTTPS with a certificate trusted by the Data Plane.
- For a private receiver address, allow its range in
memory.memory.webhooks.private_cidrson both servers and workers.
For example, allow one private receiver address in Helm values:
memory:
memory:
webhooks:
enabled: true
private_cidrs:
- <receiver-private-ip>/32
Delivery checks all resolved addresses at connection time. Redirects and environment HTTP proxies are not used. An allowlist cannot permit loopback, link-local, metadata-service, multicast, or other protected addresses. A localhost URL is not a production callback endpoint.
For Vault, use matching application configuration in the Data Plane and Control Plane:
secrets:
provider: vault
vault:
address: https://<vault-host>:8200
mount: secret
base_path: agent-memory
In chart-rendered values, put this under memory.memory and memory.controlplane.configData, respectively. Supply vault.token through a mounted configuration Secret. The Control Plane needs permission to write and delete signing-key versions; servers and workers need read permission. Keep real Vault tokens and callback keys out of source control.
Before enabling output hooks on an existing deployment, upgrade workers first, then servers, and drain jobs queued by the older release. Keep hooks disabled until both sides support them. Setting the deployment flag to false stops delivery and fails selected work closed; it does not approve pending operations.
For Active-Active backing databases, route every server and worker for a store through the same authoritative writer connection. Do not mix member addresses or use region-dependent aliases for that connection. Before changing writers, drain old writers, wait for replication, and restart the processes to clear old connections. A store with hook history fails closed if its persisted writer connection is missing or invalid; regional queue ownership does not make independent writers safe.
Then configure a store policy and deploy a callback receiver.
Configure namespace routing
Namespace routing is enabled in self-managed deployments. Keep these switches consistent on the server and worker. For chart-rendered configuration, use:
memory:
memory:
namespace_features:
api: true
routing:
policy_api: true
automatic: true
admission: true
strategies: [matcher_spec]
For a bring-your-own file, put namespace_features at the file root. This example enables the matcher_spec strategy used by the regex policy in the routing guide.
After rollout, use the read-policy request in Configure a policy. A successful response confirms that the policy API is available. Read the returned policy.enabled value; saving a policy with enabled: true enables it for that store. API availability alone does not prove that automatic routing or admission is enabled, so check the process settings as well.