API

Services

class sqlspec.extensions.adk.SQLSpecSessionService

Bases: BaseSessionService

SQLSpec-backed implementation of BaseSessionService.

Provides session and event storage using SQLSpec database adapters. Delegates all database operations to a store implementation.

Parameters:

store (BaseAsyncADKStore) – Database store implementation (e.g., AsyncpgADKStore).

Example

from sqlspec.adapters.asyncpg import AsyncpgConfig from sqlspec.adapters.asyncpg.adk.store import AsyncpgADKStore from sqlspec.extensions.adk.service import SQLSpecSessionService

config = AsyncpgConfig(connection_config={“dsn”: “postgresql://…”}) store = AsyncpgADKStore(config) await store.ensure_tables()

service = SQLSpecSessionService(store) session = await service.create_session(

app_name=”my_app”, user_id=”user123”, state={“key”: “value”}

)

__init__(store)

Initialize the session service.

Parameters:

store (BaseAsyncADKStore) – Database store implementation.

property store: BaseAsyncADKStore

Return the database store.

async create_session(*, app_name, user_id, state=None, session_id=None)

Create a new session.

Parameters:

• app_name (str) – Name of the application.

• user_id (str) – ID of the user.

• state (dict[str, typing.Any] | None) – Initial state of the session.

• session_id (str | None) – Client-provided session ID. If None, generates a UUID.

Return type:

Session

Returns:

The newly created session.

async get_session(*, app_name, user_id, session_id, config=None)

Get a session by ID.

Parameters:

• app_name (str) – Name of the application.

• user_id (str) – ID of the user.

• session_id (str) – Session identifier.

• config (GetSessionConfig | None) – Configuration for retrieving events.

Return type:

Session | None

Returns:

Session object if found, None otherwise.

async list_sessions(*, app_name, user_id=None)

List all sessions for an app, optionally filtered by user.

Parameters:

• app_name (str) – Name of the application.

• user_id (str | None) – ID of the user. If None, all sessions for the app are listed.

Return type:

ListSessionsResponse

Returns:

Response containing list of sessions (without events).

async delete_session(*, app_name, user_id, session_id)

Delete a session and all its events.

Parameters:

• app_name (str) – Name of the application.

• user_id (str) – ID of the user.

• session_id (str) – Session identifier.

Return type:

None

async append_event(session, event)

Append an event to a session.

Persists the event record and the post-append durable state atomically via store.append_event_and_update_state(). temp: keys are stripped from the persisted state snapshot so they never survive a reload.

Parameters:

• session (Session) – Session to append to.

• event (Event) – Event to append.

Return type:

Event

Returns:

The appended event.

class sqlspec.extensions.adk.memory.SQLSpecMemoryService

Bases: BaseMemoryService

SQLSpec-backed implementation of BaseMemoryService.

Provides memory entry storage using SQLSpec database adapters. Delegates all database operations to a store implementation.

ADK BaseMemoryService defines two core methods: - add_session_to_memory(session) - Ingests session into memory (returns void) - search_memory(app_name, user_id, query) - Searches stored memories

Parameters:

store (BaseAsyncADKMemoryStore) – Database store implementation (e.g., AsyncpgADKMemoryStore).

Example

from sqlspec.adapters.asyncpg import AsyncpgConfig from sqlspec.adapters.asyncpg.adk.store import AsyncpgADKMemoryStore from sqlspec.extensions.adk.memory.service import SQLSpecMemoryService

config = AsyncpgConfig(

connection_config={“dsn”: “postgresql://…”}, extension_config={

“adk”: {

“memory_table”: “adk_memory_entries”, “memory_use_fts”: True,

}

}

) store = AsyncpgADKMemoryStore(config) await store.ensure_tables()

service = SQLSpecMemoryService(store) await service.add_session_to_memory(completed_session)

response = await service.search_memory(

app_name=”my_app”, user_id=”user123”, query=”previous conversation about Python”

)

__init__(store)

Initialize the memory service.

Parameters:

store (BaseAsyncADKMemoryStore) – Database store implementation.

property store: BaseAsyncADKMemoryStore

Return the database store.

async add_session_to_memory(session)

Add a completed session to the memory store.

Extracts all events with content from the session and stores them as searchable memory entries. Uses UPSERT to skip duplicates.

The Session object contains app_name and user_id properties. Events are converted to memory records and bulk inserted via store. Returns void per ADK BaseMemoryService contract.

Parameters:

session (Session) – Completed ADK Session with events.

Return type:

None

Notes

• Events without content are skipped

• Duplicate event_ids are silently ignored (idempotent)

• Uses bulk insert for efficiency

async add_events_to_memory(*, app_name, user_id, events, session_id=None, custom_metadata=None)

Add an explicit list of events to the memory service.

Same Event-to-MemoryRecord extraction logic as add_session_to_memory, but operates on a sequence of Events directly (no Session wrapper needed).

Parameters:

• app_name (str) – The application name for memory scope.

• user_id (str) – The user ID for memory scope.

• events (Sequence[Event]) – The events to add to memory.

• session_id (str | None) – Optional session ID for memory scope/partitioning. If None, memory entries are user-scoped only.

• custom_metadata (Mapping[str, object] | None) – Optional portable metadata stored in MemoryRecord.metadata_json.

Return type:

None

async add_memory(*, app_name, user_id, memories, custom_metadata=None)

Add explicit memory items directly to the memory service.

Each entry’s content is serialized to content_json, text is extracted from content.parts for content_text, and custom_metadata merges the entry-level entry.custom_metadata with the call-level custom_metadata parameter.

Parameters:

• app_name (str) – The application name for memory scope.

• user_id (str) – The user ID for memory scope.

• memories (Sequence[MemoryEntry]) – Explicit memory items to add.

• custom_metadata (Mapping[str, object] | None) – Optional portable metadata for memory writes. Merged with each entry’s custom_metadata.

Return type:

None

async search_memory(*, app_name, user_id, query)

Search memory entries by text query.

Uses the store’s configured search strategy (simple ILIKE or FTS).

Parameters:

• app_name (str) – Name of the application.

• user_id (str) – ID of the user.

• query (str) – Text query to search for.

Returns:

List[MemoryEntry].

Return type:

SearchMemoryResponse with memories

class sqlspec.extensions.adk.memory.SQLSpecSyncMemoryService

Bases: object

Synchronous SQLSpec-backed memory service.

Provides memory entry storage using SQLSpec sync database adapters. This is a sync-compatible version for use with sync drivers like SQLite.

Note: This does NOT inherit from BaseMemoryService since ADK’s base class requires async methods. Use this for sync-only deployments.

Parameters:

store (BaseSyncADKMemoryStore) – Sync database store implementation.

Example

from sqlspec.adapters.sqlite import SqliteConfig from sqlspec.adapters.sqlite.adk.store import SqliteADKMemoryStore from sqlspec.extensions.adk.memory.service import SQLSpecSyncMemoryService

config = SqliteConfig(

connection_config={“database”: “app.db”}, extension_config={

“adk”: {

“memory_table”: “adk_memory_entries”,

}

}

) store = SqliteADKMemoryStore(config) store.ensure_tables()

service = SQLSpecSyncMemoryService(store) service.add_session_to_memory(completed_session)

memories = service.search_memory(

app_name=”my_app”, user_id=”user123”, query=”Python discussion”

)

__init__(store)

Initialize the sync memory service.

Parameters:

store (BaseSyncADKMemoryStore) – Sync database store implementation.

property store: BaseSyncADKMemoryStore

Return the database store.

add_session_to_memory(session)

Add a completed session to the memory store.

Extracts all events with content from the session and stores them as searchable memory entries. Uses UPSERT to skip duplicates.

Parameters:

session (Session) – Completed ADK Session with events.

Return type:

None

search_memory(*, app_name, user_id, query)

Search memory entries by text query.

Parameters:

• app_name (str) – Name of the application.

• user_id (str) – ID of the user.

• query (str) – Text query to search for.

Return type:

list[MemoryEntry]

Returns:

List of MemoryEntry objects.

class sqlspec.extensions.adk.SQLSpecArtifactService

Bases: BaseArtifactService

SQLSpec-backed implementation of BaseArtifactService.

Composes SQL metadata storage with sqlspec/storage/ content backends to provide versioned artifact management for Google ADK.

Metadata (version number, filename, MIME type, custom metadata, canonical URI) is stored in a SQL table managed by the artifact store. Content bytes are stored in object storage (S3, GCS, Azure, local filesystem) via the storage registry.

Parameters:

• store (BaseAsyncADKArtifactStore) – Artifact metadata store implementation.

• artifact_storage_uri (str) – Base URI for content storage (e.g., "s3://my-bucket/adk-artifacts/", "file:///var/data/artifacts/"). Can also be a registered alias in the storage registry.

• registry (StorageRegistry | None) – Storage registry to use. Defaults to the global singleton.

Example

from sqlspec.adapters.asyncpg.adk.artifact_store import AsyncpgADKArtifactStore from sqlspec.extensions.adk.artifact import SQLSpecArtifactService

artifact_store = AsyncpgADKArtifactStore(config) await artifact_store.ensure_table()

service = SQLSpecArtifactService(

store=artifact_store, artifact_storage_uri=”s3://my-bucket/adk-artifacts/”,

)

version = await service.save_artifact(

app_name=”my_app”, user_id=”user123”, filename=”output.png”, artifact=part,

)

__init__(store, artifact_storage_uri, registry=None)

property store: BaseAsyncADKArtifactStore

Return the artifact metadata store.

property artifact_storage_uri: str

Return the base URI for content storage.

async save_artifact(*, app_name, user_id, filename, artifact, session_id=None, custom_metadata=None)

Save an artifact, returning the new version number.

Writes content to object storage first, then inserts the metadata row. If content write succeeds but metadata insert fails, the orphaned content blob is logged but not automatically cleaned up (eventual consistency is acceptable; orphan sweep can be added later).

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• filename (str) – Artifact filename.

• artifact (Part | dict[str, typing.Any]) – ADK Part or dict to save.

• session_id (str | None) – Session identifier (None for user-scoped).

• custom_metadata (dict[str, typing.Any] | None) – Optional per-version metadata dict.

Return type:

int

Returns:

The version number (0-based, incrementing).

async load_artifact(*, app_name, user_id, filename, session_id=None, version=None)

Load an artifact by reading metadata then fetching content.

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• filename (str) – Artifact filename.

• session_id (str | None) – Session identifier (None for user-scoped).

• version (int | None) – Specific version, or None for latest.

Return type:

Part | None

Returns:

Deserialized Part, or None if not found.

async list_artifact_keys(*, app_name, user_id, session_id=None)

List distinct artifact filenames.

When session_id is provided, returns both session-scoped and user-scoped filenames. When None, returns only user-scoped filenames.

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• session_id (str | None) – Session identifier.

Return type:

list[str]

Returns:

List of artifact filenames.

async delete_artifact(*, app_name, user_id, filename, session_id=None)

Delete an artifact and all its versions.

Deletes metadata rows first (fail-fast), then removes content objects from storage (best-effort).

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• filename (str) – Artifact filename.

• session_id (str | None) – Session identifier (None for user-scoped).

Return type:

None

async list_versions(*, app_name, user_id, filename, session_id=None)

List all version numbers for an artifact.

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• filename (str) – Artifact filename.

• session_id (str | None) – Session identifier (None for user-scoped).

Return type:

list[int]

Returns:

Sorted list of version numbers.

async list_artifact_versions(*, app_name, user_id, filename, session_id=None)

List all versions with full metadata for an artifact.

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• filename (str) – Artifact filename.

• session_id (str | None) – Session identifier (None for user-scoped).

Return type:

list[ArtifactVersion]

Returns:

List of ArtifactVersion objects ordered by version ascending.

async get_artifact_version(*, app_name, user_id, filename, session_id=None, version=None)

Get metadata for a specific artifact version.

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• filename (str) – Artifact filename.

• session_id (str | None) – Session identifier (None for user-scoped).

• version (int | None) – Version number, or None for latest.

Return type:

ArtifactVersion | None

Returns:

ArtifactVersion if found, None otherwise.

Session Stores

class sqlspec.extensions.adk.BaseAsyncADKStore

Bases: ABC, Generic[ConfigT]

Base class for async SQLSpec-backed ADK session stores.

Implements storage operations for Google ADK sessions and events using SQLSpec database adapters with async/await.

This abstract base class provides common functionality for all database-specific store implementations including: - Connection management via SQLSpec configs - Table name validation - Session and event CRUD operations

Subclasses must implement dialect-specific SQL queries and will be created in each adapter directory (e.g., sqlspec/adapters/asyncpg/adk/store.py).

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) – SQLSpec database configuration with extension_config[“adk”] settings.

Notes

Configuration is read from config.extension_config[“adk”]: - session_table: Sessions table name (default: “adk_sessions”) - events_table: Events table name (default: “adk_events”) - owner_id_column: Optional owner FK column DDL (default: None)

__init__(config)

Initialize the ADK store.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) – SQLSpec database configuration.

