Google ADK

SQLSpec provides session, event, memory, and artifact service contracts. These contracts support the Google Agent Development Kit.

Session Service

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 | BaseSyncADKStore) -- Database store implementation.

__init__(store)

Initialize the session service.

Parameters:

store (BaseAsyncADKStore | BaseSyncADKStore) -- Database store implementation.

property store: BaseAsyncADKStore | BaseSyncADKStore

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 get_user_state(*, app_name, user_id)

Get user-scoped state for an app and user.

ADK's service API returns unprefixed user state keys, while SQLSpec stores the durable state using ADK's documented user: prefix.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

Return type:

dict[str, typing.Any]

Returns:

User-scoped state with user: prefixes removed.

async list_sessions(*, app_name, user_id=None, order_by='update_time', descending=True, limit=None, offset=None)

List sessions for an app, optionally filtered by user.

Ordering and bounded pagination are a SQLSpec extension to Google ADK's narrower base signature; the response model itself is unchanged and carries neither a total count nor a cursor token.

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.

• order_by (Literal['create_time', 'update_time']) -- Timestamp column to sort on. Only create_time and update_time are accepted.

• descending (bool) -- Sort direction applied to the timestamp column and the id tie-break that keeps pages deterministic.

• limit (int | None) -- Maximum number of sessions to return. 0 returns an empty response without reaching the store.

• offset (int | None) -- Number of leading rows to skip. Requires a finite limit when positive.

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(), then updates the in-memory session only after persistence succeeds.

Implements stale-session detection: if the session has been modified in storage since it was last loaded, a ValueError is raised instead of silently overwriting.

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.

Raises:

ValueError -- If the session has been modified in storage since it was loaded (stale session).

Memory Services

class sqlspec.extensions.adk.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 | BaseSyncADKMemoryStore) -- Database store implementation.

__init__(store)

Initialize the memory service.

Parameters:

store (BaseAsyncADKMemoryStore | BaseSyncADKMemoryStore) -- Database store implementation.

property store: BaseAsyncADKMemoryStore | BaseSyncADKMemoryStore

Return the database store.

async add_session_to_memory(session, scope='user')

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.

• scope (str) -- Visibility scope ('user' or 'app').

Return type:

None

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

Add an explicit list of events to the memory service.

Same Event-to-StoredMemory 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 StoredMemory.metadata_json.

• scope (str) -- Visibility scope ('user' or 'app').

Return type:

None

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

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.

• scope (str) -- Visibility scope ('user' or 'app').

Return type:

None

async search_memory(*, app_name, user_id, query, scope_filter='all', embedding=None)

Search memory entries by text query, optionally fused with vector similarity.

Uses the store's configured search strategy. Supplying an embedding lets stores that support vector indexes combine similarity with text rank; omitting it performs the text-only search.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

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

• scope_filter (Literal['all', 'user', 'app']) -- Scope filter ('all', 'user', 'app'). Defaults to 'all'.

• embedding (Sequence[float] | None) -- Optional query vector for similarity search.

Returns:

List[MemoryEntry].

Return type:

SearchMemoryResponse

class sqlspec.extensions.adk.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.

__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, scope='user')

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.

• scope (str) -- Visibility scope ('user' or 'app').

Return type:

None

search_memory(*, app_name, user_id, query, scope_filter='all', embedding=None)

Search memory entries by text query, optionally fused with vector similarity.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

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

• scope_filter (Literal['all', 'user', 'app']) -- Scope filter ('all', 'user', 'app'). Defaults to 'all'.

• embedding (Sequence[float] | None) -- Optional query vector for similarity search.

Return type:

list[MemoryEntry]

Returns:

List of MemoryEntry objects.

Artifact Service

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. Can also be a registered alias in the storage registry.

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

__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 delete_artifacts_older_than(before, app_name=None)

Delete artifact versions created before a cutoff.

Metadata rows are deleted first (fail-fast). Content objects for the deleted versions are then removed on a best-effort basis: a failed content delete is logged with its canonical URI and version, and the remaining versions are still processed. Because the metadata row is already gone, a later run of this method cannot rediscover that content, so the warning records are the input to an independent object-store orphan sweep.

Parameters:

• before (datetime) -- Timezone-aware UTC cutoff; versions created strictly before it are deleted.

• app_name (str | None) -- Application name to limit the deletion, or None for every application.

