# Getting Started with Redis Iris

**Authors:** Chanh Tran | **Category:** For AI | **Published:** 2026-06-16 | **Updated:** 2026-06-16

# Getting Started with Redis Iris

## Introduction

Redis Iris is a purpose-built context and memory platform designed to bridge the gap between AI agents and fragmented enterprise data. It acts as a foundational layer in the AI stack, providing AI agents with live, accurate, and navigable data so they can operate reliably in production.

Redis Iris consists of five core tools that work together:

| Tool                                                                   | Description                                                                                                                                                                                                                                                                                     |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[Context Retriever](https://redis.io/context-retriever/)**           | Defines a semantic model of your business entities (e.g., customers, tickets, policies) and automatically generates Model Context Protocol (MCP) tools. Instead of querying databases blindly, agents can dynamically discover and execute these tools with scoped keys and row-level security. |
| **[Agent Memory](https://redis.io/agent-memory/)**                     | Manages both short-term session state and long-term durable memory across multiple interactions.                                                                                                                                                                                                |
| **[Redis Data Integration (RDI)](https://redis.io/data-integration/)** | Continuously ingests and synchronizes data from external systems (such as relational databases and data warehouses) into Redis so agents always act on fresh context.                                                                                                                           |
| **[LangCache](https://redis.io/langcache/)**                           | A semantic caching service that stores and reuses LLM responses for similar queries, drastically reducing API costs and latency.                                                                                                                                                                |
| **[Redis Search](https://redis.io/search/)**                           | The core data layer powering the platform, enabling fast retrieval across structured, unstructured, and vector data.                                                                                                                                                                            |

This tutorial will cover LangCache, Agent Memory, and Context Retriever.

> **Note:** This tutorial uses the code from the following git repository:
>
> [https://github.com/redis-developer/getting-started-with-redis-iris](https://github.com/redis-developer/getting-started-with-redis-iris/)

## Prerequisites

- Python >= 3.11
- Jupyter
- Redis Cloud account
- Redis Insight (optional, for inspecting data)

## Setup

### 1. Create a database

From the Redis Cloud console, select **New Database.** Then click **Try 30 MB for free** to create a free Redis database in the cloud.

![01-create-db](https://cdn.sanity.io/images/sy1jschh/production/d5bc7fe6f0d43d968aa2648d540c0b18316a6568-2332x1188.png)

#### Cloud settings

| Setting              | Description                                       |
| -------------------- | ------------------------------------------------- |
| **Name**             | Name of your database.                            |
| **Database version** | Version of your cloud database, leave as default. |
| **Cloud vendor**     | The cloud infrastructure service provider.        |
| **Region**           | The region where your database will be hosted.    |

Name your database and click **Create database.**

### 2. Redis Insight

You can use the web version of Redis Insight or optionally [download the desktop app](https://cloud.redis.io/#/rlec-downloads). The Redis Insight desktop app will allow for faster bulk loading of data, but this tutorial will cover how to load data with both.

In the Redis Cloud console in your database's **Configuration** page, click **Connect**.

Choose either **Open in desktop** or **Launch Redis Insight web**.

![01-connect-db](https://cdn.sanity.io/images/sy1jschh/production/f76e78a208382e5ba9a657860869d5dea465ddf9-986x856.png?h=400)

### 3. Clone the repo

```bash
git clone https://github.com/redis-developer/getting-started-with-redis-iris.git
cd getting-started-with-redis-iris
```

In your cloned repo, copy `.env.example` to `.env`

```bash
cp .env.example .env
```

### 4. Set up a Python environment and install Jupyter

```bash
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip i
```

## Redis LangCache

### 1. Create a LangCache Service

From the Redis Cloud console, select **LangCache** from the left-hand menu. This takes you to the **Create LangCache service** page.

![02-create-langcache](https://cdn.sanity.io/images/sy1jschh/production/8edd30f5dc1e74d69c8b2c4c0650725e9a17f173-2050x1748.png)

#### General settings

| Setting                   | Description                                                                     |
| ------------------------- | ------------------------------------------------------------------------------- |
| **Service name**          | A name that describes your service's purpose.                                   |
| **Select database**       | The Redis Cloud database to use for this service.                               |
| **TTL**                   | Time to live for cache entries, in milliseconds. Default: no expiration.        |
| **User for this service** | Database access user. Only the default user is supported during public preview. |

#### Embedding settings

| Setting                        | Description                                                                                           |
| ------------------------------ | ----------------------------------------------------------------------------------------------------- |
| **Embedding Provider**         | Choose between Redis, OpenAI, or Bring your own. Any provider must support the OpenAI embeddings API. |
| **Embedding provider API key** | Your provider's API key (OpenAI and Bring your own only).                                             |
| **Embedding provider URL**     | Your provider's API URL (Bring your own only).                                                        |
| **Model**                      | The embedding model to use.                                                                           |
| **Similarity threshold**       | Minimum similarity score to consider a cached response a match. Range: 0.5–1.0. Default: 0.92.        |

> **Tip:** Higher values mean more precise matches; lower values increase match rate but may include less relevant results.

#### Attributes settings (optional)

Attributes provide scoping capabilities for your cache operations — think of them as tags that help organize cached data.

You can define up to 5 custom attributes:

1. Select **Add attribute**.
2. Enter a descriptive name and select the checkmark to save.
3. Repeat to add additional attributes (up to 5).

#### Create the service

When you have finished configuring your service, select **Create**.

A window will display your **LangCache service key**. Select **Copy** to save it.

> **Warning:** This is the only time the service key is shown. Save it to a secure location before closing the dialog. If you lose it, you will need to generate a new key.

### 2. Configure your environment

Edit the `.env` file to fill in the LangCache values that you saved from the Redis Cloud console:

```ini
LANGCACHE_ENDPOINT="<your-langcache-endpoint-url>"
LANGCACHE_ID="<your-langcache-id>"
LANGCACHE_KEY="<your-langcache-api-key>"
```

Find `LANGCACHE_ENDPOINT` and `LANGCACHE_ID` on your service's **Configuration** page in the Redis Cloud console under **Connectivity**. For `LANGCACHE_ENDPOINT`, copy the URL of the region closest to you. `LANGCACHE_KEY` is the service key you copied when creating the service.

![03-langcache-vars](https://cdn.sanity.io/images/sy1jschh/production/810a69a907d10511972dbed9b9b3c9e05dff532f-2506x1104.png)

### 3. Jupyter Notebook Walkthrough

Open [`jupyter/langcache.ipynb`](https://github.com/redis-developer/getting-started-with-redis-iris/blob/main/jupyter/langcache.ipynb).

#### Install dependencies

```python
%pip install langcache
%pip install python-dotenv
```

#### Import libraries

```python
import os

from dotenv import load_dotenv
from langcache import LangCache
```

#### Load environment variables and initialize the client

```python
load_dotenv()

langcache_endpoint = os.getenv("LANGCACHE_ENDPOINT")
langcache_id = os.getenv("LANGCACHE_ID")
langcache_key = os.getenv("LANGCACHE_KEY")

llm_cache = LangCache(
    server_url=langcache_endpoint,
    cache_id=langcache_id,
    api_key=langcache_key
)
```

#### Save a cache entry

```python
save_response = await llm_cache.set_async(
    prompt="How does semantic caching work?",
    response="Semantic caching stores and retrieves data based on meaning, not exact matches."
)

print("Save entry response:\n", save_response)
```

#### Search for a cached entry

```python
search_response = await llm_cache.search_async(prompt="What is semantic caching?")

print("Search entry response:\n", search_response)
```

Even though the search prompt differs slightly from the saved prompt, the semantic similarity is high enough that LangCache returns the cached response — no LLM call required.

#### View data in Redis Insight

Open Redis Insight and connect to your database to browse the cached entries stored by LangCache.

![04-langcache-insight](https://cdn.sanity.io/images/sy1jschh/production/bb2f651da40f8c98e8eedb8fe41e9811bfa5e3aa-1534x892.png?h=450)

### 4. Clean up

Go to the LangCache configuration page in the Redis Cloud console. Scroll down to Actions, click Delete next Delete service.

## Redis Agent Memory

### 1. Create an Agent Memory Service

From the Redis Cloud console, select **Agent Memory** from the left-hand menu. Select **Create custom** and configure the service settings.

![05-create-agent-memory](https://cdn.sanity.io/images/sy1jschh/production/e720caece503c172f4dbf7fa418c67ea69edb8e0-2048x1122.png)

#### General settings

| Setting                   | Description                                                                     |
| ------------------------- | ------------------------------------------------------------------------------- |
| **Service name**          | A name that describes your service's purpose.                                   |
| **Select database**       | The Redis Cloud database to use for this service.                               |
| **User for this service** | Database access user. Only the default user is supported during public preview. |

#### Memory configuration

| Setting            | Description                                                                                                    |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| **Short-term TTL** | Time to live for session (short-term) memory. Can be set in seconds, minutes, hours, or days. Default: 1 hour. |
| **Long-term TTL**  | Time to live for long-term memory. Default: 365 days.                                                          |

#### Create the service

When you have finished configuring your service, select **Create**.

A window will display your **Agent Memory service key**. Select **Copy** to save it.

> **Warning:** This is the only time the service key is shown. Save it to a secure location before closing the dialog. If you lose it, you will need to generate a new key.

### 2. Configure your environment

Find `AGENT_MEMORY_ENDPOINT` and `AGENT_MEMORY_STORE_ID` on your service's **Configuration** page in the Redis Cloud console. `AGENT_MEMORY_KEY` is the service key you just copied in the last step.

![06-agent-memory-vars](https://cdn.sanity.io/images/sy1jschh/production/651be121c88a56a30e3c27918f14b139a5379c09-2506x842.png)

Edit the Agent Memory variables in your `.env` file:

```ini
AGENT_MEMORY_ENDPOINT="<your-agent-memory-endpoint>"
AGENT_MEMORY_STORE_ID="<your-agent-memory-store-id>"
AGENT_MEMORY_KEY="<your-agent-memory-api-key>"
```

### 3. Jupyter Notebook Walkthrough

Open [`jupyter/agent-memory.ipynb`](https://github.com/redis-developer/getting-started-with-redis-iris/blob/main/jupyter/agent-memory.ipynb).

#### Install dependencies

```python
%pip install redis-agent-memory
%pip install python-dotenv
```

#### Import libraries

```python
import os
import time

from dotenv import load_dotenv
from redis_agent_memory import AgentMemory, models
```

#### Load environment variables and initialize the client

```python
load_dotenv()

agent_memory_endpoint = os.getenv("AGENT_MEMORY_ENDPOINT")
agent_memory_store_id = os.getenv("AGENT_MEMORY_STORE_ID")
agent_memory_key = os.getenv("AGENT_MEMORY_KEY")

agent_memory = AgentMemory(
    agent_memory_endpoint,
    store_id=agent_memory_store_id,
    api_key=agent_memory_key,
)
```

#### Add a session (short-term) memory event

```python
add_session = await agent_memory.add_session_event_async(
    session_id="session-1",
    actor_id="user-123",
    role=models.MessageRole.USER,
    content=[{"text": "hello world!"}],
    created_at=int(time.time() * 1000),
)

print(add_session)
```

#### Retrieve session memory

```python
session_memory = await agent_memory.get_session_memory_async(session_id="session-1")

print("Session memory:\n", session_memory)
```

#### Add a long-term memory

```python
create_ltm = await agent_memory.bulk_create_long_term_memories_async(memories=[
    {"id": "memory-1", "text": "Semantic memory stores facts and knowledge for later retrieval."},
])

print(create_ltm)
```

#### Get or search long-term memory

```python
get_ltm = await agent_memory.get_long_term_memory_async(memory_id="memory-1")

print(get_ltm)

search_ltm = await agent_memory.search_long_term_memory_async(
    request={"text": "What is semantic memory?"}
)

print("Search results:\n", search_ltm)
```

The search uses semantic similarity, so the query does not need to exactly match the stored memory text.

#### View data in Redis Insight

Open Redis Insight and connect to your database to browse the session and long-term memory entries stored by Agent Memory.

![07-agent-memory-insight](https://cdn.sanity.io/images/sy1jschh/production/c1bed98f6d7a410f048a27612b47acf733a9baf1-1546x1264.png?h=600)

### 4. Clean up

Go to the Agent Memory configuration page in the Redis Cloud console. Scroll down to Actions, click Delete next Delete service.

## Redis Context Retriever

### 1. Load data into Redis

In the Redis Cloud console, open your `redis-iris` database confiuration page create during the Setup step and click **Connect**.

Choose either **Open in desktop** for the desktop app or **Launch Redis Insight web**.

![01-connect-db](https://cdn.sanity.io/images/sy1jschh/production/f76e78a208382e5ba9a657860869d5dea465ddf9-986x856.png?h=400)

#### If using Redis Insight Desktop

Click **Bulk Actions** then **Upload Data** tab.

Drag and drop the [`data.redis`](https://github.com/redis-developer/getting-started-with-redis-iris/blob/main/data.redis) file from this repo into Redis Insight and click **Upload** to load in the hospital management dataset.

![08-load-data-desktop](https://cdn.sanity.io/images/sy1jschh/production/2525108fb10dba05455fa373889e3c940caff00c-1548x1506.png?h=500)

#### If using Redis Insight Web

Click on the **Workbench** tab and paste in the contents of [`data.redis`](https://github.com/redis-developer/getting-started-with-redis-iris/blob/main/data.redis). Then click **Run** to load in the hospital management dataset.

![08-load-data-web](https://cdn.sanity.io/images/sy1jschh/production/ccebcb15aa01bfc502fe2a1a96bf92be26892cb4-2894x1236.png)

### 2. Create a Context Retriever Service

From the Redis Cloud console, select **Context Retriever** from the left-hand menu.

If this is your first service, you'll see an introduction page. Otherwise, select **New service**. From the introduction page, select **Create custom service** to manually configure your settings.

![09-create-context-retriever](https://cdn.sanity.io/images/sy1jschh/production/d2ed1b7a0ea76cb242d830d9b926f229a518633b-2054x832.png)

#### General settings

| Setting             | Description                                       |
| ------------------- | ------------------------------------------------- |
| **Service name**    | A name that describes your service's purpose.     |
| **Select database** | The Redis Cloud database to use for this service. |
| **Description**     | A description of your context retriever.          |

Select **Entities** to continue.

#### Define entities

Entities map to the business objects stored in your Redis database.

1. Select **Add Entity**.
2. In the **Entity name** field, enter the name of a business object (e.g., `Treatment`).
3. In the **Key Template** field, enter the Redis key pattern, using `{id}` to denote the ID location (e.g., `treatment:{id}`).
4. Optionally add a description.
5. Select the checkmark to confirm the entity.
6. Repeat for all 5 entities, then select **Fields** to continue.

> **Note:** I recommend creating all 5 entities but for this tutorial you will only need a minimum of the `Treatement` and `Appointment` entities mapped.

| Entity Name     | Key Template       |
| --------------- | ------------------ |
| **Treatment**   | `treatment:{id}`   |
| **Appointment** | `appointment:{id}` |
| **Patient**     | `patient:{id}`     |
| **Doctor**      | `doctor:{id}`      |
| **Bill**        | `bill:{id}`        |

![10-context-retriever-entities](https://cdn.sanity.io/images/sy1jschh/production/d2544f0c7ec10d78df9eec75f79d310566e5b944-2038x1136.png)

#### Configure fields

In this step, you define the fields of each entity and the relationships between them. You have two options:

- **Auto-detect fields** — scans your database automatically using a model to detect fields. You will need to agree to let the model scan your key names and schemas.
- **Manual configuration** — define each field yourself, marking them as `NUMERIC` or `TEXT` to generate additional `find` and `search` MCP tools.

We'll use a combination of both. We'll first use Auto-detect to define the fields and relationshships then manually configure certain fields to be `NUMERIC` or `TEXT`.

1. Click **Auto-detect fields**, this will scan your database and infer entity fields. This will also automatically map the relationships between your entities based on the entity's field key names.
2. Consent to auto-detect scand and click **Scan Database**.
3. Configure the field indexes. At a minimum, you'll need to configure 3 fields in the `Treatement` entity. Click on the entity's pencil icon then the **Configure** button to configure indexes of the entities:

- `Treatment` entity:
    - `treatment_type` to be `TEXT`
    - `descritption` to be `TEXT`
    - `cost` to be `NUMERIC`

> **Note:** Each field can only be a part of 1 index. You might encounter errors if you tried to include fields in both the `TAG` and `TEXT` indexes.

4. Make sure to click the checkmark to confirm the changes.
5. Optionally, go through the other entites and configure the field indexes as `TEXT` or `NUMERIC` as needed.

![11-context-retriever-fields](https://cdn.sanity.io/images/sy1jschh/production/145867df32827335ef51b5ffd2285f0c57977bec-896x539.png)

6. After configuring all fields, select **Create** to create the service.

### 3. Configure your environment

You will access your Context Retriever via an agent key. To create a Context Retriever agent key, go to the Redis Cloud console and open your Context Retriever service page.

1. Navigate to the **Agent key** tab in your service configuration page and select **New Agent Key**. Name and generate your agent key.

![12-context-retriever-agent-key](https://cdn.sanity.io/images/sy1jschh/production/33e49340162039c9277bdae1ea7d227ba0df1c62-1062x1100.png?h=500)

2. Copy and save the agent key

3. Edit the `CONTEXT_RETRIEVER_AGENT_KEY` variable in your `.env` file:

```ini
CONTEXT_RETRIEVER_AGENT_KEY="<your-context-retriever-agent-key>"
```

### 4. Jupyter Notebook Walkthrough

Open [`jupyter/context-retriever.ipynb`](https://github.com/redis-developer/getting-started-with-redis-iris/blob/main/jupyter/context-retriever.ipynb).

#### Install dependencies

```python
%pip install redis-context-retriever
%pip install python-dotenv
```

#### Import libraries

```python
import os
import json

from dotenv import load_dotenv
from context_surfaces import UnifiedClient
```

#### Load environment variables

```python
load_dotenv()

agent_key = os.getenv("CONTEXT_RETRIEVER_AGENT_KEY")
```

#### Initialize the client and list available tools

Context Retriever automatically generates MCP tools from your entity definitions. List them to see what's available:

```python
context_retriever = UnifiedClient()

tools = await context_retriever.list_tools(agent_key)

print(f"Total tools: {len(tools)}")
for t in tools:
    name = t["name"]
    print(f"Name: {name}")
```

#### Call the tools

Use `query_tool` to call any of the generated MCP tools directly:

```python
# Filter all appointments by patient_id
response = await context_retriever.query_tool(
    agent_key=agent_key,
    tool_name="filter_appointment_by_patient_id",
    arguments={"value": "P002", "limit": 10}
)
# Process filter response
print("Filter results:")
filter_data = json.loads(filter_response["content"][0]["text"])["results"]
for a in filter_data:
    print(a)
```

```python
# Get a doctor by doctor_id
get_response = await context_retriever.query_tool(
    agent_key=agent_key,
    tool_name="get_doctor_by_id",
    arguments={"id": "D010"}
)

# Process get data
print("Get result:")
get_data = json.loads(get_response["content"][0]["text"])
print(get_data)
```

```python
# Search treatments by text query with the "MRI" keyword
search_response = await context_retriever.query_tool(
    agent_key=agent_key,
    tool_name="search_treatment_by_text",
    arguments={"query": "MRI", "limit": 10}
)

# Process search data
print("Search results:")
search_data = json.loads(search_response["content"][0]["text"])["results"]
for a in search_data:
    print(a)
```

```python
# Find treatments by cost ranging from 100 to 1000
find_response = await context_retriever.query_tool(
    agent_key=agent_key,
    tool_name="find_treatment_by_cost_range",
    arguments={"min_value": 100, "max_value": 1000, "limit": 10}
)

# Process range data
print("Cost range results:")
find_data = json.loads(find_response["content"][0]["text"])["results"]
for c in find_data:
    print(c)

```

#### Context Retriever tool names

The tool names (e.g. `filter_appointment_by_patient_id`, `get_doctor_by_id`, etc.) reflect the entities defined in a sample healthcare dataset. Your tool names will match the entities you defined in your own Context Retriever service.

| **Index** | MCP tool generated               |
| --------- | -------------------------------- |
| `PK`      | `get_<entity>_by_id`             |
| `TAG`     | `filter_<entity>_by_<field>`     |
| `TEXT`    | `search_<entity>_by_text`        |
| `NUMERIC` | `find_<entity>_by_<field>_range` |

### 5. Clean up

Go to the Context Retriever configuration page in the Redis Cloud console. Scroll down to Actions, next to Delete service click Delete.

## Next Steps

### References

- [Redis Iris Docs](https://redis.io/docs/latest/develop/ai/context-engine/)
- [Blog post: Context Is All You Need](https://redis.io/blog/context-is-all-you-need/)

### Tutorials

1. [Semantic caching with Redis LangCache](https://redis.io/tutorials/semantic-caching-with-redis-langcache/)
2. [Redis Agent Memory and LangGraph](https://redis.io/tutorials/redis-agent-memory-with-langgraph/)
3. [Real-time AI agent with Redis Iris](https://redis.io/tutorials/redis-iris-call-agent/)