Notes

Reads configuration from config.extension_config[“adk”]: - session_table: Sessions table name (default: “adk_sessions”) - events_table: Events table name (default: “adk_events”) - owner_id_column: Optional owner FK column DDL (default: None)

property config: ConfigT

Return the database configuration.

property session_table: str

Return the sessions table name.

property events_table: str

Return the events table name.

property owner_id_column_ddl: str | None

Return the full owner ID column DDL (or None if not configured).

property owner_id_column_name: str | None

Return the owner ID column name only (or None if not configured).

abstractmethod async create_session(session_id, app_name, user_id, state, owner_id=None)

Create a new session.

Parameters:

• session_id (str) – Unique identifier for the session.

• app_name (str) – Name of the application.

• user_id (str) – ID of the user.

• state (dict[str, typing.Any]) – Session state dictionary.

• owner_id (Optional[typing.Any]) – Optional owner ID value for owner_id_column (if configured).

Return type:

SessionRecord

Returns:

The created session record.

abstractmethod async get_session(session_id)

Get a session by ID.

Parameters:

session_id (str) – Session identifier.

Return type:

SessionRecord | None

Returns:

Session record if found, None otherwise.

abstractmethod async update_session_state(session_id, state)

Update session state.

Parameters:

• session_id (str) – Session identifier.