Return type:

int

Returns:

Number of artifact version rows deleted from metadata storage.

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.

Store Base Classes

class sqlspec.extensions.adk.BaseAsyncADKStore

Bases: _ADKStoreCommon[ConfigT], ABC

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_session") - events_table: Events table name (default: "adk_event") - app_state_table: App-scoped state table name (default: "adk_app_state") - user_state_table: User-scoped state table name (default: "adk_user_state") - metadata_table: Internal metadata table name (default: "adk_internal_metadata") - owner_id_column: Optional owner FK column DDL (default: None)

async create_tables()

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

Return type:

None

async prepare_schema_async(driver)

Prepare adapter-specific schema decisions with an asynchronous driver.

Return type:

None

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:

StoredSession

Returns:

The created session record.

abstractmethod async get_session(app_name, user_id, session_id, *, renew_for=None)

Get a session.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

• session_id (str) -- Session identifier.

• renew_for (int | timedelta | None) -- If positive, touch the session update timestamp while reading.

Return type:

StoredSession | None

Returns:

Session record if found, None otherwise.

abstractmethod async update_session_state(app_name, user_id, session_id, state)

Update session state.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

• 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, *, order_by='update_time', descending=True, limit=None, offset=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.

• order_by (Literal['create_time', 'update_time']) -- Timestamp column to sort on.

• descending (bool) -- Sort direction applied to the timestamp column and the id tie-break.

• limit (int | None) -- Maximum number of sessions to return. 0 returns an empty list without database work.

• offset (int | None) -- Number of leading rows to skip. Requires a finite limit when positive.

Return type:

list[StoredSession]

Returns:

List of session records.

abstractmethod async delete_session(app_name, user_id, session_id)

Delete a session and 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

abstractmethod async append_event(event_record)

Append an event to a session.

Parameters:

event_record (StoredEvent) -- Event record to insert.

Return type:

None

abstractmethod async append_event_and_update_state(event_record, app_name, user_id, session_id, state, *, app_state=None, user_state=None)

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

This is the authoritative durable write boundary for post-creation app-scoped snapshot to replace/upsert for app_name. When user_state is provided, it is a full merged user-scoped snapshot to replace/upsert for (app_name, user_id). None means that scope was untouched by the event and must not be written.

Parameters:

• event_record (StoredEvent) -- Event record to store.

• app_name (str) -- Application name for routing scoped-state upserts.

• user_id (str) -- User identifier for routing user-scoped upserts.

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

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

• app_state (dict[str, typing.Any] | None) -- Full app-scoped state snapshot (app:* keys) to upsert atomically, or None when untouched.

• user_state (dict[str, typing.Any] | None) -- Full user-scoped state snapshot (user:* keys) to upsert atomically, or None when untouched.

Return type:

StoredSession

Returns:

The updated StoredSession reflecting the new state and update_time.

Raises:

ValueError -- If the session row no longer exists at update time (raced with delete_session).

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

Get events for a session.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

• 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[StoredEvent]

Returns:

List of event records ordered by timestamp ascending.

abstractmethod async delete_expired_events(before, app_name=None)

Delete events older than the given timestamp.

Parameters:

• before (datetime) -- Timestamp threshold; events with timestamp earlier than this value are deleted.

• app_name (str | None) -- When given, restrict deletion to events belonging to this application.

Return type:

int

Returns:

Number of event rows deleted.

abstractmethod async delete_idle_user_states(updated_before, app_name=None)

Delete user-scoped state rows whose update_time predates the given threshold.

Parameters:

• updated_before (datetime) -- Timestamp threshold; rows updated earlier than this value are deleted.

• app_name (str | None) -- When given, restrict deletion to rows belonging to this application.

Return type:

int

Returns:

Number of user state rows deleted.

abstractmethod async delete_idle_sessions(updated_before, app_name=None)

Delete sessions whose update_time predates the given threshold.

Parameters:

• updated_before (datetime) -- Timestamp threshold; sessions updated earlier than this value are deleted.

• app_name (str | None) -- When given, restrict deletion to sessions belonging to this application.

Return type:

int

Returns:

Number of session rows deleted.

abstractmethod async get_app_state(app_name)

Return app-scoped state for an application.

Parameters:

app_name (str) -- Application name.

Return type:

dict[str, typing.Any] | None

