MemoryStore guide

This is the end-to-end walkthrough for MemoryStore, the platform's managed, Redis-compatible key-value store. It assumes only an account and a project, and it takes you from zero to a working cache or session store.

What MemoryStore is

MemoryStore gives you a fully managed, Redis-protocol-compatible instance. Anything you would do with redis-cli or any Redis client library works against it unchanged. Use it for caching, session storage, rate limiting, leaderboards, work queues, and the small fast state your agent's tools need.

Use cases:

• Cache for expensive API or model calls — allkeys-lru eviction is the right default.
• Session store for web apps and agents.
• Rate limiting and counters — atomic increments with no risk of eviction if you keep the default noeviction policy.
• Pub/sub and queues — the wire protocol supports the standard list and channel primitives.
• Agent tool state — the side channel for shared state between a Serverless service and an agent.

Quick start: working instance in five commands

# 1. sign in once
platformctl login

# 2. create a small cache
platformctl memorystore create cache --maxmemory-policy allkeys-lru
#    ^ the response contains the password. Copy it; it is shown exactly once.

# 3. wait for ready
platformctl memorystore get cache

# 4. see the connection details (host, port; the password was shown at create)
platformctl memorystore get cache -o json

# 5. clean up when done
platformctl memorystore delete cache

The hostname is private

connection.host resolves only inside the platform. Your laptop cannot reach it and there is no public endpoint by default, so a redis-cli against that host from your machine hangs until its own timeout rather than failing fast.

To use it from a workload, see connect from workloads. To reach it from outside, publish it first with platformctl gateway publish.

The same flow in the Console is Data services → MemoryStore → Create instance → Connect.

Core concepts

• An instance is a managed, Redis-protocol-compatible server. It is the only object you create; the platform manages placement and replication for you.
• The size class (small, medium, large) sets memory. You cannot change class after creation — recreate the instance.
• The eviction policy (noeviction by default, allkeys-lru for caches) is set at create time only.
• Persistence (on by default) writes every change to an append-only log. Turn it off (persistence.enabled: false) only if losing the data on a crash is acceptable.
• A new instance returns its password exactly once. Later reads return only the name of the Secret that holds it.
• The TLS endpoint is enabled at create time. (tls.enabled: true.) Required for any connection that crosses the project boundary.
• shared mode puts this instance on the project-shared backend (cheap, fast, less isolated). dedicated mode gives the instance its own backend (louder-neighbor protection, higher cost).
• The credential Secret lives in Secrets Manager under ms-<name>-credential once the instance is provisioned. Use it from your code, do not paste the password.
• Rename is not supported. The name is part of the hostname. Recreate if you need a different name.
• Every instance is project-scoped. Other projects cannot see it, list it, or reach it.

API examples

export MS="https://api.codyhill.dev"
export PROJ="$(platformctl projects list -o json | jq -r '.[0].id')"
export TOK="<session token or API key>"

Create a small cache (eviction tuned for a cache):

curl -sX POST "$MS/v1/projects/$PROJ/memorystores" \
  -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \
  -d '{"name":"cache","size_class":"small","maxmemory_policy":"allkeys-lru","tls":{"enabled":true}}'

The response contains the only copy of the password. A later read of the same instance returns the credential name, not the value:

curl -s "$MS/v1/projects/$PROJ/memorystores/cache" -H "Authorization: Bearer $TOK"

Live stats:

curl -s "$MS/v1/projects/$PROJ/memorystores/cache/stats" -H "Authorization: Bearer $TOK"

Rotate the credential if it leaks:

curl -sX POST "$MS/v1/projects/$PROJ/memorystores/cache/rotate-credential" \
  -H "Authorization: Bearer $TOK"

CLI examples

platformctl memorystore list                            # all instances
platformctl memorystore get cache                       # state, hostname, size_class, eviction policy
platformctl memorystore stats cache                     # live memory, evictions, hit ratio
platformctl memorystore create cache --size-class small --maxmemory-policy allkeys-lru
platformctl memorystore rotate-credential cache         # admin only; issues a new password, revokes the old one
platformctl memorystore renew-credential cache          # admin only; renews the existing credential lease
platformctl memorystore delete cache                    # admin only; drops the instance and its data

Console walkthrough

1. Open the Console, pick your project.
2. Go to Data services → MemoryStore.
3. Click Create instance. Pick a name, size class, eviction policy, and whether to enable the TLS endpoint. For a cache, choose allkeys-lru. For anything that matters, leave the default noeviction.
4. The response shows the password once, with copy and Save to Secrets buttons. Save it to Secrets — that is the easiest way to never lose it.
5. When the row flips to Ready, click the instance to open it. The detail page shows the private hostname, port, TLS endpoint, and live stats.
6. To connect from your code, use the TLS endpoint, not the private hostname — see Connect from workloads.
7. Rotate credential (admin) issues a fresh password without downtime. Delete terminates the instance.

Limits and quotas

Limit	Default
Size classes	small (~192 MiB usable), medium, large
Instances per project	10 (soft; raise via support)
Eviction policies	noeviction (default), allkeys-lru, volatile-lru, allkeys-random, plus the standard policy set of the wire protocol
Max requests/second	bounded by the chosen size class; the stats endpoint reports the live ceiling
TTL per key	any positive value up to the protocol maximum (~2^31 ms)

The one-time password is returned only at create and at rotate. If you lose both copies, your only recovery is rotate-credential.

Troubleshooting snippets

Symptom	First thing to check
NOAUTH Authentication required	The password was wrong or rotated. platformctl memorystore get cache shows the current credential name; the value lives only in Secrets Manager.
OOM command not allowed when used memory > maxmemory	The instance is full and the eviction policy is noeviction. Either raise the size class (recreate), switch to allkeys-lru (recreate), or delete keys.
Connection refused from your code	You are using the private hostname. Use the TLS endpoint — see Connect from workloads.
state stuck at provisioning	Normal for ~30 seconds on a small instance. If it stays past five minutes, check the project for a stuck resource with platformctl memorystore get cache -o json.
Lost password	The API will not show it again. Use rotate-credential to issue a new one.
read-only errors	The instance went into a degraded state. stats reports master_link_status; recreate if it does not recover in a few minutes.

Security notes

• Password shown once is a hard rule. Anything else would be a silently-leaking secret. Pair the create call with an immediate Secrets Manager write.
• TLS endpoint when crossing the project line. Traffic inside the project's services runs over mutual TLS already. The moment a laptop, CI runner, or external tool connects, use the TLS endpoint and validate the server certificate.
• Eviction policy and durability are a security choice. noeviction plus persistence is the safest; allkeys-lru without persistence is the fastest. Do not put authentication tokens in a allkeys-lru cache — a full cache will silently log your users out.
• Delete is irreversible. There is no soft-delete, snapshot, or point-in-time restore. Export anything that matters with connect before calling delete.
• Audit is on. Every create, rotate, renew, and delete lands in the project's audit log with the actor, the time, and the previous credential name where applicable.

Where next

• Connect from workloads — TLS, service accounts, and example client code in every common language.
• Use with agents — where the agent's chat history actually lives, and when to give it its own store.
• Quickstart — the five-minute standalone version.