Redis vs Redis Iris: Beginner’s Guide to AI Agent Context & Memory

Confused about Redis vs Redis Iris? Learn the 5 pillars, when to use each, LangCache cost savings up to 90%, and real setup code for AI agents. Beginner-friendly.

Table of Contents

1. The Detective Who Keeps Forgetting (The Problem)

2. What’s the Difference? (The 2-Minute Answer)

3. Meet Redis Iris: The Context Engine

4. The 5 Pillars of Redis Iris 

5. Agent Memory: The Two-Tier System

6. Context Retriever: Auto-Generated Tools

7. LangCache: The Money-Saving Machine

8. Redis vs Redis Iris: The Decision Checklist

9. Getting Started: Your First Iris Setup

10. Real Code: Building a Complete Agent

11. How It All Works: Request Flow

12. Production Guardrails

13. Limitations & When NOT to Use Redis Iris

14. FAQs

15. The Bottom Line

1. The Detective Who Keeps Forgetting (The Problem) 

Picture this.

You’re a detective trying to solve a complex case. Your desk is covered in thousands of loose papers—witness statements, forensic reports, phone records, and suspect profiles. Every time you need an answer, you have to dig through the entire pile, hoping to find the right document. You forget what you read yesterday, and you constantly re-read the same files.

This is Traditional RAG.

Now imagine you have an assistant who:

• Hands you the exact file you need, instantly

• Remembers what you learned in previous cases

• Knows your preferences and working style

• Keeps organized notes on every conversation you’ve ever had

This is an AI Agent powered by Redis Iris.

Agents today don’t have an intelligence problem; they have a context problem. As Redis CEO Rowan Trollope puts it: “Agents don’t have an intelligence problem. They have a context problem.”  They fail because their context layer is scattered, stale, slow, or hard to use .

2. What’s the Difference? 

Redis is a database. A really fast one that lives in your system’s memory.

Redis Iris is a context engine built on top of Redis. It adds five specialized services that make your AI agent smart, fast, and cost-effective .

The Analogy: Redis is like a high-speed train engine. Redis Iris is the entire railway system—trains, tracks, signals, automated ticketing, and stations—all working together to move passengers (your agent’s data) efficiently.

The short answer: Use Redis for basic caching and key-value storage. Use Redis Iris when you’re building AI agents that need short/long-term memory, semantic caching, and structured tools to query your business databases.

3. Meet Redis Iris: The Context Engine 

Redis Iris sits directly between your AI agent (like LangGraph) and your enterprise data. Instead of feeding your agent stale prompts and brittle API integrations, Iris gives it fast, live, “agent-ready” context .

Think of Redis Iris like a fridge in your kitchen.

• Without it: Every time you want to make a sandwich, you have to run to the grocery store (slow, expensive database/LLM calls).

• With it: You keep the ingredients you need in the fridge, always fresh, always ready (sub-millisecond retrieval).

43% of enterprise AI agent stacks already use Redis in the runtime layer to serve the hot operational state agents need .

How It Changes Things ?

4. The 5 Pillars of Redis Iris :

Redis Iris brings together five components into one unified system :

Pillar 1: Agent Memory

Gives your agent both short-term (session) and long-term (permanent) memory. It remembers what you said 2 minutes ago AND what you said last week .

Real example: A wealth advisor agent remembers what a client said about wanting to retire early, and brings it up automatically in the next meeting.

Pillar 2: Context Retriever

Turns your business data into structured tools. Instead of writing custom APIs, you define your data model once, and Redis auto-generates tools your agent can call .

Real example: Define a Client entity, and the agent gets get_client_by_id and search_client_by_text tools automatically. Add a new entity and the tools appear without code changes .

Pillar 3: LangCache (Semantic Caching)

Saves money by reusing LLM responses for similar questions. If someone asks “What’s the weather in Tokyo?” and someone else asks “Is it raining in Tokyo?”, it returns the cached answer instead of calling OpenAI again .

Real numbers: Semantic caching can reduce LLM token costs by up to 90% .

Pillar 4: Data Integration

