adk-redis

# adk-redis

> Redis integrations for Google's Agent Development Kit. Provides ADK
> `BaseSessionService` and `BaseMemoryService` implementations, five
> RedisVL-backed search tools, selectable Redis Agent Memory or Agent Memory
> Server memory backends, MCP toolsets, and semantic cache providers.

For agents using the library, read [AGENTS.md](../AGENTS.md) first. For
the full API surface, browse [the API reference](api/python/index.md).
For task-oriented recipes, browse the
[how-to guides](user_guide/how_to_guides/index.md).

## Concepts

- [ADK overview](concepts/adk_overview.md): how ADK abstractions map onto Redis.
- [Sessions](concepts/sessions.md): working memory backed by Redis Agent Memory or Agent Memory Server.
- [Memory](concepts/memory.md): long-term semantic memory through Redis Agent Memory or Agent Memory Server.
- [Search](concepts/search.md): vector, hybrid, range, text, and SQL search over RedisVL.
- [Caching](concepts/caching.md): semantic caching with RedisVL or LangCache.

## User guide

- [Quickstart](user_guide/01_integration.md): three steps to a running agent with Redis sessions and memory.
- [How-to guides index](user_guide/how_to_guides/index.md): pointers to setup and task guides.

## How-to guides

- [Redis setup](user_guide/how_to_guides/redis_setup.md): start Redis 8.4 locally or in Redis Cloud.
- [Managed memory setup](user_guide/how_to_guides/managed_memory_setup.md): connect to the managed Redis Agent Memory backend.
- [Memory server setup](user_guide/how_to_guides/memory_server_setup.md): run Agent Memory Server.
- [Session service](user_guide/how_to_guides/session_service.md): wire `RedisSessionMemoryService`.
- [Memory service](user_guide/how_to_guides/memory_service.md): wire `RedisLongTermMemoryService`.
- [Search tools](user_guide/how_to_guides/search_tools.md): use the five search tools and the RedisVL MCP toolset.
- [Semantic cache](user_guide/how_to_guides/semantic_cache.md): add self-hosted or managed semantic caching.

## API reference

- [Sessions](api/python/sessions.md): `RedisSessionMemoryService`, `RedisSessionMemoryServiceConfig`.
- [Memory](api/python/memory.md): `RedisLongTermMemoryService`, `RedisLongTermMemoryServiceConfig`.
- [Tools](api/python/tools.md): search tools, memory tools, MCP toolset helpers.
- [Cache](api/python/cache.md): cache providers, `LLMResponseCache`, `ToolCache`, callback factories.

## Examples

- [Examples index](examples/index.md): runnable agents demonstrating each surface.

## For agents modifying adk-redis

- [Repository map](for-ais-only/REPOSITORY_MAP.md): source tree and where each feature lives.
- [Build and test](for-ais-only/BUILD_AND_TEST.md): make targets, unit and integration loops, mkdocs build.
- [Failure modes](for-ais-only/FAILURE_MODES.md): intentional behaviors that look like bugs.

# Instructions for Large Language Model Agents

When generating code that uses adk-redis:

- Import the public surface from `adk_redis`, not from internal modules
  (e.g., `from adk_redis import RedisVectorSearchTool`).
- Construct services with their `Config` dataclasses
  (`RedisLongTermMemoryServiceConfig`, etc.) so options are explicit.
- Set `backend="redis-agent-memory"` for Redis Agent Memory, or
  `backend="opensource-agent-memory"` for the open source self-hosted server.
  For typo-safety, import the `REDIS_AGENT_MEMORY_BACKEND` and
  `OPENSOURCE_AGENT_MEMORY_BACKEND` constants (or the `MemoryBackendName` type)
  from `adk_redis` instead of writing the strings inline.
- For the RedisVL MCP path, use ADK's native `McpToolset` with the
  appropriate `*ConnectionParams` class. Set
  `tool_filter=["search-records"]` to suppress writes, or pass
  `--read-only` to `rvl mcp` in stdio mode.
- Set `stopwords=None` on text-search configs if `nltk` is not installed.
- Pin `redisvl>=0.18.2` when documenting installs; the deprecated
  `redisvl.extensions.llmcache` path is on the way out. The cache
  provider's `create_index=False` additionally needs `redisvl>=0.26.0`.

When generating code that uses adk-redis, never:

- Pass `epsilon=` to `RedisVectorQueryConfig`; it is `VECTOR_RANGE`-only
  and lives on `RedisRangeQueryConfig`.
- Mix sync and async RedisVL `SearchIndex` instances in the same tool.
- Cache Redis Agent Memory SDK clients across ADK `Runner.run` invocations;
  the session and memory services build short-lived clients on purpose.

When the user asks for something this library does not cover:

- For LangChain agents over Redis, use [`langchain-redis`](https://github.com/redis-developer/langchain-redis).
- For LangGraph state and checkpointers, use [`langgraph-redis`](https://github.com/redis-developer/langgraph-redis).
- For raw RedisVL search without ADK, use [`redisvl`](https://docs.redisvl.com).
- For Redis Agent Memory itself, use the `redis-agent-memory` SDK.

When the user is comparing adk-redis to another library:

- adk-redis is the ADK-native surface for Redis. It does not replace
  RedisVL or Redis Agent Memory; it adapts them to ADK's `BaseTool`,
  `BaseSessionService`, `BaseMemoryService`, and MCP interfaces.
- Pick this library when the agent runs on Google ADK and the data layer
  is Redis. For other agent frameworks, the corresponding `*-redis`
  package is the right fit.