• state (dict[str, typing.Any]) – New state dictionary.

Return type:

None

abstractmethod async list_sessions(app_name, user_id=None)

List all sessions for an app, optionally filtered by user.

Parameters:

• app_name (str) – Name of the application.

• user_id (str | None) – ID of the user. If None, returns all sessions for the app.

Return type:

list[SessionRecord]

Returns:

List of session records.

abstractmethod async delete_session(session_id)

Delete a session and its events.

Parameters:

session_id (str) – Session identifier.

Return type:

None

abstractmethod async append_event(event_record)

Append an event to a session.

Parameters:

event_record (EventRecord) – Event record to store.

Return type:

None

abstractmethod async append_event_and_update_state(event_record, session_id, state)

Atomically append an event and update the session’s durable state.

This is the authoritative durable write boundary for post-creation session mutations. The event insert and state update must succeed together or fail together.

Parameters:

• event_record (EventRecord) – Event record to store.

• session_id (str) – Session identifier whose state should be updated.

• state (dict[str, typing.Any]) – Post-append durable state snapshot (temp: keys already stripped by the service layer).

Return type:

None

abstractmethod async get_events(session_id, after_timestamp=None, limit=None)

Get events for a session.

Parameters:

• session_id (str) – Session identifier.

• after_timestamp (datetime | None) – Only return events after this time.

• limit (int | None) – Maximum number of events to return.

Return type:

list[EventRecord]

Returns:

List of event records ordered by timestamp ascending.

abstractmethod async create_tables()

Create the sessions and events tables if they don’t exist.

Return type:

None

async ensure_tables()

Create tables and emit a standardized log entry.

Return type:

None

class sqlspec.extensions.adk.BaseSyncADKStore

Bases: ABC, Generic[ConfigT]

Base class for sync SQLSpec-backed ADK session stores.

Implements storage operations for Google ADK sessions and events using SQLSpec database adapters with synchronous execution.

This abstract base class provides common functionality for sync database-specific store implementations including: - Connection management via SQLSpec configs - Table name validation - Session and event CRUD operations

Subclasses must implement dialect-specific SQL queries and will be created in each adapter directory (e.g., sqlspec/adapters/sqlite/adk/store.py).

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) – SQLSpec database configuration with extension_config[“adk”] settings.

Notes

Configuration is read from config.extension_config[“adk”]: - session_table: Sessions table name (default: “adk_sessions”) - events_table: Events table name (default: “adk_events”) - owner_id_column: Optional owner FK column DDL (default: None)

__init__(config)

Initialize the sync ADK store.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) – SQLSpec database configuration.

Notes

Reads configuration from config.extension_config[“adk”]: - session_table: Sessions table name (default: “adk_sessions”) - events_table: Events table name (default: “adk_events”) - owner_id_column: Optional owner FK column DDL (default: None)

property config: ConfigT

Return the database configuration.

property session_table: str

Return the sessions table name.

property events_table: str

Return the events table name.

property owner_id_column_ddl: str | None

Return the full owner ID column DDL (or None if not configured).

property owner_id_column_name: str | None

