|
| 1 | +--- |
| 2 | +catalog_title: Database Memory Service |
| 3 | +catalog_description: SQL-backed persistent memory for agents |
| 4 | +catalog_icon: /integrations/assets/adk-database-memory.png |
| 5 | +catalog_tags: ["data"] |
| 6 | +--- |
| 7 | + |
| 8 | +# Database Memory Service for ADK |
| 9 | + |
| 10 | +<div class="language-support-tag"> |
| 11 | + <span class="lst-supported">Supported in ADK</span><span class="lst-python">Python</span> |
| 12 | +</div> |
| 13 | + |
| 14 | +[`adk-database-memory`](https://github.com/anmolg1997/adk-database-memory) is a |
| 15 | +drop-in persistent `BaseMemoryService` for ADK Python, backed by async |
| 16 | +SQLAlchemy. This integration provides persistent cross-session memory for ADK |
| 17 | +agents using your own database: use SQLite for development, or Postgres / MySQL |
| 18 | +for production. |
| 19 | + |
| 20 | +## Use cases |
| 21 | + |
| 22 | +- **Personalized assistants**: Accumulate long-term user preferences, facts, and |
| 23 | + past decisions across sessions so the agent can recall them on demand. |
| 24 | +- **Support and task agents**: Persist conversation history across tickets and |
| 25 | + devices, so context is available whenever the user returns. |
| 26 | +- **Self-hosted deployments**: When Vertex AI Memory Bank is not an option |
| 27 | + (on-prem, air-gapped, non-GCP cloud), keep memory on the database you already |
| 28 | + use. |
| 29 | +- **Local development**: Drop in SQLite for zero-config persistent memory that |
| 30 | + survives restarts, then flip the connection string to Postgres in production. |
| 31 | + |
| 32 | +## Prerequisites |
| 33 | + |
| 34 | +- Python 3.10 or later |
| 35 | +- A supported database: SQLite, PostgreSQL, or MySQL / MariaDB |
| 36 | + |
| 37 | +## Installation |
| 38 | + |
| 39 | +Install the package together with the driver for your database: |
| 40 | + |
| 41 | +```bash |
| 42 | +pip install "adk-database-memory[sqlite]" # SQLite (via aiosqlite) |
| 43 | +pip install "adk-database-memory[postgres]" # PostgreSQL (via asyncpg) |
| 44 | +pip install "adk-database-memory[mysql]" # MySQL / MariaDB (via aiomysql) |
| 45 | +``` |
| 46 | + |
| 47 | +The core package does not include any database drivers. Choose the extra that |
| 48 | +matches your backend, or install your own async driver separately. |
| 49 | + |
| 50 | +## Use with agent |
| 51 | + |
| 52 | +The service implements |
| 53 | +`google.adk.memory.base_memory_service.BaseMemoryService`, so it slots into any |
| 54 | +ADK `Runner` that accepts a `memory_service`: |
| 55 | + |
| 56 | +```python |
| 57 | +import asyncio |
| 58 | + |
| 59 | +from adk_database_memory import DatabaseMemoryService |
| 60 | +from google.adk.agents import Agent |
| 61 | +from google.adk.runners import InMemoryRunner |
| 62 | + |
| 63 | +memory = DatabaseMemoryService("sqlite+aiosqlite:///memory.db") |
| 64 | + |
| 65 | +agent = Agent( |
| 66 | + name="assistant", |
| 67 | + model="gemini-flash-latest", |
| 68 | + instruction="You are a helpful assistant.", |
| 69 | +) |
| 70 | + |
| 71 | +async def main(): |
| 72 | + async with memory: |
| 73 | + # Run the agent, then persist the session to memory |
| 74 | + runner = InMemoryRunner(agent=agent, app_name="my_app") |
| 75 | + session = await runner.session_service.create_session(app_name="my_app", user_id="u1") |
| 76 | + # After the session completes: |
| 77 | + await memory.add_session_to_memory(session) |
| 78 | + |
| 79 | + # Later, recall relevant memories for a new query: |
| 80 | + result = await memory.search_memory( |
| 81 | + app_name="my_app", |
| 82 | + user_id="u1", |
| 83 | + query="what did we decide about the pricing model?", |
| 84 | + ) |
| 85 | + for entry in result.memories: |
| 86 | + print(entry.author, entry.timestamp, entry.content) |
| 87 | + |
| 88 | +asyncio.run(main()) |
| 89 | +``` |
| 90 | + |
| 91 | +## Supported backends |
| 92 | + |
| 93 | +| Backend | Connection URL example | Extra | |
| 94 | +| ---- | ---- | ---- | |
| 95 | +| SQLite | `sqlite+aiosqlite:///memory.db` | `[sqlite]` | |
| 96 | +| SQLite (in-memory) | `sqlite+aiosqlite:///:memory:` | `[sqlite]` | |
| 97 | +| PostgreSQL | `postgresql+asyncpg://user:pass@host/db` | `[postgres]` | |
| 98 | +| MySQL / MariaDB | `mysql+aiomysql://user:pass@host/db` | `[mysql]` | |
| 99 | +| Any async SQLAlchemy dialect | depends on driver | bring your own | |
| 100 | + |
| 101 | +## API |
| 102 | + |
| 103 | +| Method | Description | |
| 104 | +| ---- | ---- | |
| 105 | +| `add_session_to_memory(session)` | Index every event in a completed session. | |
| 106 | +| `add_events_to_memory(app_name, user_id, events, ...)` | Index an explicit slice of events (useful for streaming ingestion). | |
| 107 | +| `search_memory(app_name, user_id, query)` | Return `MemoryEntry` objects whose indexed keywords overlap with the query, scoped to the given app and user. | |
| 108 | + |
| 109 | +On first write, the service creates a single table (`adk_memory_entries`) with |
| 110 | +an index on `(app_name, user_id)`. JSON content is stored as `JSONB` on |
| 111 | +PostgreSQL, `LONGTEXT` on MySQL, and `TEXT` on SQLite. |
| 112 | + |
| 113 | +Retrieval uses the same keyword-extraction and matching approach as the |
| 114 | +in-memory and Firestore memory services in ADK. For embedding-based recall, pair |
| 115 | +this package with Vertex AI Memory Bank or a vector store. |
| 116 | + |
| 117 | +## Resources |
| 118 | + |
| 119 | +- [GitHub repository](https://github.com/anmolg1997/adk-database-memory): source |
| 120 | + code, issues, and examples. |
| 121 | +- [PyPI package](https://pypi.org/project/adk-database-memory/): releases and |
| 122 | + install instructions. |
| 123 | +- [ADK Memory overview](/sessions/memory/): |
| 124 | + background on how ADK uses memory services. |
0 commit comments