google / google/adk-python-community

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

Offen
#46 0 Kommentare 3 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
Python
Sterne
182
Forks
75
PR-Merge-Kennzahlen
Keine gemergten PRs in 30 T.

Beschreibung

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

Beitragsleitfaden

Beitragsleitfaden öffnen

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.