diff --git a/content/develop/ai/context-engine/_index.md b/content/develop/ai/context-engine/_index.md index 0c25a643d9..9d80f4727b 100644 --- a/content/develop/ai/context-engine/_index.md +++ b/content/develop/ai/context-engine/_index.md @@ -15,7 +15,8 @@ Give your AI agents the context layer they need to reliably act on business data Redis Iris eliminates the infrastructure burden of building context-aware AI agents — persistent memory, semantic caching, governed data access, and live data sync, all on Redis Cloud. -
+
+ {{< image-card image="images/ai-model.svg" alt="Concepts icon" title="Concepts — How familiar Redis patterns work differently in Redis Iris" url="/develop/ai/context-engine/concepts" >}} {{< image-card image="images/ai-brain.svg" alt="Agent Memory icon" title="Agent Memory — Persistent short-term and long-term memory across agent interactions" url="/develop/ai/context-engine/agent-memory" >}} {{< image-card image="images/ai-LLM-memory.svg" alt="LangCache icon" title="LangCache — Semantic caching to reduce LLM costs and improve response times" url="/develop/ai/context-engine/langcache" >}} {{< image-card image="images/ai-cube.svg" alt="Context Retriever icon" title="Context Retriever — Governed, schema-first data access tools for agents" url="/develop/ai/context-engine/context-retriever" >}} @@ -33,6 +34,8 @@ Redis Iris is a production-ready context engine for AI agents that:
  • ●Requires no database management — All four services are fully managed on Redis Cloud via REST API
    • +If you already know Redis, some of this looks familiar but works differently than you'd expect — see [Redis Iris concepts](/content/develop/ai/context-engine/concepts.md) before you start building. + ## Why use Redis Iris?
    diff --git a/content/develop/ai/context-engine/agent-memory/_index.md b/content/develop/ai/context-engine/agent-memory/_index.md index 153a0d221d..fc9af42827 100644 --- a/content/develop/ai/context-engine/agent-memory/_index.md +++ b/content/develop/ai/context-engine/agent-memory/_index.md @@ -23,7 +23,8 @@ When enabled, automatic summarization compacts session memory by summarizing old Access Redis Agent Memory through the Python and TypeScript SDKs or its REST API. It works with any agent framework or LLM provider. -
    +
    + {{< image-card image="images/ai-model.svg" alt="Concepts icon" title="Concepts — What's the same and what's different if you already know Redis" url="/develop/ai/context-engine/agent-memory/concepts" >}} {{< image-card image="images/python-sdk-mark.svg" alt="Python SDK mark" title="Python SDK quickstart — Explore Redis Agent Memory with Python" url="/develop/ai/context-engine/agent-memory/python-sdk-quickstart" >}} {{< image-card image="images/typescript-sdk-mark.svg" alt="TypeScript SDK mark" title="TypeScript SDK quickstart — Explore Redis Agent Memory with TypeScript" url="/develop/ai/context-engine/agent-memory/typescript-sdk-quickstart" >}} {{< image-card image="images/rest-api-mark.svg" alt="REST API mark" title="REST API quickstart — Explore Redis Agent Memory with curl" url="/develop/ai/context-engine/agent-memory/rest-api-quickstart" >}} diff --git a/content/develop/ai/context-engine/agent-memory/concepts.md b/content/develop/ai/context-engine/agent-memory/concepts.md new file mode 100644 index 0000000000..9c77b17a42 --- /dev/null +++ b/content/develop/ai/context-engine/agent-memory/concepts.md @@ -0,0 +1,62 @@ +--- +alwaysopen: false +categories: +- docs +- develop +- ai +description: Learn how Redis Agent Memory's memory types and automatic promotion differ from the Redis session storage you already know. +hideListLinks: true +linktitle: Concepts +title: Redis Agent Memory concepts +weight: 3 +--- + +## Memory types + +Redis Agent Memory splits memory the same way people do, and each kind maps to a specific tier in the service: + +| Human memory | What it holds | Redis Agent Memory tier | +|:---|:---|:---| +| Working memory | What's being discussed right now | Session memory — the ordered events of the current conversation | +| Episodic memory | What happened in a specific past experience | Long-term memory, `episodic` type — a snapshot from one session | +| Semantic memory | Facts and preferences you've generalized over time | Long-term memory, `semantic` type — durable, cross-session facts | + +Session memory is the working set: the current conversation's events, read and written every turn. Long-term memory is what survives after the session ends — durable enough to recall in a conversation the agent hasn't seen before. + +## The mental-model shift: this store writes to itself + +If you've built session storage in Redis before, you're used to a simple rule: the store only holds what the application writes. Agent Memory breaks that rule on purpose. + +Once summarization and extraction are enabled, the service reads session events in the background and does two things without an application write: + +- **Summarizes** older events into a compact summary once the session passes a configured threshold, so a long conversation doesn't blow the model's context window. +- **Extracts long-term memories** — facts and preferences worth keeping — and writes them as separate, searchable records with vector embeddings. + +Both are asynchronous. If you search long-term memory immediately after a session event, the memory extracted from that event might not exist yet — this isn't a bug, it's the tradeoff for keeping session writes fast. Long-term writes also deduplicate. A new memory that's a near-paraphrase of an existing one is collapsed into it rather than stored again. The dedup key is semantic similarity, not the exact equality an idempotency key relies on. + +The most common failure mode: code writes a session event, immediately searches long-term memory, and finds nothing. That's not a broken extraction — it hasn't run yet. + +## FAQ + +**Does this replace my session store?** +Only if your session store's job was holding conversation state. Session memory in Redis Agent Memory is that store, with automatic TTL-based expiration and no schema to design. It doesn't replace a general-purpose cache or your application's other session data unrelated to the conversation. + +**What happens if I write directly to long-term memory instead of letting extraction do it?** +Both paths are supported. Use direct writes for bulk imports or external knowledge sources — anything that didn't originate in a conversation. Automatic extraction is for facts that emerge from session events themselves. + +**Why does dedup sometimes skip a memory I expected to be created?** +Dedup compares the new memory against existing ones by embedding distance, not exact text. A close paraphrase of something already stored increments that memory's hit count instead of creating a new one. If you need every extraction to persist as a distinct record regardless of similarity, create it directly rather than relying on automatic extraction. + +## Further reading + +- [Semantic memory search for AI agents](https://redis.io/blog/semantic-memory-search-ai-agents/) — how semantic recall handles the freshness/staleness problem that keyword search doesn't. +- [Long-horizon AI agents: memory & state infrastructure](https://redis.io/blog/long-horizon-ai-agents-memory-state-infrastructure/) — failure modes (context rot, memory drift, goal-coherence loss) that show up once an agent runs longer than a single session. +- [Agent memory as a moat: how context compounds](https://redis.io/blog/compounding-context-memory-as-the-moat/) — scoping, retention, and access-control tradeoffs as memory accumulates. +- [Build AI agents with short-term & long-term memory in Redis](https://redis.io/blog/build-smarter-ai-agents-manage-short-term-and-long-term-memory-with-redis/) — a broader architectural-decision framework if you're weighing memory tiers, retention, and decay for your own agent. + +See the [AI agent context engine FAQ](https://redis.io/blog/faq-real-time-context-engine-agent-memory-and-retrieval/) for build-vs-buy and vendor-comparison questions this page doesn't cover. + +## Next steps + +- [Developer guide](/content/develop/ai/context-engine/agent-memory/developer-guide.md) to connect an application and start writing session events. +- [Python SDK quickstart](/content/develop/ai/context-engine/agent-memory/python-sdk-quickstart.md), [TypeScript SDK quickstart](/content/develop/ai/context-engine/agent-memory/typescript-sdk-quickstart.md), or [REST API quickstart](/content/develop/ai/context-engine/agent-memory/rest-api-quickstart.md) to see session memory, extraction, and summarization in action. diff --git a/content/develop/ai/context-engine/concepts.md b/content/develop/ai/context-engine/concepts.md new file mode 100644 index 0000000000..897c4dcc69 --- /dev/null +++ b/content/develop/ai/context-engine/concepts.md @@ -0,0 +1,36 @@ +--- +alwaysopen: false +categories: +- docs +- develop +- ai +description: Learn how familiar Redis patterns work differently in Redis Iris, and what's new for building AI agents. +hideListLinks: true +linktitle: Concepts +title: Redis Iris concepts +weight: 5 +--- + +Redis Iris reuses Redis primitives you likely already know, but not all of your existing assumptions carry over. This page covers the shifts that apply across all three services. Each service also has its own concepts page for what's specific to it: [LangCache](/content/develop/ai/context-engine/langcache/concepts.md), [Agent Memory](/content/develop/ai/context-engine/agent-memory/concepts.md), and [Context Retriever](/content/develop/ai/context-engine/context-retriever/concepts.md). + +## Context is a budget, not a store + +Every service in Iris exists to manage a resource that's smaller than it looks: the model's context window. Agent Memory decides what's worth keeping and summarizes the rest. LangCache avoids spending a model call at all when a similar one already ran. Context Retriever returns exactly the data a tool call needs, not a raw query result. Treat "what goes into the next model call" as a budget you're actively managing at every layer, not something that takes care of itself once you've wired up the right service. + +## State isolation is semantic, not just structural + +If you've built concurrent systems before, you're used to races being structural — two writers touching the same key, resolved with a lock or a transaction. When multiple agents or multiple users share Redis Iris services, the races that matter are often semantic instead: two agents writing similar-but-different memories about the same user, or two near-duplicate cache entries competing to answer the same class of question. Locking a key doesn't prevent this — scoping by user, namespace, and memory or entry type does. Design your scoping keys (owner ID, namespace, session ID) as carefully as you'd design a lock strategy in a traditional concurrent system. + +## Trust boundaries move to where the agent acts, not where data is stored + +In a traditional application, the trust boundary is usually the database: application code is trusted, external input is not, and the database enforces permissions at the boundary between them. An agent complicates this, because the agent's next action can be influenced by content it's processing — a retrieved document, a summarized conversation, a tool's own output — that you don't fully control. Context Retriever's governed tool-calling model exists specifically because "trusted code, untrusted data" breaks down once the code's next step is chosen by a model reading that data. Assume anything an agent reads can shape what it does next, and design the tools and memory it can reach accordingly. + +## Further reading + +- [Long-horizon AI agents: memory & state infrastructure](https://redis.io/blog/long-horizon-ai-agents-memory-state-infrastructure/) — failure modes specific to agents that run longer than a single request. +- [Agent memory as a moat: how context compounds](https://redis.io/blog/compounding-context-memory-as-the-moat/) — governance and retention tradeoffs as context accumulates across services. +- [AI agent context engine FAQ](https://redis.io/blog/faq-real-time-context-engine-agent-memory-and-retrieval/) — build-vs-buy, vendor-comparison, and "isn't this overkill" questions this page doesn't cover. + +## Next steps + +See the [Getting Started with Redis Iris](https://redis.io/tutorials/getting-started-with-redis-iris/) tutorial for a hands-on walkthrough of LangCache, Agent Memory, and Context Retriever, or go directly to a service's own concepts page and quickstart. diff --git a/content/develop/ai/context-engine/context-retriever/_index.md b/content/develop/ai/context-engine/context-retriever/_index.md index b5e83bac30..54df7de73e 100644 --- a/content/develop/ai/context-engine/context-retriever/_index.md +++ b/content/develop/ai/context-engine/context-retriever/_index.md @@ -17,7 +17,8 @@ Give your agents structured, governed access to business data — without buildi Context Retriever lets you define your data model once. It automatically generates the retrieval tools agents call at runtime, so agents always work with accurate, live data through a controlled interface rather than guessing at SQL or calling databases directly. -
    +
    + {{< image-card image="images/ai-model.svg" alt="Concepts icon" title="Concepts — Governed tool-calling instead of direct database access, and why it matters" url="/develop/ai/context-engine/context-retriever/concepts" >}} {{< image-card image="images/ai-cube.svg" alt="Quick start icon" title="Quick Start — Create a Context Retriever service on Redis Cloud" url="/operate/iris/context-retriever/create-service" >}} {{< image-card image="images/ai-lib.svg" alt="Python SDK icon" title="Python SDK and CLI — Model entities and deploy tools with the redis-context-retriever package" url="https://pypi.org/project/redis-context-retriever/" >}} {{< image-card image="images/ai-brain.svg" alt="Admin keys icon" title="Manage Access — Create and manage agent keys to control what each agent can access" url="/operate/iris/context-retriever/view-admin-keys" >}} diff --git a/content/develop/ai/context-engine/context-retriever/concepts.md b/content/develop/ai/context-engine/context-retriever/concepts.md new file mode 100644 index 0000000000..19578d3e88 --- /dev/null +++ b/content/develop/ai/context-engine/context-retriever/concepts.md @@ -0,0 +1,50 @@ +--- +alwaysopen: false +categories: +- docs +- develop +- ai +description: Learn how Context Retriever's governed tool-calling differs from giving application code direct database access. +hideListLinks: true +linktitle: Concepts +title: Context Retriever concepts +weight: 3 +--- + +## What this doesn't replace + +Context Retriever doesn't replace your database. It replaces **direct query access from an agent** — the model you'd otherwise reach for is giving the agent a database connection, or generating SQL for it to run. Your database, its schema, and its own access controls are unchanged; Context Retriever sits between the agent and that database as a fixed, predefined set of callable tools. + +## Direct data access vs. governed tool-calling + +If you've built backend services before, you're used to reasoning about data access as a permissions problem: which role can query which tables. Context Retriever reframes it as an API-design problem: which tools exist, and what does each one return. + +| | Direct database access | Context Retriever | +|:---|:---|:---| +| What the agent gets | A query interface (SQL, an ORM, a generic API) | A fixed set of tools generated from your data model | +| How you scope access | Row/column permissions, roles | Access tags on the agent's key, filtering which tools and data it can reach | +| What a bad request looks like | A malformed or overly broad query | A call to a tool that isn't defined — Context Retriever doesn't guess a path around it | +| Where you invest | Query optimization, permission grants | Modeling entities and relationships once, reused by every agent | + +## Why agents don't get raw query access + +The reason isn't that governance is abstractly good practice — it's that an agent's input often includes content it didn't choose to trust. An agent that summarizes a document, reads a support ticket, or follows a web page can have its next action influenced by text embedded in that content (prompt injection). If that agent also holds a database connection or can generate arbitrary SQL, injected content can turn into an arbitrary query. A fixed tool surface bounds the blast radius: the worst an agent can do is call a tool it was already allowed to call, with parameters that tool already accepts. + +## FAQ + +**Why can't my agent run SQL directly?** +Because "run SQL" means the set of things an agent can do is as large as your schema, and an agent's next action can be influenced by untrusted content it's processing. A fixed tool surface — call this tool with these parameters — bounds that risk to what the tool itself allows. + +**How is this different from a regular REST API?** +It's the same idea (a fixed, callable surface instead of a query language) but the tools are generated from your entity model instead of hand-written per endpoint, and access is scoped per agent key via tags rather than a single API-wide permission model. + +**What happens when an agent needs a query I haven't defined a tool for?** +It can't get that data. That's deliberate — Context Retriever doesn't fall back to an open query path. Extend your entity model and regenerate the tool set instead. + +See the [AI agent context engine FAQ](https://redis.io/blog/faq-real-time-context-engine-agent-memory-and-retrieval/) for how this compares to text-to-SQL and OpenAPI-to-MCP approaches. + +## Next steps + +- [Create a Context Retriever service](/content/operate/iris/context-retriever/create-service.md) on Redis Cloud. +- Model your entities with the [Python client and `ctxctl` CLI](https://pypi.org/project/redis-context-retriever/). +- [Manage agent keys and access tags](/content/operate/iris/context-retriever/view-admin-keys.md) to control what each agent can reach. diff --git a/content/develop/ai/context-engine/langcache/_index.md b/content/develop/ai/context-engine/langcache/_index.md index 7b30989af2..d62ad9b140 100644 --- a/content/develop/ai/context-engine/langcache/_index.md +++ b/content/develop/ai/context-engine/langcache/_index.md @@ -19,7 +19,8 @@ Cut LLM costs and improve response times with semantic caching. LangCache checks whether a semantically similar prompt has been answered before and returns the cached response instantly — no LLM call required. When there's no match, your app calls the LLM as usual and stores the result for future use. -
    +
    + {{< image-card image="images/ai-model.svg" alt="Concepts icon" title="Concepts — Why a cache hit isn't binary anymore, and how to choose a similarity threshold" url="/develop/ai/context-engine/langcache/concepts" >}} {{< image-card image="images/ai-LLM-memory.svg" alt="Quick start icon" title="Quick Start — Create a LangCache service on Redis Cloud and make your first API call" url="/operate/iris/langcache/create-service" >}} {{< image-card image="images/ai-search.svg" alt="API examples icon" title="API and SDK Examples — Search, store, and manage cache entries with REST, Python, or JS" url="/develop/ai/context-engine/langcache/api-examples" >}} {{< image-card image="images/ai-brain-2.svg" alt="Monitor icon" title="Monitor Cache — Track hit rates, usage, and performance in Redis Cloud" url="/operate/iris/langcache/monitor-cache" >}} diff --git a/content/develop/ai/context-engine/langcache/concepts.md b/content/develop/ai/context-engine/langcache/concepts.md new file mode 100644 index 0000000000..084b42b115 --- /dev/null +++ b/content/develop/ai/context-engine/langcache/concepts.md @@ -0,0 +1,49 @@ +--- +alwaysopen: false +categories: +- docs +- develop +- ai +description: Learn how semantic caching in LangCache differs from exact-key caching, and what that means for correctness. +hideListLinks: true +linktitle: Concepts +title: LangCache concepts +weight: 3 +--- + +## The failure mode exact-key caching doesn't have + +A standard cache is either right or absent. The key you looked up either matches a stored value exactly, or it's a miss — there's no way for a hit to return the wrong answer, because equality is exact. + +Semantic caching gives up that guarantee on purpose. LangCache matches an incoming prompt against stored entries by similarity, not exact text, so two prompts that are close enough are treated as the same request. That's the entire point — it's what lets "What are Product A's features?" and "Tell me about Product A's capabilities" share a cached response. It's also the new risk: a prompt that's similar but not equivalent can match and return an answer for a question the user didn't ask. A traditional cache can be stale. A semantic cache can be *wrong*, and that failure looks identical to a correct hit until you check the content. + +## Exact-key caching vs. semantic caching + +| | Exact-key caching | LangCache | +|:---|:---|:---| +| Match criterion | Exact key equality | Similarity above a threshold | +| Hit/miss | Binary — no in-between | Threshold-tuned — a near-miss is still possible | +| Correctness risk | None from the cache itself | A false-positive match can return a wrong answer | +| Tuning | TTL, eviction policy | TTL, eviction policy, **and** similarity threshold | + +## Choosing a threshold is a tradeoff, not a default + +There's no globally correct similarity threshold. A tighter threshold reduces wrong-answer risk but also reduces the hit rate you're paying for the cache to get. A looser threshold raises the hit rate but raises the odds of a false-positive match. The right setting depends on the relative cost of a wrong answer versus an unnecessary LLM call. A support FAQ bot can tolerate a looser threshold than a bot answering account-specific financial questions. + +## FAQ + +**Why did I get back a cached response for a question I didn't ask?** +The incoming prompt matched an existing cache entry above the configured similarity threshold, but the match wasn't semantically equivalent. Tighten the threshold, or inspect the matched entry to see how close the embeddings actually were. + +**How do I choose a threshold if there's no default that's "correct"?** +Start conservative (tighter) and loosen it while monitoring hit rate and spot-checking matches, rather than starting loose and trying to catch bad matches after the fact. + +**Does LangCache replace my existing cache layer?** +Only the part of it caching LLM responses by similarity. It doesn't replace general-purpose exact-key caching for anything else in your application. + +See the [AI agent context engine FAQ](https://redis.io/blog/faq-real-time-context-engine-agent-memory-and-retrieval/) for how LangCache compares to building your own cache or skipping caching for smaller workloads. + +## Next steps + +- [Use the LangCache API and SDK](/content/develop/ai/context-engine/langcache/api-examples.md) to search and populate a cache. +- [LangCache REST API reference](/content/develop/ai/context-engine/langcache/api-reference.md) for the full endpoint and parameter details, including threshold configuration.