Redis Vector Library
The AI-native Redis Python client
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/redisvl/)
[](https://github.com/redis/redis-vl-python/stargazers)
[](https://github.com/psf/black)
**[Documentation](https://docs.redisvl.com)** • **[Recipes](https://github.com/redis-developer/redis-ai-resources)** • **[GitHub](https://github.com/redis/redis-vl-python)**
---
## Introduction
Redis Vector Library (RedisVL) is the production-ready Python client for AI applications built on Redis. **Lightning-fast vector search meets enterprise-grade reliability.**
Perfect for building **RAG pipelines** with real-time retrieval, **AI agents** with memory and semantic routing, and **recommendation systems** with fast search and reranking.
| **🎯 Core Capabilities** | **🚀 AI Extensions** | **🛠️ Dev Utilities** |
|:---:|:---:|:---:|
| **[Index Management](#index-management)**
*Schema design, data loading, CRUD ops* | **[Semantic Caching](#semantic-caching)**
*Reduce LLM costs & boost throughput* | **[CLI](#command-line-interface)**
*Index management from terminal* |
| **[Vector Search](#retrieval)**
*Similarity search with metadata filters* | **[LLM Memory](#llm-memory)**
*Agentic AI context management* | **Async Support**
*Async indexing and search for improved performance* |
| **[Complex Filtering](#retrieval)**
*Combine multiple filter types* | **[Semantic Routing](#semantic-routing)**
*Intelligent query classification* | **[Vectorizers](#vectorizers)**
*8+ embedding provider integrations* |
| **[Hybrid Search](#retrieval)**
*Combine semantic & full-text signals* | **[Embedding Caching](#embedding-caching)**
*Cache embeddings for efficiency* | **[Rerankers](#rerankers)**
*Improve search result relevancy* |
| | | **[MCP Server](#mcp-server)**
*Expose one or more existing Redis indexes to MCP clients* |
# 💪 Getting Started
## Installation
Install `redisvl` into your Python (>=3.10) environment using `pip`:
```bash
pip install redisvl
```
Install the MCP server extra when you want to expose one or more existing Redis indexes through MCP:
```bash
pip install redisvl[mcp]
```
> For more detailed instructions, visit the [installation guide](https://docs.redisvl.com/en/latest/user_guide/installation.html).
> For MCP concepts and setup, see the [RedisVL MCP docs](https://docs.redisvl.com/en/latest/concepts/mcp.html) and the [MCP how-to guide](https://docs.redisvl.com/en/latest/user_guide/how_to_guides/mcp.html).
## Redis
Choose from multiple Redis deployment options:
Redis Cloud - Managed cloud database (free tier available)
[Redis Cloud](https://redis.io/try-free) offers a fully managed Redis service with a free tier, perfect for getting started quickly.
Docker - Local development
Run Redis locally using Docker:
```bash
docker run -d --name redis -p 6379:6379 redis:latest
```
This runs Redis 8+ with built-in vector search capabilities.
Redis Enterprise - Commercial, self-hosted database
[Redis Enterprise](https://redis.io/enterprise/) provides enterprise-grade features for production deployments.
Redis Sentinel - High availability with automatic failover
Configure Redis Sentinel for high availability:
```python
# Connect via Sentinel
redis_url="redis+sentinel://sentinel1:26379,sentinel2:26379/mymaster"
```
Azure Managed Redis - Fully managed Redis Enterprise on Azure
[Azure Managed Redis](https://azure.microsoft.com/en-us/products/managed-redis) provides fully managed Redis Enterprise on Microsoft Azure.
> 💡 **Tip**: Enhance your experience and observability with the free [Redis Insight GUI](https://redis.io/insight/).
# Overview
## Index Management
1. **Design a schema** for your use case that models your dataset with built-in Redis indexable fields (*e.g. text, tags, numerics, geo, and vectors*).
Load schema from YAML file
```yaml
index:
name: user-idx
prefix: user
storage_type: json
fields:
- name: user
type: tag
- name: credit_score
type: tag
- name: job_title
type: text
attrs:
sortable: true
no_index: false # Index for search (default)
unf: false # Normalize case for sorting (default)
- name: embedding
type: vector
attrs:
algorithm: flat
dims: 4
distance_metric: cosine
datatype: float32
```
```python
from redisvl.schema import IndexSchema
schema = IndexSchema.from_yaml("schemas/schema.yaml")
```
Load schema from Python dictionary
```python
from redisvl.schema import IndexSchema
schema = IndexSchema.from_dict({
"index": {
"name": "user-idx",
"prefix": "user",
"storage_type": "json"
},
"fields": [
{"name": "user", "type": "tag"},
{"name": "credit_score", "type": "tag"},
{
"name": "job_title",
"type": "text",
"attrs": {
"sortable": True,
"no_index": False, # Index for search
"unf": False # Normalize case for sorting
}
},
{
"name": "embedding",
"type": "vector",
"attrs": {
"algorithm": "flat",
"datatype": "float32",
"dims": 4,
"distance_metric": "cosine"
}
}
]
})
```
> 📚 Learn more about [schema design](https://docs.redisvl.com/en/stable/user_guide/01_getting_started.html#define-an-indexschema) and [schema creation](https://docs.redisvl.com/en/stable/user_guide/01_getting_started.html#example-schema-creation).
2. [Create a SearchIndex](https://docs.redisvl.com/en/stable/user_guide/01_getting_started.html#create-a-searchindex) class with an input schema to perform admin and search operations on your index in Redis:
```python
from redis import Redis
from redisvl.index import SearchIndex
# Define the index
index = SearchIndex(schema, redis_url="redis://localhost:6379")
# Create the index in Redis
index.create()
```
> An async-compatible index class also available: [AsyncSearchIndex](https://docs.redisvl.com/en/stable/api/searchindex.html#redisvl.index.AsyncSearchIndex).
3. [Load](https://docs.redisvl.com/en/stable/user_guide/01_getting_started.html#load-data-to-searchindex)
and [fetch](https://docs.redisvl.com/en/stable/user_guide/01_getting_started.html#fetch-an-object-from-redis) data to/from your Redis instance:
```python
data = {"user": "john", "credit_score": "high", "embedding": [0.23, 0.49, -0.18, 0.95]}
# load list of dictionaries, specify the "id" field
index.load([data], id_field="user")
# fetch by "id"
john = index.fetch("john")
```
## Retrieval
Define queries and perform advanced searches over your indices, including vector search, complex filtering, and hybrid search combining semantic and full-text signals.
Quick Reference: Query Types
| Query Type | Use Case | Description |
|:---|:---|:---|
| `VectorQuery` | Semantic similarity search | Find similar vectors with optional filters |
| `RangeQuery` | Distance-based search | Vector search within a defined distance range |
| `FilterQuery` | Metadata filtering | Filter and search using metadata fields |
| `TextQuery` | Full-text search | BM25-based keyword search with field weighting |
| `HybridQuery` | Combined search | Combine semantic + full-text signals (Redis 8.4.0+) |
| `CountQuery` | Counting records | Count documents matching filter criteria |
### Vector Search
- [VectorQuery](https://docs.redisvl.com/en/stable/api/query.html#vectorquery) - Flexible vector queries with customizable filters enabling semantic search:
```python
from redisvl.query import VectorQuery
query = VectorQuery(
vector=[0.16, -0.34, 0.98, 0.23],
vector_field_name="embedding",
num_results=3,
# Optional: tune search performance with runtime parameters
ef_runtime=100 # HNSW: higher for better recall
)
# run the vector search query against the embedding field
results = index.query(query)
```
- [RangeQuery](https://docs.redisvl.com/en/stable/api/query.html#rangequery) - Vector search within a defined range paired with customizable filters
### Complex Filtering
Build complex filtering queries by combining multiple filter types (tags, numerics, text, geo, timestamps) using logical operators:
```python
from redisvl.query import VectorQuery
from redisvl.query.filter import Tag, Num
# Combine multiple filter types
tag_filter = Tag("user") == "john"
price_filter = Num("price") >= 100
# Create complex filtering query with combined filters
query = VectorQuery(
vector=[0.16, -0.34, 0.98, 0.23],
vector_field_name="embedding",
filter_expression=tag_filter & price_filter,
num_results=10
)
results = index.query(query)
```
- [FilterQuery](https://docs.redisvl.com/en/stable/api/query.html#filterquery) - Standard search using filters and full-text search
- [CountQuery](https://docs.redisvl.com/en/stable/api/query.html#countquery) - Count the number of indexed records given attributes
- [TextQuery](https://docs.redisvl.com/en/stable/api/query.html#textquery) - Full-text search with support for field weighting and BM25 scoring
> Learn more about building [complex filtering queries](https://docs.redisvl.com/en/stable/user_guide/02_complex_filtering.html).
### Hybrid Search
Combine semantic (vector) search with full-text (BM25) search signals for improved search quality:
- [HybridQuery](https://docs.redisvl.com/en/stable/api/query.html#hybridquery) - Native hybrid search combining text and vector similarity (Redis 8.4.0+):
```python
from redisvl.query import HybridQuery
hybrid_query = HybridQuery(
text="running shoes",
text_field_name="description",
vector=[0.1, 0.2, 0.3],
vector_field_name="embedding",
combination_method="LINEAR", # or "RRF"
num_results=10
)
results = index.query(hybrid_query)
```
- [AggregateHybridQuery](https://docs.redisvl.com/en/stable/api/query.html#aggregatehybridquery) - Hybrid search using aggregation (compatible with earlier Redis versions)
> Learn more about [hybrid search](https://docs.redisvl.com/en/stable/user_guide/11_advanced_queries.html#hybrid-queries-combining-text-and-vector-search).
## Dev Utilities
### Vectorizers
Integrate with popular embedding providers to greatly simplify the process of vectorizing unstructured data for your index and queries.
Supported Vectorizer Providers
- [AzureOpenAI](https://docs.redisvl.com/en/stable/api/vectorizer.html#azureopenaitextvectorizer)
- [Cohere](https://docs.redisvl.com/en/stable/api/vectorizer.html#coheretextvectorizer)
- [Custom](https://docs.redisvl.com/en/stable/api/vectorizer.html#customtextvectorizer)
- [GCP VertexAI](https://docs.redisvl.com/en/stable/api/vectorizer.html#vertexaitextvectorizer)
- [HuggingFace](https://docs.redisvl.com/en/stable/api/vectorizer.html#hftextvectorizer)
- [Mistral](https://docs.redisvl.com/en/stable/api/vectorizer/html#mistralaitextvectorizer)
- [OpenAI](https://docs.redisvl.com/en/stable/api/vectorizer.html#openaitextvectorizer)
- [VoyageAI](https://docs.redisvl.com/en/stable/api/vectorizer/html#voyageaitextvectorizer)
```python
from redisvl.utils.vectorize import CohereTextVectorizer
# set COHERE_API_KEY in your environment
co = CohereTextVectorizer()
embedding = co.embed(
text="What is the capital city of France?",
input_type="search_query"
)
embeddings = co.embed_many(
texts=["my document chunk content", "my other document chunk content"],
input_type="search_document"
)
```
> Learn more about using [vectorizers](https://docs.redisvl.com/en/stable/user_guide/04_vectorizers.html) in your embedding workflows.
### Rerankers
[Integrate with popular reranking providers](https://docs.redisvl.com/en/stable/user_guide/06_rerankers.html) to improve the relevancy of the initial search results from Redis
## Extensions
**RedisVL Extensions** provide production-ready modules implementing best practices and design patterns for working with LLM memory and agents. These extensions encapsulate learnings from our user community and enterprise customers.
> 💡 *Have an idea for another extension? Open a PR or reach out to us at . We're always open to feedback.*
### Semantic Caching
Increase application throughput and reduce the cost of using LLM models in production by leveraging previously generated knowledge with the [`SemanticCache`](https://docs.redisvl.com/en/stable/api/cache.html#semanticcache).
Example: Semantic Cache Usage
```python
from redisvl.extensions.cache.llm import SemanticCache
# init cache with TTL and semantic distance threshold
llmcache = SemanticCache(
name="llmcache",
ttl=360,
redis_url="redis://localhost:6379",
distance_threshold=0.1 # Redis COSINE distance [0-2], lower is stricter
)
# store user queries and LLM responses in the semantic cache
llmcache.store(
prompt="What is the capital city of France?",
response="Paris"
)
# quickly check the cache with a slightly different prompt (before invoking an LLM)
response = llmcache.check(prompt="What is France's capital city?")
print(response[0]["response"])
```
```stdout
>>> Paris
```
> Learn more about [semantic caching](https://docs.redisvl.com/en/stable/user_guide/03_llmcache.html) for LLMs.
### Embedding Caching
Reduce computational costs and improve performance by caching embedding vectors with their associated text and metadata using the [`EmbeddingsCache`](https://docs.redisvl.com/en/stable/api/cache.html#embeddingscache).
Example: Embedding Cache Usage
```python
from redisvl.extensions.cache.embeddings import EmbeddingsCache
from redisvl.utils.vectorize import HFTextVectorizer
# Initialize embedding cache
embed_cache = EmbeddingsCache(
name="embed_cache",
redis_url="redis://localhost:6379",
ttl=3600 # 1 hour TTL
)
# Initialize vectorizer with cache
vectorizer = HFTextVectorizer(
model="sentence-transformers/all-MiniLM-L6-v2",
cache=embed_cache
)
# First call computes and caches the embedding
embedding = vectorizer.embed("What is machine learning?")
# Subsequent calls retrieve from cache (much faster!)
cached_embedding = vectorizer.embed("What is machine learning?")
```
```stdout
>>> Cache hit! Retrieved from Redis in <1ms
```
> Learn more about [embedding caching](https://docs.redisvl.com/en/stable/user_guide/10_embeddings_cache.html) for improved performance.
### LLM Memory
Improve personalization and accuracy of LLM responses by providing user conversation context. Manage access to memory data using recency or relevancy, *powered by vector search* with the [`MessageHistory`](https://docs.redisvl.com/en/stable/api/message_history.html).
Example: Message History Usage
```python
from redisvl.extensions.message_history import SemanticMessageHistory
history = SemanticMessageHistory(
name="my-session",
redis_url="redis://localhost:6379",
distance_threshold=0.7
)
# Supports roles: system, user, llm, tool
# Optional metadata field for additional context
history.add_messages([
{"role": "user", "content": "hello, how are you?"},
{"role": "llm", "content": "I'm doing fine, thanks."},
{"role": "user", "content": "what is the weather going to be today?"},
{"role": "llm", "content": "I don't know", "metadata": {"model": "gpt-4"}}
])
# Get recent chat history
history.get_recent(top_k=1)
# >>> [{"role": "llm", "content": "I don't know", "metadata": {"model": "gpt-4"}}]
# Get relevant chat history (powered by vector search)
history.get_relevant("weather", top_k=1)
# >>> [{"role": "user", "content": "what is the weather going to be today?"}]
# Filter messages by role
history.get_recent(role="user") # Get only user messages
history.get_recent(role=["user", "system"]) # Or multiple roles
```
> Learn more about [LLM memory](https://docs.redisvl.com/en/stable/user_guide/07_message_history.html).
### Semantic Routing
Build fast decision models that run directly in Redis and route user queries to the nearest "route" or "topic".
Example: Semantic Router Usage
```python
from redisvl.extensions.router import Route, SemanticRouter
routes = [
Route(
name="greeting",
references=["hello", "hi"],
metadata={"type": "greeting"},
distance_threshold=0.3,
),
Route(
name="farewell",
references=["bye", "goodbye"],
metadata={"type": "farewell"},
distance_threshold=0.3,
),
]
# build semantic router from routes
router = SemanticRouter(
name="topic-router",
routes=routes,
redis_url="redis://localhost:6379",
)
router("Hi, good morning")
# >>> RouteMatch(name='greeting', distance=0.273891836405)
```
> Learn more about [semantic routing](https://docs.redisvl.com/en/stable/user_guide/08_semantic_router.html).
## Command Line Interface
Create, destroy, and manage Redis index configurations from a purpose-built CLI interface: `rvl`.
```bash
$ rvl --help
usage: rvl []
Redis Vector Library CLI.
Command groups:
index Create, inspect, list, and delete Redis search indexes
stats Show statistics for an existing Redis search index
version Show the installed RedisVL version
mcp Run the RedisVL MCP server
Examples:
rvl index --help
rvl index create -s schema.yaml
rvl stats -i user_index
rvl mcp --config /path/to/mcp.yaml
```
Use `rvl index --help` to see documented subcommands such as `create`, `info`, `listall`, `delete`, and `destroy`. Use `rvl stats --help` to see both index-name and schema-path examples plus the shared Redis connection options for data-plane commands.
Run the MCP server over stdio (default):
```bash
uvx --from redisvl[mcp] rvl mcp --config /path/to/mcp.yaml
```
Or over Streamable HTTP for remote MCP clients:
```bash
uvx --from redisvl[mcp] rvl mcp --config /path/to/mcp.yaml --transport streamable-http --host 0.0.0.0 --port 8000
```
Or over SSE:
```bash
uvx --from redisvl[mcp] rvl mcp --config /path/to/mcp.yaml --transport sse --host 0.0.0.0 --port 9000
```
Use `--read-only` to expose search without upsert.
> Read more about [using the CLI](https://docs.redisvl.com/en/latest/overview/cli.html) and [running RedisVL MCP](https://docs.redisvl.com/en/latest/user_guide/how_to_guides/mcp.html).
### MCP Server
RedisVL includes an MCP server that lets MCP-compatible clients search or upsert data in one or more existing Redis indexes through a small, stable tool contract.
The server:
- connects to one or more existing Redis Search indexes, each addressed by a logical id
- reconstructs each index's schema from Redis at startup
- uses each index's configured vectorizer for query embedding and optional upsert embedding
- exposes `list-indexes` for discovery, `search-records`, and (unless every index is read-only) `upsert-records`
- supports stdio (default), Streamable HTTP, and SSE transports
A single configured index is the simplest case and works exactly as before — callers omit the index selector. With multiple indexes, clients call `list-indexes` first and pass the chosen `index` to `search-records` and `upsert-records`.
Run it over stdio (default):
```bash
uvx --from redisvl[mcp] rvl mcp --config /path/to/mcp.yaml
```
Run it over Streamable HTTP for remote clients:
```bash
uvx --from redisvl[mcp] rvl mcp --config /path/to/mcp.yaml --transport streamable-http --host 0.0.0.0 --port 8000
```
Use `--read-only` when clients should only search:
```bash
uvx --from redisvl[mcp] rvl mcp --config /path/to/mcp.yaml --read-only
```
For configuration details, tool arguments, and examples, see the [RedisVL MCP docs](https://docs.redisvl.com/en/latest/concepts/mcp.html) and the [MCP how-to guide](https://docs.redisvl.com/en/latest/user_guide/how_to_guides/mcp.html).
## 🚀 Why RedisVL?
Redis is a proven, high-performance database that excels at real-time workloads. With RedisVL, you get a production-ready Python client that makes Redis's vector search, caching, and session management capabilities easily accessible for AI applications.
Built on the [Redis Python](https://github.com/redis/redis-py/tree/master) client, RedisVL provides an intuitive interface for vector search, LLM caching, and conversational AI memory - all the core components needed for modern AI workloads.
## 😁 Helpful Links
For additional help, check out the following resources:
- [Getting Started Guide](https://docs.redisvl.com/en/stable/user_guide/01_getting_started.html)
- [RedisVL MCP](https://docs.redisvl.com/en/latest/concepts/mcp.html)
- [API Reference](https://docs.redisvl.com/en/stable/api/index.html)
- [Redis AI Recipes](https://github.com/redis-developer/redis-ai-resources)
## 🫱🏼🫲🏽 Contributing
Please help us by contributing PRs, opening GitHub issues for bugs or new feature ideas, improving documentation, or increasing test coverage. [Read more about how to contribute!](CONTRIBUTING.md)
## 🚧 Maintenance
This project is supported by [Redis, Inc](https://redis.io) on a good faith effort basis. To report bugs, request features, or receive assistance, please [file an issue](https://github.com/redis/redis-vl-python/issues).