Use with agents
Agent conversations on this platform are stored in a Valkey key-value store — the same technology MemoryStore instances run. This page explains exactly which store that is (it's probably not the one you think), what the alpha shared-store setup means for you, and when to create your own instance for agent workloads.
Sessions live in a key-value store
Every conversation with an agent happens inside a session: the running record of user and assistant turns that gives the agent short-term memory. When you invoke an agent with a session id, the platform loads that session's history from storage, hands it to the model, and appends the new turns afterward.
That storage is a Valkey store. Sessions are saved under keys that encode the project, the agent, and the session id — in the form sess:<project-short>:<agent>:<session-id>. Fast in-memory reads and writes are exactly what conversation state needs: a session is touched on every single turn.
The shared-store alpha caveat
Here is the honest part, and it matters:
Agent sessions are not stored in a MemoryStore instance you create. They live in a single Valkey store that the platform operates and shares across the platform's agents. You don't create it, size it, secure it, or manage it — and you can't browse it with redis-cli. Session data is isolated logically by key prefix (project and agent are part of every key), not by giving each project its own server.
Two practical consequences:
CRUSOE_MEMORYSTORE_ADDRpoints at the shared store. Agents run with this environment variable set. Despite the name, it is the address of the platform's shared session store — not of any MemoryStore instance in your project. Don't build on it for your own data; treat it as platform plumbing. To use your own instance from an agent, connect explicitly as shown in Connect from workloads.- You manage sessions through the Agent Engine, not through MemoryStore. Listing, reading, and deleting sessions happens via the agent's session APIs — see Sessions. The MemoryStore pages of the console will never show you session data, because sessions don't live in your instances.
Per-project session stores are the direction the platform is headed; the shared store is the alpha reality, and we'd rather tell you that than have you discover it while debugging.
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 keeps counts honest |
| Shared state between an agent and other services | Your MemoryStore instance | One store both sides can reach, with a password you manage |
The pattern for wiring an instance into an agent is always the same: create the instance, store its password in your project or agent secrets, and connect from the agent's code with a standard Redis client using the instance's private hostname. The step-by-step lives in Connect from workloads.
Choosing settings for agent-adjacent instances
- Cache for tool results:
allkeys-lru, persistence off if the data is cheap to recreate (you must send"persistence":{"enabled":false}explicitly — the default is on). - Counters, queues, or anything you'd be sad to lose: default
noevictionand default persistence (append-only file, roughly one second of loss window on a crash). - Size: start
small(192Mi usable). The eviction policy and persistence cannot be changed after creation, but you can watch usage live withplatformctl memorystore stats <name>and recreate deliberately if you outgrow it.
Summary
| Question | Answer |
|---|---|
| Where do my agent's sessions live? | A platform-operated shared Valkey 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 Engine's 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? | Private hostname + password from 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.