google / google/adk-python-community
feat: Add ValkeyMemoryService with vector similarity search (Valkey Search module)
- 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ả
## 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
Hướng dẫn đóng góp
Hướng nghiên cứu
Bắt đầu bằng cách đọc interface BaseMemoryService hiện có và phần triển khai tương tự VertexAiRagMemoryService. Xem xét ValkeyMemoryServiceConfig được đề xuất, các phương thức public và kế hoạch kiểm thử, sau đó xác minh các trường hợp tích hợp mocked-client và Valkey trực tiếp được mô tả trong issue. Công việc được xem là hoàn tất khi service hỗ trợ truy xuất vector theo phạm vi, nạp dữ liệu, cấu hình và các edge case được liệt kê.
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
- 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
- Ít trao đổi
- Độ rõ ràng
- Khá rõ ràng
- Mức phù hợp với người mới
- 35/100