Automatically syncs data from your existing operational databases (Postgres, Oracle, Snowflake) into Redis. Your data is always fresh .

Pillar 5: Search

The vector and full-text search engine underneath it all that makes retrieval instantaneous .

5. Agent Memory: The Two-Tier System 

Agent Memory mimics human cognition using a two-tier model :

Tier 1: Session Memory (Short-Term)

Holds the current conversation state. It’s like your brain’s working memory. It uses a TTL (Time-To-Live) to expire when the session ends .

Tier 2: Long-Term Memory (Permanent)

Stores facts extracted from past sessions as text with vector embeddings. It’s like your permanent memory .

How They Work Together

Note: The code below uses the official Redis Agent Memory SDK. Method names may change during preview .

from redis_agent_memory import AgentMemory, models
import os
import time

# Initialize Agent Memory (using official SDK pattern [citation:8])
agent_memory = AgentMemory(
    endpoint=os.environ["AGENT_MEMORY_ENDPOINT"],
    store_id=os.environ["AGENT_MEMORY_STORE_ID"],
    api_key=os.environ["AGENT_MEMORY_KEY"]
)

# Add a session event (this goes to short-term memory) [citation:8][citation:14]
add_session = await agent_memory.add_session_event_async(
    session_id="session-1",
    actor_id="user-123",
    role=models.MessageRole.USER,
    content=[{"text": "Hi! My name is Priya. I prefer window seats on flights."}],
    created_at=int(time.time() * 1000),
)

# Retrieve session memory [citation:8]
session_memory = await agent_memory.get_session_memory_async(session_id="session-1")

# Add a long-term memory directly [citation:8][citation:14]
create_ltm = await agent_memory.bulk_create_long_term_memories_async(memories=[
    {"memory_id": "memory-1", "owner_id": "user-123", 
     "text": "User prefers window seats on flights"}
])

# Search long-term memories by owner_id [citation:8][citation:14]
search_ltm = await agent_memory.search_long_term_memory_async(request={
    "owner_id": "user-123",
    "query": "window"
})

# Agent Memory automatically creates long-term memories from session memory
# You might have to wait a few minutes and re-run the search query
# to see the auto-created long-term memories [citation:8]

The Magic: As the user chats, Agent Memory automatically extracts important facts (e.g., “User prefers non-stop flights”) and promotes them from short-term to long-term memory in the background. You don’t have to write any extraction logic .

6. Context Retriever: Auto-Generated Tools 

This is where Iris shines for enterprise developers. Instead of writing complex SQL queries for your agent, you define a semantic model, and Iris creates MCP (Model Context Protocol) tools .

Step 1: Define Your Schema

Note: The code below uses the official Context Retriever SDK patterns .

import os
from context_surfaces import ContextSurfacesClient, CreateContextSurfaceRequest

# Using the official ContextSurfacesClient [citation:4]
async with ContextSurfacesClient() as client:
    admin_key = os.environ["CTX_ADMIN_KEY"]
    
    # Create a context surface with your entity schema [citation:4]
    surface = await client.create_context_surface(
        request=CreateContextSurfaceRequest(
            name="wealth-advisor",
            data_model={
                "entities": {
                    "Client": {
                        "fields": {
                            "client_id": {"type": "string", "index": True},
                            "name": {"type": "text", "index": True},
                            "email": {"type": "text"}
                        },
                        "key_template": "client:{id}"
                    },
                    "Holding": {
                        "fields": {
                            "holding_id": {"type": "string", "index": True},
                            "client_id": {"type": "string", "index": True},
                            "symbol": {"type": "text", "index": True},
                            "value": {"type": "numeric", "index": True}
                        },
                        "key_template": "holding:{id}"
                    }
                }
            }
        ),
        admin_key=admin_key,
    )
    
    # Create an agent key for MCP access [citation:4]
    agent_key = await client.create_agent_key(
        admin_key=admin_key,
        surface_id=surface.id,
        name="wealth-agent"
    )
    print(f"Agent Key: {agent_key}")  # Save this - it won't be shown again!

