Skip to content

feat(memory): SQL-backed DatabaseMemoryService with scratchpad for durable agent memory #4735

Closed
Feature
Closed
feat(memory): SQL-backed DatabaseMemoryService with scratchpad for durable agent memory#4735
Feature
Assignees
DeanChensjklateefa
Labels
needs review[Status] The PR/issue is awaiting review from the maintainerservices[Component] This issue is related to runtime services, e.g. sessions, memory, artifacts, etc

Description

@kronos3610
kronos3610
opened on Mar 6, 2026

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 MemoryEntry writes are stored in a SQL table (adk_memory_entries) that survives process restarts
  • Idempotent session ingest — add_session_to_memory is safe to call multiple times (DELETE + re-INSERT)
  • Delta ingest — add_events_to_memory skips already-stored event_ids
  • Pluggable search — MemorySearchBackend ABC allows swapping in FTS or vector-embedding backends; ships with KeywordSearchBackend (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 four BaseTool subclasses 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")  # production

New 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 BaseMemoryService methods
  • 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

  1. adk-bot
    added
    services[Component] This issue is related to runtime services, e.g. sessions, memory, artifacts, etc
    on Mar 6, 2026
  2. adk-bot
    added the
    Feature
    issue type on Mar 6, 2026

  3. klateefa commented on Mar 9, 2026

    @klateefa
    klateefa
    on Mar 9, 2026
    Collaborator

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

  4. klateefa
    assigned
    klateefa
    and
    DeanChensj
    on Mar 9, 2026
  5. klateefa
    added
    needs review[Status] The PR/issue is awaiting review from the maintainer
    on Mar 9, 2026

  6. DeanChensj commented on Oct 9, 2026

    @DeanChensj
    DeanChensj
    on Oct 9, 2026
    Collaborator

    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 under google.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-community repository (as discussed in #5339). We would warmly welcome and encourage community packages extending BaseMemoryService for 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!

  7. DeanChensj
    closed this as completedon Oct 9, 2026

  8. github-actions commented on Oct 9, 2026

    @github-actions
    github-actionsbot
    on Oct 9, 2026 – with GitHub Actions

    Are you satisfied with the resolution of your issue?
    Yes
    No

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

needs review[Status] The PR/issue is awaiting review from the maintainerservices[Component] This issue is related to runtime services, e.g. sessions, memory, artifacts, etc

Type

Feature

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions