AutoGineer
Generated banner for Amazon Elasticache
Generated logo for Amazon Elasticache

Amazon Elasticache

AWSOfficialPublished by AWS

  • Skill
  • Tool integration
  • Cloud and DevOps
  • Apache-2.0
  • Medium risk
  • Has scripts
Download ZIP

From the author

Activate when developers have latent caching needs: slow API responses, database read bottlenecks, DynamoDB throttling or cost, RDS/Aurora scaling pressure, Bedrock latency or cost, or adding a cache; activate when working with Redis, Valkey, Memcached, or any in-memory data store, cache-aside patterns, session stores, rate limiting, leaderboards, counters, streams, queues, pub/sub, distributed locks, feature flags, shopping carts, or other caching strategies. Activate for GenAI and ML retrieval: vector similarity search for low-latency retrieval, semantic caching, RAG, LLM response caching, embedding stores, AI agent memory, recommendation, personalization. Activate for ElastiCache lifecycle: provisioning (serverless or node-based), engine selection, CloudFormation/CDK/Terraform IaC, VPC connectivity, TLS, RBAC, IAM auth, Global Datastore, monitoring, troubleshooting, cost optimization, and migration from self-managed Redis. Do not trigger for browser caches, CDN/CloudFront, HTTP Cache-Control, CPU caches.
— the description by AWS

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The Amazon ElastiCache skill provides a structured, modular approach to managing in-memory data stores on AWS. It guides developers through the entire lifecycle of ElastiCache and Valkey, from initial requirements gathering and provisioning to complex data modeling, AI-driven vector search, and operational monitoring. The skill enforces best practices for connection safety, security, and infrastructure-as-code, ensuring reliable performance for caching, session management, and GenAI workloads.

What it does

  • Assesses workload requirements to recommend optimal ElastiCache configurations.
  • Automates provisioning and connectivity setup for serverless and node-based clusters.
  • Provides implementation patterns for common use cases like cache-aside, session stores, and rate limiting.
  • Supports advanced AI workloads including semantic caching, RAG, and vector similarity search.
  • Delivers operational diagnostics for performance tuning, cost optimization, and troubleshooting.
  • Manages migration paths from self-managed Redis or between different deployment models.

When to use it

  • When you need to reduce database load or improve API response times with an in-memory cache.
  • When implementing AI agent memory, RAG retrieval, or semantic caching for LLM applications.
  • When migrating existing Redis workloads to a managed AWS environment.
  • When troubleshooting performance issues like high latency, replication lag, or memory pressure.
  • When setting up secure, production-ready caching infrastructure using IaC.

Advantages

  • Standardizes deployment and operational patterns across development teams.
  • Ensures compliance with security best practices like TLS and IAM authentication.
  • Reduces configuration errors through automated input validation and tagging.
  • Provides clear guidance on engine selection and version-specific feature availability.
  • Simplifies complex tasks like cross-region migration and vector search setup.

Usage examples

“I need to speed up my RDS database. Should I use ElastiCache?”
The agent will initiate the requirements sub-skill to analyze your workload, stack, and latency needs, then provide a recommendation on whether ElastiCache is the right fit.
“How do I set up a Valkey cluster for vector search?”
The agent will route to the genai sub-skill, verify you are using a node-based Valkey 8.2+ cluster, and provide the necessary configuration and code to enable vector similarity search.
“My cache hit rate is low and latency is spiking. Can you help me troubleshoot?”
The agent will activate the monitoring sub-skill to analyze your metrics, identify potential hot keys or memory imbalance, and suggest specific remediation steps.
“Help me migrate my self-managed Redis to ElastiCache.”
The agent will guide you through the migration sub-skill, performing preflight checks and validating your source configuration for a zero-downtime cutover.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/aws/amazon-elasticache/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip amazon-elasticache.zip -d .agents/skills

Documentation by AWS

ElastiCache

A modular ElastiCache toolkit organized as a registry of sub-skills. Each sub-skill handles one domain of ElastiCache work. The router below matches user intent to the right sub-skill, then loads only the references needed for that sub-skill.

How this skill works

  1. Match the user's request against the semantic categories in the registry below. Match on meaning, not exact wording ("help me figure out which data structures to use" matches data-modeling even without the word "pattern").

  2. Disambiguation: If the user's intent matches multiple sub-skills, apply these rules in order:

    • If .elasticache/requirements.json exists with infrastructure.endpoint set, prefer monitoring or data-modeling (the user has an existing cache).

    • If no cache exists (no requirements.json or no endpoint), prefer requirements.

    • If still ambiguous, ask one clarifying question: "Are you looking to set up something new, or troubleshoot something existing?"

  3. Check the Guardrails section before recommending an engine or deployment model.

  4. Read references/{sub-skill-id}/instructions.md for the matched sub-skill. If the file is not found at a relative path, check your prompt or environment for the skill directory absolute path and retry with {skill-directory}/references/{sub-skill-id}/instructions.md.

  5. If the request spans multiple sub-skills, execute them in pipeline order.

  6. If a sub-skill requires upstream context (engine, deployment model, endpoint) not yet in session memory, route to the upstream sub-skill first.

  7. If no sub-skill matches, activate requirements first.

  8. If a script or CLI call fails, show the error to the user and suggest a specific fix before retrying.

Sub-skill registry

Each entry has: an ID (directory name under references/), a domain description, semantic categories for matching, and upstream/downstream dependencies.

IDNameDomainSemantic CategoriesUpstreamDownstream
requirementsSolution FitGathers workload, stack, scale, latency, persistence, and budget through workspace scan + structured interview. Decides whether ElastiCache is the right service and hands off with a routing recommendation.I need a cache, speed up my app, reduce database load, lower Bedrock cost, should I use ElastiCache, what's best for my workload, evaluating cache options, ElastiCache vs X, Valkey vs X, vague new workload—setup, data-modeling, genai, monitoring, migration
setupCreate and ConnectProvisioning, connectivity, security, authentication, IaC, deployment choice. Gets the user to a working cache with least friction. Covers engine selection, serverless vs node-based, VPC, TLS, RBAC/IAM, jump-host/SSM tunnels, CLI/SDK/CFN/CDK/Terraform starters.create a cache, set up ElastiCache, provision, Valkey cluster, connect Lambda/ECS/EKS/EC2, VPC, security groups, TLS, RBAC, IAM auth, jump host, SSM tunnel, CloudFormation, CDK, Terraform, engine selection, serverless vs node-based, backup, snapshot, restore, exportrequirements (optional)data-modeling, genai, monitoring
data-modelingApplication PatternsPicks data structures, key schema, TTL strategy, invalidation approach, and client code for non-AI patterns: cache-aside, session store, rate limiting, leaderboards, counters, pub/sub, streams, shopping carts, job queues, activity feeds.session store, rate limiting, leaderboard, cache-aside, query caching, counters, streams, pub/sub, shopping cart, job queue, activity feed, key schema, TTL, invalidation, data structuressetup (cache must exist)monitoring
genaiAI and Vector WorkloadsClassifies request into Mode 1 (plain cache), Mode 2 (semantic response cache), or Mode 3 (full vector search). Selects Valkey and forces node-based Valkey 8.2 or above (recommend 9.0) when server-side vector similarity is needed. Covers semantic caching, agent memory, RAG retrieval, recommendation, personalization, conversation/session persistence for AI agents, and framework wiring (Strands, mem0, LangChain).semantic cache, RAG, agent memory, conversational memory, vector search, embeddings, recommendation, personalization, Bedrock latency, Bedrock cost, LLM caching, Strands, mem0, LangChain, conversation history, AI session store, embedding provider, framework integrationsetup (cache must exist)monitoring
monitoringOperate and ObserveDiagnoses performance, cost, and reliability using metrics first, then recommends the smallest change. Covers dashboards, alarms, log delivery, cost reporting, event routing, troubleshooting high CPU / memory / replication lag / connection spikes / low hit rate / hot keys / big keys / slot imbalance / latency spike root cause.cache is slow, cost too high, hit rate low, high CPU, memory pressure, replication lag, connection spikes, dashboards, alarms, CloudWatch, cost comparison, troubleshoot, hot key, uneven shard load, one node pinned, big key, memory bloat, which key is biggest, keyspace distribution, prefix analysis, cost attribution by tenant, memory imbalance, one shard full, slot memory skew, latency spike, slow command incident, root cause for latency bump—setup, migration
migrationEngine and Platform MigrationSelects the migration path and sequences preflight, validation, cutover, and rollback. Covers self-managed Redis → ElastiCache, Redis OSS → Valkey, node-based ↔ serverless, version upgrades. Hard validate-before-migrate gate.migrate, Redis OSS to Valkey, self-managed to ElastiCache, node-based to serverless, serverless to node-based, engine upgrade, version upgrade, zero-downtime cutover, rollback—setup, monitoring

Pipeline order

Sub-skills run independently, but common multi-step journeys follow these pipelines:

  • requirements → setup → (data-modeling | genai) → monitoring

  • migration → setup → monitoring

  • monitoring → setup | migration (if metrics indicate)

State handoff: requirements.json

.elasticache/requirements.json is the single source of truth for cross-sub-skill state. Each sub-skill reads it at start and writes its section after completing work. Read before writing; merge, do not overwrite.

SectionOwnerKey fields
top-levelrequirementsengine, deployment_model, region, runtime, patterns, use_case, vpc_id, subnet_ids, security_group_ids
infrastructuresetupcache_name, resource_id, engine_version, topology, endpoint, port, auth_model, tls, client_library, execution_path, access_mode, tunnel_instance_id, embedding_provider, embedding_model, embedding_dim, embedding_module
genaigenaimode, mode_2_path, framework
migrationmigrationsource_type, source_host, migration_path, cutover_status

Ownership note: deployment_model is set by requirements during initial interview. migration may update it after an engine or deployment model switch (e.g., node-based to serverless).

requirements.json should include "schema_version": 1 and "last_updated": "<ISO timestamp>" at the top level. Every sub-skill that writes to requirements.json must update last_updated. If last_updated is older than 7 days, warn the user that cached state may be stale.

requirements.json tracks one active cache. If the user works with multiple caches in the same project, confirm which cache is active before reading or writing state.

When a sub-skill needs upstream context (engine, endpoint, auth model), check requirements.json first. If the field is null or the file does not exist, route to the upstream sub-skill.

Global rules (apply to every sub-skill)

  1. Execution path. Use AWS CLI, SDK (boto3), CloudFormation, or CDK as the primary path for control-plane work. Use valkey-py as the primary path for data-plane work.

  2. Response depth. Summary (2-3 sentences) for "should I" or "which" questions. Standard (recommendation + config + code + next steps) by default. Expert (full decision matrix with alternatives, cost, security caveats) for "why" or "compare all" questions. Escalate on user request; never downgrade unprompted.

  3. Session memory. Track region, VPC, engine, deployment model, auth model, compute runtime, and language. Carry forward across sub-skills. Do not re-ask. If the user overrides a value, update it everywhere. Inferred values (from workspace scan or IaC) must be re-confirmed before high-risk decisions (engine, deployment model, security posture); low-risk inferences (language, framework, region) can be used as defaults silently.

  4. Source priority. Always answer from skill-local files first (sub-skill references, then scripts/). Do not fetch external documentation or web search unless the local files cannot answer the query. When local files are insufficient, fall back to official AWS docs: https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/ for features and https://aws.amazon.com/elasticache/pricing/ for pricing. Never invent price points or version constraints. If the user references a Valkey or Redis version, feature, or pricing tier not covered in local files, fall back to https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/ before answering. Do not extrapolate from local content that may be outdated.

  5. Freshness disclaimer. When outputting pricing, version constraints, or feature availability, include a one-line disclaimer: "For current pricing see https://aws.amazon.com/elasticache/pricing/. For current feature availability see https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/."

  6. Connection safety. Never create a Valkey/Redis client at module level (top of file, import time). Initialize connections inside a function or on first use. Module-level connections crash applications that import the module before the cache is reachable.

  7. Code environment. Use python3 (not python) in all commands and shebangs. Do not generate pip install or pytest commands in application code. Prefer the agent's file-writing tool over shell redirection for writing files.

  8. Input validation (write operations only). Before running any create, modify, or delete CLI command or SDK call that uses user-provided values (cache name, region, subnet IDs, security group IDs, VPC ID, KMS key, snapshot name), validate them with scripts/input_validator.py. Run python3 scripts/input_validator.py cache_name=<val> region=<val> ... or import validate_all as a library. Skip validation for read-only operations (describe, list) where bad input is harmless.

  9. Resource tagging (always apply on resource creation). When creating any cache (create-serverless-cache, create-replication-group, create-cache-cluster), ALWAYS include these tags:

    --tags Key=managed_by,Value=aws-skills Key=skill,Value=elasticache Key=skill_version,Value=1.0.0 Key=created_by,Value=elasticache-skill Key=generation_model,Value={your-model-id}

    Example: --tags Key=managed_by,Value=aws-skills Key=skill,Value=elasticache Key=skill_version,Value=1.0.0 Key=created_by,Value=elasticache-skill Key=generation_model,Value=claude-sonnet-4-20250514

    Set generation_model to your own model identifier. Include these tags even if the user does not mention tagging. If the user provides additional tags, append these to their tags rather than replacing them.

