strands-persql 0.1.0

AWS Strands Agents session persistence backed by PerSQL — durable sessions, agents, and messages in an isolated SQLite database per agent.

strands-persql

AWS Strands Agents session persistence backed by PerSQL — durable sessions, agents, and messages in an isolated SQLite database per agent, provisioned instantly.

pip install strands-persql

Usage

import os
from strands import Agent
from persql import PerSQL
from strands_persql import PerSQLSessionManager

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

agent = Agent(session_manager=manager)
agent("hi")  # history and state persist across restarts

Or let the manager own the client:

manager = PerSQLSessionManager.from_token("user-42", os.environ["PERSQL_TOKEN"], "acme/agent-state")

PerSQLSessionRepository is also exported for use with RepositorySessionManager or your own manager.

What it stores

The same data model as FileSessionManager, with tables instead of directories — one row per session (strands_sessions), per agent (strands_agents), and per message (strands_messages), each holding the dataclass's JSON. Multi-agent (Graph/Swarm) state goes to strands_multi_agents. Pass table_prefix= to change the strands_ prefix.

Limits

• The repository contract is synchronous, so calls block on HTTP to your PerSQL database (or run in-process in local mode).
• update_agent / update_message are read-then-write (to preserve created_at), not atomic over HTTP. Keep one writer per session — the same assumption Strands' file and S3 managers make.
• Requires strands-agents >= 1.42, < 2 — the package subclasses SessionRepository, so a framework major version can change the contract.

Local mode for tests

from persql import PerSQL
manager = PerSQLSessionManager("t", PerSQL(local=":memory:").database("test/db"))

Runs against in-process SQLite — no network, no token.