Skip to main content

MemoryStore quickstart

In about five minutes you will create a MemoryStore instance, save its password (shown exactly once), watch it become ready, check live stats, and run PING, SET, and GET against it.

Before you begin​

  • You have a platform account and can sign in. If not, ask your administrator for an account or an invitation link — see Create an account.

  • You have installed the platformctl CLI and run platformctl login.

  • For the curl tabs, you need your project ID. It is a UUID — a 36-character random identifier like 7f3c1e02-9b5d-4a11-8c6f-2d0e5a91b4cc. Copy it from the console URL at https://console.codyhill.dev (#/projects/<uuid>/...), or run platformctl projects list.

    export MS="https://api.codyhill.dev"          # MemoryStore is served on the shared public API
    export CAI_PROJECT="00000000-0000-0000-0000-000000000000"   # your project UUID
    export CAI_TOKEN="<your session token or API key>"

    The platformctl tabs need none of this — the CLI defaults to the same address and resolves your project itself.

Step 1: Create an instance​

You are creating a small instance to use as a cache. That is why the request overrides the default eviction policy with allkeys-lru, which throws out the least recently used keys when memory fills up. The default policy, noeviction, would make writes fail instead — a deliberate default, because this store backs agent sessions as often as it backs a cache, and an evicted session is a conversation that silently forgets its first turn.

Only the name is required; every other field has a server-side default.

platformctl memorystore create cache --maxmemory-policy allkeys-lru

You should see:

name:              cache
state:             unknown
host:              <private-hostname>
port:              6379
username:          default
credential secret: ms-cache-credential

password (shown once):
<24-random-bytes>

uri:               redis://:<password>@<private-hostname>:6379

This is the only response that contains the password. Later reads return the name of the Secret holding it, never the value. The instance is still provisioning; poll until it reports ready before connecting.

The response reports state as unknown, not provisioning. That is deliberate: the instance was created a millisecond ago and nothing has looked at it yet, so the API reports the truth rather than guessing at progress. Read it again a moment later and you will see provisioning, then ready. The state words are always lowercase — unknown, provisioning, ready, degraded, deleting — so a comparison against "ready" means the same thing here as it does on every other resource.

Beside state sit two more fields you will see on everything the platform returns: ready, a plain boolean that answers "can I connect to this yet", and message, which says why not while the answer is no. state is the word to show a person; ready is the field to branch on in code.

Copy the password now

This is the only time the API will ever show you the password. Every later read returns the name of the Secret that holds it, never the value itself. Save the credential somewhere safe before you move on. If you lose it, an admin can issue a new one with platformctl memorystore rotate-credential cache.

export MS_PASSWORD="<the password from the response>"

Step 2: Wait for it to be ready​

platformctl memorystore get cache

You should see (usually within ~15 seconds):

NAME   SIZE_CLASS  STATE  READY
cache  small       ready  yes

What failure looks like​

Ask for stats before the instance is provisioned and you get a 409 with a plain-English explanation:

{"error":"this memorystore is not provisioned yet; wait until it reports ready, then read its stats","request_id":"..."}

Step 3: Check live stats​

Once the instance reports ready, the platform reads live server statistics on your behalf. You do not need a connection of your own.

platformctl memorystore stats cache

You should see a key/value table including lines like:

used_memory_human      1.00M
maxmemory_policy       allkeys-lru
connected_clients      1
db_keys                0
uptime_in_seconds      42

These values are read straight from the running instance at the moment you ask. They are a snapshot, not a history you can graph over time.

Step 4: Connect and run PING, SET, GET​

The instance is private. It has no public address, so your laptop cannot reach it.

Read this before you write connection code

Port 6379 on the address below is firewalled. Only the platform's own components may reach it — your agents, functions, and services may not, and a plain redis:// connection from them times out with no explanation.

The supported route for your own code is the opt-in TLS endpoint, which you have to turn on when you create the instance. Connect from workloads covers who can reach what, and how to create an instance with that endpoint enabled.

The commands below are the ones to run once you have a route to the instance. Over the TLS endpoint they are the same commands with --tls and port 443.

You already have the exact hostname: it is the host part of the uri you saved in step 1.

export MS_HOST="<private-hostname>"   # copy the host out of the 'uri' field

Then check that the instance answers:

redis-cli -h "$MS_HOST" -p 6379 -a "$MS_PASSWORD" PING

You should see:

PONG

Now a round trip:

redis-cli -h "$MS_HOST" -p 6379 -a "$MS_PASSWORD" SET greeting "hello"
redis-cli -h "$MS_HOST" -p 6379 -a "$MS_PASSWORD" GET greeting

You should see:

OK
hello

MemoryStore speaks the Redis wire protocol, so any Redis client library works unchanged — redis-cli above is just the quickest one to reach for.

Clean up​

Deleting an instance destroys it and its data volume. This is not reversible, and it requires the project admin role.

platformctl memorystore delete cache

The API answers 202 rather than 204 because the deletion is asynchronous: the platform still has to stop the instance and reclaim the volume, and reporting "done" would claim the storage is already gone.

Next steps​

  • Connect from workloads — the credential Secret, agents and functions, and the external TLS endpoint.
  • Use with agents — where agent sessions live (spoiler: not in this instance).
  • API reference — every field on create, including persistence and external exposure.