# Load data into Redis 
# Using ctxctl CLI for data import
# ctxctl surface import-data --surface-id <surface-id> --data ./data.json

Step 2: Watch the Magic Happen

The Context Retriever automatically generates tools like :

• get_client_by_id – Fetch a specific client

• search_client_by_text – Find clients by name

• filter_holding_by_client_id – Get all holdings for a client

• find_holding_by_value_range – Find holdings in a value range

Step 3: Your Agent Discovers Tools at Runtime

# Your agent automatically discovers these tools
# Using the ctxctl CLI 
# ctxctl tools list --agent-key <agent-key>

# Or use the SDK
# This returns all auto-generated MCP tools
tools = await client.list_tools(agent_key=agent_key)
# The agent now has 25+ tools it can call

# If you add a new "Orders" entity tomorrow,
# the agent instantly gets new order-searching tools
# —zero code changes required [citation:3].

7. LangCache: The Money-Saving Machine 

LangCache intercepts semantically similar queries before they reach your LLM .

What It Is

LangCache is Redis’s fully managed semantic caching service. With LangCache, you can seamlessly integrate LLM response caching into your application. It features a REST API interface and includes advanced optimizations to ensure highly accurate caching performance .

How It Works 

1. User asks: “What’s the weather in Tokyo?”

2. LangCache generates an embedding

3. LangCache checks if a similar question has been answered

4. If yes (similarity > threshold) → Returns cached response (fast + free)

5. If no → Calls LLM, stores the response

Setup Code

Option A: Managed LangCache (Redis Cloud) 

# Managed LangCache - fully managed semantic cache [citation:2]
# Sign up for private preview at redis.io/langcache [citation:7]

from langcache import LangCache

# Initialize with your LangCache credentials
cache = LangCache(
    cache_id=os.environ["LANGCACHE_ID"],
    api_key=os.environ["LANGCACHE_API_KEY"],
    endpoint="https://aws-us-east-1.langcache.redis.io"  # Your region
)

def get_cached_or_generate(prompt):
    # Check cache
    cached = cache.get(prompt)
    if cached:
        print("🎯 Cache hit! Saving money...")
        return cached
    
    # Cache miss - call LLM
    print("🤖 Cache miss - calling LLM...")
    response = call_openai(prompt)
    
    # Store in cache
    cache.set(prompt, response)
    return response

Option B: Self-hosted with RedisVL 

# Self-hosted semantic cache using RedisVL [citation:7]
from redisvl.cache import SemanticCache
from redisvl.utils.vectorize import HFTextVectorizer

cache = SemanticCache(
    name="llm_cache",
    distance_threshold=0.1,  # Similarity threshold
    ttl=86400,  # Cache expires in 24 hours
    vectorizer=HFTextVectorizer("all-MiniLM-L6-v2"),
    redis_url="redis://localhost:6379"
)

def get_cached_or_generate(prompt):
    cached = cache.check(prompt=prompt)
    if cached:
        return cached[0]["response"]
    
    response = call_openai(prompt)
    cache.store(prompt=prompt, response=response)
    return response

The Math :

Let’s say your agent handles 100,000 queries/day at $0.001/query.

Similarity Threshold Guide 

8. Redis vs Redis Iris:

Not sure which one you need? Run through this checklist:

Quick Decision Tree

Are you building:
├── A simple cache, rate limiter, or session store?
│   └── Use standard Redis
│
├── An AI agent?
│   ├── Need short-term memory only for a single chat thread?
│   │   └── Use RedisSaver (Standard Redis checkpointer in LangGraph)
│   │
│   └── Need long-term memory, MCP tools, and high token savings?
│       └── Use Redis Iris (The full context engine) [citation:3]

The 5-Question Checklist

9. Getting Started: Your First Iris Setup 

Let’s get your environment ready.

Prerequisites:

pip install redis-agent-memory redis-context-retriever langgraph langchain-openai

Step 1: Sign Up for Redis Cloud

Go to Redis Cloud and create a free account. The free tier has 30 MB storage—perfect for testing.

