0
# Memory and Session Management
1
2
Infrastructure services for persistent memory, session state, and artifact storage with support for in-memory and cloud-based implementations.
3
4
## Capabilities
5
6
### Memory Services
7
8
Classes for managing persistent memory across agent interactions.
9
10
```python { .api }
11
class BaseMemoryService:
12
"""Base class for memory services."""
13
14
def __init__(self, **kwargs):
15
"""
16
Initialize base memory service.
17
18
Args:
19
**kwargs: Memory service configuration parameters
20
"""
21
pass
22
23
def store(self, key: str, value: any, **kwargs):
24
"""
25
Store a value in memory.
26
27
Args:
28
key (str): Memory key
29
value (any): Value to store
30
**kwargs: Additional storage parameters
31
"""
32
pass
33
34
def retrieve(self, key: str, **kwargs) -> any:
35
"""
36
Retrieve a value from memory.
37
38
Args:
39
key (str): Memory key
40
**kwargs: Additional retrieval parameters
41
42
Returns:
43
any: Retrieved value or None if not found
44
"""
45
pass
46
47
def delete(self, key: str, **kwargs):
48
"""
49
Delete a value from memory.
50
51
Args:
52
key (str): Memory key to delete
53
**kwargs: Additional deletion parameters
54
"""
55
pass
56
57
def list_keys(self, prefix: str = None, **kwargs) -> list:
58
"""
59
List memory keys.
60
61
Args:
62
prefix (str, optional): Key prefix filter
63
**kwargs: Additional listing parameters
64
65
Returns:
66
list: List of memory keys
67
"""
68
pass
69
70
class InMemoryMemoryService(BaseMemoryService):
71
"""In-memory memory implementation."""
72
73
def __init__(self, **kwargs):
74
"""
75
Initialize in-memory memory service.
76
77
Args:
78
**kwargs: Configuration parameters
79
"""
80
pass
81
82
class VertexAiMemoryBankService(BaseMemoryService):
83
"""Vertex AI memory bank service."""
84
85
def __init__(
86
self,
87
project_id: str,
88
location: str = "us-central1",
89
memory_bank_id: str = None,
90
**kwargs
91
):
92
"""
93
Initialize Vertex AI memory bank service.
94
95
Args:
96
project_id (str): Google Cloud project ID
97
location (str): Vertex AI location
98
memory_bank_id (str, optional): Memory bank identifier
99
**kwargs: Additional configuration parameters
100
"""
101
pass
102
103
class VertexAiRagMemoryService(BaseMemoryService):
104
"""Vertex AI RAG memory service (optional dependency)."""
105
106
def __init__(
107
self,
108
project_id: str,
109
location: str = "us-central1",
110
rag_corpus_id: str = None,
111
**kwargs
112
):
113
"""
114
Initialize Vertex AI RAG memory service.
115
116
Note: Requires additional dependencies.
117
118
Args:
119
project_id (str): Google Cloud project ID
120
location (str): Vertex AI location
121
rag_corpus_id (str, optional): RAG corpus identifier
122
**kwargs: Additional configuration parameters
123
"""
124
pass
125
```
126
127
### Session Services
128
129
Classes for managing session state and user interactions.
130
131
```python { .api }
132
class BaseSessionService:
133
"""Base class for session services."""
134
135
def __init__(self, **kwargs):
136
"""
137
Initialize base session service.
138
139
Args:
140
**kwargs: Session service configuration parameters
141
"""
142
pass
143
144
def create_session(self, session_id: str = None, **kwargs) -> 'Session':
145
"""
146
Create a new session.
147
148
Args:
149
session_id (str, optional): Session identifier
150
**kwargs: Additional session parameters
151
152
Returns:
153
Session: Created session object
154
"""
155
pass
156
157
def get_session(self, session_id: str, **kwargs) -> 'Session':
158
"""
159
Retrieve an existing session.
160
161
Args:
162
session_id (str): Session identifier
163
**kwargs: Additional retrieval parameters
164
165
Returns:
166
Session: Session object or None if not found
167
"""
168
pass
169
170
def update_session(self, session_id: str, state: 'State', **kwargs):
171
"""
172
Update session state.
173
174
Args:
175
session_id (str): Session identifier
176
state (State): New session state
177
**kwargs: Additional update parameters
178
"""
179
pass
180
181
def delete_session(self, session_id: str, **kwargs):
182
"""
183
Delete a session.
184
185
Args:
186
session_id (str): Session identifier
187
**kwargs: Additional deletion parameters
188
"""
189
pass
190
191
class InMemorySessionService(BaseSessionService):
192
"""In-memory session implementation."""
193
194
def __init__(self, **kwargs):
195
"""
196
Initialize in-memory session service.
197
198
Args:
199
**kwargs: Configuration parameters
200
"""
201
pass
202
203
class VertexAiSessionService(BaseSessionService):
204
"""Vertex AI session service."""
205
206
def __init__(
207
self,
208
project_id: str,
209
location: str = "us-central1",
210
**kwargs
211
):
212
"""
213
Initialize Vertex AI session service.
214
215
Args:
216
project_id (str): Google Cloud project ID
217
location (str): Vertex AI location
218
**kwargs: Additional configuration parameters
219
"""
220
pass
221
222
class DatabaseSessionService(BaseSessionService):
223
"""Database-backed session service (optional dependency)."""
224
225
def __init__(
226
self,
227
connection_string: str,
228
table_name: str = "sessions",
229
**kwargs
230
):
231
"""
232
Initialize database session service.
233
234
Args:
235
connection_string (str): Database connection string
236
table_name (str): Session table name
237
**kwargs: Additional configuration parameters
238
"""
239
pass
240
241
class Session:
242
"""Session object for managing user interactions."""
243
244
def __init__(
245
self,
246
session_id: str,
247
state: 'State' = None,
248
metadata: dict = None,
249
**kwargs
250
):
251
"""
252
Initialize session.
253
254
Args:
255
session_id (str): Session identifier
256
state (State, optional): Session state
257
metadata (dict, optional): Session metadata
258
**kwargs: Additional session parameters
259
"""
260
pass
261
262
def get_state(self) -> 'State':
263
"""
264
Get current session state.
265
266
Returns:
267
State: Current session state
268
"""
269
pass
270
271
def set_state(self, state: 'State'):
272
"""
273
Set session state.
274
275
Args:
276
state (State): New session state
277
"""
278
pass
279
280
class State:
281
"""Session state object."""
282
283
def __init__(self, data: dict = None, **kwargs):
284
"""
285
Initialize session state.
286
287
Args:
288
data (dict, optional): State data
289
**kwargs: Additional state parameters
290
"""
291
pass
292
293
def get(self, key: str, default=None):
294
"""
295
Get state value.
296
297
Args:
298
key (str): State key
299
default: Default value if key not found
300
301
Returns:
302
State value or default
303
"""
304
pass
305
306
def set(self, key: str, value: any):
307
"""
308
Set state value.
309
310
Args:
311
key (str): State key
312
value (any): Value to set
313
"""
314
pass
315
316
def to_dict(self) -> dict:
317
"""
318
Convert state to dictionary.
319
320
Returns:
321
dict: State as dictionary
322
"""
323
pass
324
```
325
326
### Artifact Services
327
328
Classes for managing artifacts and file storage.
329
330
```python { .api }
331
class BaseArtifactService:
332
"""Base class for artifact services."""
333
334
def __init__(self, **kwargs):
335
"""
336
Initialize base artifact service.
337
338
Args:
339
**kwargs: Artifact service configuration parameters
340
"""
341
pass
342
343
def store_artifact(
344
self,
345
artifact_id: str,
346
data: bytes,
347
content_type: str = None,
348
**kwargs
349
):
350
"""
351
Store an artifact.
352
353
Args:
354
artifact_id (str): Artifact identifier
355
data (bytes): Artifact data
356
content_type (str, optional): MIME content type
357
**kwargs: Additional storage parameters
358
"""
359
pass
360
361
def retrieve_artifact(self, artifact_id: str, **kwargs) -> bytes:
362
"""
363
Retrieve an artifact.
364
365
Args:
366
artifact_id (str): Artifact identifier
367
**kwargs: Additional retrieval parameters
368
369
Returns:
370
bytes: Artifact data
371
"""
372
pass
373
374
def delete_artifact(self, artifact_id: str, **kwargs):
375
"""
376
Delete an artifact.
377
378
Args:
379
artifact_id (str): Artifact identifier
380
**kwargs: Additional deletion parameters
381
"""
382
pass
383
384
def list_artifacts(self, prefix: str = None, **kwargs) -> list:
385
"""
386
List artifacts.
387
388
Args:
389
prefix (str, optional): Artifact ID prefix filter
390
**kwargs: Additional listing parameters
391
392
Returns:
393
list: List of artifact IDs
394
"""
395
pass
396
397
class InMemoryArtifactService(BaseArtifactService):
398
"""In-memory artifact service."""
399
400
def __init__(self, **kwargs):
401
"""
402
Initialize in-memory artifact service.
403
404
Args:
405
**kwargs: Configuration parameters
406
"""
407
pass
408
409
class GcsArtifactService(BaseArtifactService):
410
"""Google Cloud Storage artifact service."""
411
412
def __init__(
413
self,
414
bucket_name: str,
415
project_id: str = None,
416
credentials_path: str = None,
417
**kwargs
418
):
419
"""
420
Initialize GCS artifact service.
421
422
Args:
423
bucket_name (str): GCS bucket name
424
project_id (str, optional): Google Cloud project ID
425
credentials_path (str, optional): Path to service account credentials
426
**kwargs: Additional configuration parameters
427
"""
428
pass
429
```
430
431
## Usage Examples
432
433
### Basic Memory Usage
434
435
```python
436
from google.adk.memory import InMemoryMemoryService
437
from google.adk.agents import Agent
438
439
# Create memory service
440
memory_service = InMemoryMemoryService()
441
442
# Store data
443
memory_service.store("user_preferences", {
444
"language": "en",
445
"theme": "dark",
446
"notifications": True
447
})
448
449
# Configure agent with memory
450
agent = Agent(
451
name="memory_agent",
452
model="gemini-2.0-flash",
453
memory_service=memory_service
454
)
455
456
# Agent can now access stored memories
457
response = agent.run("What are my preferences?")
458
```
459
460
### Session Management
461
462
```python
463
from google.adk.sessions import InMemorySessionService, State
464
from google.adk.agents import Agent
465
466
# Create session service
467
session_service = InMemorySessionService()
468
469
# Create a new session
470
session = session_service.create_session("user-123")
471
472
# Set session state
473
state = State({
474
"conversation_history": [],
475
"current_task": "data_analysis",
476
"user_context": {"role": "analyst"}
477
})
478
session.set_state(state)
479
480
# Use with agent
481
agent = Agent(
482
name="session_agent",
483
model="gemini-2.0-flash",
484
session_service=session_service
485
)
486
487
# Agent maintains session context
488
response = agent.run("Continue with the analysis", session_id="user-123")
489
```
490
491
### Vertex AI Memory Integration
492
493
```python
494
from google.adk.memory import VertexAiMemoryBankService
495
from google.adk.agents import Agent
496
497
# Configure Vertex AI memory
498
memory_service = VertexAiMemoryBankService(
499
project_id="my-project",
500
location="us-central1",
501
memory_bank_id="my-memory-bank"
502
)
503
504
# Store long-term memories
505
memory_service.store("company_policies", {
506
"vacation_policy": "...",
507
"remote_work_policy": "...",
508
"expense_policy": "..."
509
})
510
511
# Agent with persistent cloud memory
512
agent = Agent(
513
name="hr_assistant",
514
model="gemini-2.0-flash",
515
memory_service=memory_service,
516
instruction="Help employees with HR questions using company policies"
517
)
518
```
519
520
### Artifact Management
521
522
```python
523
from google.adk.artifacts import GcsArtifactService
524
from google.adk.agents import Agent
525
526
# Configure GCS artifact storage
527
artifact_service = GcsArtifactService(
528
bucket_name="my-artifacts-bucket",
529
project_id="my-project"
530
)
531
532
# Store document
533
with open("report.pdf", "rb") as f:
534
artifact_service.store_artifact(
535
"quarterly_report_q4",
536
f.read(),
537
content_type="application/pdf"
538
)
539
540
# Agent with artifact access
541
agent = Agent(
542
name="document_agent",
543
model="gemini-2.0-flash",
544
artifact_service=artifact_service
545
)
546
547
# Agent can access stored artifacts
548
response = agent.run("Summarize the Q4 quarterly report")
549
```
550
551
### Multi-Service Integration
552
553
```python
554
from google.adk.memory import VertexAiMemoryBankService
555
from google.adk.sessions import VertexAiSessionService
556
from google.adk.artifacts import GcsArtifactService
557
from google.adk.agents import Agent
558
559
# Configure all services
560
memory_service = VertexAiMemoryBankService(
561
project_id="my-project",
562
memory_bank_id="agent-memory"
563
)
564
565
session_service = VertexAiSessionService(
566
project_id="my-project"
567
)
568
569
artifact_service = GcsArtifactService(
570
bucket_name="agent-artifacts",
571
project_id="my-project"
572
)
573
574
# Create comprehensive agent
575
enterprise_agent = Agent(
576
name="enterprise_assistant",
577
model="gemini-2.0-flash",
578
memory_service=memory_service,
579
session_service=session_service,
580
artifact_service=artifact_service,
581
instruction="Help with enterprise tasks using persistent memory and artifacts"
582
)
583
```
584
585
### Session State Management
586
587
```python
588
from google.adk.sessions import InMemorySessionService, Session, State
589
590
session_service = InMemorySessionService()
591
592
# Create session with initial state
593
initial_state = State({
594
"workflow_step": 1,
595
"collected_data": [],
596
"pending_tasks": ["task1", "task2", "task3"]
597
})
598
599
session = session_service.create_session("workflow-session", state=initial_state)
600
601
# Update state as workflow progresses
602
current_state = session.get_state()
603
current_state.set("workflow_step", 2)
604
current_state.set("completed_task", "task1")
605
606
session.set_state(current_state)
607
session_service.update_session("workflow-session", current_state)
608
```
609
610
### Memory Search and Retrieval
611
612
```python
613
from google.adk.memory import InMemoryMemoryService
614
615
memory_service = InMemoryMemoryService()
616
617
# Store various memories
618
memory_service.store("meeting_notes_2024_01", "Team discussed Q1 goals...")
619
memory_service.store("meeting_notes_2024_02", "Reviewed project timeline...")
620
memory_service.store("user_profile", {"name": "John", "role": "Manager"})
621
622
# List and search memories
623
meeting_keys = memory_service.list_keys(prefix="meeting_notes")
624
print(f"Found {len(meeting_keys)} meeting notes")
625
626
# Retrieve specific memories
627
profile = memory_service.retrieve("user_profile")
628
print(f"User: {profile['name']}")
629
```