Session, State, and Memory

ADK-TS provides a three-tier architecture for managing conversation data: Sessions for active conversation threads, State for dynamic conversation data, and Memory for long-term knowledge retrieval. Each layer serves a distinct purpose and can be customized to match your deployment requirements.

Core Components

What is Session?

A Session represents an individual conversation thread, similar to a chat thread in messaging apps. Each session contains:

• Message History: Chronological record of all interactions (events)
• State: Dynamic data specific to the conversation
• Metadata: Identification, timestamps, and tracking information

Sessions ensure your agents maintain context across multiple turns, enabling natural, coherent conversations.

What is State?

State is the agent's scratchpad for storing and updating information during a conversation. It supports:

• Scoped Storage: Session-level, user-level, and app-level data
• Dynamic Updates: Change state throughout the conversation
• Persistence: Automatic saving based on your session service
• Templating: Inject state values directly into agent instructions

State enables agents to remember user preferences, track multi-step workflows, and provide personalized experiences.

What is Memory?

Memory provides long-term knowledge storage that persists across conversations. It enables:

• Cross-Conversation Recall: Remember information from past interactions
• Semantic Search: Find relevant knowledge using natural language queries
• Knowledge Integration: Access external knowledge bases and documentation

While sessions handle short-term conversation context, memory provides the long-term knowledge your agents need to learn and improve over time.

Session Services

ADK-TS provides multiple session service implementations for different use cases:

• In-Memory: Fast and simple for development and testing. Data is lost on restart.
• Database (PostgreSQL, MySQL, SQLite): Production-ready persistence with full SQL support.
• Vertex AI: Enterprise Google Cloud-managed sessions with automatic scaling and backups.

Each implementation provides the same API, making them interchangeable. Choose based on your deployment needs.

Choosing Your Stack

With sessions and memory, you can mix and match implementations based on your needs:

Next Steps