Memory is what separates a useful agent from a frustrating one. Without it, every message is a blank slate. The agent forgets what you said 30 seconds ago. With the right memory configuration, your agent maintains conversation context, learns user preferences, and builds organizational knowledge over time. Xpander gives you three types of memory, each serving a different purpose. Configure them in the Memory tab of the Agent Studio.Documentation Index
Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
Use this file to discover all available pages before exploring further.
- Session Storage: conversation history within a thread
- User Memories: personal facts about each user that persist across all conversations
- Agent Memories: global knowledge that applies to all users
Session Storage
Session storage is short-term memory. It keeps the conversation history within a single thread so the agent remembers what was said earlier in the same conversation. Every conversation thread has its own history. As long as messages are in the same thread, the agent sees the full history up to the configured limit. Starting a new thread means a clean slate. The agent won’t remember what was said in a previous conversation. Multiple users can share the same thread (e.g., a support ticket where Alice opens the conversation and Bob follows up). Both see the same conversation history, but the thread is still self-contained. Nothing carries over to other threads. Each session storage is associated with one thread. Every session connects a user and the agent, and gets its own isolated storage right beside it.| Setting | What it does | Recommendation |
|---|---|---|
| No. of history runs | How many past runs the agent can see. A run is one full agent loop that begins with a user message and ends when the LLM finishes its response. A single run can include many tool calls. | 3–5 for most use cases. 10 if conversations are long and context-heavy. |
User Memories
User memories store personal facts about individual users that persist across all conversations. When Alice tells your agent “I prefer metric units” in Thread 1, the agent remembers that when she starts Thread 2, Thread 3, or any future conversation. User memories are scoped touser_id. They follow the user, not the thread.
Each user’s memories are completely isolated. Alice’s preferences never leak into Bob’s conversations, even when they interact with the same agent. This makes user memories safe for multi-tenant environments where personalization matters but privacy is critical.
User memory is associated with the user, not with any session or agent. Every session connects a user and the agent, but the memory sits right beside the user and follows them across all sessions.
| Setting | What it does |
|---|---|
| Enable User Memories | Turns the feature on or off. |
| Agentic managed | When enabled, the agent decides what to remember automatically. When disabled, memories must be created manually via the update_user_memory tool (actions: add, update, delete, clear). |
Agent Memories
Agent memories work like dynamic prompt management. When turned ON, xpander tells the agent to manage memories across each session using markdown files saved in the sandbox environment. This is useful for agent-specific memories that are helpful for all conversations with that agent. For example, “our support hours are 9-5 EST” or “the billing API was updated last week.” Agent memory is associated with the agent itself. Every session connects a user and the agent, and the memory sits right beside the agent, shared across every session.| Setting | What it does |
|---|---|
| Agentic Managed | When on, the agent manages its own memories as markdown files in the workspace. When off, agent memories are disabled. |
Agentic vs. Manual Memory
You have two choices for how memories get created and maintained.| Agentic Managed | Manual | |
|---|---|---|
| How memories are created | Agent decides what to save automatically | You (or your team) create memories manually |
| Maintenance | Self-updating, less work for you | Full control, more maintenance |
| Best for | Internal tools, single-tenant use cases, rapid iteration | Production systems, compliance environments, multi-tenant deployments |
| Risk | Agent may save inaccurate or unwanted information | Slower to learn, requires ongoing attention |
Memory Optimization
These settings help you manage token usage and performance for tool-heavy agents. They appear in the Memory tab in the order listed below.Max Tool Calls from History
Limits how many past tool call results are included when loading conversation history. Set to 0 (disabled) for most cases. Only enable if you’re consistently hitting token limits.Session Summaries
Automatically summarizes long conversations into a compact summary for future reference. This does not affect the agent’s context window. It’s metadata for monitoring and observability dashboards.Tool Calls Compression
When your agent makes many tool calls in a single conversation, the raw outputs pile up in context and eat through tokens. Tool calls compression condenses verbose outputs after a threshold number of calls.| Setting | What it does | Default |
|---|---|---|
| Enable compression | Turns on automatic compression of tool outputs. | Off |
| Threshold | Number of tool calls before compression kicks in. After N tool calls, summaries replace prior verbose results to keep context within limits. | 3 |
| Compression instructions | Optional guidance on what to keep vs. drop when compressing. Keep exact numbers, dates, entities, URLs, causal links; remove boilerplate and repetition. | - |
Memory Optimization Strategy
Controls how the agent manages its context window during long executions. This is especially useful for agents that handle extended conversations or make many tool calls in a single session.| Mode | What it does |
|---|---|
| Disabled | No optimization. The full conversation history (up to the configured history runs) is included as-is. This is the default. |
| Summarization | Condenses older messages while preserving key points and tool call results. Reduces token usage while retaining the important context from earlier in the conversation. |
| Context | Retains the initial instructions and the most recent messages, summarizing everything in between. Best for long-running executions where the beginning (task definition) and end (recent progress) matter most. |
Troubleshooting
Agent forgets what I said earlier in the conversation
Agent forgets what I said earlier in the conversation
Make sure you’re passing the same
session_id for all messages in the thread. Increase history runs to 3+.User memories aren't working
User memories aren't working
Verify
user_id is being passed consistently. Check that User Memories is toggled on.Agent is slow or hitting token limits
Agent is slow or hitting token limits
Reduce history runs. Enable tool calls compression. Lower max tool calls from history.
Agent remembered something it shouldn't have
Agent remembered something it shouldn't have
Review and delete the memory. Consider switching from agentic to manual management.
Agent memories affecting the wrong users
Agent memories affecting the wrong users
Agent memories are global. Move user-specific facts to User Memories instead.
Next Steps
AI Models & Intelligence
Model selection, planning mode, and reasoning mode
Knowledge Bases
Give your agent searchable document knowledge
Testing & Chat
Test memory behavior in the built-in chat
Agent Configuration
Full overview of all Agent Studio settings