Returns:

App-scoped state mapping if present, otherwise None.

abstractmethod async get_user_state(app_name, user_id)

Return user-scoped state for an application user.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

Return type:

dict[str, typing.Any] | None

Returns:

User-scoped state mapping if present, otherwise None.

abstractmethod async upsert_app_state(app_name, state)

Insert or replace app-scoped state for an application.

Parameters:

• app_name (str) -- Application name.

• state (dict[str, typing.Any]) -- App-scoped state mapping.

Return type:

None

abstractmethod async upsert_user_state(app_name, user_id, state)

Insert or replace user-scoped state for an application user.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• state (dict[str, typing.Any]) -- User-scoped state mapping.

Return type:

None

abstractmethod async get_metadata(key)

Return a value from the ADK internal metadata table.

Parameters:

key (str) -- Metadata key.

Return type:

str | None

Returns:

Metadata value if present, otherwise None.

abstractmethod async set_metadata(key, value)

Set a value in the ADK internal metadata table.

Parameters:

• key (str) -- Metadata key.

• value (str) -- Metadata value.

Return type:

None

async reconcile_schema(*, assume_existing=False)

Apply additive ADK table changes from canonical adapter DDL.

Parameters:

assume_existing (bool) -- Skip table discovery after adapter-level creation.

Return type:

None

async ensure_tables()

Create tables and emit a standardized log entry.

Return type:

None

async drop_tables()

Drop all ADK tables managed by this store in FK-safe order.

Return type:

None

async recreate_tables()

Drop and recreate all ADK tables managed by this store.

Return type:

None

class sqlspec.extensions.adk.BaseSyncADKStore

Bases: _ADKStoreCommon[ConfigT], ABC

Base class for sync SQLSpec-backed ADK session stores.

Sync-backed adapters expose a real synchronous API for direct use in synchronous applications. Async bridging belongs in SQLSpecSessionService when Google ADK calls into a sync store from its async service surface.

Parameters:

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

abstractmethod create_tables()

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

Return type:

None

prepare_schema_sync(driver)

Prepare adapter-specific schema decisions with a synchronous driver.

Return type:

None

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

Create a new session.

Return type:

StoredSession

abstractmethod get_session(app_name, user_id, session_id, *, renew_for=None)

Get a session.

Return type:

StoredSession | None

abstractmethod update_session_state(app_name, user_id, session_id, state)

Update session state.

Return type:

None

abstractmethod list_sessions(app_name, user_id=None, *, order_by='update_time', descending=True, limit=None, offset=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.

• order_by (Literal['create_time', 'update_time']) -- Timestamp column to sort on.

• descending (bool) -- Sort direction applied to the timestamp column and the id tie-break.

• limit (int | None) -- Maximum number of sessions to return. 0 returns an empty list without database work.

• offset (int | None) -- Number of leading rows to skip. Requires a finite limit when positive.

Return type:

list[StoredSession]

Returns:

List of session records.

abstractmethod delete_session(app_name, user_id, session_id)

Delete a session and its events.

Return type:

None

abstractmethod append_event(event_record)

Append an event to a session.

Return type:

None

abstractmethod append_event_and_update_state(event_record, app_name, user_id, session_id, state, *, app_state=None, user_state=None)

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

Return type:

StoredSession

abstractmethod get_events(app_name, user_id, session_id, after_timestamp=None, limit=None)

Get events for a session.

Return type:

list[StoredEvent]

abstractmethod delete_expired_events(before, app_name=None)

Delete events older than the given timestamp, optionally scoped to one application.

Return type:

int

abstractmethod delete_idle_user_states(updated_before, app_name=None)

Delete user-scoped state rows whose update_time predates the threshold, optionally scoped to one application.

Return type:

int

abstractmethod delete_idle_sessions(updated_before, app_name=None)

Delete sessions whose update_time predates the given threshold, optionally scoped to one application.

Return type:

int

abstractmethod get_app_state(app_name)

Return app-scoped state for an application.

Return type:

dict[str, typing.Any] | None

abstractmethod get_user_state(app_name, user_id)

Return user-scoped state for an application user.

Return type:

dict[str, typing.Any] | None

abstractmethod upsert_app_state(app_name, state)

Insert or replace app-scoped state for an application.

Return type:

None

abstractmethod upsert_user_state(app_name, user_id, state)

Insert or replace user-scoped state for an application user.

Return type:

None

abstractmethod get_metadata(key)

Return a value from the ADK internal metadata table.

Return type:

str | None

abstractmethod set_metadata(key, value)

Set a value in the ADK internal metadata table.

Return type:

None

reconcile_schema(*, assume_existing=False)

Apply additive ADK table changes from canonical adapter DDL.

Parameters:

assume_existing (bool) -- Skip table discovery after adapter-level creation.

Return type:

None

ensure_tables()

Create tables and emit a standardized log entry.

Return type:

None

drop_tables()

Drop all ADK tables managed by this store in FK-safe order.

Return type:

None

recreate_tables()

Drop and recreate all ADK tables managed by this store.

Return type:

None

Memory Store Base Classes

class sqlspec.extensions.adk.BaseAsyncADKMemoryStore

Bases: _ADKMemoryStoreCommon[ConfigT], ABC

Base class for async SQLSpec-backed ADK memory stores.

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

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 drop_tables()

Drop the memory table and indexes if they exist.

Should drop all dialect-specific objects (tables, indexes, FTS virtual tables, triggers).

Return type:

None

async ensure_tables()

Create tables and emit a standardized log entry.

Return type:

None

async reconcile_schema(*, assume_existing=False)

Apply additive ADK memory table changes from canonical adapter DDL.

Return type:

None

abstractmethod async insert_memory_entries(entries, owner_id=None)

Bulk insert memory entries with deduplication.

Parameters:

• entries (list[StoredMemory]) -- List of stored 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).

abstractmethod async search_entries(query, app_name, user_id, limit=None, scope_filter='all', embedding=None)

Search memory entries by text query or vector embedding.

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).

• scope_filter (Literal['all', 'user', 'app']) -- Scope filter ('all', 'user', 'app').

• embedding (Sequence[float] | None) -- Optional query vector embedding for semantic/hybrid search.

Return type:

list[StoredMemory]

Returns:

List of matching memory records ordered by relevance/timestamp.

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, app_name=None, scope=None)

Delete memory entries older than specified days.

Parameters:

• days (int) -- Number of days to retain entries.

• app_name (str | None) -- Optional application name to scope deletion.

• scope (str | None) -- Optional scope ('user' or 'app') to scope deletion.

Return type:

int

Returns:

Number of entries deleted.

class sqlspec.extensions.adk.BaseSyncADKMemoryStore

Bases: _ADKMemoryStoreCommon[ConfigT], ABC

Base class for sync SQLSpec-backed ADK memory stores.

abstractmethod create_tables()

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

Return type:

None

drop_tables()

Drop the memory table and indexes if they exist.

Return type:

None

ensure_tables()

Create tables and emit a standardized log entry.

Return type:

None

reconcile_schema(*, assume_existing=False)

Apply additive ADK memory table changes from canonical adapter DDL.

Return type:

None

abstractmethod insert_memory_entries(entries, owner_id=None)

Bulk insert memory entries with deduplication.

Return type:

int

abstractmethod search_entries(query, app_name, user_id, limit=None, scope_filter='all', embedding=None)

Search memory entries by text query or vector embedding.

Return type:

list[StoredMemory]

abstractmethod delete_entries_by_session(session_id)

Delete all memory entries for a specific session.

Return type:

int

abstractmethod delete_entries_older_than(days, app_name=None, scope=None)

Delete memory entries older than specified days.

Return type:

int

Artifact Store Base Classes

class sqlspec.extensions.adk.BaseAsyncADKArtifactStore

Bases: _ADKArtifactStoreCommon[ConfigT], ABC

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.

abstractmethod async insert_artifact(record)

Insert an artifact version metadata row.

Parameters:

record (StoredArtifact) -- 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:

StoredArtifact | 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[StoredArtifact]

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[StoredArtifact]

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 delete_artifacts_older_than(before, app_name=None)

Delete artifact version rows created before a cutoff and return them.

Implementations delete and return the affected version rows in a single atomic operation where the database supports it, ordered deterministically so cleanup logs stay reproducible. The caller uses the returned records to remove content from object storage.

Parameters:

• before (datetime) -- Timezone-aware UTC cutoff; rows created strictly before it are deleted.

• app_name (str | None) -- Application name to limit the deletion, or None for every application.

Return type:

list[StoredArtifact]

Returns:

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

Raises:

NotImplementedError -- If the store does not implement artifact retention.

async ensure_table()

Create the artifact table and emit a standardized log entry.

Return type:

None

class sqlspec.extensions.adk.BaseSyncADKArtifactStore

Bases: _ADKArtifactStoreCommon[ConfigT], ABC

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.

abstractmethod insert_artifact(record)

Insert an artifact version metadata row.

Parameters:

record (StoredArtifact) -- 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:

StoredArtifact | 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[StoredArtifact]

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[StoredArtifact]

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

delete_artifacts_older_than(before, app_name=None)

Delete artifact version rows created before a cutoff and return them.

Implementations delete and return the affected version rows in a single atomic operation where the database supports it, ordered deterministically so cleanup logs stay reproducible. The caller uses the returned records to remove content from object storage.

Parameters:

• before (datetime) -- Timezone-aware UTC cutoff; rows created strictly before it are deleted.

• app_name (str | None) -- Application name to limit the deletion, or None for every application.

Return type:

list[StoredArtifact]

Returns:

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

Raises:

NotImplementedError -- If the store does not implement artifact retention.

ensure_table()

Create the artifact table and emit a standardized log entry.

Return type:

None

Record Types

class sqlspec.extensions.adk.StoredSession

Bases: TypedDict

Database record for a session.

Represents the schema for sessions stored in the database.

class sqlspec.extensions.adk.StoredEvent

Bases: TypedDict

Database record for an event.

Stores the full ADK Event as a single JSON blob (event_data) alongside indexed scalar columns used for scoped query filtering.

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

class sqlspec.extensions.adk.StoredMemory

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.StoredArtifact

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)

migrations_path: NotRequired[str | Path]

Directory containing this extension's migrations, or a '<dotted.module>:<subdir>' specification.

Overrides the default sqlspec.extensions.<name> lookup. Setting this auto-includes the extension in migration_config["include_extensions"].

manage_schema: NotRequired[bool]

True.

Type:

Apply additive target-schema reconciliation. Default

create_schema: NotRequired[bool]

True.

Type:

Create missing ADK tables during managed reconciliation. Default

run_migrations: NotRequired[bool]

False.

Type:

Run packaged versioned migrations when an integration supplies a runner. Default

enable_sessions: NotRequired[bool]

True.

When False the session service is unavailable, session store operations are disabled, and packaged ADK migrations emit no session, event, state, or metadata DDL.

Type:

Enable the session store at runtime and in packaged migrations. Default

enable_memory: NotRequired[bool]

True.

When False the memory service is unavailable, memory store operations are disabled, and packaged ADK migrations emit no memory table DDL or PostgreSQL vector extension statement.

Type:

Enable the memory store at runtime and in packaged migrations. Default

session_table: NotRequired[str]

'adk_session'

Type:

Name of the sessions table. Default

events_table: NotRequired[str]

'adk_event'

Type:

Name of the events table. Default

app_state_table: NotRequired[str]

'adk_app_state'

Type:

Name of the app-scoped state table. Default

user_state_table: NotRequired[str]

'adk_user_state'

Type:

Name of the user-scoped state table. Default

metadata_table: NotRequired[str]

'adk_internal_metadata'

Type:

Name of the internal metadata table. Default

memory_table: NotRequired[str]

'adk_memory'

Type:

Name of the memory entries table. Default

artifact_table: NotRequired[str]

'adk_artifact'

Type:

Name of the artifact metadata 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.

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 - 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)

vector_index_type: NotRequired[Literal['hnsw', 'ivfflat', 'scann']]

'hnsw'.

Type:

Vector index algorithm for memory embeddings ('hnsw', 'ivfflat', 'scann'). Default

vector_dimensions: NotRequired[int]

Type:

Dimensionality of embedding vectors (e.g. 768 for gemini-embedding-001 with MRL). Default

enable_bm25: NotRequired[bool]

False.

Type:

Enable native pg_textsearch BM25 full-text indexing on AlloyDB / PostgreSQL 17+. Default

scann_num_leaves: NotRequired[int]

Type:

Number of partition leaves (clusters) for ScaNN tree quantization. Default

scann_quantizer: NotRequired[str]

'SQ8'.

Type:

Quantization method for ScaNN index ('SQ8', 'FP32'). Default