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

[daric93]

Summary

Closes: #155

Implements ValkeyMemoryService for the ADK community memory module, backed by Valkey using the Valkey Search module for vector similarity search (HNSW). Uses the valkey-glide client library (v2.4.0+). This provides functionality analogous to VertexAiRagMemoryService for developers with Valkey infrastructure.

Changes

• src/google/adk_community/memory/valkey_memory_service.py — New memory service implementing BaseMemoryService
  • ValkeyMemoryServiceConfig: Pydantic config with similarity_top_k, vector_distance_threshold, embedding_dimensions, key_prefix, index_name, distance_metric, ttl_seconds
  • ValkeyMemoryService: Accepts a configurable async embedding function (users bring their own embedder)
  • 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
  • Uses FT.SEARCH with KNN for vector similarity retrieval, pre-filtered by TAG
  • Implements add_session_to_memory and add_events_to_memory
  • Configurable distance threshold, distance metric (COSINE/L2/IP), TTL
  • Batch embedding generation for efficient ingestion
  • Pipelined writes via Batch for single round-trip ingestion
  • asyncio.Lock with double-check locking for index creation
  • Comprehensive TAG character escaping (including ? wildcard)
• src/google/adk_community/memory/__init__.py — Exports ValkeyMemoryService and ValkeyMemoryServiceConfig
• src/google/adk_community/memory/README.md — Documentation with usage examples
• pyproject.toml — Added valkey-glide>=2.4.0 as optional dependency under [valkey] extra
• tests/unittests/memory/test_valkey_memory_service.py — 46 unit tests (mocked client)
• tests/integration/test_valkey_memory_service_integration.py — 12 integration tests against live Valkey with Search module

How it works

1. Ingestion (add_session_to_memory / add_events_to_memory): text is extracted from events, embeddings are generated in batch via the user-provided embedding function, and each event is stored as a Valkey Hash containing the text content, metadata, and the embedding vector. All writes are pipelined via Batch for a single network round-trip.

2. Search (search_memory): an embedding is generated for the query text, then FT.SEARCH performs a KNN search over the HNSW index with pre-filtering by app_name and user_id TAG fields. Results are ranked by vector distance and optionally filtered by vector_distance_threshold.

Testing plan

Unit tests (46): All public methods tested with mocked valkey-glide client

pytest tests/unittests/memory/test_valkey_memory_service.py -v
46 passed

Integration tests (12): Run against Valkey 9.1 (valkey-bundle image with Search module)

podman run -d --name valkey-test -p 6379:6379 valkey/valkey-bundle:9.1
pytest tests/integration/test_valkey_memory_service_integration.py -v
12 passed

Integration test coverage:

• Vector similarity search (add + KNN search)
• Results ranked by similarity
• User isolation (TAG filter on user_id)
• App isolation (TAG filter on app_name)
• Multiple sessions accumulate
• Empty store search
• similarity_top_k limit enforcement
• Function call / empty events filtered
• Memory entry metadata preserved (author, timestamp)
• create_index idempotency
• add_events_to_memory incremental ingestion
• vector_distance_threshold filtering

Requirements

• Valkey server with the Search module loaded (e.g., valkey/valkey-bundle image)
• valkey-glide >= 2.4.0
• An async embedding function (e.g., OpenAI, Google Gemini, sentence-transformers)

Ref: AEA-497

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.