Reference loading

Load additional references only when the current turn's answer requires them.

On-demand pointers (not preloaded; fetch when the trigger applies):

  • references/shared-ux/production-readiness.md — when the user asks if their cache is ready for production, or after setup completes and the user wants to go to production

  • references/shared-ux/action-safety.md — before any destructive action (risk levels, never-auto-execute list)

  • references/shared-ux/error-remediation.md — when the user hits a specific ElastiCache error code (MOVED, CROSSSLOT, CLUSTERDOWN, MULTI/EXEC+IAM, etc.)

  • references/shared-foundation/boundary-doc.md — when the user asks what this skill covers

  • references/shared-foundation/attribution.md — when generating CLI commands, SDK code, or IaC templates

  • references/shared-foundation/architecture-diagrams.md — when the user asks for architecture diagrams or visual reference

  • references/shared-runtime/lambda.md — when connecting from Lambda (cold start gotchas, IAM auth code, lazy init)

  • references/shared-runtime/ecs.md — when connecting from ECS (SIGTERM shutdown, connection pool drain, task definition)

  • references/shared-runtime/eks.md — when connecting from EKS (IRSA, service mesh bypass, SecurityGroupPolicy CRD)

  • references/shared-runtime/api-gateway.md — when integrating with API Gateway (no direct path, caching layers comparison)

  • references/shared-runtime/rds-acceleration.md — when caching RDS/Aurora queries (thundering herd, stampede protection, invalidation)

  • references/shared-runtime/secret-injection.md — when the user asks about credential management per compute platform

  • references/shared-security/encryption-defaults.md — when adding encryption to an existing unencrypted cluster (TLS two-step migration, at-rest immutability)

  • references/shared-security/config-guardrails.md — when the user wants continuous compliance monitoring (AWS Config rules, custom Lambda rules)

  • references/shared-security/vpc-patterns.md — when debugging port/security-group issues (port 6380 serverless reader, anti-patterns)

Folder convention: references/ contains 10 folders. 6 match the sub-skills (requirements, setup, data-modeling, genai, monitoring, migration) and are routing destinations. The 4 shared-* folders (shared-foundation, shared-ux, shared-security, shared-runtime) are cross-cutting material loaded on demand, not routing destinations.

Guardrails

PriorityRule
CRITICALVector search MUST use node-based Valkey 8.2 or above. Serverless does NOT support vector search. Never suggest serverless for vector search. Apply this regardless of which sub-skill activates.
CRITICALDo not invent price points or version constraints. Use scripts/price_calculator.py and current AWS docs when precision matters.
HIGHDo not recommend Memcached when the user needs persistence, replication, RBAC or IAM auth, sorted sets, streams, pub/sub, or vector search.
HIGHDo not assume local laptop access works directly. ElastiCache is VPC-centric; explain VPC, tunnel, or jump-host access when needed.
STANDARDDo not trigger on every generic Redis mention. Trigger when the user is clearly asking about AWS, managed caching, migration, connectivity, pricing, operations, or AWS service integration.
STANDARDFor ambiguous "cache" requests inside AWS contexts, activate this skill and start with requirements.

Product truths

  • ElastiCache Serverless deploys in under a minute and removes infrastructure management.

  • Valkey serverless pricing is 33% lower than other supported engines; node-based Valkey pricing is 20% lower.

  • Serverless caches have in-transit encryption always enabled (cannot be disabled).

  • IAM auth is available for all ElastiCache Valkey versions (7.2 is the baseline Valkey version on ElastiCache) and Redis OSS 7.0+.

  • Valkey version ladder: 7.2 (baseline), 8.0 (20% more data per node (capacity improvement), per-slot metrics), 8.1 (Bloom filters, COMMANDLOG, SET IFEQ, 20% less memory via new hash table (efficiency improvement)), 8.2 (vector search), 9.0 (recommended default for new clusters). Recommend Valkey 9.0 for new clusters unless a specific feature dictates otherwise.

  • Vector search is available for Valkey 8.2 or above on node-based clusters (recommend 9.0).

  • Global Datastore is available for node-based clusters only. It does not support IPv6 or Local Zones. Global Datastore supports AUTH and RBAC. Cross-region failover must be promoted manually (no autofailover across regions). At-rest encryption must be enabled on all clusters in the Global Datastore, but each cluster can use a separate KMS key per region.

  • Online migration from self-managed Redis to ElastiCache requires: (source) AUTH must not be enabled, protected-mode set to no, replication and administrative commands must not be renamed (e.g., sync, psync, info, config, command, cluster); (target) encryption in-transit disabled, Multi-AZ enabled, engine version Redis OSS 5.0.6+ or Valkey 7.2+, not part of a Global Datastore, data tiering disabled. Shard counts must match between source and target. All source Redis instances must use the same port. Online migration is not supported for serverless caches (node-based targets only). See references/migration/topology-validation.md for the full checklist.

