Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ Extraction runs in the background. Saving "I am vegetarian" as a session event m

When nothing matches, `recall` returns an empty result and `as_prompt()` returns `What we know: nothing yet.` A REST search returns an empty `items` array. The session history and current question remain available. If you expect a memory but it does not appear:

1. Open the service's **Configuration** tab in Redis Cloud and check **Extraction cadence** under **Memory configuration**. Wait at least that interval after adding the event, then search again.
1. On the Redis Cloud console's **Configuration** tab, check **Background extraction** and **Extraction cadence** under **Long-Term Memory**. After you add an event, wait at least that interval before searching again.
1. If you expect a custom memory type, check that it is enabled under **Memory types & extraction**. Check that its extraction prompt covers the information in the event.
1. Compare the request's `ownerId`, `memoryType`, and namespace filters with the IDs and type used for the memory. Start with the owner filter alone to check whether an added filter excludes it.

Expand Down Expand Up @@ -133,6 +133,8 @@ Before retrying a write, follow its idempotency or recovery contract.

Every operation reports a `424` as `FailedDependencyErrorResponseContent`, with the problem fields under `error.data`. Its `error.data.type` tells the failures apart: an unavailable resource, database memory exhaustion, invalid model credentials, or an exceeded model quota. The generated client's exceptions are in `redis_iris.agent_memory.errors`.

If a store database write returns `424`, inspect `error.data.type` before retrying. Invalid database credentials require operator action. If the embedding provider rejects the input, the service can return `400`. For example, OpenAI can reject text that exceeds the embedding model's token limit. Shorten or split the text before retrying.

`recall` raises `StoreUnusable` from `redis_iris.errors` instead when the `424` response sets a `*_required` flag, such as `memory_recreation_required` after the store's embedding model changed. That store needs an operator, so retrying does not help. `error.required` lists the flags.

This example fails loudly when the store needs an operator and continues without long-term memory when a dependency is temporarily unavailable:
Expand Down
47 changes: 44 additions & 3 deletions content/develop/ai/context-engine/agent-memory/long-term-memory.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,25 @@ This example finds memories about the user's food preferences. `recall` restrict

{{< clients-example set="iris_agent_memory_long_term_memory" step="ltm-search" description="" lang_filter="Python (Iris),CLI (Iris),cURL (Iris)" footer="hide" />}}

A semantic search hit can include a `score` from 0 to 1. A higher score means the memory is more similar to the query. Filter-only searches omit `score`. Python clients expose `score` in `redis-agent-memory` 1.2.0 and later.

### Combine keyword and semantic search

Set `hybrid: true` to search by both the words in your query and its meaning. This helps when a name or product code matters as much as the topic. Redis combines the keyword and vector rankings with reciprocal rank fusion. Each hit includes `hybridScore`. A higher score ranks the hit closer to the top for that query.

```json
{
"query": "Atlas Pro refund policy",
"hybrid": true,
"filter": {"ownerId": {"eq": "<user-id>"}},
"limit": 10
}
```

The query must contain a searchable term. It can have up to 4,096 UTF-8 bytes and 256 searchable terms. Hybrid search cannot use `minScore` or `filter.unnamespaced`. Reuse the same query, filters, and hybrid setting when you follow a cursor. Hybrid cursors support offsets up to 1,000.

Hybrid search requires the Redis [`FT.HYBRID`](/content/commands/ft.hybrid.md) command on the content database. The API returns `501` when the command is unavailable. The first search scoped to an owner can return a retryable `424` while Redis indexes existing records. Retry with backoff. For self-managed upgrades, update every data-plane replica before sending hybrid requests.

### Filter and sort without semantic search

Omit `query` to retrieve records by filters without a semantic query. For example, retrieve the user's most recently updated memories:
Expand Down Expand Up @@ -105,6 +124,20 @@ For example, this search request combines the owner, type, and dietary requireme

Use exactly one typed clause per attribute: `string`, `number`, `boolean`, or `list`, matching the registered field type.

### Refresh memory expiry on retrieval

