Skip to content

Persist state across sessions

Keep an agent’s state and conversation history across restarts and requests. A session persists what the agent knows, so it can pick up where it left off even when your application restarts or runs across several machines.

What a session contains

Section titled “What a session contains”

A session holds the stateful information agents and multi-agent systems need to function, including:

Single Agent Sessions:

  • Conversation history (messages)
  • Agent state (key-value storage)
  • Other stateful information (like Conversation Manager)

Multi-Agent Sessions:

  • Orchestrator state and configuration
  • Individual agent states and result within the orchestrator
  • Cross-agent shared state and context
  • Execution flow and node transition history

Built-in session persistence captures and restores this information automatically, so an agent continues a conversation where it left off.

Beyond the built-in options, third-party session managers provide additional storage and memory capabilities.

Basic usage

Section titled “Basic usage”

Single agent sessions

Section titled “Single agent sessions”

Create an agent with a session manager and use it:

from strands import Agent
from strands.session import SnapshotSessionManager
from strands.storage import LocalFileStorage


# Create a snapshot session manager with a unique session ID
session_manager = SnapshotSessionManager(
    session_id="test-session",
    storage=LocalFileStorage("./sessions/"),
)


# Create an agent with the session manager
agent = Agent(session_manager=session_manager)


# Use the agent - all messages and state are automatically persisted
agent("Hello!")  # This conversation is persisted

Strands persists the conversation and its state to the underlying storage backend.

In Python, SnapshotSessionManager is the recommended manager for new single-agent sessions. FileSessionManager and S3SessionManager remain supported as the compatibility path for Graph, Swarm, bidirectional streaming, and existing repository-format sessions. TypeScript uses a single SessionManager for both.

FileSessionManager and S3SessionManager remain supported in Python, but use SnapshotSessionManager for new single-agent sessions.

Multi-agent sessions

Section titled “Multi-agent sessions”

Multi-agent systems (Graph/Swarm) can also use session management to persist their state.

Pass an explicit storage backend to SnapshotSessionManager:

from strands import Agent
from strands.multiagent import GraphBuilder
from strands.session import SnapshotSessionManager
from strands.storage import LocalFileStorage


researcher = Agent(name="researcher")
writer = Agent(name="writer")


session_manager = SnapshotSessionManager(
    session_id="multi-agent-session",
    storage=LocalFileStorage("./sessions/"),
    multi_agent_save_latest_on="node",
)


builder = GraphBuilder()
builder.add_node(researcher, "researcher")
builder.add_node(writer, "writer")
builder.add_edge("researcher", "writer")
builder.set_session_manager(session_manager)
graph = builder.build()


result = graph("Research and write about AI")

The default "node" strategy saves after every node and when the invocation ends. Use "invocation" to reduce storage writes and save only when the invocation ends. See the API reference for MultiAgentSaveLatestStrategy and its accepted values.

Multi-agent session managers only track the current state of the Graph/Swarm execution and do not persist individual agent conversation histories.

Reading the session ID

Section titled “Reading the session ID”

An agent exposes its session identifier through a readable agent.session_idagent.sessionId property. When a session manager is attached, the property returns the manager’s session_idsessionId (also readable directly on the session manager). Without a session manager, it returns a random 8-character hex string generated at construction, unique per agent instance but not persisted across restarts.

Snapshot-based session managers accept any Storage backend, including InMemoryStorage, LocalFileStorage, S3Storage, and custom implementations. See Storage for backend configuration, tradeoffs, custom backends, and required S3 permissions.

from strands import Agent
from strands.session import SnapshotSessionManager
from strands.storage import LocalFileStorage


session_manager = SnapshotSessionManager(
    session_id="user-123",
    storage=LocalFileStorage("./sessions/"),
)
agent = Agent(session_manager=session_manager)


print(agent.session_id)            # "user-123"
print(session_manager.session_id)  # "user-123"


# Without a session manager, the id is a generated, non-persisted handle
print(Agent().session_id)          # e.g. "a1b2c3d4"

Storage backends

Section titled “Storage backends”

Storage is the single place persistence backends are documented. How session management reaches a backend depends on the manager:

  • SnapshotSessionManager (Python) and SessionManager (TypeScript) compose the shared Storage abstraction: you pass any Storage backend and the manager persists snapshots through it. Manager-level storage takes precedence over an agent-level storage. If neither provides storage, Python falls back to LocalFileStorage("./.strands/") and TypeScript fails during initialization.
  • FileSessionManager and S3SessionManager (Python, compatibility path) configure storage directly with a storage directory or an S3 bucket. They do not take a Storage backend.

