google / google/adk-python-community

Add self-hosted option to manage working memory (sessions) longterm memory management with ADK

Abierto
#46 0 comentarios 3 reacciones 0 asignados Ver en GitHub
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

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.