Files

references/genai/elasticache-search.md

ElastiCache Vector Search Constraints

This file contains all ElastiCache-specific constraints for vector search. Loaded on-demand when any genai pattern needs vector search (Mode 2 server-side or Mode 3).

Platform Gate

RequirementDetail
EngineElastiCache engine version 8.2 or above for Valkey (node-based only). Note: server reports valkey_version as 8.1.x. ElastiCache engine version 8.2 (shown in AWS Console and API) maps to the underlying Valkey OSS version 8.1.x in INFO server output. Use FT._LIST to confirm vector search availability.
ServerlessNOT supported. Vector search is unavailable on serverless.
Data-tiering nodesNOT supported (r6gd family)

This is the single most common mistake. Serverless ElastiCache cannot run vector search.

Version Detection (MUST run before any FT.* command)

Before emitting any FT.CREATE, FT.SEARCH, or other FT.* command, detect the server version and confirm vector search support. Vanilla Valkey 8.0.x does NOT have FT.CREATE. Only Valkey 8.2 or above on node-based ElastiCache supports it.

from valkey.exceptions import ResponseError

def get_valkey_version(client) -> tuple[int, int]:
    """Return (major, minor) version of the connected Valkey/Redis server."""
    info = client.info("server")
    ver = info.get("valkey_version", info.get("redis_version", "0.0"))
    major, minor = int(ver.split(".")[0]), int(ver.split(".")[1])
    return major, minor

def supports_ft_search(client) -> bool:
    """True if the server supports FT.* vector search commands.

    Uses FT._LIST probing instead of version comparison because
    ElastiCache v8.2 reports valkey_version as 8.1.x, making
    version-based detection unreliable.
    """
    try:
        client.execute_command("FT._LIST")
        return True
    except ResponseError:
        return False

Usage pattern: Call supports_ft_search(client) once at startup. If it returns False, use the Python-side fallback below instead of FT.* commands. Never assume FT.CREATE is available without checking.

Note: Because ElastiCache v8.2 reports valkey_version as 8.1.x, the get_valkey_version helper above should NOT be used for vector search detection. The supports_ft_search function probes with FT._LIST which is reliable regardless of reported version.

Python-Side Vector Search Fallback

When the server does not support FT.* commands (Valkey < 8.2, serverless, or any environment without search), use application-side cosine similarity. This approach stores vectors as binary HASH fields and performs brute-force KNN in Python. Suitable for datasets under ~50K vectors.

import struct
import math

def python_cosine_similarity(a: list[float], b: list[float]) -> float:
    """Cosine similarity between two vectors using only stdlib."""
    dot = sum(x * y for x, y in zip(a, b))
    norm_a = math.sqrt(sum(x * x for x in a))
    norm_b = math.sqrt(sum(x * x for x in b))
    if norm_a == 0 or norm_b == 0:
        return 0.0
    return dot / (norm_a * norm_b)

def python_knn_search(client, prefix: str, query_vec: list[float],
                      vector_field: str = "embedding", k: int = 5,
                      filter_field: str = None, filter_value: str = None) -> list[dict]:
    """Brute-force KNN search using Python-side cosine similarity.

    Scans all keys matching prefix, decodes stored FLOAT32 vectors,
    computes cosine similarity, returns top-k results sorted by similarity.
    """
    cursor = 0
    results = []
    dim = len(query_vec)

    while True:
        cursor, keys = client.scan(cursor=cursor, match=f"{prefix}*", count=200)
        for key in keys:
            data = client.hgetall(key)
            if filter_field and filter_value:
                field_key = filter_field.encode() if isinstance(filter_field, str) else filter_field
                stored = data.get(field_key, b"").decode()
                if stored != filter_value:
                    continue
            vec_bytes = data.get(vector_field.encode() if isinstance(vector_field, str) else vector_field)
            if not vec_bytes or len(vec_bytes) != dim * 4:
                continue
            stored_vec = list(struct.unpack(f"{dim}f", vec_bytes))
            score = python_cosine_similarity(query_vec, stored_vec)
            key_str = key.decode() if isinstance(key, bytes) else key
            results.append({"key": key_str, "similarity": score, "data": data})

        if cursor == 0:
            break

    results.sort(key=lambda x: -x["similarity"])
    return results[:k]