Step 2: Create an Agent Memory Service 

1. In the Redis Cloud console, select Agent Memory from the left menu

2. Click New Service

3. Give it a name and select your database

4. A window will display your Agent Memory service key—this is the only time it’s shown. Save it to a secure location 

Step 3: Set Environment Variables 

export AGENT_MEMORY_ENDPOINT="https://<region>.agent-memory.redis.io"
export AGENT_MEMORY_STORE_ID="<your-store-id>"
export AGENT_MEMORY_KEY="<your-service-key>"
export CTX_AGENT_KEY="<your-context-retriever-key>"

Step 4: Test Your Connection 

from redis_agent_memory import AgentMemory
import os

agent_memory = AgentMemory(
    endpoint=os.environ["AGENT_MEMORY_ENDPOINT"],
    store_id=os.environ["AGENT_MEMORY_STORE_ID"],
    api_key=os.environ["AGENT_MEMORY_KEY"]
)

# Health check [citation:8]
health = await agent_memory.health_async()
print(health.model_dump_json())

10. Real Code: Building a Complete Agent 

Here is a complete, runnable LangGraph agent that uses both Agent Memory and Context Retriever tools.

The Complete Python Implementation

import os
from typing import Annotated, TypedDict
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, MessagesState, END
from langgraph.prebuilt import ToolNode  # For tool binding
from langchain_core.messages import BaseMessage, HumanMessage

# Import Iris SDKs
from redis_agent_memory import AgentMemory
from context_surfaces import ContextSurfacesClient

# 1. Set up environment
os.environ["OPENAI_API_KEY"] = "your-openai-key"

# 2. Initialize the LLM
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

# 3. Connect to Redis Iris Context Retriever
async with ContextSurfacesClient() as client:
    # Fetch auto-generated MCP tools [citation:4]
    tools = await client.list_tools(agent_key=os.environ["CTX_AGENT_KEY"])
    
# 4. Connect to Redis Agent Memory [citation:8]
memory = AgentMemory(
    endpoint=os.environ["AGENT_MEMORY_ENDPOINT"],
    store_id=os.environ["AGENT_MEMORY_STORE_ID"],
    api_key=os.environ["AGENT_MEMORY_KEY"]
)

# 5. Define the Agent State
class AgentState(MessagesState):
    session_id: str
    user_id: str

# 6. Define the Agent Node
def agent_node(state: AgentState):
    # Fetch short AND long-term memory for this user [citation:8][citation:14]
    session_memory = await memory.get_session_memory_async(
        session_id=state.get("session_id")
    )
    
    # Search long-term memory for relevant context [citation:8]
    ltm_results = await memory.search_long_term_memory_async(request={
        "owner_id": state.get("user_id"),
        "query": state["messages"][-1].content,
        "limit": 5
    })
    
    # Inject memory into the prompt
    memory_context = f"Session context: {session_memory}\n"
    memory_context += f"Past memories: {[r.text for r in ltm_results.memories]}"
    
    prompt = f"""Context from memory:
{memory_context}

User question: {state["messages"][-1].content}

Use the tools available to you to find accurate information.
"""
    
    # Bind tools to the LLM [citation:15]
    llm_with_tools = llm.bind_tools(tools)
    response = llm_with_tools.invoke(prompt)
    
    # If the LLM decided to call tools, execute them
    if hasattr(response, 'tool_calls') and response.tool_calls:
        tool_node = ToolNode(tools)
        tool_result = tool_node.invoke(response)
        return {"messages": [response, tool_result]}
    
    return {"messages": [response]}

# 7. Build and Compile the Graph
workflow = StateGraph(AgentState)
workflow.add_node("agent", agent_node)
workflow.set_entry_point("agent")
workflow.add_edge("agent", END)
graph = workflow.compile()

# 8. Run the Agent! [citation:8]
session = await memory.create_session(owner_id="user-123")
result = await graph.ainvoke({
    "messages": [HumanMessage(content="What's the status of my order O5099?")],
    "session_id": session.session_id,
    "user_id": "user-123"
})

print(result["messages"][-1].content)

