Persisting Sessions

Store session data in a database for multi-turn conversations

To enable sessions across multiple runs, you need to configure a database. Once configured, Kern automatically stores conversation history, session state, and run metadata. Paused runs persist their status and requirements so they can be continued later.

Note

Database selection, connection strings, credentials management, and operational guidance live in the Database overview. Reuse that setup here—this page only adds the session-specific considerations.

Quick Start

Once you have a db object (Postgres, SQLite, DynamoDB, …) configured per the storage docs, persistence is enabled simply by passing it to your Agent, Team, or Workflow:

1db = PostgresDb(db_url="postgresql+psycopg://...")
2
3agent = Agent(
4    model=OpenAIResponses(id="gpt-5.2"),
5    db=db,                 # Enables persistence
6    session_id="user_123", # Same ID = same conversation
7)

Supported Databases

Nothing new lives here—simply reuse the database drivers and guidance from /basics/storage:

PostgreSQL (recommended) – Production-grade, supports custom session_table names for isolating workloads.
SQLite – Great for local development; swap the file path just as you would elsewhere.
InMemoryDb – Useful for tests or demos only. Data disappears when the process exits.

If you need to tune indexing, retention, or connection pools, do that in the shared storage layer so every feature (sessions, memories, knowledge, etc.) benefits from the same configuration.

Session IDs

Sessions are identified by session_id. Use the same ID to continue a conversation:

1# First run
2agent = Agent(
3    model=OpenAIResponses(id="gpt-5.2"),
4    db=db,
5    session_id="conversation_123",
6)
7agent.run("My name is Alice")
8
9# Later run with same session_id
10agent = Agent(
11    model=OpenAIResponses(id="gpt-5.2"),
12    db=db,
13    session_id="conversation_123",  # Same ID
14    add_history_to_context=True,     # Enable history
15)
16agent.run("What's my name?")  # Agent remembers "Alice"

Need custom naming conventions, caching, or UI-friendly labels? Continue with the Session Management guide.

What Gets Stored

When you configure a database, Kern automatically stores:

✅ Messages - User inputs and agent responses
✅ Run metadata - Timestamps, token usage, model info
✅ Session state - Custom key-value data
✅ Tool calls - Tool usage and results (optional)
✅ Media - Images, audio, files (optional)

See Storage Control to customize what gets saved.

Multi-User Sessions

Use user_id to track different users:

1agent = Agent(
2    model=OpenAIResponses(id="gpt-5.2"),
3    db=db,
4)
5
6# Specify the user_id and session_id on run to start or continue the conversation
7agent.print_response("Hello!", session_id="session_456", user_id="alice@example.com")

Session Storage Schema

When you configure a database, Kern stores sessions in a structured format. Here's what gets saved for each session:

Field	Type	Description
`session_id`	`str`	Unique identifier for this conversation thread
`session_type`	`str`	Type of session (agent, team, or workflow)
`agent_id`	`str`	The agent ID (if this is an agent session)
`team_id`	`str`	The team ID (if this is a team session)
`workflow_id`	`str`	The workflow ID (if this is a workflow session)
`user_id`	`str`	The user this session belongs to
`session_data`	`dict`	Session-specific data and state
`agent_data`	`dict`	Agent configuration and metadata
`team_data`	`dict`	Team configuration and metadata
`workflow_data`	`dict`	Workflow configuration and metadata
`metadata`	`dict`	Additional custom metadata
`runs`	`list`	All the runs (interactions) in this session
`summary`	`dict`	The session summary (if enabled)
`created_at`	`int`	Unix timestamp when session was created
`updated_at`	`int`	Unix timestamp of last update

Tip

Want to visualize your sessions? Check out the AgentOS UI sessions page for a beautiful interface to view and manage all your conversation threads.

Guides

Now that you have persistence configured, explore what you can do with sessions:

Storage Control - Optimize what gets saved
History Management - Control conversation history
Session Summaries - Condense long conversations
Session Management - Naming, caching, and more