Integration pattern: Use supports_ft_search to pick the right path at startup:

client = get_client()
if supports_ft_search(client):
    ensure_index(client)
    hits = search_similar(client, query_embedding, top_k=5)
else:
    hits = python_knn_search(client, PREFIX, query_embedding, k=5)

Command Boundary

CommandStatus on ElastiCache
FT.CREATEDocumented, supported
FT.SEARCHDocumented, supported
FT.INFODocumented, supported
FT._LISTDocumented, supported
FT.DROPINDEXDocumented, supported

⚠️ FT.AGGREGATE is NOT available on ElastiCache. FT.AGGREGATE is supported on Amazon MemoryDB but is not supported on ElastiCache. If you need server-side aggregation over vector search results, use MemoryDB or perform aggregation client-side after FT.SEARCH.

Hard Limits

LimitValue
Max indexes per cluster10
Max fields per index50
Max vector dimensions32768
HNSW M (max edges per node)2,000,000 (practical recommendation: 16–64 for most workloads; higher values increase memory usage and index build time)
HNSW EF_CONSTRUCTION4096
HNSW EF_RUNTIME4096
Max prefixes per index16
Tag field max length10,000
Numeric field max length256

Transaction restriction: FT.CREATE, FT.DROPINDEX, and alias commands CANNOT run inside MULTI/EXEC, Lua scripts, or functions.

Index Lifecycle / Backfill

FT.CREATE triggers a background backfill for all existing keys matching the PREFIX. Query operations attempted while an index is undergoing backfill are not allowed and are terminated with an error.

Backfill types: During initial index creation (FT.CREATE), queries against the index are blocked and return an error until backfill completes. However, during scaling events (e.g., adding shards), the index may undergo backfill with reduced recall for search queries — queries are allowed but may return incomplete results.

Check readiness with FT.INFO. Key fields to monitor:

FieldMeaning
backfill_in_progressWhether backfill is still running
backfill_percent_completeEstimate of backfill completion, a fractional number in the range [0..1]
mutation_queue_sizePending mutations waiting to be indexed
recent_mutations_queue_delayLag between writes and indexing
stateMust be ready before querying

Wait for state=ready before issuing FT.SEARCH.

Hash Slot Constraint (Cluster Mode)

All keys queried by a single FT.SEARCH must reside in the same hash slot. Use hash tags to guarantee slot co-location:

doc:{myprefix}:chunk_001
doc:{myprefix}:chunk_002

The {myprefix} portion determines the slot. Without hash tags on multi-shard clusters, FT.SEARCH only returns results from the shard it executes on.

Client Connection for Vector Operations

When using valkey-py or redis-py for vector operations, set decode_responses=False. Vector data is binary (FLOAT32 bytes) and must not be decoded as UTF-8.

import valkey

client = valkey.Valkey(
    host="endpoint", port=6379,
    ssl=True, ssl_cert_reqs="required",  # validate the server cert (production default)
    # ssl_ca_certs="/path/to/ca-bundle.pem",  # only if your OS lacks a system CA store
    # Dev/tunnel ONLY (e.g. SSH tunnel to localhost, where the cert name won't match):
    # ssl_cert_reqs="none",  # INSECURE: disables cert validation; never in production
    decode_responses=False,  # CRITICAL for vector operations
)

If you need decode_responses=True for non-vector operations (session store, counters), use a separate client instance.

Do NOT use the high-level valkey.commands.search or redis.commands.search Python wrappers for FT.* commands. Their parameter signatures vary across library versions and produce hard-to-debug failures. Use client.execute_command() for all FT.CREATE, FT.SEARCH, FT.INFO, and FT.DROPINDEX calls.

Do NOT create the Valkey/Redis client at module level (top of file, import time). Always initialize connections inside a function or on first use. Module-level connections crash applications that import the module before the cache is reachable.

Do NOT call FT.CREATE at module level or import time. Create indexes lazily in an explicit setup function, guarded by an "already exists" check.