What Happens Under the Hood 

1. Agent Memory provides session memory + long-term memory for the user 

2. Context Retriever provides auto-generated MCP tools from your schema 

3. The agent discovers and calls the right tools based on the query 

4. The LLM generates a response using the retrieved data

5. Source attribution can be added via post-processing 

11. How It All Works: Request Flow {#request-flow}

High-Level Architecture 

┌─────────────────────────────────────────────────────────────────┐
│                         User Query                            │
└────────────────────────┬───────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                    LangCache (Semantic Cache)                   │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  Check if semantically similar query was answered      │  │
│  │                                            │  │
│  │  If YES → Return cached response (saves $$$)          │  │
│  │  If NO → Continue to agent                            │  │
│  └─────────────────────────────────────────────────────────┘  │
└────────────────────────┬───────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                    AI Agent (LangGraph)                        │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  • Short-term memory (RedisSaver)          │  │
│  │  • Long-term memory (Agent Memory)        │  │
│  │  • Context Retriever MCP tools             │  │
│  └─────────────────────────────────────────────────────────┘  │
└────────────────────────┬───────────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┬────────────────────┐
        ▼                ▼                ▼                    ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ Context     │  │ Data        │  │ Search      │  │ Agent       │
│ Retriever   │  │ Integration │  │ (Vector)    │  │ Memory      │
│ (MCP Tools) │  │ (Live Sync) │  │             │  │ (LTM)       │
└──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                │                │                │
       ▼                ▼                ▼                ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ Postgres    │  │ Oracle      │  │ Snowflake   │  │ MongoDB     │
│ (Live       │  │ (Live       │  │ (Live       │  │ (Live       │
│ Data)       │  │ Data)       │  │ Data)       │  │ Data)       │
└─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘

What Happens in One Request :

1. User sends a question. Example: “Check Jordan Rivera’s portfolio.”

2. LangCache intercepts. It generates an embedding of the question. If a similar question was answered before, it returns the cached response. If not, it passes the request to the agent .

3. Agent Memory provides context. It fetches short-term memory (current conversation) and long-term memory (past facts about this user, like “Jordan Rivera is a high-net-worth client”) .

4. Agent discovers tools. It calls listTools() on Context Retriever and gets auto-generated tools like get_client_by_id, filter_holding_by_client_id, and search_client_by_text .

5. Agent calls the right tool. The LLM decides to call filter_holding_by_client_id with client_id: C1001.

6. Context Retriever executes. It fetches the data from Redis (which was synced from Postgres via Data Integration) .

7. Agent generates response. It uses the retrieved holdings data to answer: “Jordan Rivera has holdings in AAPL ($15,000) and MSFT ($22,000).”

8. Post-processing adds attribution. The response is tagged with “[Source: Wealth Advisor Database].”

9. Response is returned to the user.

10. Agent Memory updates. The conversation is saved to short-term memory. Important facts are automatically promoted to long-term memory in the background .

12. Production Guardrails :

Before pushing to production, check these boxes:

1. Eviction Policies

Standard Redis deletes old keys when it gets full (allkeys-lru). Do NOT use this for Agent Memory, or your agent will randomly get amnesia .

2. Similarity Threshold for LangCache 

Start with a strict threshold (0.10) and adjust based on accuracy needs. A looser threshold (0.20) saves more money but risks returning slightly wrong answers.

3. Session TTLs 

Don’t let session memory grow forever. Set a Time-To-Live (TTL) so short-term threads expire after an hour of inactivity.

# Set TTL for session state
client.expire(f"session:{thread_id}", 3600)  # Expires in 1 hour

4. Metadata Isolation 

Always include owner_id filters in your vector queries. You never want User A’s agent retrieving User B’s private data.

# Filter by user_id in Agent Memory search [citation:14]
search_ltm = await agent_memory.search_long_term_memory_async(request={
    "owner_id": "user-123",  # Filter by owner
    "query": "window"
})

5. The Cold Start Problem 

Agents are dumb on Day 1. Fix this by bulk-importing your existing CRM data into the Long-Term Memory store:

# Bulk import existing user preferences [citation:8]
memories = [
    {"memory_id": "mem-1", "owner_id": "user-123", "text": "User prefers window seats"},
    {"memory_id": "mem-2", "owner_id": "user-123", "text": "User is vegetarian"},
    {"memory_id": "mem-3", "owner_id": "user-123", "text": "User had a bad experience with United"}
]
await agent_memory.bulk_create_long_term_memories_async(memories=memories)

6. Source Attribution 

Because the agent pulls from structured MCP tools, post-process your agent’s output to map the tool_name to a UI citation.

def post_process_message(message, tool_calls):
    # Map tool names to human-readable sources
    source_map = {
        "filter_holding_by_client_id": "Source: Wealth Advisor Database",
        "get_client_by_id": "Source: CRM System"
    }
    
    if tool_calls:
        for tool in tool_calls:
            if tool["name"] in source_map:
                message += f"\n\n{source_map[tool['name']]}"
    return message

13. Limitations & When NOT to Use Redis Iris :

Preview Warning

⚠️ Important Note: Both Context Retriever and Agent Memory are currently in preview . They are intended for evaluation and testing, not production workloads. Features and APIs may change before general availability.

Self-Host vs Managed Reality 

Note: LangCache and Data Integration are currently managed-only services on Redis Cloud .

When to Use Plain Redis (Not Iris) :

When NOT to Use Redis Iris :

1. You have a simple use case – If you just need a cache, Redis is enough.

2. You’re on a tight budget – Self-hosting Iris has infrastructure costs; managed Iris has Redis Cloud pricing.

3. Your data doesn’t change – If you’re working with static datasets, a simpler vector DB might work.

4. You’re not building an AI agent – Redis Iris is specifically for AI agents .

5. You need guaranteed stability – Iris is in preview; use at your own risk .

14. FAQs 

What’s the difference between memory and semantic caching?

Memory helps the agent remember useful context about a specific user (e.g., “Priya is vegetarian”). Semantic caching helps you save money by reusing answers to global, repeated questions (e.g., “What is your refund policy?”) .

Can I self-host Redis Iris?

Partially. Agent Memory and Context Retriever can be self-hosted on your own infrastructure. LangCache and Data Integration are currently managed-only services on Redis Cloud .

Do I need Redis Stack for Redis Iris?

Yes. Redis Iris relies heavily on Redis Stack features like JSON storage and Vector Search, which plain Redis doesn’t have .

What happens when I add a new entity to my database schema?

If you update your schema in the Context Retriever, it automatically generates new tools. The next time your LangGraph agent runs, it will dynamically discover those new tools—no application code changes needed .

Is Redis Iris free?

Redis Cloud has a free tier with 30 MB storage. Self-hosted Agent Memory and Context Retriever are free to use on your infrastructure. Managed services beyond the free tier have Redis Cloud pricing .

How much can LangCache actually save?

Semantic caching can reduce LLM token costs by up to 90%. With a 73% cache hit rate, a $100/day bill becomes $27/day .

How do I populate long-term memory initially?

Use bulk_create_long_term_memories_async to bulk import existing user preferences from your CRM or database .

Can I use Redis Iris with other AI frameworks besides LangGraph?

Yes. Redis Iris exposes MCP tools that can be used with any framework that supports MCP, including CrewAI, Microsoft Semantic Kernel, and others .

What’s the latency of Redis Iris?

Redis Iris operates at sub-millisecond latency for most operations, with context retrieval typically under 2 seconds total .

15. The Bottom Line :

Agents don’t have an intelligence problem; they have a context problem .

Redis is the database. Redis Iris is the context engine that solves that problem by giving your agent :

1. A brain that remembers across sessions 

2. Auto-generated tools to query your business data safely 

3. A caching layer that slashes your OpenAI bills by up to 90% 

4. Sub-millisecond retrieval for real-time responses 

When to Use What ?

Your Next Steps

If you are building an AI agent meant for production, you can’t afford to run it without a dedicated context layer. Redis Iris is that layer.