Redis Forked Into Valkey. Your CLAUDE.md Still Says redis:latest

Redis went from a permissive BSD license, to a source-available license that blocked competing managed services, to a tri-license that added an OSI-approved option back — three license changes in about 18 months, and a Linux Foundation fork called Valkey born in the middle of it. Both projects speak the same wire protocol and both answer to redis-cli, so docker run redis and docker run valkey/valkey look interchangeable in a terminal. They aren’t: different license, different owning organization, different default on the two biggest clouds, and a growing list of commands and modules that exist on one and not the other. An unguided Claude Code has no way to know which one a given project actually runs, and “redis” is common enough in its training data that it will default to the wrong assumption if CLAUDE.md doesn’t say otherwise.

That gap matters more for a datastore than it does for most dependencies, because the two projects have started to genuinely diverge rather than just rebrand. The gallery’s existing Redis rules — key naming, connection pooling, SCAN over KEYS — are still correct for either engine, but they were written before Valkey existed and say nothing about which one a project is on, which matters as soon as an agent reaches for a module command, a Docker image tag, or a managed-service SDK call.

Browse more real-world CLAUDE.md and AGENTS.md examples in our gallery.

How Redis Became Two Projects

The short version, because CLAUDE.md needs to state the current state, not the history, but the history explains why:

• March 2024 — Redis Ltd. relicensed Redis from BSD-3-Clause to a choice of SSPLv1 or RSALv2, both source-available but not OSI-approved open source. The stated goal was to stop cloud providers from selling Redis as a managed service without contributing back.
• March 2024, days later — AWS, Google Cloud, Oracle, Ericsson, and other vendors created Valkey, a hard fork of Redis 7.2.4 under the original BSD-3-Clause license, governed by the Linux Foundation rather than a single company.
• May 2025, Redis 8.0 — Redis Ltd. added AGPLv3 as a third option, on top of the existing RSALv2 and SSPLv1, after sustained community pressure for an OSI-approved license. Redis is now tri-licensed: you pick one of the three per deployment.

As of mid-2026, Redis is on its 8.x line (8.8 shipped May 2026) and Valkey is on 9.1.x (9.1.0 shipped May 2026, with an 8.1.x maintenance branch still supported). Both are actively developed by different teams with different release cadences, which is the part that makes “just use Redis, it’s fine” an increasingly risky default for a coding agent to assume.

The License Question CLAUDE.md Has to Answer First

This is the decision an agent cannot make for you, because it depends on what the project does, not what the code looks like:

If the project is a normal application that happens to use Redis for caching or queues, the RSALv2 default that ships with the Redis Docker image is fine — you’re not competing with Redis Ltd.’s hosting business. If the project is itself a hosting or PaaS product with a datastore layer, RSALv2 alone is a legal blocker, and the team needs to have consciously picked SSPLv1, AGPLv3, or Valkey — an agent generating infrastructure code has no way to know which situation it’s in unless CLAUDE.md says so.

Where the Two Engines Actually Diverge

Wire-protocol compatibility means redis-py, node-redis, and ioredis all connect to a Valkey server with zero code changes — both speak RESP2 and RESP3 unmodified. That compatibility is exactly what makes the gap dangerous: the connection works, most commands work, and the divergence only shows up when code touches one of the parts that don’t line up.

Module coverage, as of the Valkey 8.1/9.0 cycle:

If a project’s code calls TS.ADD or a Top-K command anywhere, that code has a hard dependency on Redis specifically — there is no Valkey migration path for it today, full stop. That’s the kind of constraint an agent needs stated explicitly, because “swap the Docker image to Valkey to cut hosting cost” is a completely reasonable-sounding suggestion that silently breaks the app if this dependency isn’t documented.

Command-level compatibility sits around 90% by several 2026 comparisons — close enough that most CRUD-style Redis usage (GET/SET/HSET/pipelines/pub-sub) behaves identically, not close enough to assume every command a training-data example uses will exist on both.

What the Cloud Providers Actually Default To

This is worth stating in CLAUDE.md too, because it affects what “the Redis instance” even means in a given deployment:

• AWS — ElastiCache and MemoryDB now provision Valkey by default for new clusters; Redis OSS remains selectable but isn’t the default anymore. Valkey pricing runs roughly 20% cheaper than the equivalent Redis SKU on ElastiCache.
• Google Cloud — Memorystore for Valkey went GA across all major regions in early 2026, priced below the equivalent Redis SKU; new Memorystore clusters lean Valkey the same way AWS’s do.
• Azure — the outlier. Azure Cache for Redis is still Redis-backed under Microsoft’s own commercial arrangement with Redis Ltd., with no first-party managed Valkey offering as of this writing.

A project reading REDIS_URL from an AWS or GCP environment created any time after 2024 is statistically more likely to be pointed at a Valkey endpoint than a Redis one, even if nobody on the team consciously chose that — provisioning defaults did it for them.

A CLAUDE.md Template That States the Engine Explicitly

# CLAUDE.md — Cache / Datastore Layer

## Engine
- Running: {Redis 8.x (tri-licensed) / Valkey 9.x (BSD-3-Clause)} — do not assume
  the other one. Confirm with `redis-cli INFO server` (field `redis_version` vs
  `valkey_version` in the `Server` section) before writing engine-specific code.
- License basis (if Redis): {RSALv2 / SSPLv1 / AGPLv3} — chosen because
  {this is an internal cache, not a hosted product / we ship modifications
  publicly under SSPL / we're fine with AGPL's network clause}.
  Do not suggest offering this deployment as a hosted service to third
  parties without re-checking this line — RSALv2 prohibits it outright.
- Docker image: `{redis:8-alpine / valkey/valkey:9-alpine}` — these are not
  interchangeable tags of the same image; changing one for the other is
  an engine migration, not a version bump.
- Managed service: {AWS ElastiCache for Valkey / GCP Memorystore for Valkey /
  Azure Cache for Redis / self-hosted}.

## Modules / Extended Commands In Use
- {RedisJSON / valkey-json}: used for {describe where, e.g. session blobs}.
- {RedisTimeSeries}: used for {describe where}. **No Valkey equivalent exists.**
  Do not suggest migrating this deployment to Valkey without first replacing
  every `TS.*` call — there is currently no migration path for this feature.
- Vector search: {Redis Query Engine / Vector Sets / valkey-search} — note the
  ~20-30% QPS gap on valkey-search if this path is latency-sensitive.

## Client Library
- {redis-py 5.x / node-redis 4.x / ioredis 5.x}, tested against
  {Redis 8.x / Valkey 9.x} specifically — RESP-level compatibility means the
  library connects to either, but "connects" isn't the same as "tested."

## Command Discipline (applies to either engine)
- Never `SELECT` a numbered database — use key prefixes (`app:cache:`, `app:sessions:`).
- `SCAN`, never `KEYS`, in any code path that can run against production.
- `FLUSHALL` / `FLUSHDB` are test-fixture-only commands — never in application
  code, and denied outright against any host matching `*prod*` (see settings.json below).
- Connection pooling required — no bare `redis.Redis()` / `new Redis()` per request.

settings.json: Blocking the Commands That Actually Destroy Data

Redis has almost no “irreversible infrastructure” commands the way terraform destroy or aws lambda delete-function are — the risk here is data loss on a live keyspace, not resource deletion:

{
  "permissions": {
    "allow": [
      "Bash(redis-cli -h * PING)",
      "Bash(redis-cli -h * INFO*)",
      "Bash(redis-cli -h * GET *)",
      "Bash(redis-cli -h * SCAN *)",
      "Bash(redis-cli -h * DBSIZE)"
    ],
    "deny": [
      "Bash(redis-cli -h *prod* FLUSHALL*)",
      "Bash(redis-cli -h *prod* FLUSHDB*)",
      "Bash(redis-cli -h *prod* CONFIG SET*)",
      "Bash(redis-cli -h *prod* SHUTDOWN*)",
      "Bash(redis-cli *--no-auth-warning* -a *)"
    ]
  }
}

The last deny line is worth explaining: --no-auth-warning -a <password> is the pattern that puts a Redis password in plaintext on the command line (and in shell history), which an agent copying a snippet from documentation or a Stack Overflow-style example will do without thinking twice. Prefer REDISCLI_AUTH as an environment variable in any command an agent is allowed to run.

