Repository navigation
feat(memory): SQL-backed DatabaseMemoryService with scratchpad for durable agent memory #4735
Description
Summary
The ADK currently ships only InMemoryMemoryService (volatile, keyword-only, test-only) and cloud-specific Vertex AI services. There is no durable, self-hosted memory option for production deployments that do not use Vertex AI.
Problem
Developers running ADK agents on-premise or against non-Google cloud providers have no way to persist agent memory across process restarts without writing their own implementation from scratch.
Proposed Solution
Add DatabaseMemoryService — a BaseMemoryService implementation backed by any SQLAlchemy-supported async database (SQLite, PostgreSQL, MySQL, MariaDB, Spanner via the existing SQLAlchemy adapter).
Core features
- Durable memory — events and direct
MemoryEntrywrites are stored in a SQL table (adk_memory_entries) that survives process restarts - Idempotent session ingest —
add_session_to_memoryis safe to call multiple times (DELETE + re-INSERT) - Delta ingest —
add_events_to_memoryskips already-storedevent_ids - Pluggable search —
MemorySearchBackendABC allows swapping in FTS or vector-embedding backends; ships withKeywordSearchBackend(LIKE/ILIKE, AND-first → OR-fallback) - Scratchpad — a KV store (
adk_scratchpad_kv) and append-only log (adk_scratchpad_log) for intermediate working memory during task execution, exposed as fourBaseToolsubclasses agents can call directly
Zero-config for SQLite
from google.adk.memory import DatabaseMemoryService
svc = DatabaseMemoryService("sqlite+aiosqlite:///:memory:") # tests / local dev
svc = DatabaseMemoryService("postgresql+asyncpg://user:pass@host/db") # productionNew public API surface
| Symbol | Module |
|---|---|
DatabaseMemoryService |
google.adk.memory |
MemorySearchBackend |
google.adk.memory |
KeywordSearchBackend |
google.adk.memory |
scratchpad_get_tool |
google.adk.tools.scratchpad_tool |
scratchpad_set_tool |
google.adk.tools.scratchpad_tool |
scratchpad_append_log_tool |
google.adk.tools.scratchpad_tool |
scratchpad_get_log_tool |
google.adk.tools.scratchpad_tool |
Test coverage
38 unit tests using sqlite+aiosqlite:///:memory: (no external DB required):
- All
BaseMemoryServicemethods - Scratchpad KV and log operations
- All 4 tool happy-paths and wrong-service error paths
- Multi-user isolation and session scoping
Files changed
src/google/adk/memory/schemas/__init__.py (new)
src/google/adk/memory/schemas/memory_schema.py (new)
src/google/adk/memory/memory_search_backend.py (new)
src/google/adk/memory/database_memory_service.py (new)
src/google/adk/tools/scratchpad_tool.py (new)
src/google/adk/memory/__init__.py (modified — adds exports)
tests/unittests/memory/test_database_memory_service.py (new)
Related
Complements the existing DatabaseSessionService which follows the same SQLAlchemy async pattern.
Activity
klateefa commentedon Mar 9, 2026
@Raman369AI Thanks for the update. The request is currently being reviewed, and I will let you know if anything further is needed. Thank you for understanding.
DeanChensj commentedon Oct 9, 2026
Hi @kronos3610,
Thank you so much for the detailed proposal and for putting so much thought into designing a durable, self-hosted memory solution for ADK. We truly appreciate the effort you took to outline the schema, search backend, and test strategy.
Since this issue was opened, we have added official support for local, durable SQL memory in the core library via
SqliteMemoryService(introduced in #4116, available undergoogle.adk.memory.SqliteMemoryService). It provides file-based SQLite persistence across process restarts, event-level delta ingestion (add_events_to_memory), and full-text search with FTS5 and LIKE fallback—addressing the need for a zero-cloud, self-hosted memory service out of the box.For broader relational database backends (such as PostgreSQL, MySQL, and distributed SQL) and specialized working-memory tools, our team's architectural direction is to keep the core ADK runtime lean and host external database integrations in the
google/adk-python-communityrepository (as discussed in #5339). We would warmly welcome and encourage community packages extendingBaseMemoryServicefor SQLAlchemy backends, and we would be more than happy to feature and link to them in our official integrations documentation.Because the core requirement for self-hosted durable SQL memory is now addressed via
SqliteMemoryService, and broader SQL backends are designated for the community repository, we are closing this issue.Thank you once again for your contribution and for helping make ADK better!
github-actions commentedon Oct 9, 2026
Are you satisfied with the resolution of your issue?
Yes
No