google / google/adk-python-community

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

Đang mở
#46 0 bình luận 3 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
Python
Star
182
Fork
75
Chỉ số merge pull request
Không có pull request nào được merge trong 30 ngày

Mô tả

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

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Bắt đầu với pyproject.toml và các interface BaseSessionService và BaseMemoryService được đề cập trong issue, sau đó xem xét Agent Memory Server APIs. Xác định hai phần triển khai service được đề xuất và các ranh giới cấu hình của chúng trước khi kiểm tra cách các session, event và tìm kiếm memory ánh xạ tới các interface đó. Được xem là hoàn tất khi dependency tùy chọn và cả hai service tương thích với ADK đều hỗ trợ các operation được liệt kê mà không thay đổi behavior cài đặt hiện có.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
python, redis
Lĩnh vực
backend, databases
Loại issue
Tính năng
Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức độ hoạt động
Đình trệ
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
35/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.