Vector Binary Encoding

HASH vectors must be stored as binary little-endian IEEE 754 FLOAT32.

Python encoding:

import struct
binary = struct.pack(f"{len(vec)}f", *vec)

  • JSON vectors are stored as arrays (no binary encoding needed).

  • Query vectors passed via PARAMS are also FLOAT32 bytes.

Do NOT use numpy for vector byte packing. Use only struct.pack from the Python standard library. numpy may not be available in all deployment environments.

Distance to Similarity Conversion

FT.SEARCH returns cosine DISTANCE, not similarity.

ValueMeaning (distance)Meaning (similarity)
0Identical1.0
2Opposite0.0

Conversion: similarity = 1.0 - (distance / 2.0) # Normalized to [0,1]; standard cosine similarity = 1 - distance

Cosine distance ranges from 0 (identical) to 2 (opposite). This formula normalizes to [0, 1].

Many models and tutorials use similarity (0=opposite, 1=identical). Mixing these up inverts threshold logic.

FT.CREATE Schema Reference

FT.CREATE idx ON HASH PREFIX 1 prefix:
  SCHEMA
  embedding VECTOR HNSW 6 TYPE FLOAT32 DIM <VECTOR_DIM> DISTANCE_METRIC COSINE
  request_id TAG
  state_tags TAG SEPARATOR ,
  slot_budget_usd NUMERIC

Key details:

  • 6 after HNSW means 3 key-value pairs follow (TYPE, DIM, DISTANCE_METRIC). The number is the total count of arguments, not the number of pairs.

  • PREFIX 1 prefix: scopes which hashes get indexed. The 1 is the number of prefixes.

  • TAG SEPARATOR , is optional. The default separator is ,. Only specify SEPARATOR if you need a different delimiter character.

FT.SEARCH Query Reference

Hybrid query with pre-filters:

FT.SEARCH idx "(@tag:{value})=>[KNN 1 @embedding $vec AS score]"
  PARAMS 2 vec <binary_vector>
  RETURN 2 request_id score
  DIALECT 2

  • DIALECT 2 is required for KNN queries.

  • PARAMS 2 means 1 key-value pair follows (param name, param value). The number is the total count of arguments.

  • Pre-filter goes before =>. Only documents matching the filter enter the KNN stage.

Parsing FT.SEARCH results (valkey-py / redis-py with decode_responses=False):

# result = [total_count, key_name_bytes, [field_bytes, value_bytes, ...], ...]
total = int(result[0])
if total == 0:
    return None

key_name = result[1]  # bytes
fields = result[2]    # flat list: [b"field1", b"value1", b"field2", b"value2", ...]
doc = {}
for i in range(0, len(fields), 2):
    k = fields[i].decode() if isinstance(fields[i], bytes) else fields[i]
    v = fields[i+1].decode() if isinstance(fields[i+1], bytes) else fields[i+1]
    doc[k] = v

distance = float(doc["score"])
similarity = 1.0 - (distance / 2.0)  # Normalized to [0,1]; standard cosine similarity = 1 - distance

The result format is a flat list, not a dict. Field names and values alternate. With decode_responses=False, all values are bytes and must be decoded manually.

FLAT vs HNSW

Use FLAT for small datasets (<10K vectors). Exact brute-force search, no graph overhead, zero tuning. Switch to HNSW when dataset grows and query latency matters.

HNSW Tuning Defaults

ParameterDefaultEffect
M16 (max 2,000,000 per AWS limits; practical recommendation: 16-64 for most workloads)Graph connectivity; higher = better recall, more memory
EF_CONSTRUCTION200 (max 4096)Build-time search depth; higher = better index quality, slower writes
EF_RUNTIME10 (max 4096)Query-time search depth; higher = better recall, slower queries. Can be overridden per-query.

TAG Field Escaping

Hyphens in TAG values must be escaped in queries:

escaped = value.replace("-", "\\-")

Spaces should be replaced with underscores before storing.

Complete Vector Search Recipe

Self-contained working example. Copy and adapt. Uses only stdlib + valkey-py, lazy connection, execute_command for all FT.* calls.

import struct
import valkey

VECTOR_DIM = 384  # match your embedding model's output dimensions
INDEX_NAME = "idx:items"
PREFIX = "item:"

