google / google/adk-python-community

feat: Add ValkeyMemoryService with vector similarity search (Valkey Search module)

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

Description

## Summary

Add a `ValkeyMemoryService` implementation for the ADK community memory module, backed by Valkey using the Valkey Search module for vector similarity search (HNSW). This would use the `valkey-glide` client library and provide functionality analogous to `VertexAiRagMemoryService` for developers with Valkey infrastructure.

## Motivation

Currently, the community memory module has limited backend options. Valkey (the open-source fork of Redis) with the Search module provides a high-performance, self-hosted vector database option that many teams already run in production. Adding a Valkey-backed memory service would expand the ecosystem for developers who prefer or already use Valkey infrastructure.

## Proposed Implementation

- `ValkeyMemoryService` class implementing `BaseMemoryService` interface
- `ValkeyMemoryServiceConfig` (Pydantic) with configurable: `similarity_top_k`, `vector_distance_threshold`, `embedding_dimensions`, `key_prefix`, `index_name`, `distance_metric` (COSINE/L2/IP), `ttl_seconds`
- Accepts a configurable async embedding function (users bring their own embedder — OpenAI, Gemini, sentence-transformers, etc.)
- Stores memories as Valkey Hash keys with FLOAT32 vector embeddings
- Uses `FT.CREATE` with VECTOR field (HNSW algorithm) + TAG fields for `app_name`/`user_id` scoped queries
- Uses `FT.SEARCH` with KNN for vector similarity retrieval, pre-filtered by TAG
- Implements both `add_session_to_memory` and `add_events_to_memory`
- Uses `Batch` pipelining for efficient ingestion (1 round trip regardless of event count)
- `asyncio.Lock` with double-check locking for thread-safe index creation
- Configurable distance threshold, distance metric, TTL

## Dependencies

- `valkey-glide >= 2.4.0` (as optional dependency under `[valkey]` extra)
- Valkey server with the Search module loaded (e.g., `valkey/valkey-bundle` image)

## Testing Plan

- Unit tests (mocked client): cover all public methods, edge cases, error conditions
- Integration tests: run against live Valkey 9.1 (`valkey/valkey-bundle` image) covering vector similarity search, user/app isolation, top-k limits, distance threshold filtering, metadata preservation, index idempotency

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.