How to add short-term memory to your AI agent (Sessions & State Explained)

Key Concepts

• Session: A continuous conversation thread between a user and an AI agent.
• Short-term Memory: The ability of an agent to recall information within the current active session.
• Events: The chronological transcript of all user inputs (text/media) and agent responses.
• State: A structured "scratchpad" or key-value store used to save specific variables (e.g., restaurant names, confirmation numbers) for quick access.
• ADK (Agent Development Kit): The framework used to manage agent interactions, session services, and state persistence.

1. Understanding Session Management

A session represents a single, continuous interaction thread. By default, many systems use an "in-memory" session service. If a new session is initialized for every interaction, the agent suffers from "memory loss," effectively resetting its knowledge of the user's intent, context, and previous instructions.

• The Memory Loss Problem: In a trip-planning scenario, if a user asks for a "two-day trip to Lisbon" (Turn 1) and then asks to "Plan day two" (Turn 2) in a new session, the agent fails because it has no access to the city name or the context of Day 1.
• The Solution: Reusing the same session ID across multiple turns allows the agent to reference the full conversation history, enabling it to adapt its responses based on previous context.

2. Core Components of a Session

To manage memory effectively, the ADK utilizes two primary components:

• Events: These act as the historical record of the conversation. They include every message sent by the user (including media inputs like images) and every reply generated by the agent. This provides the "context" for the model.
• State: This functions as a structured sticky note. It is used to store specific, high-value data points that the agent needs to access frequently.
  • Rationale: Storing data in the state is more efficient than forcing the model to re-parse a long transcript of 15+ messages to find a single piece of information.

3. Agent Collaboration via Session State

The session state allows multiple agents to collaborate without needing to share the entire conversation transcript.

• Methodology:
  1. Agent A identifies a specific value (e.g., a restaurant name).
  2. The output is mapped to a specific key (e.g., destination).
  3. Agent B automatically receives the destination variable from the state, allowing it to provide directions without needing to re-process the original conversation.

4. Best Practices for State Management

A critical technical requirement when working with the ADK is how data is modified:

• The "Do Not" Rule: Never modify the session object directly within tool code. Direct modification bypasses the event log, meaning changes will not be recorded or persisted when moving to database-backed storage.
• The Correct Approach: Always use the context provided by the ADK (via tools or callbacks) to write to the state. This ensures the ADK records the change alongside the event, allowing for seamless recovery and persistence in future episodes (database/long-term memory).

5. Synthesis and Takeaways

• Short-term Memory as RAM: The current implementation of session-based memory acts like computer RAM—it is fast and highly effective for immediate tasks but is temporary and volatile.
• Persistence Strategy: The series establishes a progression:
  • Episode 1 (Current): In-memory session management (Short-term).
  • Episode 2: Moving to database storage for user preferences (Persistence).
  • Episode 3: Implementing long-term memory via the Vertex AI Memory Bank (Cross-session/Cross-media recall).
• Actionable Insight: To build a functional agent, developers must distinguish between the transcript (events) and the data (state), ensuring all state updates are funneled through the ADK context to maintain data integrity for future long-term storage.