Iris concepts #4003
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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?** | ||
|
There was a problem hiding this comment. I might hold this for a troubleshooting section for operators rather than concepts. Up to you though! RAM doesn't track hit counts on similar docs, so if you keep this it should probably read something like:
There was a problem hiding this comment. This is a little more accurate because our extraction process is fairly sophisticated. An LLM tries to determine if very similar memories are actually dissimilar and should be tracked, rather than cleanly rejecting new paragraphs that are very similar to existing ones. Some of the details are encoded here: https://github.com/redislabsdev/iris/blob/38063355c6d2272ac76629945d75cab25fd7b700/memory/dataplane/internal/usecases/worker/promote_instruct_strategy.go#L145 |
||
| 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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm wondering how best to explain the difference in LTM on this page. For example, I don't think we document it, but you can extract thread summaries as long-term memories. In that case, we keep an LTM that's an always-updated summary of a specific thread. That means there are semantic, episodic, summary, and custom memory types possible, which is complicated enough that we might want to go high level here and then expand more on those in an LTM page. I defer to your judgment!