Return the owner ID column name only (or None if not configured).

abstractmethod create_session(session_id, app_name, user_id, state, owner_id=None)

Create a new session.

Parameters:

• session_id (str) – Unique identifier for the session.

• app_name (str) – Name of the application.

• user_id (str) – ID of the user.

• state (dict[str, typing.Any]) – Session state dictionary.

• owner_id (Optional[typing.Any]) – Optional owner ID value for owner_id_column (if configured).

Return type:

SessionRecord

Returns:

The created session record.

abstractmethod get_session(session_id)

Get a session by ID.

Parameters:

session_id (str) – Session identifier.

Return type:

SessionRecord | None

Returns:

Session record if found, None otherwise.

abstractmethod update_session_state(session_id, state)

Update session state.

Parameters:

• session_id (str) – Session identifier.

• state (dict[str, typing.Any]) – New state dictionary.

Return type:

None

abstractmethod list_sessions(app_name, user_id=None)

List all sessions for an app, optionally filtered by user.

Parameters:

• app_name (str) – Name of the application.

• user_id (str | None) – ID of the user. If None, returns all sessions for the app.

Return type:

list[SessionRecord]

Returns:

List of session records.

abstractmethod delete_session(session_id)

Delete a session and its events.

Parameters:

session_id (str) – Session identifier.

Return type:

None

abstractmethod create_event(event_id, session_id, app_name, user_id, author=None, actions=None, content=None, **kwargs)

Create a new event.

Parameters:

• event_id (str) – Unique event identifier.

• session_id (str) – Session identifier.

• app_name (str) – Application name.

• user_id (str) – User identifier.

• author (str | None) – Event author (user/assistant/system).

• actions (bytes | None) – Pickled actions object.

• content (dict[str, typing.Any] | None) – Event content (JSONB/JSON).

• **kwargs (Any) – Additional optional fields.

Return type:

EventRecord

Returns:

Created event record.

abstractmethod create_event_and_update_state(event_record, session_id, state)

Atomically create an event and update the session’s durable state.

This is the authoritative durable write boundary for post-creation session mutations. The event insert and state update must succeed together or fail together.

Parameters:

• event_record (EventRecord) – Event record to store.

• session_id (str) – Session identifier whose state should be updated.

• state (dict[str, typing.Any]) – Post-append durable state snapshot (temp: keys already stripped by the service layer).

Return type:

None

abstractmethod list_events(session_id)

List events for a session ordered by timestamp.

Parameters:

session_id (str) – Session identifier.

Return type:

list[EventRecord]

Returns:

List of event records ordered by timestamp ASC.

abstractmethod create_tables()

Create both sessions and events tables if they don’t exist.

Return type:

None

ensure_tables()

Create tables and emit a standardized log entry.

Return type:

None

Memory Stores

class sqlspec.extensions.adk.BaseAsyncADKMemoryStore

Bases: ABC, Generic[ConfigT]

Base class for async SQLSpec-backed ADK memory stores.

Implements storage operations for Google ADK memory entries using SQLSpec database adapters with async/await.

This abstract base class provides common functionality for all database-specific memory store implementations including: - Connection management via SQLSpec configs - Table name validation - Memory entry CRUD operations - Text search with optional full-text search support

Subclasses must implement dialect-specific SQL queries and will be created in each adapter directory (e.g., sqlspec/adapters/asyncpg/adk/store.py).

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) – SQLSpec database configuration with extension_config[“adk”] settings.

Notes

Configuration is read from config.extension_config[“adk”]: - memory_table: Memory table name (default: “adk_memory_entries”) - memory_use_fts: Enable full-text search when supported (default: False) - memory_max_results: Max search results (default: 20) - owner_id_column: Optional owner FK column DDL (default: None) - enable_memory: Whether memory is enabled (default: True)

__init__(config)

Initialize the ADK memory store.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) – SQLSpec database configuration.

Notes

Reads configuration from config.extension_config[“adk”]: - memory_table: Memory table name (default: “adk_memory_entries”) - memory_use_fts: Enable full-text search when supported (default: False) - memory_max_results: Max search results (default: 20) - owner_id_column: Optional owner FK column DDL (default: None) - enable_memory: Whether memory is enabled (default: True)

property config: ConfigT

Return the database configuration.

property memory_table: str

Return the memory table name.

property enabled: bool

Return whether memory store is enabled.

property use_fts: bool

Return whether full-text search is enabled.

property max_results: int

Return the max search results limit.

property owner_id_column_ddl: str | None

Return the full owner ID column DDL (or None if not configured).

property owner_id_column_name: str | None

Return the owner ID column name only (or None if not configured).

abstractmethod async create_tables()

Create the memory table and indexes if they don’t exist.

Should check self._enabled and skip table creation if False.

Return type:

None

async ensure_tables()

Create tables when enabled and emit a standardized log entry.

Return type:

None

abstractmethod async insert_memory_entries(entries, owner_id=None)

Bulk insert memory entries with deduplication.

Uses UPSERT pattern to skip duplicates based on event_id.

Parameters:

• entries (list[MemoryRecord]) – List of memory records to insert.

• owner_id (object | None) – Optional owner ID value for owner_id_column (if configured).

Return type:

int

Returns:

Number of entries actually inserted (excludes duplicates).

Raises:

RuntimeError – If memory store is disabled.

abstractmethod async search_entries(query, app_name, user_id, limit=None)

Search memory entries by text query.

Uses the configured search strategy (simple ILIKE or FTS).

Parameters:

• query (str) – Text query to search for.

• app_name (str) – Application name to filter by.

• user_id (str) – User ID to filter by.

• limit (int | None) – Maximum number of results (defaults to max_results config).

Return type:

list[MemoryRecord]

Returns:

List of matching memory records ordered by relevance/timestamp.

Raises:

RuntimeError – If memory store is disabled.