To refresh expiry on retrieval, send `"refreshTtl": true` in a search request or to [`RetrieveLongTermMemory`](/content/develop/ai/context-engine/agent-memory/api-reference.md#operation/RetrieveLongTermMemory):

```bash
memory_api="${IRIS_AGENT_MEMORY_URL%/}/iris/data/v1/agent-memory/stores/$IRIS_AGENT_MEMORY_STORE_ID"
curl --fail-with-body -X POST "$memory_api/memories/<memory-id>/retrieve" \
-H "Authorization: Bearer $IRIS_AGENT_MEMORY_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"refreshTtl": true}'
```

The credential needs store write permission. Search can refresh expiry for the memories on the returned page. Document-managed memories keep their own expiry. A refresh sets expiry to the current time plus the store's long-term memory TTL unless the memory already expires later. Ordinary searches and `GET` requests leave expiry unchanged.

## Update a memory

Redis Agent Memory provides two ways to change a memory you manage:
Expand All @@ -124,19 +157,19 @@ Change the text and topics with a partial update:

Replace the whole memory with `PUT`:

{{< clients-example set="iris_agent_memory_long_term_memory_update" step="ltm-put" description="" lang_filter="cURL (Iris)" footer="hide" />}}
{{< clients-example set="iris_agent_memory_long_term_memory_update" step="ltm-put" description="" lang_filter="Python (Iris),cURL (Iris)" footer="hide" />}}

### Prevent lost updates

Send `expectedRevision` with the `revision` you read to apply a `PATCH` or `PUT` only if nobody changed the memory since. A stale revision returns `412 Precondition Failed` with the type `/errors/revision-conflict`. Read the memory again, reapply your change, and retry. Omit `expectedRevision` for an unconditional write. Search results from older records can omit `revision`; read the memory by ID before a conditional update.

This request reuses the revision read before the partial update, so it fails:

{{< clients-example set="iris_agent_memory_long_term_memory_update" step="ltm-stale-revision" description="" lang_filter="cURL (Iris)" footer="hide" />}}
{{< clients-example set="iris_agent_memory_long_term_memory_update" step="ltm-stale-revision" description="" lang_filter="Python (Iris),cURL (Iris)" footer="hide" />}}

`PATCH` and `PUT` also accept an `idempotencyKey`. Reuse the key with the same request to retry safely; Redis Agent Memory replays the saved result during the retry window, which lasts at most 24 hours and no longer than the store's memory TTL. Reusing a key with a different request returns `409 Conflict`.

The Python SDK does not yet expose `revision`, `expectedRevision`, update idempotency keys, or the `PUT` operation. Use the HTTP API for replacement and conditional writes.
In Python, read `revision` from `get_long_term_memory`. Pass it as `expected_revision` to `update_long_term_memory` or `upsert_long_term_memory`, and use `idempotency_key` to retry the same write safely. The partial update and replacement examples use these fields.

## Delete memories

Expand Down Expand Up @@ -217,6 +250,12 @@ Inspect the structured fields. The examples collect dietary requirements for the

If results remain empty, check that the type is enabled and that the owner ID matches the stored records. An empty result does not mean the user has no dietary requirements.

### Unregister a custom memory type

Use the [Control Plane API](/content/operate/iris/agent-memory/self-managed/control-plane-api-reference.md#operation/RemoveMemoryType) to unregister a custom memory type. First disable the type's session extraction strategy and remove any document extractors that use it. A remaining dependency returns `409 Conflict`.

Send the type's current `revision` as the `expectedRevision` query parameter to protect the deletion from concurrent updates. On `412 Precondition Failed`, read the type again before retrying. A successful removal returns `204 No Content`. The service retains existing memories and their indexed fields. You can’t register a new type with that name in this store. Extraction jobs that had already started can finish.

### Create a custom memory directly

If your application already has structured trip data, write it directly using the registered `trip_preference` type. This example represents data from a form and uses the same user identifier:
Expand All @@ -229,6 +268,8 @@ See [custom memory types]({{< relref "/operate/iris/agent-memory/create-service#

## Direct-write exclusions

Self-managed Redis Iris 1.0.1 applies exclusions only during extraction.

Enabled built-in and custom detectors check direct creates, replacements, and content updates before embedding or saving. Extraction prompts and semantic exclusions apply only during automatic extraction.

A detector can redact matched content or reject the affected memory. Bulk creates without an input webhook report rejected records in the response's `errors` array and keep accepted records. With an input webhook, a detector rejection during admission can stop the whole request with HTTP `422`; see [webhook failures](/content/develop/ai/context-engine/agent-memory/ingestion-webhooks.md#handle-failures-and-inspect-status). An update rejected by a detector returns HTTP `400` and leaves the stored record unchanged. An attribute-only field update is also rejected if redaction removes every value from its patch.
Expand Down
6 changes: 6 additions & 0 deletions content/develop/ai/context-engine/agent-memory/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,12 @@ Call `tools/list` on an initialized connection to get the input schemas. Tool ar

`edit_long_term_memory` and `upsert_long_term_memory` accept `expected_revision` to apply a change only when the memory's `revision` is current. The write tools accept `idempotency_key` so a retry replays the original result instead of writing twice.

Semantic results can include a `score` between 0 and 1. For example, `"score": 0.87` indicates a higher similarity than `"score": 0.63`. Filter-only results omit it.

Set `hybrid: true` with `text` to combine keyword and vector rankings. Results include `hybrid_score`. Omit `similarity_threshold` from hybrid requests. An unsupported database returns the tool error `hybrid_search_unsupported`. See [Combine keyword and semantic search](/content/develop/ai/context-engine/agent-memory/long-term-memory.md#combine-keyword-and-semantic-search) for query limits and retry behavior.

Call `search_long_term_memory` with `refresh_ttl: true` to refresh expiry for the returned memories. Document-managed memories keep their own expiry. Use a credential with store write permission. See [Refresh memory expiry on retrieval](/content/develop/ai/context-engine/agent-memory/long-term-memory.md#refresh-memory-expiry-on-retrieval) for the expiry rule.

## Connect a client

This client connects, lists the tools, creates a memory, searches for it, and then deletes it.
Expand Down
2 changes: 2 additions & 0 deletions content/develop/ai/context-engine/agent-memory/memory-etl.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,8 @@ Provenance connects a memory to document or session inputs used during extractio
| Memory/source → more evidence | `list_memory_source_evidence` | `GET .../memories/{memoryId}/sources/{sourceId}/evidence` |
| Source → memories for an owner | `list_source_memories` | `GET .../sources/{sourceId}/memories` |

If a query returns `424 Database Server Busy` while Redis rebuilds the source-link index, retry with backoff before deciding whether there are any source links.

The examples take the first output memory ID. They follow its source pages and each source's independent evidence pages, then list memories that the same document source produced for `quickstart-user`:

{{< clients-example set="iris_agent_memory_memory_etl" step="memory-etl-provenance" description="" lang_filter="Python (Iris),cURL (Iris)" footer="hide" />}}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,27 @@ List direct children with `parentId`:
| Archive | Set `state` to `ARCHIVED` to stop new children and placements. You cannot unarchive a namespace. |
| Delete | Delete an empty leaf namespace. A namespace with children or memory placements returns `409 Conflict`. |

Creating a namespace at an occupied location returns `409 Conflict`, including when the existing namespace is archived. Save and reuse the returned ID instead of creating the same namespace on each agent turn. For request fields and error responses, see the [namespace API reference]({{< relref "/develop/ai/context-engine/agent-memory/api-reference" >}}#operation/CreateNamespace).
Creating or renaming a namespace can return `409 Conflict` when the name is occupied. `existingId` appears only when the existing namespace is active and you can access it. Retrieve it by ID and check that it matches the namespace you intended to use. If a duplicate conflict omits the ID, list the relevant roots or direct children and look for the exact name. Save and reuse the ID on subsequent agent turns. See the [namespace API reference](/content/develop/ai/context-engine/agent-memory/api-reference.md#operation/CreateNamespace).

## Find namespaces by name

Use [`SearchNamespaces`](/content/develop/ai/context-engine/agent-memory/api-reference.md#operation/SearchNamespaces) to populate a namespace picker. This example finds direct children of a selected namespace:

```bash
memory_api="${IRIS_AGENT_MEMORY_URL%/}/iris/data/v1/agent-memory/stores/$IRIS_AGENT_MEMORY_STORE_ID"
curl --fail-with-body -X POST "$memory_api/namespaces/search" \
-H "Authorization: Bearer $IRIS_AGENT_MEMORY_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"query":"trip","match":"PREFIX","filter":{"parentId":"<parent-id>"},"limit":20}'
```

`EXACT` matches the entire name and is the default when you supply a query. `PREFIX` matches the start of the name. Both are case-sensitive. Omit the query and match mode for a filter-only search. Omit the hierarchy filter to search at every depth, or use `rootsOnly: true` for roots.

Use each item's ID for placement and its current path for display. Access checks run before paging. Redis result limits can shorten a page, so follow `nextCursor` with the same request until the response omits it.

Prefixes accept 2–64 characters. If the prefix is shorter than the database's [`search-min-prefix`](/content/develop/ai/search-and-query/administration/configuration.md#search-min-prefix), the result can be empty. [`search-max-prefix-expansions`](/content/develop/ai/search-and-query/administration/configuration.md#search-max-prefix-expansions) defaults to 200 and can exclude matches from a broad prefix search. Paging cannot recover those matches.

On self-managed Redis, set [`search-on-timeout`](/content/develop/ai/search-and-query/administration/configuration.md#search-on-timeout) to `FAIL`. A timed-out search then returns an error. Retry with the same filters and cursor to fetch that page.

## Sort namespaces

Expand Down
Loading
Loading