Session Management

A session is a single, continuous conversation with an agent. Sessions give the agent a stable identity to attach history, state, and summaries to — and let you resume a conversation later by reusing the same identifier.

Session identity

Parameter	Type	Purpose
session_id	Optional[str]	The session identifier (autogenerated if not set).
session_name	Optional[str]	A human-readable name for the session.
session_state	Optional[Dict[str, Any]]	Arbitrary state persisted with the session.
cache_session	bool	Cache the session in memory (default True).
user_id	Optional[str]	The user the session belongs to.

from buddy.agent import Agent

agent = Agent(
    session_id="onboarding-2026-06",
    session_name="Customer onboarding",
    user_id="dana@example.com",
)

Reusing the same session_id (with persistent storage configured) lets the agent pick up where it left off.

Session state

session_state is a free-form dictionary that travels with the session. It is a natural place for tools to stash values between turns:

from buddy.tools import tool

@tool
def add_to_cart(item: str, agent) -> str:
    """Add an item to the user's cart."""
    cart = agent.session_state.setdefault("cart", [])
    cart.append(item)
    return f"Cart now has {len(cart)} item(s)."

agent = Agent(tools=[add_to_cart], session_state={"cart": []})

When add_state_in_messages=True, session-state variables can be referenced directly in the system and user messages. The agent also seeds state with current_user_id and current_session_id for convenience.

Spanning previous sessions

search_previous_sessions_history and num_history_sessions let an agent pull history from earlier sessions, not just the current one.

Session summaries

For long sessions, replaying every turn is wasteful. A session summary condenses the conversation into the important points. Enable it with enable_session_summaries:

from buddy.agent import Agent
from buddy.memory import AgentMemory
from buddy.memory.db.sqlite import SqliteMemoryDb

agent = Agent(
    memory=AgentMemory(db=SqliteMemoryDb(db_file="memory.db")),
    enable_session_summaries=True,
    user_id="dana@example.com",
)

The summary is produced by MemorySummarizer (buddy.memory.summarizer), which sends the session's (user, assistant) message pairs to a model and returns a SessionSummary:

class SessionSummary(BaseModel):
    summary: str                       # concise summary of the session
    topics: Optional[List[str]] = None # topics discussed

With AgentMemory, you can also trigger and read summaries directly:

summary = agent.memory.update_summary()   # generate from current runs
print(summary.summary)
print(summary.topics)

Default model

If no model is supplied to the summarizer (or classifier/manager), Buddy AI falls back to OpenAIChat(id="gpt-4o"). Provide your own model to the helper to use a different provider.

When summaries are enabled, add_session_summary_references defaults to True, so summary context is referenced in the response. See User Memories for durable, cross-session facts and Memory Storage for persistence.