abstractmethod async delete_entries_by_session(session_id)

Delete all memory entries for a specific session.

Parameters:

session_id (str) – Session ID to delete entries for.

Return type:

int

Returns:

Number of entries deleted.

abstractmethod async delete_entries_older_than(days)

Delete memory entries older than specified days.

Used for TTL cleanup operations.

Parameters:

days (int) – Number of days to retain entries.

Return type:

int

Returns:

Number of entries deleted.

class sqlspec.extensions.adk.BaseSyncADKMemoryStore

Bases: ABC, Generic[ConfigT]

Base class for sync SQLSpec-backed ADK memory stores.

Implements storage operations for Google ADK memory entries using SQLSpec database adapters with synchronous execution.

This abstract base class provides common functionality for sync database-specific memory store implementations including: - Connection management via SQLSpec configs - Table name validation - Memory entry CRUD operations - Text search with optional full-text search support

Subclasses must implement dialect-specific SQL queries and will be created in each adapter directory (e.g., sqlspec/adapters/sqlite/adk/store.py).

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) – SQLSpec database configuration with extension_config[“adk”] settings.

Notes

Configuration is read from config.extension_config[“adk”]: - memory_table: Memory table name (default: “adk_memory_entries”) - memory_use_fts: Enable full-text search when supported (default: False) - memory_max_results: Max search results (default: 20) - owner_id_column: Optional owner FK column DDL (default: None) - enable_memory: Whether memory is enabled (default: True)

__init__(config)

Initialize the sync ADK memory store.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) – SQLSpec database configuration.

Notes

Reads configuration from config.extension_config[“adk”]: - memory_table: Memory table name (default: “adk_memory_entries”) - memory_use_fts: Enable full-text search when supported (default: False) - memory_max_results: Max search results (default: 20) - owner_id_column: Optional owner FK column DDL (default: None) - enable_memory: Whether memory is enabled (default: True)

property config: ConfigT

Return the database configuration.

property memory_table: str

Return the memory table name.

property enabled: bool

Return whether memory store is enabled.

property use_fts: bool

Return whether full-text search is enabled.

property max_results: int

Return the max search results limit.

property owner_id_column_ddl: str | None

Return the full owner ID column DDL (or None if not configured).

property owner_id_column_name: str | None

Return the owner ID column name only (or None if not configured).

abstractmethod create_tables()

Create the memory table and indexes if they don’t exist.

Should check self._enabled and skip table creation if False.

Return type:

None

ensure_tables()

Create tables when enabled and emit a standardized log entry.

Return type:

None

abstractmethod insert_memory_entries(entries, owner_id=None)

Bulk insert memory entries with deduplication.

Uses UPSERT pattern to skip duplicates based on event_id.

Parameters:

• entries (list[MemoryRecord]) – List of memory records to insert.

• owner_id (object | None) – Optional owner ID value for owner_id_column (if configured).

Return type:

int

Returns:

Number of entries actually inserted (excludes duplicates).

Raises:

RuntimeError – If memory store is disabled.

abstractmethod search_entries(query, app_name, user_id, limit=None)

Search memory entries by text query.

Uses the configured search strategy (simple ILIKE or FTS).

Parameters:

• query (str) – Text query to search for.

• app_name (str) – Application name to filter by.

• user_id (str) – User ID to filter by.

• limit (int | None) – Maximum number of results (defaults to max_results config).

Return type:

list[MemoryRecord]

Returns:

List of matching memory records ordered by relevance/timestamp.

Raises:

RuntimeError – If memory store is disabled.

abstractmethod delete_entries_by_session(session_id)

Delete all memory entries for a specific session.

Parameters:

session_id (str) – Session ID to delete entries for.

Return type:

int

Returns:

Number of entries deleted.

abstractmethod delete_entries_older_than(days)

Delete memory entries older than specified days.

Used for TTL cleanup operations.

Parameters:

days (int) – Number of days to retain entries.

Return type:

int

Returns:

Number of entries deleted.

Artifact Stores

class sqlspec.extensions.adk.BaseAsyncADKArtifactStore

Bases: ABC, Generic[ConfigT]

Base class for async SQLSpec-backed ADK artifact metadata stores.

Manages artifact version metadata in a SQL table. Content bytes are stored externally via sqlspec/storage/ backends and referenced by canonical URI in each metadata row.

Subclasses must implement dialect-specific SQL queries.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) – SQLSpec database configuration with extension_config[“adk”] settings.

Notes

Configuration is read from config.extension_config[“adk”]: - artifact_table: Artifact versions table name (default: “adk_artifact_versions”)

__init__(config)

Initialize the async ADK artifact store.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) – SQLSpec database configuration.

property config: ConfigT

Return the database configuration.

property artifact_table: str

Return the artifact versions table name.

abstractmethod async insert_artifact(record)

Insert an artifact version metadata row.

Parameters:

record (ArtifactRecord) – Artifact metadata record to insert.

Return type:

None

abstractmethod async get_artifact(app_name, user_id, filename, session_id=None, version=None)

Get a specific artifact version’s metadata.

When version is None, returns the latest version.

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• filename (str) – Artifact filename.

• session_id (str | None) – Session identifier (None for user-scoped).

• version (int | None) – Specific version number, or None for latest.

Return type:

ArtifactRecord | None

Returns:

Artifact record if found, None otherwise.

abstractmethod async list_artifact_keys(app_name, user_id, session_id=None)

List distinct artifact filenames.

When session_id is provided, returns filenames from both session-scoped and user-scoped artifacts. When None, returns only user-scoped artifact filenames.

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• session_id (str | None) – Session identifier (None for user-scoped only).

Return type:

list[str]

Returns:

List of distinct artifact filenames.

abstractmethod async list_artifact_versions(app_name, user_id, filename, session_id=None)

List all version records for an artifact, ordered by version ascending.

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• filename (str) – Artifact filename.

• session_id (str | None) – Session identifier (None for user-scoped).

Return type:

list[ArtifactRecord]

Returns:

List of artifact records ordered by version ascending.

abstractmethod async delete_artifact(app_name, user_id, filename, session_id=None)

Delete all version records for an artifact and return them.

The caller uses the returned records to clean up content from object storage. Metadata is deleted first (fail-fast); content cleanup is best-effort.

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• filename (str) – Artifact filename.

• session_id (str | None) – Session identifier (None for user-scoped).

Return type:

list[ArtifactRecord]

Returns:

List of deleted artifact records (needed for content cleanup).

abstractmethod async get_next_version(app_name, user_id, filename, session_id=None)

Get the next version number for an artifact.

Returns 0 if no versions exist (first version), otherwise max(version) + 1.

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• filename (str) – Artifact filename.

• session_id (str | None) – Session identifier (None for user-scoped).

Return type:

int

Returns:

Next version number (0-based).

abstractmethod async create_table()

Create the artifact versions table if it does not exist.

Return type:

None

async ensure_table()

Create the artifact table and emit a standardized log entry.

Return type:

None

class sqlspec.extensions.adk.BaseSyncADKArtifactStore

Bases: ABC, Generic[ConfigT]

Base class for sync SQLSpec-backed ADK artifact metadata stores.

Synchronous counterpart of BaseAsyncADKArtifactStore.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) – SQLSpec database configuration with extension_config[“adk”] settings.

__init__(config)

Initialize the sync ADK artifact store.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) – SQLSpec database configuration.

property config: ConfigT

Return the database configuration.

property artifact_table: str

Return the artifact versions table name.

abstractmethod insert_artifact(record)

Insert an artifact version metadata row.

Parameters:

record (ArtifactRecord) – Artifact metadata record to insert.

Return type:

None

abstractmethod get_artifact(app_name, user_id, filename, session_id=None, version=None)

Get a specific artifact version’s metadata.

When version is None, returns the latest version.

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• filename (str) – Artifact filename.

• session_id (str | None) – Session identifier (None for user-scoped).

• version (int | None) – Specific version number, or None for latest.

Return type:

ArtifactRecord | None

Returns:

Artifact record if found, None otherwise.

abstractmethod list_artifact_keys(app_name, user_id, session_id=None)

List distinct artifact filenames.

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• session_id (str | None) – Session identifier (None for user-scoped only).

Return type:

list[str]

Returns:

List of distinct artifact filenames.

abstractmethod list_artifact_versions(app_name, user_id, filename, session_id=None)

List all version records for an artifact, ordered by version ascending.

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• filename (str) – Artifact filename.

• session_id (str | None) – Session identifier (None for user-scoped).

Return type:

list[ArtifactRecord]

Returns:

List of artifact records ordered by version ascending.

abstractmethod delete_artifact(app_name, user_id, filename, session_id=None)

Delete all version records for an artifact and return them.

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• filename (str) – Artifact filename.

• session_id (str | None) – Session identifier (None for user-scoped).

Return type:

list[ArtifactRecord]

Returns:

List of deleted artifact records (needed for content cleanup).

abstractmethod get_next_version(app_name, user_id, filename, session_id=None)

Get the next version number for an artifact.

Parameters:

• app_name (str) – Application name.

• user_id (str) – User identifier.

• filename (str) – Artifact filename.

• session_id (str | None) – Session identifier (None for user-scoped).

Return type:

int

Returns:

Next version number (0-based).

abstractmethod create_table()

Create the artifact versions table if it does not exist.

Return type:

None

ensure_table()

Create the artifact table and emit a standardized log entry.

Return type:

None

Record Types

class sqlspec.extensions.adk.SessionRecord

Bases: TypedDict

Database record for a session.

Represents the schema for sessions stored in the database.

class sqlspec.extensions.adk.EventRecord

Bases: TypedDict

Database record for an event.

Stores the full ADK Event as a single JSON blob (event_json) alongside a small number of indexed scalar columns used for query filtering.

This design eliminates column drift with upstream ADK: new Event fields are automatically captured in event_json without schema changes.

class sqlspec.extensions.adk.MemoryRecord

Bases: TypedDict

Database record for a memory entry.

Represents the schema for memory entries stored in the database. Contains extracted content from ADK events for searchable long-term memory.

class sqlspec.extensions.adk.ArtifactRecord

Bases: TypedDict

Database record for an artifact version.

Represents the schema for artifact metadata stored in the database. Content is stored separately in object storage; this record tracks versioning, ownership, and the canonical URI pointing to the content.

The composite key is (app_name, user_id, session_id, filename, version), where session_id may be NULL for user-scoped artifacts.

Configuration

class sqlspec.extensions.adk.ADKConfig

Bases: TypedDict

Configuration options for ADK session and memory store extension.

All fields are optional with sensible defaults. Use in extension_config[“adk”]:

Configuration supports three deployment scenarios: 1. SQLSpec manages everything (runtime + migrations) 2. SQLSpec runtime only (external migration tools like Alembic/Flyway) 3. Selective features (sessions OR memory, not both)

Example

from sqlspec.adapters.asyncpg import AsyncpgConfig

config = AsyncpgConfig(

connection_config={“dsn”: “postgresql://localhost/mydb”}, extension_config={

“adk”: {

“session_table”: “my_sessions”, “events_table”: “my_events”, “memory_table”: “my_memories”, “memory_use_fts”: True, “owner_id_column”: “tenant_id INTEGER REFERENCES tenants(id)”

}

}

)

Notes

This TypedDict provides type safety for extension config but is not required. You can use plain dicts as well.

enable_sessions: NotRequired[bool]

True.

When False: session service unavailable, session store operations disabled. Independent of migration control - can use externally-managed tables.

Type:

Enable session store at runtime. Default

enable_memory: NotRequired[bool]

True.

