google / google/adk-python-community

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

Open
#46 0 comments 3 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
182
Forks
75
PR merge metrics
No merged PRs in 30d

Description

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

Contributor guide

Open the contributing guide

Research direction

Start with pyproject.toml and the BaseSessionService and BaseMemoryService interfaces mentioned in the issue, then review the Agent Memory Server APIs. Define the two proposed service implementations and their configuration boundaries before checking how sessions, events, and memory searches map to those interfaces. Done means the optional dependency and both ADK-compatible services support the listed operations without changing existing installation behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, redis
Domain
backend, databases
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.