Use with agents

Agent conversations on this platform are kept in a managed key-value store. This page explains how session storage operates and when to create a dedicated MemoryStore instance for agent workloads.

Sessions live in a key-value store

Every conversation with an agent happens inside a session. A session is the running record of user and assistant turns, and it is what gives the agent short-term memory. Invoke an agent with a session id and the platform loads that session's history from storage, hands it to the model, then appends the new turns afterward.

That storage is a key-value store the platform runs for you. Each session is saved under a key that spells out the project, the agent, and the session id, in the form sess:<project-short>:<agent>:<session-id>, where <project-short> is your project short id. A key-value store in RAM is the right fit here, because every single turn reads and rewrites the session.

Session Storage Architecture

The store holding your sessions is not one of yours. That is worth stating plainly:

Platform Session Storage

Agent sessions are automatically managed by the platform session store. You do not need to create or manage a MemoryStore instance for basic conversation history.

One project's sessions are kept apart from another's by key naming rather than by separate servers: the project and the agent are part of every key.

Two practical consequences:

1. CRUSOE_MEMORYSTORE_ADDR points at the shared store. Agents run with this environment variable set. The name is misleading: it is the address of the platform's shared session store, not of any MemoryStore instance in your project. Treat it as platform plumbing and do not put your own data there. To use your own instance from an agent, connect to it explicitly, as shown in Connect from workloads.
2. You manage sessions through the Agents service, not through MemoryStore. Listing, reading, and deleting sessions all happen through the agent's session APIs — see Sessions. The MemoryStore pages in the console never show session data, because sessions do not live in your instances.

When to create your own instance for agent workloads

The shared store handles conversation history for you. Create your own MemoryStore instance when your agent needs key-value storage for its application data:

Need	Store	Why
Conversation history across turns	Shared session store (automatic)	Built in; nothing to set up
Long-term semantic memory ("what do you know about me?")	Agent memory bank	That's vector search, not key-value
Caching API results or computed data your agent's tools use	Your MemoryStore instance	You control size and eviction (allkeys-lru)
Rate limiting and counters across invocations	Your MemoryStore instance	Atomic increments; noeviction preserves accurate counts
Shared state between an agent and other services	Your MemoryStore instance	One store both sides reach over its TLS endpoint, with a password you manage

The memory bank is the built-in path: Memory shows how an agent commits a conversation to long-term memory and recalls it later. If you would rather build your own retrieval on top of raw vector search, Use VectorDB with agents covers that instead.

Wiring an instance into an agent always follows the same three steps. Create the instance with its TLS endpoint turned on, because that switch is create-time only. Store the password in your project or agent secrets. Then connect from the agent's code with a standard Redis client, pointed at the TLS endpoint. Connect from workloads has the step-by-step, including why the instance's plain private address does not work from your own code.

Choose settings for agent-adjacent instances

• Cache for tool results: use allkeys-lru. Turn persistence off if the data is cheap to recreate — with no disk, any restart returns an empty instance, including the one a size class change causes (the size bullet below). Persistence is on by default, so turning it off means sending "persistence":{"enabled":false} yourself, and it cannot be turned back on later.
• Counters, queues, or anything you would be sad to lose: keep the defaults. That means noeviction plus persistence, which writes every change to an append-only file and can lose up to about one second of acknowledged writes if the machine dies. platformctl memorystore update <name> --fsync always narrows that window: an acknowledged write is on disk before we acknowledge it, at a write-latency cost we have not measured. It is refused with 409 on an instance with persistence off: there is no append-only file to flush.
• Size: start with small. If you outgrow it, platformctl memorystore update <name> --size-class medium resizes in place: one restart, about 30 seconds. With persistence on the instance reloads its data from the disk afterwards; with persistence off — the setting the cache bullet above suggests — the same restart brings it back empty, so warm the cache again rather than assuming it survived. The eviction policy and persistence itself are still create-time only, and the disk does not grow with the class. Watch usage live and check it before shrinking: a shrink to a class whose limit is at or below the live usage is refused whatever your eviction policy is — with noeviction the instance would fail every write, with allkeys-lru it would silently evict keys to fit.

platformctl memorystore stats <name>                        # live usage, before you change anything
platformctl memorystore update <name> --size-class medium   # more memory; one restart
platformctl memorystore update <name> --fsync always        # durability, while persistence is on

Summary

Question	Answer
Where do my agent's sessions live?	A platform-operated shared key-value store, keyed by project + agent + session id
Can I see that store in my MemoryStore list?	No — it isn't a project resource
What is CRUSOE_MEMORYSTORE_ADDR?	The shared session store's address, injected into agents; not your instance
How do I manage session data?	Through the agent's own session APIs — see Sessions
When do I create my own instance?	For your agent's own caching, counters, queues, and shared state
How does my agent reach my instance?	Through the instance's TLS endpoint, with the password read from your secrets — see Connect from workloads

Next steps

• Sessions — session lifecycle, ids, and management APIs.
• Use VectorDB with agents — the other half of agent memory.
• MemoryStore quickstart — create your first instance in five minutes.