When False: memory service unavailable, memory store operations disabled. Independent of migration control - can use externally-managed tables.

Type:

Enable memory store at runtime. Default

include_sessions_migration: NotRequired[bool]

True.

When False: session migration DDL skipped (use external migration tools). Decoupled from enable_sessions - allows external table management with SQLSpec runtime.

Type:

Include session tables in SQLSpec migrations. Default

include_memory_migration: NotRequired[bool]

True.

When False: memory migration DDL skipped (use external migration tools). Decoupled from enable_memory - allows external table management with SQLSpec runtime.

Type:

Include memory tables in SQLSpec migrations. Default

session_table: NotRequired[str]

‘adk_sessions’

Examples

“agent_sessions” “my_app_sessions” “tenant_acme_sessions”

Type:

Name of the sessions table. Default

events_table: NotRequired[str]

‘adk_events’

Examples

“agent_events” “my_app_events” “tenant_acme_events”

Type:

Name of the events table. Default

memory_table: NotRequired[str]

‘adk_memory_entries’

Examples

“agent_memories” “my_app_memories” “tenant_acme_memories”

Type:

Name of the memory entries table. Default

artifact_table: NotRequired[str]

‘adk_artifact_versions’

Examples

“agent_artifacts” “my_app_artifact_versions”

Type:

Name of the artifact versions table. Default

artifact_storage_uri: NotRequired[str]

Base URI for artifact content storage.