def get_client():
    """Lazy connection. Never call at module level."""
    return valkey.Valkey(
        host="your-endpoint", port=6379,
        ssl=True, ssl_cert_reqs="required",  # validate the server cert (production default)
        # ssl_ca_certs="/path/to/ca-bundle.pem",  # only if your OS lacks a system CA store
        # Dev/tunnel ONLY (e.g. SSH tunnel to localhost, where the cert name won't match):
        # ssl_cert_reqs="none",  # INSECURE: disables cert validation; never in production
        decode_responses=False,
    )

def ensure_index(client):
    """Create index if it doesn't exist. Call once at app startup, not at import time."""
    try:
        client.execute_command(
            "FT.CREATE", INDEX_NAME,
            "ON", "HASH",
            "PREFIX", "1", PREFIX,
            "SCHEMA",
            "embedding", "VECTOR", "HNSW", "6",
                "TYPE", "FLOAT32", "DIM", str(VECTOR_DIM), "DISTANCE_METRIC", "COSINE",
            "category", "TAG",
        )
    except Exception as e:
        if "already exists" not in str(e).lower():
            raise

def store_vector(client, item_id, embedding, category=""):
    """Store a vector. embedding is a list of floats."""
    key = f"{PREFIX}{item_id}"
    client.hset(key, mapping={
        "embedding": struct.pack(f"{VECTOR_DIM}f", *embedding),
        "category": category,
    })

def search_similar(client, query_embedding, top_k=5):
    """KNN search. Returns list of {key, similarity} dicts."""
    query_bytes = struct.pack(f"{VECTOR_DIM}f", *query_embedding)

    result = client.execute_command(
        "FT.SEARCH", INDEX_NAME,
        f"*=>[KNN {top_k} @embedding $vec AS score]",
        "PARAMS", "2", "vec", query_bytes,
        "RETURN", "1", "score",
        "LIMIT", "0", str(top_k),
        "DIALECT", "2",
    )

    if int(result[0]) == 0:
        return []

    hits = []
    for i in range(1, len(result), 2):
        key = result[i].decode() if isinstance(result[i], bytes) else result[i]
        fields = result[i + 1]
        field_dict = {}
        for j in range(0, len(fields), 2):
            k = fields[j].decode() if isinstance(fields[j], bytes) else fields[j]
            v = fields[j+1].decode() if isinstance(fields[j+1], bytes) else fields[j+1]
            field_dict[k] = v
        distance = float(field_dict["score"])
        similarity = 1.0 - (distance / 2.0)  # Normalized to [0,1]; standard cosine similarity = 1 - distance
        hits.append({"key": key, "similarity": similarity})

    return hits

Error Recovery

Common failures and how to fix them.

App crashes on import / startup: Move all valkey.Valkey() calls and FT.CREATE calls out of module scope. Wrap in a get_client() function called inside route handlers or on first use.

ImportError: No module named 'numpy': Replace numpy.array(...).tobytes() with struct.pack(f"{len(vec)}f", *vec). Never depend on numpy for vector byte packing.

FT.CREATE returns an error: Verify the command matches the exact syntax: FT.CREATE <name> ON HASH PREFIX 1 <prefix> SCHEMA <fields>. The most common mistakes: missing SCHEMA keyword, wrong argument count after HNSW (must be 6 for 3 key-value pairs: TYPE, DIM, DISTANCE_METRIC), or using INDEX instead of CREATE.

FT.SEARCH returns 0 results when data exists:

  1. Check index state: FT.INFO <index_name>, look for state: ready. If backfill is in progress, wait.

  2. Check DIALECT 2 is present in the query. KNN queries require it.

  3. Check the query vector is FLOAT32 bytes (struct.pack), not a string or list.

  4. Check the key prefix matches what FT.CREATE was given.

ResponseError mentioning valkey.commands.search: Do not use the high-level Python search wrapper. Replace with client.execute_command("FT.SEARCH", ...) as shown in the recipe above.

Score/similarity values seem inverted: COSINE distance is 0 (identical) to 2 (opposite). Convert with similarity = 1.0 - (distance / 2.0). If your thresholds aren't working, verify you're comparing similarity (not distance) against the threshold.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python, Needs Node.js

Security

What our scanner noticed· Medium risk

  • References to credential files
  • Instructions that use the network
  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
AWS
Publisher
AWS (Official)
Source
aws/agent-toolkit-for-aws · skills/specialized-skills/database-skills/amazon-elasticache · commit 0a218f8
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • NOTICE (added by AutoGineer from NOTICE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by AWS or AWS.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download amazon-elasticache.zip