{
  "id": "prerequisites",
  "title": "Self-managed Agent Memory prerequisites",
  "url": "https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/self-managed/prerequisites/",
  "summary": "Review software, Redis, network, Secret, image, and sizing prerequisites for self-managed Redis Agent Memory.",
  "tags": [
    "docs",
    "develop",
    "ai"
  ],
  "last_updated": "2026-07-28T14:23:48-07:00",
  "page_type": "content",
  "content_hash": "98c7dda8483626bf583f429616d8e6bb945bb8991c17aba78444ab9fd4ceed0c",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "Redis Agent Memory is distributed as container images on Docker Hub plus a Helm\nchart in the Redis AI Helm repository. The chart deploys the Agent Memory Data\nPlane, Agent Memory workers, and optionally the Agent Memory Control Plane.\n\nYou provide the Redis databases, provider credentials, Kubernetes exposure, and\nlicense material used by the deployment.\n\n\nThis guide is for system administrators deploying Agent Memory on a self-managed\nKubernetes cluster."
    },
    {
      "id": "what-you-need",
      "title": "What you need",
      "role": "content",
      "text": "| Item | Where it comes from |\n| ---- | ------------------- |\n| Container images | Docker Hub: `redislabs/agent-memory` and, when the Control Plane is enabled, `redislabs/agent-memory-control-plane` |\n| Helm chart | `redis-agent-memory` chart in the Redis AI Helm repository, or a chart package provided by Redis |\n| Redis databases | You provide Store Redis, Job Redis, and Metadata Redis as needed by the deployment mode |\n| License key | Contact your Redis representative or [contact sales](https://redis.io/contact/). |\n| Provider credentials | You provide embedding provider credentials and, when worker features are enabled, promotion or summarization LLM credentials |"
    },
    {
      "id": "required-software",
      "title": "Required software",
      "role": "content",
      "text": "| Software | Minimum version | Purpose |\n| -------- | --------------- | ------- |\n| Kubernetes | 1.19+ | Orchestration |\n| kubectl | 1.19+ | Kubernetes CLI |\n| Helm | 3.x | Package manager |"
    },
    {
      "id": "redis-databases",
      "title": "Redis databases",
      "role": "content",
      "text": "The Helm chart does not deploy Redis databases. Provision the Redis databases\noutside the Agent Memory chart and pass their URLs in\n`memory-dataplane.config.yaml` and, when the Control Plane is enabled,\n`controlplane-onprem.config.yaml`.\n\nStore Redis must support Search and JSON capabilities because Agent Memory\ncreates JSON and vector search indexes for memory data. Job Redis and Metadata\nRedis do not need those capabilities when they are deployed as separate Redis\ndatabases."
    },
    {
      "id": "static-stores",
      "title": "Static stores",
      "role": "content",
      "text": "Use static stores for a first install or a private single-store deployment.\nStores are declared directly in `memory-dataplane.config.yaml`. The Control\nPlane and Metadata Redis are not used.\n\n| Redis database | Required when | Configure in `memory-dataplane.config.yaml` | Purpose |\n| --- | --- | --- | --- |\n| Store Redis | Always | `metadata.stores.<store-id>.urls` | Session memory JSON, long-term memory hashes, RediSearch indexes, vectors, and TTL-managed data. |\n| Job Redis | Worker/background jobs enabled | `background_jobs.redis.urls` | Background work, retry state, delayed jobs, and idempotency markers. |"
    },
    {
      "id": "control-plane-managed-stores",
      "title": "Control Plane managed stores",
      "role": "content",
      "text": "Use Control Plane managed stores when operators need to create stores or agent\nkeys at runtime. The Data Plane and Control Plane must point to the same\nMetadata Redis namespace and Store Redis.\n\n| Redis database | Required when | Configure in `memory-dataplane.config.yaml` | Configure in `controlplane-onprem.config.yaml` | Purpose |\n| --- | --- | --- | --- | --- |\n| Store Redis | Always | `metadata.live.store_db.urls` | `store_db.urls` | Memory data for Control Plane managed stores. |\n| Metadata Redis | Always | `metadata.live.urls` and `metadata.live.namespace` | `metadata.urls` and `metadata.namespace` | Store records, agent-key records, and grant metadata. |\n| Job Redis | Worker/background jobs enabled | `background_jobs.redis.urls` | Not used by Control Plane | Background work, retry state, delayed jobs, and idempotency markers. |\n\nDo not combine static `metadata.stores` with Control Plane managed store\nmetadata for the same Data Plane. Static stores do not use Metadata Redis.\nControl Plane managed stores require Metadata Redis and are required for\nagent-key authentication.\n\nFor a lab deployment, the Redis roles required by your chosen mode can point to\nthe same Redis endpoint if it has the required modules and capacity. For\nproduction, separate Store Redis, Job Redis, and Metadata Redis when possible so\nmemory data, background work, and control metadata can be scaled, backed up, and\noperated independently.\n\nFor Job Redis, use a non-evicting policy such as `noeviction` or\n`volatile-ttl`."
    },
    {
      "id": "metadata-redis-durability",
      "title": "Metadata Redis durability",
      "role": "content",
      "text": "Metadata Redis is small compared with Store Redis, but it is operationally\ncritical. Use persistent storage, Redis authentication, network isolation, and\nTLS where required.\n\nIn FIPS-oriented deployments, Redis URLs covered by the posture must use\n`rediss://`. Avoid eviction of metadata keys; losing metadata removes Control\nPlane store records and agent-key records."
    },
    {
      "id": "network-access",
      "title": "Network access",
      "role": "content",
      "text": "- **Connected install:** the cluster must be able to pull images from\n  `docker.io` and reach the Redis AI Helm repository.\n- **Air-gapped install:** mirror the images into an internal registry and use a\n  chart package or locally downloaded chart.\n- **Runtime access:** Agent Memory pods must reach the Redis databases and any\n  embedding or LLM provider endpoints used by the deployment.\n- **Data Plane exposure:** use NetworkPolicy, ingress, gateway, service mesh,\n  private load balancer, or equivalent controls to restrict API access."
    },
    {
      "id": "credentials-and-secrets",
      "title": "Credentials and Secrets",
      "role": "content",
      "text": "The chart consumes configuration and license material from Kubernetes Secrets:\n\n| Secret | Required when | Default key |\n| --- | --- | --- |\n| Agent Memory license Secret | Always | `license` |\n| Agent Memory Data Plane config Secret | Always | `memory-dataplane.config.yaml` |\n| Control Plane config Secret | Control Plane enabled | `controlplane-onprem.config.yaml` |\n| Control Plane admin-token Secret | Control Plane enabled | `token` |\n\nThe config file is mounted as a Secret because it commonly contains provider API\nkeys and Redis URLs may include credentials."
    },
    {
      "id": "release-artifacts-and-image-tags",
      "title": "Release artifacts and image tags",
      "role": "content",
      "text": "Agent Memory self-managed image tags use the release SemVer value, for example:\n\n[code example]\n\nUse the image tag listed for the release on Docker Hub or provided by Redis.\n\nUse the chart version supplied by Redis for the release. The published chart is\n`redis-ai/redis-agent-memory` from `https://helm.redis.io/ai`.\n\nStandard customer installs use the public Docker Hub images published by the\nAgent Memory self-managed release: `docker.io/redislabs/agent-memory:<ram-version>`\nand, when the Control Plane is enabled,\n`docker.io/redislabs/agent-memory-control-plane:<ram-version>`."
    },
    {
      "id": "air-gapped-and-private-registry-installs",
      "title": "Air-gapped and private registry installs",
      "role": "content",
      "text": "Mirror the published images into your internal registry:\n\n[code example]\n\nIf the registry requires authentication, create an image pull Secret:\n\n[code example]\n\nAdd the registry settings to `ram-values.yaml`:\n\n[code example]\n\nOmit `imagePullSecrets` if the internal registry does not require\nauthentication.\n\nFor air-gapped deployments, also set:\n\n[code example]"
    },
    {
      "id": "system-requirements",
      "title": "System requirements",
      "role": "content",
      "text": "Default chart values:\n\n| Component | Default | Purpose |\n| --------- | ------- | ------- |\n| Agent Memory server | 2 replicas with autoscaling enabled and a minimum of 2 | Data Plane API traffic |\n| Agent Memory worker | 2 replicas with autoscaling enabled and a minimum of 2 | Background promotion, summarization, and forgetting jobs |\n| Agent Memory Control Plane | 1 replica when `controlplane.enabled=true` | Admin API for stores and agent keys |\n\nDuring a rolling update, Kubernetes may temporarily run old and new pods at the\nsame time. A small two-node test cluster can run out of CPU during install or\nupgrade.\n\nFor realistic validation, use at least three nodes or enough CPU headroom for\nthe maximum rolling-update overlap.\n\nFor a constrained lab cluster, reduce replicas and autoscaling explicitly:\n\n[code example]\n\nDo not use reduced replica counts as the production HA recommendation."
    },
    {
      "id": "helm-values-to-review",
      "title": "Helm values to review",
      "role": "content",
      "text": "The walkthroughs use `redis-agent-memory` as the Helm release name. The\ngenerated service and deployment names in the verification steps assume that\nrelease name.\n\n| Area | Values | Use when |\n| --- | --- | --- |\n| Image | `image.repository`, `image.tag`, `imagePullSecrets` | Selecting a release, private registry, or mirrored image. |\n| Air-gapped installs | `airgap.enabled` | Validating a disconnected or private-registry install. |\n| API server capacity | `server.resources`, `server.autoscaling.*` | Tuning request capacity or memory footprint. |\n| Worker capacity | `worker.resources`, `worker.autoscaling.*` | Tuning background job throughput. |\n| Scheduling | `server.nodeSelector`, `worker.nodeSelector`, `server.affinity`, `worker.affinity`, `server.tolerations`, `worker.tolerations` | Controlling pod placement. |\n| Networking | `service.type`, `ingress.*` | Exposing Agent Memory outside the cluster. |\n| Naming | `fullnameOverride` | Running more than one Agent Memory release in a namespace. |\n| Service account | `serviceAccount.*` | Matching customer namespace security policy. |\n| Worker authentication | `workerAuth.enabled`, `worker.serviceAccount.*`, `worker.serviceAccount.token.*` | Giving Agent Memory workers a Kubernetes projected service-account token for authenticated Data Plane callbacks. |\n| Secret rollouts | `license.existingSecretChecksum`, `config.existingSecretChecksum`, `controlplane.config.existingSecretChecksum` | Rolling pods after externally managed Secret changes. |\n| Control Plane | `controlplane.enabled`, `controlplane.image.*`, `controlplane.config.existingSecret`, `controlplane.adminToken.*` | Enabling the optional admin API for stores and agent keys. |\n\nDo not use floating image tags in production."
    }
  ],
  "examples": [
    {
      "id": "release-artifacts-and-image-tags-ex0",
      "language": "yaml",
      "code": "image:\n  repository: redislabs/agent-memory\n  tag: \"<ram-version>\"",
      "section_id": "release-artifacts-and-image-tags"
    },
    {
      "id": "air-gapped-and-private-registry-installs-ex0",
      "language": "bash",
      "code": "docker pull redislabs/agent-memory:<ram-version>\ndocker tag redislabs/agent-memory:<ram-version> \\\n  registry.example.com/redislabs/agent-memory:<ram-version>\ndocker push registry.example.com/redislabs/agent-memory:<ram-version>\n\ndocker pull redislabs/agent-memory-control-plane:<ram-version>\ndocker tag redislabs/agent-memory-control-plane:<ram-version> \\\n  registry.example.com/redislabs/agent-memory-control-plane:<ram-version>\ndocker push registry.example.com/redislabs/agent-memory-control-plane:<ram-version>",
      "section_id": "air-gapped-and-private-registry-installs"
    },
    {
      "id": "air-gapped-and-private-registry-installs-ex1",
      "language": "bash",
      "code": "kubectl -n <namespace-name> create secret docker-registry ram-registry \\\n  --docker-server=registry.example.com \\\n  --docker-username=<username> \\\n  --docker-password=<password>",
      "section_id": "air-gapped-and-private-registry-installs"
    },
    {
      "id": "air-gapped-and-private-registry-installs-ex2",
      "language": "yaml",
      "code": "image:\n  repository: registry.example.com/redislabs/agent-memory\n  tag: \"<ram-version>\"\n\ncontrolplane:\n  image:\n    repository: registry.example.com/redislabs/agent-memory-control-plane\n    tag: \"<ram-version>\"\n\nimagePullSecrets:\n  - name: ram-registry",
      "section_id": "air-gapped-and-private-registry-installs"
    },
    {
      "id": "air-gapped-and-private-registry-installs-ex3",
      "language": "yaml",
      "code": "airgap:\n  enabled: true",
      "section_id": "air-gapped-and-private-registry-installs"
    },
    {
      "id": "system-requirements-ex0",
      "language": "yaml",
      "code": "server:\n  replicaCount: 1\n  autoscaling:\n    enabled: false\n\nworker:\n  replicaCount: 1\n  autoscaling:\n    enabled: false",
      "section_id": "system-requirements"
    }
  ]
}