Points to a sqlspec/storage/ backend where artifact binary content is stored. Can be a direct URI (s3://bucket/path, file:///path) or a registered alias in the storage registry.

Examples

“s3://my-bucket/adk-artifacts/” “file:///var/data/artifacts/” “gcs://my-gcs-bucket/artifacts/”

memory_use_fts: NotRequired[bool]

False.

When True, adapters will use their native FTS capabilities where available: - PostgreSQL: to_tsvector/to_tsquery with GIN index - SQLite: FTS5 virtual table - DuckDB: FTS extension with match_bm25 - Oracle: CONTAINS() with CTXSYS.CONTEXT index - BigQuery: SEARCH() function (requires search index) - Spanner: TOKENIZE_FULLTEXT with search index - MySQL: MATCH…AGAINST with FULLTEXT index

When False, adapters use simple LIKE/ILIKE queries (works without indexes).

Type:

Enable full-text search when supported. Default

memory_max_results: NotRequired[int]

Limits the number of memory entries returned by search_memory(). Can be overridden per-query via the limit parameter.

Type:

Maximum number of results for memory search queries. Default

owner_id_column: NotRequired[str]

Optional owner ID column definition to link sessions/memories to a user, tenant, team, or other entity.

Format: “column_name TYPE [NOT NULL] REFERENCES table(column) [options…]”

The entire definition is passed through to DDL verbatim. We only parse the column name (first word) for use in INSERT/SELECT statements.

This column is added to both session and memory tables for consistent multi-tenant isolation.

Supports:

• Foreign key constraints: REFERENCES table(column)

• Nullable or NOT NULL

• CASCADE options: ON DELETE CASCADE, ON UPDATE CASCADE

• Dialect-specific options (DEFERRABLE, ENABLE VALIDATE, etc.)

• Plain columns without FK (just extra column storage)

Examples

PostgreSQL with UUID FK:

“account_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE”

MySQL with BIGINT FK:

“user_id BIGINT NOT NULL REFERENCES users(id) ON DELETE RESTRICT”

Oracle with NUMBER FK:

“user_id NUMBER(10) REFERENCES users(id) ENABLE VALIDATE”

SQLite with INTEGER FK:

“tenant_id INTEGER NOT NULL REFERENCES tenants(id)”

Nullable FK (optional relationship):

“workspace_id UUID REFERENCES workspaces(id) ON DELETE SET NULL”

No FK (just extra column):

“organization_name VARCHAR(128) NOT NULL”

Deferred constraint (PostgreSQL):

“user_id UUID REFERENCES users(id) DEFERRABLE INITIALLY DEFERRED”

Notes

• Column name (first word) is extracted for INSERT/SELECT queries

• Rest of definition is passed through to CREATE TABLE DDL

• Database validates the DDL syntax (fail-fast on errors)

• Works with all database dialects (PostgreSQL, MySQL, SQLite, Oracle, etc.)

in_memory: NotRequired[bool]

False.

When enabled, tables are created with the INMEMORY clause for Oracle Database, which stores table data in columnar format in memory for faster query performance.

This is an Oracle-specific feature that requires:

• Oracle Database 12.1.0.2 or higher

• Database In-Memory option license (Enterprise Edition)

• Sufficient INMEMORY_SIZE configured in the database instance

Other database adapters ignore this setting.

Examples

Oracle with in-memory enabled:

config = OracleAsyncConfig(

connection_config={“dsn”: “oracle://…”}, extension_config={

“adk”: {

“in_memory”: True

}

}

)

Notes

• Improves query performance for analytics (10-100x faster)

• Tables created with INMEMORY clause

• Requires Oracle Database In-Memory option license

• Ignored by non-Oracle adapters

Type:

Enable in-memory table storage (Oracle-specific). Default

shard_count: NotRequired[int]

Optional hash shard count for session/event tables to reduce hotspotting.

When set (>1), adapters that support computed shard columns will create a generated shard_id using MOD(FARM_FINGERPRINT(primary_key), shard_count) and include it in the primary key and filters. Ignored by adapters that do not support computed shards.

session_table_options: NotRequired[str]

Adapter-specific table OPTIONS/clauses for the sessions table.

Passed verbatim when supported (e.g., Spanner columnar/tiered storage). Ignored by adapters without table OPTIONS support.

events_table_options: NotRequired[str]

Adapter-specific table OPTIONS/clauses for the events table.

memory_table_options: NotRequired[str]

Adapter-specific table OPTIONS/clauses for the memory table.

expires_index_options: NotRequired[str]

Adapter-specific options for the expires/index used in ADK stores.

fts_language: NotRequired[str]

‘english’.

Controls the language dictionary/stemmer used by FTS implementations: - PostgreSQL: to_tsvector/to_tsquery language parameter - SQLite FTS5: tokenizer language for unicode61/porter - MySQL: FULLTEXT parser language (with ngram for CJK on 5.7.6+) - Oracle: CTXSYS.CONTEXT lexer language - Spanner: TOKENIZE_FULLTEXT language parameter - DuckDB: FTS stemmer language

Only takes effect when memory_use_fts is True.

Common values: ‘english’, ‘simple’, ‘german’, ‘french’, ‘spanish’, ‘portuguese’, ‘italian’, ‘dutch’, ‘russian’, ‘chinese’, ‘japanese’, ‘korean’.

Notes

Available languages vary by backend. Backends that do not support the specified language will fall back to ‘simple’ or ‘english’.

Type:

Language configuration for full-text search indexing. Default

schema_version: NotRequired[int]

None (auto-detect).

When set, locks the ADK schema to a specific version. This is useful for: - Preventing automatic schema upgrades in production - Pinning to a known-good schema during testing - Coordinating schema changes across multiple application instances

When None, the ADK extension auto-detects the current schema version and applies any pending upgrades during initialization.

Notes

Schema versions are monotonically increasing integers managed by the ADK extension migration system. Setting this to a version lower than the current database schema will raise a configuration error at startup.

Type:

Explicit schema version for ADK tables. Default

partitioning: NotRequired[ADKPartitionConfig]

None (no partitioning).

Controls how ADK tables are partitioned for improved query performance and data management at scale. See ADKPartitionConfig for options.

Supported by: PostgreSQL, MySQL 8+, Oracle, BigQuery, Spanner. Ignored by: SQLite, DuckDB.

Type:

Table partitioning configuration. Default

retention: NotRequired[ADKRetentionConfig]

None (no automatic cleanup).

Controls automatic expiry and cleanup of old session, event, and memory data. See ADKRetentionConfig for options.

Backends with native TTL (CockroachDB, Spanner) use database-level enforcement. Others fall back to application-level sweep queries.

Type:

Data retention and TTL configuration. Default

compression: NotRequired[ADKCompressionConfig]

None (no compression).

Controls table-level compression for ADK tables. See ADKCompressionConfig for options.

Type:

Table compression configuration. Default

sqlite_optimization: NotRequired[ADKSqliteOptimizationConfig]

None (SQLite defaults).

Controls SQLite performance tuning parameters. Ignored by non-SQLite adapters. See ADKSqliteOptimizationConfig for options.

Type:

SQLite-specific PRAGMA optimization settings. Default

Converters

Conversion functions between ADK models and database records.

Implements full-event JSON storage: the entire Event is serialized via Event.model_dump_json(exclude_none=True) into a single event_json column, with a small set of indexed scalar columns extracted alongside for query performance. Reconstruction uses Event.model_validate_json().

Also provides scoped-state helpers that normalise ADK state prefixes (app:, user:, temp:) so the shared service layer can split, filter, and merge state before handing it to backend stores.

sqlspec.extensions.adk.converters.event_to_record(event, session_id)

Convert ADK Event to database record using full-event JSON storage.

The entire Event is serialized into event_json via Pydantic’s model_dump_json(exclude_none=True). A small number of indexed scalar columns are extracted alongside for query performance.

Parameters:

• event (Event) – ADK Event object.

• session_id (str) – ID of the parent session.

Return type:

EventRecord

Returns:

EventRecord for database storage.

sqlspec.extensions.adk.converters.filter_temp_state(state)

Return a copy of state with all temp: keys removed.

temp: keys are process-local/session-runtime state and must never be written to persistent storage.

Parameters:

state (dict[str, typing.Any]) – ADK state dictionary (may contain temp: prefixed keys).

Return type:

dict[str, typing.Any]

Returns:

A new dict without any temp:-prefixed keys.

sqlspec.extensions.adk.converters.merge_scoped_state(session_state, app_state=None, user_state=None)

Merge scoped state buckets into a single state dict.

Priority: session_state is base, app_state and user_state overlay. This matches ADK’s documented merge semantics on session load.

Parameters:

• session_state (dict[str, typing.Any]) – Per-session state.

• app_state (dict[str, typing.Any] | None) – App-scoped state (shared across sessions for same app).

• user_state (dict[str, typing.Any] | None) – User-scoped state (shared across sessions for same app+user).

Return type:

dict[str, typing.Any]

Returns:

Merged state dict.

sqlspec.extensions.adk.converters.record_to_event(record)

Convert database record to ADK Event.

Reconstruction is lossless: the full Event is restored from event_json via Event.model_validate_json().

Parameters:

record (EventRecord) – Event database record.

Return type:

Event

Returns:

ADK Event object.

sqlspec.extensions.adk.converters.record_to_session(record, events)

Convert database record to ADK Session.

Parameters:

• record (SessionRecord) – Session database record.

• events (list[EventRecord]) – List of event records for this session.

Return type:

Session

Returns:

ADK Session object.

sqlspec.extensions.adk.converters.session_to_record(session)

Convert ADK Session to database record.

Parameters:

session (Session) – ADK Session object.

Return type:

SessionRecord

Returns:

SessionRecord for database storage.

sqlspec.extensions.adk.converters.split_scoped_state(state)

Split state into app-scoped, user-scoped, and session-scoped buckets.

Parameters:

state (dict[str, typing.Any]) – Full session state dict (temp: already stripped).

Return type:

tuple[dict[str, typing.Any], dict[str, typing.Any], dict[str, typing.Any]]

Returns:

Tuple of (app_state, user_state, session_state). app_state: keys starting with “app:” user_state: keys starting with “user:” session_state: all other keys