Session Management

Session management in Kern gives you control over how sessions are identified, named, and cached for optimal performance. Runs can pause for human-in-the-loop requirements and continue after those requirements are resolved.

Session IDs

Every session has a unique identifier (session_id) that tracks conversations across multiple runs:

• Auto-generated: If not provided, Kern generates a UUID automatically
• Manual: You can provide your own session IDs for custom tracking
• Per-user: Combine with user_id to track multiple users' sessions

1from kern.agent import Agent
2from kern.models.openai import OpenAIResponses
3from kern.db.sqlite import SqliteDb
4
5agent = Agent(
6    model=OpenAIResponses(id="gpt-5.2"),
7    db=SqliteDb(db_file="tmp/agent.db"),
8)
9
10# Use your own session ID
11agent.run("Hello", session_id="user_123_session_456")

1from kern.team import Team
2from kern.models.openai import OpenAIResponses
3from kern.db.sqlite import SqliteDb
4
5team = Team(
6    model=OpenAIResponses(id="gpt-5.2"),
7    members=[...],
8    db=SqliteDb(db_file="tmp/team.db"),
9)
10
11# Use your own session ID
12team.run("Hello", session_id="user_123_session_789")

Access to Messages & Chat History

You can access the messages in a session using the get_messages method:

1session = agent.get_session(session_id="session_123")
2messages = session.get_messages()

1session = team.get_session(session_id="session_456")
2messages = session.get_messages()

This gives you all messages for all runs in the session, including tool calls and system messages.

For a simpler list of only user and assistant messages, you can use the get_chat_history method:

1messages = agent.get_chat_history(session_id="session_123")

1messages = team.get_chat_history(session_id="session_456")

See the detailed AgentSession reference and TeamSession reference for more information.

Session Naming

Session names are human-readable labels that make it easier to identify and manage conversations—perfect for inbox-style UIs, support queues, or linking a conversation back to an external ticket.

Manual Naming

Set custom names using set_session_name():

1agent.set_session_name(session_id="session_001", session_name="Product Launch Planning")
2name = agent.get_session_name(session_id="session_001")

1team.set_session_name(session_id="session_001", session_name="Product Launch Planning")
2name = team.get_session_name(session_id="session_001")

Tips:

• Treat the session ID as the source of truth; names are just metadata for humans
• Rename conversations whenever the topic shifts—there's no limit on how often you call the method
• Need guardrails or naming policies? Wrap set_session_name in your own helper before exposing it to end-users

Auto-generated Names

Let the AI generate meaningful names from conversation content:

1session = agent.set_session_name(
2    session_id="session_123",
3    autogenerate=True,
4)
5# Access the generated name
6name = agent.get_session_name(session_id="session_123")
7print(name)  # e.g. "E-commerce API Planning"

1session = team.set_session_name(
2    session_id="session_456",
3    autogenerate=True,
4)
5# Access the generated name
6name = team.get_session_name(session_id="session_456")
7print(name)  # e.g. "Product Launch Strategy"

Calling set_session_name(autogenerate=True) asks the model to read the first few messages in the session and generate a short (≤5 words) label. The method returns the updated session object. Use get_session_name() to retrieve the generated name.

Best Practices:

• Delay generation until the conversation has meaningful context (e.g., after 2–3 messages)
• Provide a fallback: wrap the call in your own helper that falls back to a human-entered name or a ticket ID if the generation fails
• Batch jobs: loop over session IDs from your database and call set_session_name(..., autogenerate=True) once for each. The API is synchronous, so plan around model latency
• Costs: Each generation is an extra model call. Use cheaper models via session_summary_manager or run it out-of-band if you're cost sensitive

Session Caching

Session caching stores the session object in memory to improve performance. cache_session=True keeps the hydrated session object in memory after the first database read, avoiding extra queries for subsequent runs.

1from kern.agent import Agent
2from kern.models.openai import OpenAIResponses
3
4agent = Agent(
5    model=OpenAIResponses(id="gpt-5.2"),
6    session_id="my_session",
7    cache_session=True,  # Enable in-memory caching
8)
9
10# First run loads from database and caches
11agent.run("First message")
12
13# Subsequent runs use cached session (faster)
14agent.run("Second message")

1from kern.team import Team
2from kern.models.openai import OpenAIResponses
3
4team = Team(
5    model=OpenAIResponses(id="gpt-5.2"),
6    session_id="team_session",
7    cache_session=True,  # Enable in-memory caching
8)
9
10# First run loads from database and caches
11team.run("First message")
12
13# Subsequent runs use cached session (faster)
14team.run("Second message")

When It Helps

• Many sequential turns in the same session (support chats, copilots, etc.)
• Latency-sensitive deployments where every DB round trip matters
• Resource-heavy databases (remote Postgres, serverless drivers) where connection setup dominates