What Anthropic’s Own Redis Plugin Covers (and Doesn’t)

Redis Ltd. publishes an official Claude Code plugin (redis-development, installed by nearly 3,000 users as of this writing) that covers data structures, the query engine, vector search, caching patterns, and performance optimization:

Installing the plugin and writing a CLAUDE.md aren’t in tension — the plugin teaches Claude Code Redis command syntax and patterns it might not reliably recall on its own; CLAUDE.md tells it which engine this specific project runs, which of those patterns actually apply, and which modules have no equivalent on the other engine.

Common Mistakes to Watch For

Suggesting a Valkey migration to cut hosting cost without checking for TS.*, Top-K, or Cuckoo filter usage first. These have no Valkey path today — a migration that looks like a config change breaks the application at the first call to a missing command, and that call might not be exercised until a monitoring job runs.

Treating redis:latest and valkey/valkey:latest as interchangeable base image tags in a Dockerfile. They’re different projects with different release cadences and, per the module table above, different feature surfaces — pin one explicitly and state which in CLAUDE.md, the same way a runtime version gets pinned.

Assuming RSALv2 is fine because “it’s just source-available, not really different from open source.” It’s fine right up until the project’s business model changes to include hosting the datastore for third parties, at which point RSALv2 alone actively prohibits it — this is a business-model question CLAUDE.md needs to carry, not something to infer from the code.

Pasting a Redis CLI command with -a <password> inline from a tutorial. It’s a common pattern in older documentation and puts a live credential in shell history and process listings; REDISCLI_AUTH avoids both.

Assuming a numbered-database (SELECT 1) example from training data is fine because it “used to be common.” It still works on both engines, but it’s been a discouraged anti-pattern for years — cluster mode doesn’t support multiple databases at all, and a codebase that starts with SELECT blocks a future move to cluster mode.

None of this is a reason to avoid Redis or Valkey — both are solid, well-understood pieces of infrastructure, and for a typical caching or session-store use case, the choice barely matters day to day. It’s a reason to write down, once, which engine a given project runs, why, and which of its commands have no equivalent on the other side — because an agent generating infrastructure code, a Dockerfile, or a “let’s cut cache costs” suggestion has no way to reconstruct that decision from the code alone, and guessing wrong on a datastore is a different category of mistake than guessing wrong on a linter config.

Browse more real database, infrastructure, and framework-specific CLAUDE.md/AGENTS.md examples in our gallery.

FAQ

Is Redis still open source? Not in the OSI sense by default. Since Redis 8 (May 2025), Redis ships under a choice of three licenses: RSALv2 and SSPLv1 (both source-available, not OSI-approved), or AGPLv3 (OSI-approved open source). Which one applies depends on which license terms a deployment is used under — it’s a choice, not a single fixed license.

What is Valkey, and is it a full Redis replacement? Valkey is a Linux Foundation-governed fork of Redis 7.2.4, created in March 2024 by AWS, Google Cloud, Oracle, Ericsson, and others, licensed under the original BSD-3-Clause. It’s protocol-compatible and roughly 90% command-compatible with Redis as of 2026, with JSON and Bloom filter support at parity through community modules — but RedisTimeSeries, Top-K, Cuckoo filters, and T-Digest have no Valkey equivalent, and its vector search module runs meaningfully slower than Redis’s native implementation on published benchmarks.

Do I need to change my code to switch between Redis and Valkey? For standard commands, no — redis-py, node-redis, and ioredis all connect to either engine over the same RESP protocol without code changes. Code that calls module-specific commands not available on the other engine (TS.* on Redis, for example) does need to change, or the migration isn’t possible without replacing that functionality.

Which cloud providers default to Valkey now? AWS ElastiCache and MemoryDB, and Google Cloud Memorystore, provision Valkey by default for new clusters as of 2026, at roughly 20% lower pricing than the equivalent Redis SKU. Azure Cache for Redis remains Redis-backed with no first-party managed Valkey offering.

Does Anthropic’s official Redis plugin cover the Valkey/license question? No. The redis-development plugin covers general Redis command syntax, data structures, and performance patterns, and is Redis-branded — it doesn’t distinguish Redis from Valkey or address licensing. That’s project-specific context a CLAUDE.md needs to carry.