Claude Redis

Redis RESP2 MCP License MIT

Most "give the AI a memory" projects reach for a document store or a vector index. Sometimes what you actually want is a counter, a ranked list, and a note that deletes itself in an hour. That is Redis, and it turns out to map onto assistant workflows unusually cleanly.

Redis type	What it is good for in a Claude session	Commands you will actually use
String + TTL	Working notes that should not outlive the week	SET, GET, EXPIRE, TTL
Hash	One record per entity, updated field by field	HSET, HGETALL, HINCRBYFLOAT
Sorted set	Rankings, and anything keyed by a number you sort on	ZADD, ZREVRANGE, ZRANGEBYSCORE
List	Append-only logs read from either end	LPUSH, LRANGE, LTRIM
Counter	Tallies that survive the conversation	INCR, INCRBYFLOAT
Set	Membership questions, deduplication	SADD, SISMEMBER, SINTER
Stream	Ordered event history with consumer groups	XADD, XRANGE, XREAD

The running-training log in examples/ uses five of the seven. It is a small enough domain to hold in your head and awkward enough — weekly totals, personal bests, a rolling scratchpad of how the legs feel — that the data-structure choices matter.

Getting connected

A free Redis 7.2.3 instance and an MCP token:

1. Sign up, create a session, choose Redis.
2. Open Settings → MCP → New Token, choose that connection, and copy what it gives you.

https://freebase.cloud/api/mcp/YOUR_TOKEN

The token is part of the path, so nothing needs an auth header. That also means the URL is the credential — keep it out of screenshots and commits.

Claude Code:

claude mcp add --transport http scratch https://freebase.cloud/api/mcp/YOUR_TOKEN

Add --scope project to write .mcp.json into the repo, --scope user to make it available everywhere. If you hand-edit that file, the entry needs "type": "http" — Claude Code will not guess the transport from the presence of a url, it will just fail to load the server.

Claude Desktop: Settings → Connectors (Customize → Connectors in newer builds) → Add custom connector → paste → Add. Turn it on inside a conversation using the + button next to the composer. One custom connector at a time on the Free plan. Remote HTTP servers cannot be declared in claude_desktop_config.json; if you need a file-based setup, mcp-remote bridges stdio to HTTP as a documented fallback. If either menu has moved again, check connecting Claude to Redis.

redis-cli, in parallel:

redis-cli -h HOST -p 6379

Redis is one of three engines on the free tier that speak their real wire protocol, so ioredis, redis-py, node-redis and Lettuce all connect without modification over RESP2. Two of the three example scripts use that route.

The four MCP tools

With a connection named scratch — whatever you called it in the dashboard:

• scratch_query — the workhorse. Send Redis commands and read the reply.
• scratch_store — bulk-writes structured rows; useful when you have a batch to load rather than a command to run.
• scratch_list_tables — enumerates what exists on the connection, along with any annotations.
• scratch_annotate_table — attaches a persistent description. For Redis this is where key patterns and expiry rules belong, and the annotation format has a key_pattern and a ttl field for exactly that purpose.

Annotate early. A key namespace is only legible if someone wrote down the convention:

key_pattern: run:{iso_date}          hash, one training run
             week:{iso_year}-W{ww}   sorted set, athlete -> km that week
             pb:{distance}           sorted set, seconds -> athlete, lower is better
             note:{topic}            string, 14 day TTL, throwaway working notes
ttl:         note:* expires in 14 days; nothing else expires

Without that, a later session will invent runs:2026-08-17 alongside your run:2026-08-17 and neither of you will notice for a month.

Cookbook

Commands worth having in front of you when you start designing keys on a fresh Redis 7.2.3 instance.

# a run, as a hash
HSET run:2026-08-17 km 14.2 minutes 78 surface trail rpe 6 shoes "trail-2"
HGETALL run:2026-08-17
PERSIST run:2026-08-17                # never expire; training history is not disposable
                                      # (note: EXPIRE with a negative TTL deletes the key)

# weekly volume, as a counter you can add to
INCRBYFLOAT week:2026-W33 14.2
GET week:2026-W33

# a leaderboard across a training group
ZADD week:2026-W33:group 62.4 "rana" 51.0 "tomas" 74.8 "iris"
ZREVRANGE week:2026-W33:group 0 4 WITHSCORES

# personal bests, where lower is better, so read the sorted set forwards
ZADD pb:5k 1147 "rana" 1206 "tomas"
ZRANGE pb:5k 0 0 WITHSCORES           # current record holder

# a working note that cleans itself up
SET note:achilles "left achilles tight after Tuesday hills, easing back" EX 1209600
TTL note:achilles

# recent sessions as an append-only list, capped at 30
LPUSH log:recent "2026-08-17 14.2km trail rpe6"
LTRIM log:recent 0 29
LRANGE log:recent 0 9

EX 1209600 is fourteen days. Writing the seconds inline is unreadable; write the intent in the annotation instead.

An illustrative session

Constructed to show the flow, not transcribed from a run, but every command in it runs as written once Claude is pointed at the connection.

You: Log today: 14.2 km on trail, 78 minutes, effort about 6 out of 10. Achilles was tight for the first 20 minutes and then settled.

Claude: (calls scratch_query four times) Stored as run:2026-08-17, added 14.2 to week:2026-W33 — you are at 51.6 km for the week — and put the achilles note in note:achilles with a two-week expiry.

A fortnight later, new conversation: You: Anything I should know before today's session?

Claude: (reads the week counter, the recent list and any live notes) You are at 38 km across four days, which is down from the last two weeks. The achilles note expired yesterday, so either it resolved or nobody wrote a new one — worth a sentence either way. Last hard effort was six days ago.

The expiry is doing real work in that second answer. A note that has aged out is information: it means nobody has flagged the problem recently. A document store would have kept the note forever and the model would still be worrying about an achilles that stopped hurting in July.

Examples

examples/training_log.sh    redis-cli; log runs, roll up weeks, print the group table
examples/weekly_ranking.py  redis-py; sorted sets, pipelines, and a mileage report
examples/scratchpad.mjs     node-redis; TTL-backed notes with a sweep of what is expiring
examples/README.md          setup and run order

All three connect to the same instance over the native protocol, so you can watch the same keys the assistant is touching. Run training_log.sh seed first — the other two assume its key layout.

What to watch out for

• Redis is not your system of record. It is excellent as the working set and poor as an archive. If the training log matters to you in five years, keep the source of truth somewhere relational and use Redis for the parts you query constantly.
• TTLs are silent. A key that expires produces no event you will notice in a conversation. If an absence would be misleading, do not put it behind an expiry.
• KEYS scans everything. Use SCAN in anything that runs unattended, and prefer well-known key names over pattern searches when a model is driving.
• Sorted-set direction is a footgun. ZREVRANGE for "most", ZRANGE for "fastest". Get it backwards and the leaderboard is confidently upside down. Say which one you mean in the annotation.
• What the free tier is for. Development, prototyping, and small production workloads. No quota, persistence-policy or availability claims are made here — your account dashboard is authoritative.
• The MCP URL is unrestricted access. FLUSHALL is a command like any other. Point a shared connection at data you can afford to lose, and rotate the token if it escapes.

Reading

• Free Redis cloud instance
• How to connect Claude to Redis
• freebase.cloud
• Redis command reference
• Model Context Protocol

Pull requests welcome, particularly additional key-layout patterns that survive contact with a model over several sessions.

MIT licensed.

freebase.cloud is an independent service and is not affiliated with Redis Ltd. or Anthropic, PBC.