@stackone/openai-agents-js-sessions

In-memory and SQLite, PostgreSQL, and MySQL with Drizzle ORM sessions for maintaining conversation history with OpenAI Agents JS SDK. This package is based on the OpenAI Agents Python SDK Sessions.

Features

• 🔄 Automatic conversation history management
• 💾 Multiple storage backends (In-Memory, Drizzle ORM)
• 🔌 Easy integration with OpenAI Agents
• 🎯 TypeScript support with full type definitions
• 📦 Zero configuration required
• 🗄️ Schema matches Python SDK (agent_sessions + agent_messages tables)

Installation

npm install @stackone/openai-agents-js-sessions

For database support, install the appropriate driver:

# SQLite
npm install drizzle-orm better-sqlite3

# PostgreSQL
npm install drizzle-orm pg

# MySQL
npm install drizzle-orm mysql2

Quick Start

InMemorySession

In-memory storage (data lost when process ends). Ideal for development and testing.

import { InMemorySession } from '@stackone/openai-agents-js-sessions';

const session = new InMemorySession('chat_123');

DrizzleSession

Drizzle ORM-powered storage supporting SQLite, PostgreSQL, and MySQL. Matches the Python SDK's SQLAlchemySession implementation with two tables:

• agent_sessions - Tracks session metadata (created_at, updated_at)
• agent_messages - Stores conversation messages with timestamps

import { DrizzleSession } from '@stackone/openai-agents-js-sessions';

// SQLite
const session = await DrizzleSession.fromUrl('chat_123', 'sqlite:./sessions.db');

// PostgreSQL
const session = await DrizzleSession.fromUrl('chat_123', 'postgres://user:pass@localhost:5432/mydb');

// MySQL
const session = await DrizzleSession.fromUrl('chat_123', 'mysql://user:pass@localhost:3306/mydb');

// With custom configuration
const session = await DrizzleSession.fromUrl('chat_123', 'postgres://localhost/db', {
    createTables: true          // Auto-create tables (default: true)
    maxRetries: 6,              // Maximum connection retry attempts (default: 3)
    retryDelay: 2000,           // Delay between retries in ms (default: 1000)
    connectionTimeout: 20000,   // Connection timeout in ms (default: 10000)
});

Usage with OpenAI Agents JS SDK

import { Agent, run, user, type AgentInputItem } from '@openai/agents';
import { InMemorySession } from '@stackone/openai-agents-js-sessions';

// Create your agent
const agent = new Agent({
  name: 'Customer Support',
  instructions: 'You are a helpful customer support assistant.',
  model: 'gpt-5.1',
});

// Create a session
const sessionId = 'chat_123';
const session = new InMemorySession(sessionId);

// First conversation turn
async function handleUserMessage(userMessage: string) {
  // Load existing conversation history
  const history = await session.getItems();
  
  // Add the new user message
  const newUserMessage = user(userMessage);
  const input: AgentInputItem[] = [...history, newUserMessage];
  
  // Run the agent with full conversation context
  const result = await run(agent, input);
  await result.completed;
  
  // Save the conversation (user message + agent response) to session
  const newItems = result.history.slice(history.length);
  await session.addItems([newUserMessage, ...newItems]);
  
  return result;
}

// Example conversation
await handleUserMessage('Hi, I need help with my order');
await handleUserMessage('It was order #12345'); // Agent remembers previous context
await handleUserMessage('Can you check the status?'); // Agent still has full context

API Reference

Session Interface

All session implementations provide the following methods:

getItems(limit?: number): Promise<AgentInputItem[]>

Retrieve the conversation history for this session.

• limit - Maximum number of items to retrieve. If undefined, retrieves all items.

addItems(items: AgentInputItem[]): Promise<void>

Add new items to the conversation history.

popItem(): Promise<AgentInputItem | undefined>

Remove and return the most recent item from the session.

clearSession(): Promise<void>

Clear all items for this session.

DrizzleSession

static fromUrl(sessionId: string, url: string, config?: ConnectionConfig): Promise<DrizzleSession>

Create a new database-backed session.

• sessionId - Unique identifier for this session
• url - Database connection URL:
  • SQLite: sqlite::memory: or sqlite:./path/to/db.sqlite
  • PostgreSQL: postgres://user:pass@host:port/database
  • MySQL: mysql://user:pass@host:port/database
• config - Optional connection configuration:
  • createTables - Auto-create tables if they don't exist (default: true)
  • maxRetries - Maximum connection retry attempts (default: 3)
  • retryDelay - Delay between retries in milliseconds (default: 1000)
  • connectionTimeout - Connection timeout in milliseconds (default: 10000)

close(): Promise<void>

Close the database connection and release resources (this is handled automatically).

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Fix linting issues
npm run lint:fix

Contributing

Contributions are welcome! Please follow the Conventional Commits specification for commit messages.

License

MIT © StackOne