google / google/adk-python-community
Add self-hosted option to manage working memory (sessions) longterm memory management with ADK
- Lenguaje dominante
- Python
- Estrellas
- 182
- Forks
- 75
- Métricas de merge de PR
- Sin PR fusionados en 30 d
Descripción
## Problem Statement
ADK provides `BaseSessionService` and `BaseMemoryService` interfaces for agent state and memory management, but the built-in implementations are limited.
Developers building production agents would benefit from the following for self-hosted infrastructure:
1. **Persistent session management** with automatic context window handling
2. **Long-term memory** with semantic search across conversations
The [Redis Agent Memory Server](https://github.com/redis/agent-memory-server) provides exactly this! A two-tier memory architecture with working memory (sessions) and long-term memory (persistent facts).
## Solution
Add `agent-memory-client` as an optional dependency with two service implementations that wrap the Agent Memory Server APIs as ADK `BaseSessionService` and `BaseMemoryService` implementations.
### pyproject.toml change
```toml
[project.optional-dependencies]
redis-agent-memory = [
"agent-memory-client>=0.2.0",
]
```
### Installation
```bash
# Existing functionality unchanged
pip install google-adk-community
# Opt-in to Redis Agent Memory capabilities
pip install "google-adk-community[redis-agent-memory]"
```
This aligns with the community repository's stated philosophy:
> "This approach allows the core ADK to remain stable and lightweight, while giving the community the freedom to build and share powerful extensions."
## Services Implemented
| Service | ADK Interface | Agent Memory Server API | Purpose |
|---------|---------------|-------------------------|---------|
| `RedisWorkingMemorySessionService` | `BaseSessionService` | Working Memory API | Session management with auto-summarization |
| `RedisLongTermMemoryService` | `BaseMemoryService` | Long-Term Memory API | Persistent memory with semantic search |
## Architecture
```
┌────────────────────────────────────────────────────────────────┐
│ ADK Agent │
├──────────────────────────────┬─────────────────────────────────┤
│ TIER 1: Working Memory │ TIER 2: Long-Term Memory │
├──────────────────────────────┼─────────────────────────────────┤
│ • Current session messages │ • Extracted facts & preferences │
│ • Auto-summarization │ • Semantic vector search │
│ • Context window management │ • Cross-session persistence │
│ • TTL support │ • Recency-boosted retrieval │
├──────────────────────────────┴─────────────────────────────────┤
│ Agent Memory Server API │
├────────────────────────────────────────────────────────────────┤
│ Redis Stack │
└────────────────────────────────────────────────────────────────┘
```
## Developer Experience
```python
from google.adk import Agent
from google.adk.runners import Runner
from google.adk_community.sessions import (
RedisWorkingMemorySessionService,
RedisWorkingMemorySessionServiceConfig,
)
from google.adk_community.memory import (
RedisLongTermMemoryService,
RedisLongTermMemoryServiceConfig,
)
# Configure session service (Tier 1: Working Memory)
session_config = RedisWorkingMemorySessionServiceConfig(
api_base_url="http://localhost:8000",
default_namespace="my_app",
context_window_max=8000, # Auto-summarize when exceeded
)
session_service = RedisWorkingMemorySessionService(config=session_config)
# Configure memory service (Tier 2: Long-Term Memory)
memory_config = RedisLongTermMemoryServiceConfig(
api_base_url="http://localhost:8000",
default_namespace="my_app",
recency_boost=True, # Balance semantic relevance with recency
extraction_strategy="discrete", # Extract individual facts
)
memory_service = RedisLongTermMemoryService(config=memory_config)
# Use with ADK Runner
agent = Agent(name="assistant", model="gemini-2.0-flash")
runner = Runner(
app_name="my_app",
agent=agent,
session_service=session_service,
memory_service=memory_service,
)
```
## Features
### RedisWorkingMemorySessionService (BaseSessionService)
| Method | Description |
|--------|-------------|
| `create_session()` | Create new session with working memory |
| `get_session()` | Retrieve session state and messages |
| `list_sessions()` | List sessions with pagination |
| `delete_session()` | Delete session and working memory |
| `append_event()` | Add message with automatic context management |
**Automatic Features** (handled by Agent Memory Server):
- Token counting and context window tracking
- Auto-summarization when context limit exceeded
- Background memory extraction to long-term storage
### RedisLongTermMemoryService (BaseMemoryService)
| Method | Description |
|--------|-------------|
| `add_session_to_memory()` | Store session for memory extraction |
| `search_memory()` | Semantic search with recency boosting |
**Search Features**:
- Vector similarity search
- Recency-boosted ranking (configurable weights)
- Namespace and user filtering
- Distance threshold filtering
## Why Agent Memory Server?
The [Redis Agent Memory Server](https://github.com/redis/agent-memory-server) is an open-source, production-ready memory system that provides:
| Feature | Description |
|---------|-------------|
| **Two-tier architecture** | Working memory (session) + Long-term memory (persistent) |
| **Automatic extraction** | LLM-based extraction of facts, preferences, episodic memories |
| **Vector search** | Semantic similarity via Redis Stack's HNSW index |
| **Recency boosting** | Balance relevance with temporal freshness |
| **Multi-model support** | OpenAI, Anthropic, Gemini, Ollama via LiteLLM |
| **Deduplication** | Automatic merging of similar memories |
| **Official Docker image** | `redislabs/agent-memory-server:latest` |
## Alternatives Considered
1. **Direct Redis operations** — Would require reimplementing memory extraction, vector indexing, and search. The Agent Memory Server already provides this.
2. **Use only long-term memory** — Loses the benefits of working memory (auto-summarization, context management). The two-tier architecture is the intended design.
3. **Require users to build their own integration** — Creates friction and doesn't provide ADK-native abstractions with proper interface implementations.
Guía de contribución
Evaluación
Este issue todavía no se ha evaluado.