The examples below show each form.

The recommended SnapshotSessionManager accepts any Storage backend, so you choose durability the same way the offloader and memory subsystems do:

from strands import Agent
from strands.session import SnapshotSessionManager
from strands.storage import LocalFileStorage, S3Storage


# File-based persistence (development, single-machine)
session_manager = SnapshotSessionManager(
    session_id="user-123",
    storage=LocalFileStorage("./sessions/"),
)


# S3-based persistence (production, distributed)
session_manager = SnapshotSessionManager(
    session_id="user-123",
    storage=S3Storage(bucket="my-agent-sessions", prefix="production/"),
)


agent = Agent(session_manager=session_manager)

The repository-based managers cover Graph, Swarm, bidirectional streaming, and existing repository-format sessions. They configure storage directly rather than through a Storage backend:

Session ManagerPersistenceBest for
FileSessionManagerLocal diskDevelopment, single-machine
S3SessionManagerAmazon S3Production, distributed
from strands import Agent
from strands.session import FileSessionManager, S3SessionManager


# File-based persistence
session_manager = FileSessionManager(
    session_id="user-123",
    storage_dir="/path/to/sessions",
)


# S3-based persistence
session_manager = S3SessionManager(
    session_id="user-123",
    bucket="my-agent-sessions",
    prefix="production/",
)


agent = Agent(session_manager=session_manager)

How session management works

Section titled “How session management works”

Snapshot-based session managers

Section titled “Snapshot-based session managers”

SnapshotSessionManager in Python and SessionManager in TypeScript persist a complete point-in-time snapshot. For single agents, both restore snapshot_latest during initialization and support immutable checkpoints. For graph and swarm, both restore the latest orchestrator snapshot before the first invocation.

Single Agent Events

  • Agent Initialization: When an agent is created with a session manager, it automatically restores any existing state and messages from the session.
  • Message Addition: When a new message is added to the conversation, it’s automatically persisted to the session (SnapshotSessionManager does this under save_latest_on="message").
  • Agent Invocation: After each agent invocation, the agent state is synchronized with the session to capture any updates (SnapshotSessionManager default, save_latest_on="invocation").
  • Message Redaction: When sensitive information needs to be redacted, the session manager replaces the original message with a redacted version while maintaining conversation flow. SnapshotSessionManager flushes the redacted content to the latest snapshot under every strategy.
  • Snapshot Trigger (SnapshotSessionManager): Creates an immutable checkpoint when the snapshot_trigger callback returns True.

Multi-Agent Events

  • Before Multi-Agent Invocation: Restores orchestrator state from snapshot_latest on the first invocation.
  • After Node Call (multi_agent_save_latest_on="node", default): Saves after each node and again when the invocation ends.
  • After Multi-Agent Invocation (multi_agent_save_latest_on="invocation"): Saves only when the full invocation ends.

Repository-based session managers

Section titled “Repository-based session managers”

Immutable snapshots

Section titled “Immutable snapshots”

A snapshot captures agent state at a point in time. Snapshot-based session managers persist them for you: alongside snapshot_latest, SnapshotSessionManager (Python) and SessionManager (TypeScript) keep immutable snapshots, append-only checkpoints identified by UUID v7. These enable time-travel restore: you can restore the agent to any prior checkpoint, not just the latest state.

Creating immutable snapshots

Section titled “Creating immutable snapshots”

Use the snapshot-trigger callback to control when an immutable snapshot is created. The callback receives the current agent data and returns a boolean:

from strands import Agent
from strands.session import SnapshotSessionManager
from strands.storage import LocalFileStorage


session_manager = SnapshotSessionManager(
    session_id="my-session",
    storage=LocalFileStorage("./sessions/"),
    snapshot_trigger=lambda *, agent_data, **_: len(agent_data.messages) % 4 == 0,
)


agent = Agent(session_manager=session_manager)

Listing and restoring snapshots

Section titled “Listing and restoring snapshots”

Snapshot IDs are UUID v7, so they sort lexicographically in chronological order. Use list_snapshot_idslistSnapshotIds on the session manager to retrieve them, then pass a snapshot_idsnapshotId to restore_snapshotrestoreSnapshot:

import asyncio


