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:
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:
CRUSOE_MEMORYSTORE_ADDRpoints 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.- 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. Persistence is on by default, so turning it off means sending"persistence":{"enabled":false}yourself. - Counters, queues, or anything you would be sad to lose: keep the defaults. That means
noevictionplus persistence, which writes every change to an append-only file and can lose roughly one second of writes in a crash. - Size: start with
small, which gives you 192Mi of usable memory. You cannot change the eviction policy or persistence after creation. You can watch usage live withplatformctl memorystore stats <name>, and recreate the instance deliberately if you outgrow it.
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.