openai-agents-persql 0.1.0

OpenAI Agents SDK session memory backed by PerSQL — durable conversation history in an isolated SQLite database per agent.

openai-agents-persql

Session memory for the OpenAI Agents SDK backed by PerSQL — durable conversation history in an isolated SQLite database per agent.

pip install openai-agents-persql

Usage

import os
from agents import Agent, Runner
from persql import PerSQL
from openai_agents_persql import PerSQLSession

client = PerSQL(token=os.environ["PERSQL_TOKEN"])
session = PerSQLSession("user-42", client.database("acme/agent-state"))

agent = Agent(name="assistant", instructions="Be helpful.")
result = await Runner.run(agent, "hi", session=session)
result = await Runner.run(agent, "remember me?", session=session)  # history persists

Or let the session own its client:

with PerSQLSession.from_token("user-42", os.environ["PERSQL_TOKEN"], "acme/agent-state") as session:
    result = Runner.run_sync(agent, "hi", session=session)

Async apps can pass an AsyncPerSQLDatabase instead — calls are awaited natively rather than dispatched to a thread:

from persql import AsyncPerSQL

async with AsyncPerSQL(token=os.environ["PERSQL_TOKEN"]) as client:
    session = PerSQLSession("user-42", client.database("acme/agent-state"))
    result = await Runner.run(agent, "hi", session=session)

Storage layout

Two tables, created lazily on first use — the same layout as the SDK's built-in SQLiteSession:

• agent_sessions(session_id, created_at, updated_at)
• agent_messages(id, session_id, message_data, created_at)

Items are stored as JSON text, so the history is queryable like any other data:

SELECT session_id, COUNT(*) AS items, MAX(created_at) AS last_active
FROM agent_messages GROUP BY session_id ORDER BY 2 DESC;

Table names are configurable via sessions_table= / messages_table=.

Local tests, no network

The persql SDK's local mode runs the same session against in-process SQLite:

session = PerSQLSession("test", PerSQL(local=":memory:").database("test/db"))

Limits

• Each session operation is one HTTP round-trip to the database (reads and writes alike ride single query/batch calls) — the same trade-off as the SDK's SQLAlchemy session against a remote database.
• Rows are metered like any other PerSQL usage; see pricing.
• PerSQLSession implements the Session protocol (get_items / add_items / pop_item / clear_session). Compaction-aware extras (run_compaction) are not implemented.

License

MIT © PerSQL