from strands import Agent
from strands.session import SnapshotSessionManager
from strands.storage import LocalFileStorage


session_manager = SnapshotSessionManager(
    session_id="my-session",
    storage=LocalFileStorage("./sessions/"),
)
agent = Agent(session_manager=session_manager)




async def restore() -> None:
    # Force an immutable checkpoint and read it back later
    snapshot_id = await session_manager.save_snapshot(agent, is_latest=False)
    snapshot_ids = await session_manager.list_snapshot_ids(agent)
    assert snapshot_id in snapshot_ids
    await session_manager.restore_snapshot(agent, snapshot_id=snapshot_id)




asyncio.run(restore())

Deleting sessions

Section titled “Deleting sessions”

To remove all snapshots for a session, call the session manager’s delete method. This removes the entire session root directory (filesystem) or all objects under the session prefix (S3):

import asyncio


from strands.session import SnapshotSessionManager
from strands.storage import LocalFileStorage


session_manager = SnapshotSessionManager(
    session_id="my-session",
    storage=LocalFileStorage("./sessions/"),
)
asyncio.run(session_manager.delete_session())

Data models

Section titled “Data models”

SnapshotSessionManager stores a single versioned Snapshot JSON blob whose data field carries the messages, agent state, conversation manager state, interrupt state, model state, and system prompt.

The record-based models below apply to FileSessionManager, S3SessionManager, and RepositorySessionManager, which persist each message individually:

Session

The Session model is the top-level container for session data:

  • Purpose: Provides a namespace for organizing multiple agents and their interactions
  • Key Fields:
    • session_id: Unique identifier for the session
    • session_type: Type of session (currently "AGENT" for both agent & multiagent in order to keep backward compatibility)
    • created_at: ISO format timestamp of when the session was created
    • updated_at: ISO format timestamp of when the session was last updated

SessionAgent

The SessionAgent model stores agent-specific data:

  • Purpose: Maintains the state and configuration of a specific agent within a session
  • Key Fields:
    • agent_id: Unique identifier for the agent within the session
    • state: Dictionary containing the agent’s state data (key-value pairs)
    • conversation_manager_state: Dictionary containing the state of the conversation manager
    • created_at: ISO format timestamp of when the agent was created
    • updated_at: ISO format timestamp of when the agent was last updated

SessionMessage

The SessionMessage model stores individual messages in the conversation:

  • Purpose: Preserves the conversation history with support for message redaction
  • Key Fields:
    • message: The original message content (role, content blocks)
    • redact_message: Optional redacted version of the message (used when sensitive information is detected)
    • message_id: Index of the message in the agent’s messages array
    • created_at: ISO format timestamp of when the message was created
    • updated_at: ISO format timestamp of when the message was last updated

These data models work together to provide a complete representation of an agent’s state and conversation history. The session management system handles serialization and deserialization of these models, including special handling for binary data using base64 encoding.

Multi-Agent State

Multi-agent systems serialize their state as JSON objects containing:

  • Orchestrator Configuration: Settings, parameters, and execution preferences
  • Node State: Current execution state and node transition history
  • Shared Context: Cross-agent shared state and variables

Third-party session managers

Section titled “Third-party session managers”

The following third-party session managers extend Strands with additional storage and memory capabilities:

Session ManagerProviderDescriptionDocumentation
AgentCoreMemorySessionManagerAmazonAdvanced memory with intelligent retrieval using Amazon Bedrock AgentCore Memory. Supports both short-term memory (STM) and long-term memory (LTM) with strategies for user preferences, facts, and session summaries.View Documentation
Contribute Your OwnCommunityHave you built a session manager? Share it with the community!Learn How

Custom session repositories

Section titled “Custom session repositories”

For advanced use cases, you can implement your own session storage backend.

For new single-agent sessions, implement a custom Storage backend and pass it to SnapshotSessionManager: the manager owns the session layout, so the backend only moves bytes.

To customize a repository-based session, implement the SessionRepository interface:

from typing import Optional
from strands import Agent
from strands.session.repository_session_manager import RepositorySessionManager
from strands.session.session_repository import SessionRepository
from strands.types.session import Session, SessionAgent, SessionMessage


class CustomSessionRepository(SessionRepository):
    """Custom session repository implementation."""


    def __init__(self):
        """Initialize with your custom storage backend."""
        # Initialize your storage backend (e.g., database connection)
        self.db = YourDatabaseClient()


    def create_session(self, session: Session) -> Session:
        """Create a new session."""
        self.db.sessions.insert(asdict(session))
        return session


    def read_session(self, session_id: str) -> Optional[Session]:
        """Read a session by ID."""
        data = self.db.sessions.find_one({"session_id": session_id})
        if data:
            return Session.from_dict(data)
        return None


    # Implement other required methods...
    # create_agent, read_agent, update_agent
    # create_message, read_message, update_message, list_messages


# Use your custom repository with RepositorySessionManager
custom_repo = CustomSessionRepository()
session_manager = RepositorySessionManager(
    session_id="user-789",
    session_repository=custom_repo
)


agent = Agent(session_manager=session_manager)

This lets you store session data in any backend while reusing the built-in session management logic.

Data layout

Section titled “Data layout”

Both file and S3 backends use the same key structure:

SnapshotSessionManager layout (recommended for new single-agent sessions). The Storage backend prepends a session/ namespace, so the layout is byte-identical to the TypeScript SDK:

<root>/
└── session/
    └── <session_id>/
        └── scopes/
            └── agent/
                └── <agent_id>/
                    └── snapshots/
                        ├── snapshot_latest.json
                        └── immutable_history/
                            └── snapshot_<uuid7>.json

Repository-based layout (FileSessionManager, S3SessionManager):

<root>/
└── session_<session_id>/
    ├── session.json
    ├── agents/
    │   └── agent_<agent_id>/
    │       ├── agent.json
    │       └── messages/
    │           ├── message_0.json
    │           └── message_1.json
    └── multi_agents/
        └── multi_agent_<orchestrator_id>/
            └── multi_agent.json

Using the same session ID and storage location does not migrate repository-based Python data to SnapshotSessionManager. Existing sessions can continue using their current manager, or applications can migrate the required state explicitly.

Sessions, agents, and concurrency

Section titled “Sessions, agents, and concurrency”

Session management is designed around a single live writer per conversation: the session ID plus the agent ID (agent_idid), or the orchestrator ID for a Graph or Swarm, address one conversation thread in storage.

One conversation per session

Section titled “One conversation per session”

Give each conversation its own session ID. Several agents can share one session ID as long as their agent IDs differ: the session acts as a namespace, and each agent keeps its own messages and state inside it. A single agent instance processes one invocation at a time by default and rejects overlap, as described in Concurrent Invocations.

Create an agent per conversation

Section titled “Create an agent per conversation”

Constructing an agent is cheap: it wires up tools, hooks, and plugins locally and makes no model call. Build one per request, invoke it, and let it go out of scope. The model provider is the part worth reusing: providers such as BedrockModel build their client in the constructor, so create the provider once per process and pass the same instance to every agent.

Common failure modes

Section titled “Common failure modes”

The built-in session managers take no distributed lock, and the single-instance invocation guard is in-process, so neither can detect a second writer running elsewhere. Two patterns result:

  • Two live agents addressing the same session ID and agent ID. The default IDs (agent_id="default"id: 'agent') make this easy to do by accident, including across separate executions that each build their own agent. Overlapping invocations overwrite each other’s turns, sequential ones merge two conversations into one history, and neither call errors.
  • Two callers creating the same session at the same time. Session creation is a check followed by a write, not an atomic operation, so simultaneous cold starts on a new session ID can both succeed, with the later write winning.

Session persistence best practices

Section titled “Session persistence best practices”

When implementing session persistence in your applications, consider these best practices:

  • Use Unique Session IDs: Generate unique session IDs for each user or conversation context to prevent data overlap.
  • Session Cleanup: Implement a strategy for cleaning up old or inactive sessions. Consider adding TTL (Time To Live) for sessions in production environments.
  • Understand Persistence Triggers: Remember that changes to agent state or messages are only persisted during specific lifecycle events.
  • Concurrent Access: Session managers are not thread-safe and take no distributed lock. See Sessions, Agents, and Concurrency.
  • Secure Storage Directories: The session storage directory is a trusted data store. Restrict filesystem permissions so that only the agent process can read and write to it. In shared or multi-tenant environments (shared volumes, containers), be aware that the SDK does not block symlinks in the session storage directory. If an attacker with write access to the storage directory creates a symlink (e.g., message_0.json pointing to an arbitrary file), the SDK will follow it, which could cause sensitive file contents to be loaded into the agent’s conversation history.