diff --git a/content/develop/ai/context-engine/agent-memory/api-reference/openapi-agent-memory.json b/content/develop/ai/context-engine/agent-memory/api-reference/openapi-agent-memory.json index 270245d843..ae2e50fc29 100644 --- a/content/develop/ai/context-engine/agent-memory/api-reference/openapi-agent-memory.json +++ b/content/develop/ai/context-engine/agent-memory/api-reference/openapi-agent-memory.json @@ -1562,6 +1562,16 @@ } } } + }, + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } + }, + "description": "NotImplementedError 501 response" } }, "tags": [ @@ -3134,7 +3144,7 @@ ] }, "post": { - "description": "Creates a namespace resource as a root, direct child, or explicit hierarchy path. Returns 409 when an active or archived namespace already occupies the requested location.", + "description": "Creates a namespace resource as a root, direct child, or explicit hierarchy path. Returns 409 when an active or archived namespace already occupies the requested location; when an active namespace the caller can access occupies it, the problem's existingId is that namespace's ID. existingId is optional: older servers and lost races can omit it, so clients fall back to listing by name.", "operationId": "CreateNamespace", "requestBody": { "content": { @@ -3586,7 +3596,7 @@ ] }, "patch": { - "description": "Renames or archives a namespace. Returns 409 when the namespace changed concurrently, an active or archived sibling already uses the requested name, or the namespace is archived.", + "description": "Renames or archives a namespace. Returns 409 when the namespace changed concurrently, an active or archived sibling already uses the requested name, or the namespace is archived.\n\nA duplicate-name conflict can include existingId for an accessible, active namespace on supported releases.", "operationId": "UpdateNamespace", "requestBody": { "content": { @@ -3754,7 +3764,7 @@ }, "/iris/data/v1/agent-memory/stores/{storeId}/sessions": { "get": { - "description": "Returns paginated session rows with metadata and caller-selected order.", + "description": "Returns paginated session rows with metadata and caller-selected order. All supplied filters must match.", "operationId": "ListSessions", "parameters": [ { @@ -3797,25 +3807,25 @@ { "name": "ownerId", "in": "query", - "description": "Filter sessions by owner. The owner of a session is the actorId of its first event. Matching is exact and case-sensitive. Combined with namespaceId using AND. Mutually exclusive with includeAll.", + "description": "Filter sessions by owner. The owner of a session is the actorId of its first event. Matching is exact and case-sensitive. All supplied filters must match. Mutually exclusive with includeAll.", "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", - "description": "Filter sessions by owner. The owner of a session is the actorId of its first event. Matching is exact and case-sensitive. Combined with namespaceId using AND. Mutually exclusive with includeAll." + "description": "Filter sessions by owner. The owner of a session is the actorId of its first event. Matching is exact and case-sensitive. All supplied filters must match. Mutually exclusive with includeAll." } }, { "name": "namespaceId", "in": "query", - "description": "Filter by stable namespace ID. Combined with ownerId using AND. Mutually exclusive with includeAll.", + "description": "Filter by stable namespace ID. All supplied filters must match. Mutually exclusive with includeAll.", "schema": { "type": "string", "maxLength": 35, "minLength": 35, "pattern": "^ns_[0-9a-f]{32}$", - "description": "Filter by stable namespace ID. Combined with ownerId using AND. Mutually exclusive with includeAll." + "description": "Filter by stable namespace ID. All supplied filters must match. Mutually exclusive with includeAll." } }, { @@ -3842,6 +3852,86 @@ "schema": { "$ref": "#/components/schemas/SessionListSortOrder" } + }, + { + "description": "Match sessions whose createdAt is greater than this timestamp. Mutually exclusive with createdAtGte and includeAll.", + "in": "query", + "name": "createdAtGt", + "schema": { + "description": "Match sessions whose createdAt is greater than this timestamp. Mutually exclusive with createdAtGte and includeAll.", + "format": "date-time", + "type": "string" + } + }, + { + "description": "Match sessions whose createdAt is greater than or equal to this timestamp. Mutually exclusive with createdAtGt and includeAll.", + "in": "query", + "name": "createdAtGte", + "schema": { + "description": "Match sessions whose createdAt is greater than or equal to this timestamp. Mutually exclusive with createdAtGt and includeAll.", + "format": "date-time", + "type": "string" + } + }, + { + "description": "Match sessions whose createdAt is less than this timestamp. Mutually exclusive with createdAtLte and includeAll.", + "in": "query", + "name": "createdAtLt", + "schema": { + "description": "Match sessions whose createdAt is less than this timestamp. Mutually exclusive with createdAtLte and includeAll.", + "format": "date-time", + "type": "string" + } + }, + { + "description": "Match sessions whose createdAt is less than or equal to this timestamp. Mutually exclusive with createdAtLt and includeAll.", + "in": "query", + "name": "createdAtLte", + "schema": { + "description": "Match sessions whose createdAt is less than or equal to this timestamp. Mutually exclusive with createdAtLt and includeAll.", + "format": "date-time", + "type": "string" + } + }, + { + "description": "Match sessions whose updatedAt is greater than this timestamp. Mutually exclusive with updatedAtGte and includeAll.", + "in": "query", + "name": "updatedAtGt", + "schema": { + "description": "Match sessions whose updatedAt is greater than this timestamp. Mutually exclusive with updatedAtGte and includeAll.", + "format": "date-time", + "type": "string" + } + }, + { + "description": "Match sessions whose updatedAt is greater than or equal to this timestamp. Mutually exclusive with updatedAtGt and includeAll.", + "in": "query", + "name": "updatedAtGte", + "schema": { + "description": "Match sessions whose updatedAt is greater than or equal to this timestamp. Mutually exclusive with updatedAtGt and includeAll.", + "format": "date-time", + "type": "string" + } + }, + { + "description": "Match sessions whose updatedAt is less than this timestamp. Mutually exclusive with updatedAtLte and includeAll.", + "in": "query", + "name": "updatedAtLt", + "schema": { + "description": "Match sessions whose updatedAt is less than this timestamp. Mutually exclusive with updatedAtLte and includeAll.", + "format": "date-time", + "type": "string" + } + }, + { + "description": "Match sessions whose updatedAt is less than or equal to this timestamp. Mutually exclusive with updatedAtLt and includeAll.", + "in": "query", + "name": "updatedAtLte", + "schema": { + "description": "Match sessions whose updatedAt is less than or equal to this timestamp. Mutually exclusive with updatedAtLt and includeAll.", + "format": "date-time", + "type": "string" + } } ], "responses": { @@ -4610,6 +4700,220 @@ "tags": [ "Session Memory" ] + }, + "get": { + "description": "Lists events still stored in the session, including events covered by a session summary until cleanup removes them. With DESC, the first page starts at the end of the range.\n\nAvailability depends on the deployed Agent Memory release.", + "operationId": "ListSessionEvents", + "parameters": [ + { + "name": "storeId", + "in": "path", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "schema": { + "type": "string", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." + }, + "required": true + }, + { + "name": "sessionId", + "in": "path", + "description": "Session identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). When the server generates one, it uses 32 lowercase hex characters.", + "schema": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Session identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). When the server generates one, it uses 32 lowercase hex characters." + }, + "required": true + }, + { + "name": "afterEventId", + "in": "query", + "description": "Exclusive lower bound by position in the session. Returns 404 Event Not Found if the bound event is no longer retained. If this ID came from a summary checkpoint, restart without afterEventId or a cursor to read the retained events.", + "schema": { + "type": "string", + "maxLength": 36, + "minLength": 36, + "pattern": "^evt_[0-9a-f]{32}$", + "description": "Exclusive lower bound by position in the session. Returns 404 Event Not Found if the bound event is no longer retained. If this ID came from a summary checkpoint, restart without afterEventId or a cursor to read the retained events." + } + }, + { + "name": "beforeEventId", + "in": "query", + "description": "Exclusive upper bound by position in the session. Returns 404 if the event is no longer retained.", + "schema": { + "type": "string", + "maxLength": 36, + "minLength": 36, + "pattern": "^evt_[0-9a-f]{32}$", + "description": "Exclusive upper bound by position in the session. Returns 404 if the event is no longer retained." + } + }, + { + "name": "order", + "in": "query", + "description": "Direction of session order. Defaults to ASC, which starts at the oldest event in the range.", + "schema": { + "$ref": "#/components/schemas/SessionListSortOrder" + } + }, + { + "name": "limit", + "in": "query", + "description": "Maximum number of events to return. Defaults to 50.", + "schema": { + "type": "integer", + "maximum": 100, + "minimum": 1, + "description": "Maximum number of events to return. Defaults to 50.", + "format": "int32" + } + }, + { + "name": "last", + "in": "query", + "description": "Return the last N events in the range in session order. Each continuation returns an earlier page in session order. Mutually exclusive with limit and order.", + "schema": { + "type": "integer", + "maximum": 100, + "minimum": 1, + "description": "Return the last N events in the range in session order. Each continuation returns an earlier page in session order. Mutually exclusive with limit and order.", + "format": "int32" + } + }, + { + "name": "cursor", + "in": "query", + "description": "Continuation from a previous page. Keep the session, bounds, order, and last the same. If the cursor's event was deleted, returns 400 Invalid Cursor. Restart without the cursor.", + "schema": { + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Continuation from a previous page. Keep the session, bounds, order, and last the same. If the cursor's event was deleted, returns 400 Invalid Cursor. Restart without the cursor." + } + } + ], + "responses": { + "200": { + "description": "ListSessionEvents 200 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListSessionEventsResponseContent" + } + } + } + }, + "400": { + "description": "BadRequestError 400 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + } + }, + "401": { + "description": "AuthenticationError 401 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + } + }, + "403": { + "description": "ForbiddenError 403 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + } + }, + "404": { + "description": "NotFoundError 404 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + } + }, + "408": { + "description": "TimeoutError 408 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TimeoutErrorResponseContent" + } + } + } + }, + "413": { + "description": "PayloadTooLargeError 413 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PayloadTooLargeErrorResponseContent" + } + } + } + }, + "423": { + "description": "ResourceSuspendedError 423 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResourceSuspendedErrorResponseContent" + } + } + } + }, + "424": { + "description": "FailedDependencyError 424 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" + } + } + } + }, + "429": { + "description": "TooManyRequestsError 429 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsErrorResponseContent" + } + } + } + }, + "500": { + "description": "UnexpectedError 500 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + } + } + }, + "tags": [ + "Session Memory" + ] } }, "/iris/data/v1/agent-memory/stores/{storeId}/sessions/{sessionId}/events/{eventId}": { @@ -6186,12 +6490,316 @@ "Summary Views" ] } - } - }, - "components": { - "schemas": { - "AddSessionEventRequestContent": { - "type": "object", + }, + "/iris/data/v1/agent-memory/stores/{storeId}/memories/{memoryId}/retrieve": { + "post": { + "description": "Returns a long-term memory by its ID with optional expiry refresh.\n\nAvailability depends on the deployed Agent Memory release.", + "operationId": "RetrieveLongTermMemory", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetrieveLongTermMemoryOptions" + } + } + }, + "required": true + }, + "parameters": [ + { + "name": "storeId", + "in": "path", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "schema": { + "type": "string", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." + }, + "required": true + }, + { + "name": "memoryId", + "in": "path", + "description": "Memory record identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). Client-provided for idempotent long-term memory creation.", + "schema": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Memory record identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). Client-provided for idempotent long-term memory creation." + }, + "required": true + } + ], + "responses": { + "200": { + "description": "RetrieveLongTermMemory 200 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetrieveLongTermMemoryResponseContent" + } + } + } + }, + "400": { + "description": "BadRequestError 400 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + } + }, + "401": { + "description": "AuthenticationError 401 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + } + }, + "403": { + "description": "ForbiddenError 403 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + } + }, + "404": { + "description": "NotFoundError 404 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + } + }, + "408": { + "description": "TimeoutError 408 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TimeoutErrorResponseContent" + } + } + } + }, + "413": { + "description": "PayloadTooLargeError 413 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PayloadTooLargeErrorResponseContent" + } + } + } + }, + "423": { + "description": "ResourceSuspendedError 423 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResourceSuspendedErrorResponseContent" + } + } + } + }, + "424": { + "description": "FailedDependencyError 424 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" + } + } + } + }, + "429": { + "description": "TooManyRequestsError 429 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsErrorResponseContent" + } + } + } + }, + "500": { + "description": "UnexpectedError 500 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + } + } + }, + "tags": [ + "Long-Term Memory" + ] + } + }, + "/iris/data/v1/agent-memory/stores/{storeId}/namespaces/search": { + "post": { + "description": "Searches namespace names within a store. Prefix searches use Redis expansion limits and may omit matching names. Pagination covers only the matches Redis returned. Set Redis search-on-timeout to FAIL to prevent partial pages on timeout. Retry a timed-out search with the same request.\n\nAvailability depends on the deployed Agent Memory release.", + "operationId": "SearchNamespaces", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchNamespacesRequestContent" + } + } + } + }, + "parameters": [ + { + "name": "storeId", + "in": "path", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "schema": { + "type": "string", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters." + }, + "required": true + } + ], + "responses": { + "200": { + "description": "SearchNamespaces 200 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchNamespacesResponseContent" + } + } + } + }, + "400": { + "description": "BadRequestError 400 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + } + }, + "401": { + "description": "AuthenticationError 401 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + } + }, + "403": { + "description": "ForbiddenError 403 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + } + }, + "404": { + "description": "NotFoundError 404 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + } + }, + "408": { + "description": "TimeoutError 408 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TimeoutErrorResponseContent" + } + } + } + }, + "413": { + "description": "PayloadTooLargeError 413 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PayloadTooLargeErrorResponseContent" + } + } + } + }, + "423": { + "description": "ResourceSuspendedError 423 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResourceSuspendedErrorResponseContent" + } + } + } + }, + "424": { + "description": "FailedDependencyError 424 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" + } + } + } + }, + "429": { + "description": "TooManyRequestsError 429 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TooManyRequestsErrorResponseContent" + } + } + } + }, + "500": { + "description": "UnexpectedError 500 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + } + } + }, + "tags": [ + "Namespaces" + ] + } + } + }, + "components": { + "schemas": { + "AddSessionEventRequestContent": { + "type": "object", "description": "The event fields shared by CreateSession and AddSessionEvent.", "properties": { "idempotencyKey": { @@ -6231,7 +6839,7 @@ "format": "date-time" }, "metadata": { - "description": "Optional metadata as any valid JSON value." + "description": "Optional metadata as any valid JSON value, with at most 120 nested objects or arrays. Excessive nesting returns HTTP 400 without writing the event." } }, "required": [ @@ -6857,7 +7465,7 @@ "format": "date-time" }, "metadata": { - "description": "Optional metadata as any valid JSON value." + "description": "Optional metadata as any valid JSON value, with at most 120 nested objects or arrays. Excessive nesting returns HTTP 400 without writing the event." }, "sessionId": { "type": "string", @@ -6930,6 +7538,9 @@ }, "refreshPolicy": { "$ref": "#/components/schemas/SummaryViewRefreshPolicy" + }, + "timeBasis": { + "$ref": "#/components/schemas/SummaryViewTimeBasis" } }, "required": [ @@ -7012,6 +7623,9 @@ "updatedAt": { "type": "string", "format": "date-time" + }, + "timeBasis": { + "$ref": "#/components/schemas/SummaryViewTimeBasis" } }, "required": [ @@ -7433,6 +8047,22 @@ "documentManaged": { "type": "boolean", "description": "True when this memory was created by document ingestion and is protected from generic overwrite." + }, + "score": { + "type": "number", + "maximum": 1, + "minimum": 0, + "description": "Similarity score of a semantic search hit: (2 - cosine distance) / 2, in the range 0-1, with higher values indicating greater similarity. Absent from filter-only search and other responses.", + "format": "double" + }, + "summarizedUpToEventId": { + "type": "string", + "description": "For a generated long-term session summary, the last event in its input range. Use this ID as afterEventId when listing session events. If the event was deleted and listing returns 404 Event Not Found, restart without afterEventId or a cursor to read the retained events. Omitted when no checkpoint was recorded." + }, + "hybridScore": { + "description": "Reciprocal rank fusion score for a hybrid search hit. Higher values indicate a better rank within this query.", + "format": "double", + "type": "number" } }, "required": [ @@ -7534,6 +8164,16 @@ }, "summary": { "$ref": "#/components/schemas/SessionSummary" + }, + "createdAt": { + "description": "Timestamp when the session was created (UTC). Absent when unknown.", + "format": "date-time", + "type": "string" + }, + "updatedAt": { + "description": "Timestamp of the latest event append, event removal, or summary write (UTC). Absent when unknown.", + "format": "date-time", + "type": "string" } }, "required": [ @@ -7614,6 +8254,9 @@ "updatedAt": { "type": "string", "format": "date-time" + }, + "timeBasis": { + "$ref": "#/components/schemas/SummaryViewTimeBasis" } }, "required": [ @@ -7706,6 +8349,9 @@ }, "errorCode": { "$ref": "#/components/schemas/SummaryViewResultErrorCode" + }, + "refresh": { + "$ref": "#/components/schemas/SummaryViewRefreshProgress" } }, "required": [ @@ -8243,6 +8889,22 @@ "documentManaged": { "type": "boolean", "description": "True when this memory was created by document ingestion and is protected from generic overwrite." + }, + "score": { + "type": "number", + "maximum": 1, + "minimum": 0, + "description": "Similarity score of a semantic search hit: (2 - cosine distance) / 2, in the range 0-1, with higher values indicating greater similarity. Absent from filter-only search and other responses.", + "format": "double" + }, + "summarizedUpToEventId": { + "type": "string", + "description": "For a generated long-term session summary, the last event in its input range. Use this ID as afterEventId when listing session events. If the event was deleted and listing returns 404 Event Not Found, restart without afterEventId or a cursor to read the retained events. Omitted when no checkpoint was recorded." + }, + "hybridScore": { + "description": "Reciprocal rank fusion score for a hybrid search hit. Higher values indicate a better rank within this query.", + "format": "double", + "type": "number" } }, "required": [ @@ -8865,7 +9527,7 @@ }, "RegexSpec": { "type": "object", - "description": "A regular expression to match against.\n\nEvaluated by RE2, which runs in linear time \u2014 so an expensive pattern is not a\ndenial-of-service risk, but lookaround and backreferences are unavailable.\nRejected on write if it does not compile, or if it can match without consuming\ntext: such a pattern matches at every position, so it would exclude every memory\nthe store writes.", + "description": "A regular expression to match against.\n\nEvaluated by RE2, which runs in linear time — so an expensive pattern is not a\ndenial-of-service risk, but lookaround and backreferences are unavailable.\nRejected on write if it does not compile, or if it can match without consuming\ntext: such a pattern matches at every position, so it would exclude every memory\nthe store writes.", "properties": { "pattern": { "type": "string", @@ -8957,13 +9619,13 @@ "properties": { "query": { "type": "string", - "description": "Text to use for semantic search." + "description": "Text to use for semantic search and, when hybrid is true, keyword search." }, "minScore": { "type": "number", "maximum": 1, "minimum": 0, - "description": "The minimum score for vector search results: (2 - cosine distance) / 2. Allowed range: 0-1.", + "description": "The minimum score for vector search results: (2 - cosine distance) / 2. Allowed range: 0-1. Cannot be combined with hybrid.", "format": "double" }, "filter": { @@ -8992,6 +9654,14 @@ "maxLength": 1024, "minLength": 1, "description": "Opaque token from a previous response for the next page." + }, + "refreshTtl": { + "type": "boolean", + "description": "When true, extend the expiry of eligible memories returned on this page to at least the current time plus the store's long-term memory TTL. Requires store write permission. Document-managed memories keep their own retention policy. Omit or set false to search without refreshing expiry." + }, + "hybrid": { + "description": "When true, rank keyword and vector matches with reciprocal rank fusion. Requires query (up to 4096 UTF-8 bytes and 256 searchable terms) and native FT.HYBRID support on the content database. Cannot be combined with filter.unnamespaced. The hybrid cursor supports offsets up to 1000. The first owner-scoped hybrid search adds an ownership lookup to the existing search index. Hybrid requests that use the lookup return a retryable failed dependency while Redis indexes historical records. Enable hybrid only after all data-plane replicas support it. During rollout or rollback, an older REST replica can ignore hybrid and return semantic results. Start a new search after changing the hybrid setting.", + "type": "boolean" } } }, @@ -9010,7 +9680,7 @@ "type": "string", "maxLength": 1024, "minLength": 1, - "description": "Opaque token for fetching the next page. Omitted when no more results." + "description": "Opaque token for fetching the next page. Reuse it with the same store, query, hybrid setting, filters, and other search options. Concurrent writes can shift results between pages. Omitted at the end of the results or when the next hybrid offset would exceed 1000." } }, "required": [ @@ -9183,11 +9853,13 @@ }, "createdAt": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the session was created (UTC). Absent when unknown." }, "updatedAt": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp of the latest event append, event removal, or summary write (UTC). Absent when unknown." }, "namespaceId": { "type": "string", @@ -9436,6 +10108,9 @@ "updatedAt": { "type": "string", "format": "date-time" + }, + "timeBasis": { + "$ref": "#/components/schemas/SummaryViewTimeBasis" } }, "required": [ @@ -10101,6 +10776,22 @@ "documentManaged": { "type": "boolean", "description": "True when this memory was created by document ingestion and is protected from generic overwrite." + }, + "score": { + "type": "number", + "maximum": 1, + "minimum": 0, + "description": "Similarity score of a semantic search hit: (2 - cosine distance) / 2, in the range 0-1, with higher values indicating greater similarity. Absent from filter-only search and other responses.", + "format": "double" + }, + "summarizedUpToEventId": { + "type": "string", + "description": "For a generated long-term session summary, the last event in its input range. Use this ID as afterEventId when listing session events. If the event was deleted and listing returns 404 Event Not Found, restart without afterEventId or a cursor to read the retained events. Omitted when no checkpoint was recorded." + }, + "hybridScore": { + "description": "Reciprocal rank fusion score for a hybrid search hit. Higher values indicate a better rank within this query.", + "format": "double", + "type": "number" } }, "required": [ @@ -10257,75 +10948,267 @@ "type": "string", "format": "date-time" }, - "updatedAt": { + "updatedAt": { + "type": "string", + "format": "date-time" + }, + "timeBasis": { + "$ref": "#/components/schemas/SummaryViewTimeBasis" + } + }, + "required": [ + "createdAt", + "definitionVersion", + "groupBy", + "name", + "output", + "ownerId", + "refreshPolicy", + "source", + "state", + "updatedAt", + "viewId", + "visibility" + ] + }, + "UpsertLongTermMemoryRequestContent": { + "type": "object", + "properties": { + "idempotencyKey": { + "type": "string", + "maxLength": 128, + "minLength": 1, + "pattern": "^[ -~]+$", + "description": "Reuse the same key and original request to replay the saved result during the retry window (at most 24 hours, capped by the store memory TTL). Reusing the key with a different request returns 409." + }, + "expectedRevision": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "description": "Apply the write only if this revision is current. A stale revision returns 412. Omit for an unconditional write." + }, + "text": { + "type": "string", + "maxLength": 50000, + "minLength": 1, + "description": "Memory text content (1-50000 chars)." + }, + "ownerId": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", + "description": "Actor/owner identifier: a user ID (1-64 chars: letters, digits and _+=.@-, not . or .., case-sensitive). Used for users, agents, or other participants." + }, + "memoryType": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "description": "Identifier of a long-term memory type.\n\nBuilt-in types include `semantic`, `episodic`, `message`, and `session_summary`.\nThe legacy `session_summary_view` name remains reserved. Search filters for either\nsummary name match both, except on stores with an existing custom `session_summary`\ntype, where each name retains its separate meaning.\nStores may also register custom memory types; this open string accepts any\nregistered type name.\n\nConstraints: 1-64 chars, must start with a letter, followed by letters, digits,\nunderscores, or dashes." + }, + "sessionId": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Session identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). When the server generates one, it uses 32 lowercase hex characters." + }, + "namespaceId": { + "type": "string", + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters." + }, + "topics": { + "type": "array", + "items": { + "type": "string", + "maxLength": 100, + "minLength": 1, + "description": "Topic name (1-100 chars)." + }, + "maxItems": 50 + }, + "attributes": { + "$ref": "#/components/schemas/AttributeMap" + } + }, + "required": [ + "ownerId", + "text" + ] + }, + "UpsertLongTermMemoryResponseContent": { + "type": "object", + "properties": { + "memoryId": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Memory record identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). Client-provided for idempotent long-term memory creation." + }, + "created": { + "type": "boolean" + } + }, + "required": [ + "created", + "memoryId" + ] + }, + "ListSessionEventsResponseContent": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SessionEvent" + } + }, + "nextCursor": { "type": "string", - "format": "date-time" + "maxLength": 1024, + "minLength": 1, + "description": "Continuation cursor. Omitted when there are no more events in the range." } }, "required": [ - "createdAt", - "definitionVersion", - "groupBy", - "name", - "output", - "ownerId", - "refreshPolicy", - "source", - "state", - "updatedAt", - "viewId", - "visibility" + "items" ] }, - "UpsertLongTermMemoryRequestContent": { + "NamespaceNameMatch": { + "type": "string", + "enum": [ + "EXACT", + "PREFIX" + ] + }, + "NamespaceSearchFilter": { "type": "object", "properties": { - "idempotencyKey": { + "rootsOnly": { + "type": "boolean", + "default": false, + "description": "Search only roots. Defaults to false. Cannot be true when parentId is supplied." + }, + "parentId": { "type": "string", - "maxLength": 128, + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Search only direct children of this namespace. A missing or inaccessible parent yields an empty result." + }, + "scope": { + "$ref": "#/components/schemas/NamespaceScope" + }, + "ownerId": { + "type": "string", + "maxLength": 64, "minLength": 1, - "pattern": "^[ -~]+$", - "description": "Reuse the same key and original request to replay the saved result during the retry window (at most 24 hours, capped by the store memory TTL). Reusing the key with a different request returns 409." + "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", + "description": "Restrict results to personal namespaces of this root owner, at any depth. Cannot be combined with SHARED scope." }, - "expectedRevision": { + "state": { + "$ref": "#/components/schemas/NamespaceState" + } + } + }, + "RetrieveLongTermMemoryOptions": { + "type": "object", + "properties": { + "refreshTtl": { + "type": "boolean", + "description": "When true, extend the memory's expiry to at least the current time plus the store's long-term memory TTL. Requires store write permission. Document-managed memories keep their own retention policy. Omit or set false to retrieve without refreshing expiry." + } + } + }, + "RetrieveLongTermMemoryResponseContent": { + "type": "object", + "description": "A long-term memory record.", + "properties": { + "attributes": { + "$ref": "#/components/schemas/AttributeMap" + }, + "createdAt": { + "type": "string", + "description": "Timestamp when the memory was created (UTC).", + "format": "date-time" + }, + "documentManaged": { + "type": "boolean", + "description": "True when this memory was created by document ingestion and is protected from generic overwrite." + }, + "memoryId": { "type": "string", "maxLength": 64, "minLength": 1, - "description": "Apply the write only if this revision is current. A stale revision returns 412. Omit for an unconditional write." + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Unique memory record ID." }, - "text": { + "memoryType": { "type": "string", - "maxLength": 50000, + "maxLength": 64, "minLength": 1, - "description": "Memory text content (1-50000 chars)." + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "description": "Type of memory. Built-in or a custom type registered on the store." + }, + "namespaceId": { + "type": "string", + "maxLength": 35, + "minLength": 35, + "pattern": "^ns_[0-9a-f]{32}$", + "description": "Current namespace. Absent when the record has no namespace." }, "ownerId": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^(?:[\\w+=@-][\\w+=.@-]*|\\.[\\w+=@-][\\w+=.@-]*|\\.\\.[\\w+=.@-]+)$", - "description": "Actor/owner identifier: a user ID (1-64 chars: letters, digits and _+=.@-, not . or .., case-sensitive). Used for users, agents, or other participants." + "description": "Owner ID associated with this memory." }, - "memoryType": { + "revision": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", - "description": "Identifier of a long-term memory type.\n\nBuilt-in types include `semantic`, `episodic`, `message`, and `session_summary`.\nThe legacy `session_summary_view` name remains reserved. Search filters for either\nsummary name match both, except on stores with an existing custom `session_summary`\ntype, where each name retains its separate meaning.\nStores may also register custom memory types; this open string accepts any\nregistered type name.\n\nConstraints: 1-64 chars, must start with a letter, followed by letters, digits,\nunderscores, or dashes." + "description": "Opaque revision for conditional writes. Legacy search results can omit it; read the memory by ID before a conditional update." + }, + "score": { + "type": "number", + "maximum": 1, + "minimum": 0, + "description": "Similarity score of a semantic search hit: (2 - cosine distance) / 2, in the range 0-1, with higher values indicating greater similarity. Absent from filter-only search and other responses.", + "format": "double" }, "sessionId": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+$", - "description": "Session identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). When the server generates one, it uses 32 lowercase hex characters." + "description": "Session ID associated with this memory." }, - "namespaceId": { + "sources": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MemorySourceLink" + }, + "description": "Generic source links for this memory. Document sources include the customer document ID and revision that produced the memory." + }, + "sourcesNextCursor": { "type": "string", - "maxLength": 35, - "minLength": 35, - "pattern": "^ns_[0-9a-f]{32}$", - "description": "Server-generated namespace identifier: ns_ followed by 32 lowercase hex characters." + "maxLength": 1024, + "minLength": 1, + "description": "Opaque token for additional source links when this response truncated attribution. Absent when every link is included." + }, + "summarizedUpToEventId": { + "type": "string", + "description": "For a generated long-term session summary, the last event in its input range. Use this ID as afterEventId when listing session events. If the event was deleted and listing returns 404 Event Not Found, restart without afterEventId or a cursor to read the retained events. Omitted when no checkpoint was recorded." + }, + "text": { + "type": "string", + "description": "The memory content." }, "topics": { "type": "array", @@ -10335,35 +11218,186 @@ "minLength": 1, "description": "Topic name (1-100 chars)." }, - "maxItems": 50 + "maxItems": 50, + "description": "Topic tags for categorization." }, - "attributes": { - "$ref": "#/components/schemas/AttributeMap" + "updatedAt": { + "type": "string", + "description": "Timestamp when the memory was last updated (UTC).", + "format": "date-time" + }, + "hybridScore": { + "description": "Reciprocal rank fusion score for a hybrid search hit. Higher values indicate a better rank within this query.", + "format": "double", + "type": "number" } }, "required": [ - "ownerId", - "text" + "createdAt", + "memoryId", + "text", + "updatedAt" ] }, - "UpsertLongTermMemoryResponseContent": { + "SearchNamespacesRequestContent": { "type": "object", "properties": { - "memoryId": { + "query": { "type": "string", "maxLength": 64, "minLength": 1, - "pattern": "^[A-Za-z0-9_-]+$", - "description": "Memory record identifier (1-64 chars: letters, digits, underscores and hyphens, case-sensitive). Client-provided for idempotent long-term memory creation." + "pattern": "^[a-zA-Z0-9_-]+$", + "description": "Case-sensitive namespace name or prefix. Omit to search by filters alone. The API requires at least two characters in a prefix. Redis can return an empty page for prefixes shorter than its configured search-min-prefix." }, - "created": { - "type": "boolean" + "match": { + "$ref": "#/components/schemas/NamespaceNameMatch" + }, + "filter": { + "$ref": "#/components/schemas/NamespaceSearchFilter" + }, + "sortBy": { + "$ref": "#/components/schemas/NamespaceSortBy" + }, + "sortOrder": { + "$ref": "#/components/schemas/NamespaceSortOrder" + }, + "limit": { + "type": "integer", + "default": 50, + "maximum": 200, + "minimum": 1, + "description": "Maximum number of results. Defaults to 50. A Redis result cap can shorten a page that still has a nextCursor.", + "format": "int32" + }, + "cursor": { + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque token from the previous page. Search continues after the last returned result in sort order. Keep the query, matching mode, filters, and sort options unchanged. Concurrent changes can shift results between pages." + } + } + }, + "SearchNamespacesResponseContent": { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Namespace" + } + }, + "nextCursor": { + "type": "string", + "maxLength": 1024, + "minLength": 1, + "description": "Opaque token for the next page. Omitted when the result set is exhausted. A prefix search may hit the Redis expansion limit before finding all matching names." } }, "required": [ - "created", - "memoryId" + "items" + ] + }, + "SummaryViewRefreshProgress": { + "type": "object", + "description": "Current refresh attempt. RUNNING means the worker has a live lease; lastProgressAt advances only at source-page and generation-batch boundaries. INTERRUPTED means its lease expired. FAILED means the last attempt failed and may be retried. No time estimate or percentage is implied.", + "properties": { + "status": { + "$ref": "#/components/schemas/SummaryViewRefreshStatus" + }, + "queuedAt": { + "type": "string", + "format": "date-time" + }, + "startedAt": { + "type": "string", + "format": "date-time" + }, + "lastHeartbeatAt": { + "type": "string", + "format": "date-time" + }, + "lastProgressAt": { + "type": "string", + "format": "date-time" + }, + "phase": { + "type": "string" + }, + "sourcePage": { + "type": "integer", + "minimum": 0, + "format": "int64" + }, + "batch": { + "type": "integer", + "minimum": 0, + "format": "int64" + } + }, + "required": [ + "queuedAt", + "status" + ] + }, + "SummaryViewRefreshStatus": { + "type": "string", + "enum": [ + "QUEUED", + "RUNNING", + "INTERRUPTED", + "FAILED" + ] + }, + "SummaryViewTimeBasis": { + "type": "string", + "description": "Immutable rolling-window time basis. createdAt uses memory storage time. eventTime uses the newest known source message time; memories without a known event time are excluded. Views without a time window retain storage-time ordering.", + "enum": [ + "createdAt", + "eventTime" ] + }, + "NotImplementedErrorResponseContent": { + "description": "The requested capability is recognized but not implemented.", + "externalDocs": { + "description": "RFC 9457", + "url": "https://www.rfc-editor.org/rfc/rfc9457.html" + }, + "properties": { + "detail": { + "description": "A human-readable explanation specific to this occurrence of the problem.", + "type": "string" + }, + "instance": { + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.", + "type": "string" + }, + "status": { + "default": 501, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32", + "type": "integer" + }, + "title": { + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4).", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/NotImplementedErrorType" + } + }, + "required": [ + "status", + "title", + "type" + ], + "type": "object" + }, + "NotImplementedErrorType": { + "description": "Problem type URI for not-implemented errors.", + "enum": [ + "/errors/not-implemented" + ], + "type": "string" } }, "securitySchemes": { diff --git a/content/develop/ai/context-engine/agent-memory/developer-guide.md b/content/develop/ai/context-engine/agent-memory/developer-guide.md index 7b02627288..840feb63e6 100644 --- a/content/develop/ai/context-engine/agent-memory/developer-guide.md +++ b/content/develop/ai/context-engine/agent-memory/developer-guide.md @@ -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. @@ -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: diff --git a/content/develop/ai/context-engine/agent-memory/long-term-memory.md b/content/develop/ai/context-engine/agent-memory/long-term-memory.md index d8a0b72d94..fda0d034e5 100644 --- a/content/develop/ai/context-engine/agent-memory/long-term-memory.md +++ b/content/develop/ai/context-engine/agent-memory/long-term-memory.md @@ -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": ""}}, + "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: @@ -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//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: @@ -124,7 +157,7 @@ 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 @@ -132,11 +165,11 @@ Send `expectedRevision` with the `revision` you read to apply a `PATCH` or `PUT` 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 @@ -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: @@ -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. diff --git a/content/develop/ai/context-engine/agent-memory/mcp.md b/content/develop/ai/context-engine/agent-memory/mcp.md index 4226688379..d787b798ad 100644 --- a/content/develop/ai/context-engine/agent-memory/mcp.md +++ b/content/develop/ai/context-engine/agent-memory/mcp.md @@ -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. diff --git a/content/develop/ai/context-engine/agent-memory/memory-etl.md b/content/develop/ai/context-engine/agent-memory/memory-etl.md index ca6f377753..4ab1b34ef0 100644 --- a/content/develop/ai/context-engine/agent-memory/memory-etl.md +++ b/content/develop/ai/context-engine/agent-memory/memory-etl.md @@ -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" />}} diff --git a/content/develop/ai/context-engine/agent-memory/namespaces/_index.md b/content/develop/ai/context-engine/agent-memory/namespaces/_index.md index 7c94fc9043..67947803b4 100644 --- a/content/develop/ai/context-engine/agent-memory/namespaces/_index.md +++ b/content/develop/ai/context-engine/agent-memory/namespaces/_index.md @@ -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":""},"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 diff --git a/content/develop/ai/context-engine/agent-memory/sessions/_index.md b/content/develop/ai/context-engine/agent-memory/sessions/_index.md index 7fcfce7cc4..c14b83f751 100644 --- a/content/develop/ai/context-engine/agent-memory/sessions/_index.md +++ b/content/develop/ai/context-engine/agent-memory/sessions/_index.md @@ -34,6 +34,8 @@ Redis Agent Memory adds the event ID and storage timestamp. The event fields are | `systemTimestamp` | Server-generated. | Time Redis Agent Memory stored the event. | | `metadata` | Optional from the client. | Application-specific information associated with the event. | +Event metadata can contain up to 120 levels of nested JSON objects and arrays. A deeper value returns `400` before the service writes the event. + 1. Set the first event's `actorId` to the signed-in user's account ID from your application. Use the same ID each time this user returns. The server uses it as the session owner. Later events can identify other actors, such as the assistant. In Python, `conversation.user` sends the `owner` as `actorId`, and `conversation.assistant` sends the `assistant_id` passed to `AgentMemory.from_env()`. 1. Supply a `sessionId`, or omit it to let the server create one. Save the returned `event.sessionId` for later requests. See [Identify users and conversations]({{< relref "/develop/ai/context-engine/agent-memory/developer-guide#identify-users-and-conversations" >}}) for examples. 1. Set the message's `role`, `content`, and `createdAt` timestamp. @@ -57,11 +59,33 @@ The `events` array contains the retained conversation messages. If older events Your application must check that the current user can access this session before using it. The request selects a session by ID; it does not include an owner filter. Compare the returned `ownerId` (`transcript.owner` in Python) with the authenticated user, as the example does. +### Read part of a transcript + +Use [`ListSessionEvents`](/content/develop/ai/context-engine/agent-memory/api-reference.md#operation/ListSessionEvents) to fetch the events you need for the next agent turn. For example, request the last 20 retained events in transcript order: + +```bash +memory_api="${IRIS_AGENT_MEMORY_URL%/}/iris/data/v1/agent-memory/stores/$IRIS_AGENT_MEMORY_STORE_ID" +curl --fail-with-body "$memory_api/sessions//events?last=20" \ + -H "Authorization: Bearer $IRIS_AGENT_MEMORY_API_KEY" +``` + +Use `afterEventId` or `beforeEventId` to set exclusive bounds. Use `limit` and `order` for a page in either direction, or use `last` on its own to page backwards while each page stays in transcript order. Pass `nextCursor` as `cursor` with the same bounds and ordering to continue. + +If a [long-term recap](#store-searchable-session-recaps) includes `summarizedUpToEventId`, use it as the lower bound: + +```bash +curl --fail-with-body --get "$memory_api/sessions//events" \ + -H "Authorization: Bearer $IRIS_AGENT_MEMORY_API_KEY" \ + --data-urlencode "afterEventId=" +``` + +If the recap has no checkpoint or the request returns `404 Event Not Found` for the checkpoint, restart without `afterEventId` or a cursor. If the event your cursor points to was deleted, the service returns `400 Invalid Cursor`. Restart the same range without the cursor. + ## List sessions To let a user reopen an earlier conversation, list their sessions and retrieve the selected session by ID. Use `GET /iris/data/v1/agent-memory/stores/{storeId}/sessions`, `memory.sessions(owner)` or `memory.client.list_sessions` in Python, or `iris agent-memory sessions list`. These rows do not contain events or generated summary text. See [List and sort sessions](/content/develop/ai/context-engine/agent-memory/sessions/list-sessions.md) for SDK examples and pagination. -Filter the list by owner or namespace. +Filter the list by owner, namespace, creation time, or last update time. For a user's personal conversations, set `ownerId` to that user's authenticated ID. A namespace-only query is suitable for shared conversations only after your application checks access to that namespace. Reserve `includeAll=true` for callers your application authorizes to list the whole store. See [Authorize every memory request](/content/develop/ai/context-engine/agent-memory/developer-guide.md#authorize-every-memory-request). @@ -79,11 +103,11 @@ Add `ownerId` to return sessions that match both the namespace and the owner: {{< clients-example set="iris_agent_memory_sessions" step="agent-memory-sessions-list-namespace-owner" description="" lang_filter="Python (Iris),cURL (Iris)" footer="hide" />}} -To list all sessions, omit both filters and set `includeAll=true`: +To list all sessions, omit the filters and set `includeAll=true`. {{< clients-example set="iris_agent_memory_sessions" step="agent-memory-sessions-list-all" description="" lang_filter="Python (Iris),cURL (Iris)" footer="hide" />}} -Do not combine `includeAll=true` with either filter. A request without a filter must set `includeAll=true`. +Do not combine `includeAll=true` with any filter. A request without a filter must set `includeAll=true`. The response contains session rows in `items` and no total count. If the response includes `nextCursor`, pass it as `cursor` with the same filters to fetch the next page. See the [List Sessions API reference]({{< relref "/develop/ai/context-engine/agent-memory/api-reference" >}}#operation/ListSessions) for pagination limits. @@ -112,6 +136,25 @@ For an example that combines session events with long-term recall, follow the [d To group a session and its extracted memories, use an optional [namespace]({{< relref "/develop/ai/context-engine/agent-memory/namespaces#place-and-retrieve-memories" >}}). +## Store searchable session recaps + +Automatic summarization helps you resume a conversation. A long-term session recap is a searchable memory about a conversation. User-defined [Summary Views](/content/develop/ai/context-engine/agent-memory/summary-views.md) summarize a set of long-term memories. + +To enable recaps, set `"longTermMemory": {"sessionSummaryEnabled": true}` when creating or updating the store. The store setting defaults to false. Self-managed deployments also need [recap extraction on the server and worker](/content/operate/iris/agent-memory/self-managed/configuration.md#configure-searchable-session-recaps). + +Search for the recap using the session and memory type: + +```json +{ + "filter": { + "sessionId": {"eq": ""}, + "memoryType": {"eq": "session_summary"} + } +} +``` + +The legacy memory type `session_summary_view` also matches these recaps. In a store with an existing custom type named `session_summary`, use `session_summary_view` to find the built-in recaps. + ## Try automatic summarization {{< embed-md "agent-memory-continue-from-quickstart.md" >}} diff --git a/content/develop/ai/context-engine/agent-memory/sessions/list-sessions.md b/content/develop/ai/context-engine/agent-memory/sessions/list-sessions.md index 2931130bb3..ef5b47d735 100644 --- a/content/develop/ai/context-engine/agent-memory/sessions/list-sessions.md +++ b/content/develop/ai/context-engine/agent-memory/sessions/list-sessions.md @@ -4,7 +4,7 @@ categories: - docs - develop - ai -description: List session metadata by owner or namespace, sort results, and follow pagination. +description: Filter sessions by owner, namespace, or time, sort results, and follow pagination. hideListLinks: true linktitle: List sessions title: List and sort sessions @@ -32,7 +32,20 @@ To list the quickstart user's session IDs: For a user's personal conversations, set `ownerId` to the user's authenticated ID. The session owner is the first event's `actorId`. Add `namespaceId` to require an exact namespace ID as well. It does not include descendants, deprecated namespace labels, or sessions without a namespace resource. Owner and namespace matching is case-sensitive. -A request without filters must set `includeAll=true`. Do not combine `includeAll=true` with either filter. Authorize store-wide or shared namespace listing in your application before making the request. A filter selects records; it does not establish the caller's right to access them. +A request without filters must set `includeAll=true`. Do not combine `includeAll=true` with any filter. Authorize store-wide or shared namespace listing in your application before making the request. A filter selects records; it does not establish the caller's right to access them. + +## Filter by creation time or last update + +Use an RFC 3339 timestamp such as `2026-11-01T00:00:00Z` in any of these query parameters. + +| Time bound | Creation time | Last update | +|:-----------|:--------------|:------------| +| After | `createdAtGt` | `updatedAtGt` | +| At or after | `createdAtGte` | `updatedAtGte` | +| Before | `createdAtLt` | `updatedAtLt` | +| At or before | `createdAtLte` | `updatedAtLte` | + +For an activity window, combine `updatedAtGte` and `updatedAtLt`. Use one lower bound and one upper bound per timestamp. You can combine time bounds with `ownerId` and `namespaceId`. A time filter excludes sessions whose matching timestamp is unknown. ## Sort and paginate session rows @@ -42,6 +55,6 @@ To list session rows for one owner, with the most recently updated sessions firs {{< clients-example set="iris_agent_memory_list_sessions" step="agent-memory-list-sessions-sorted" description="" lang_filter="Python (Iris),cURL (Iris)" footer="hide" />}} -Pass each returned `nextCursor` as `cursor`. Keep filters and sort options unchanged; the cursor is bound to them. Stop when the cursor is absent. The cursor is opaque, so URL-encode it in REST requests. Changing a filter or sort requires a new request without the old cursor. +Pass each returned `nextCursor` as `cursor`. Keep all filters, including time bounds, and sort options unchanged. Stop when the cursor is absent. The cursor is opaque, so URL-encode it in REST requests. Changing a filter or sort requires a new request without the old cursor. -Sessions stored without owner or timestamp metadata can omit `ownerId`, `createdAt`, or `updatedAt`. Handle those missing values when rendering a conversation list. A row's timestamps describe session metadata; they do not promise that background extraction or summarization has completed. +List rows and single-session reads both return `createdAt` and `updatedAt` when known. Older session rows can omit `ownerId` and unknown timestamps. Adding events, removing events, and writing a summary advance `updatedAt`. To see whether a summary is available, check the single-session response. diff --git a/content/develop/ai/context-engine/agent-memory/summary-views.md b/content/develop/ai/context-engine/agent-memory/summary-views.md index 5fc2b5ed89..bed32c6b26 100644 --- a/content/develop/ai/context-engine/agent-memory/summary-views.md +++ b/content/develop/ai/context-engine/agent-memory/summary-views.md @@ -15,7 +15,7 @@ A Summary View turns selected long-term memories into a reusable text or structu A **definition** specifies the sources, filters, grouping, output, and refresh policy. A **partition** is one materialized result for an exact combination of grouping values. An ungrouped definition has one result. Results are derived data; they do not enter long-term-memory search or replace the source records. -Summary Views differ from [session summarization](/content/develop/ai/context-engine/agent-memory/sessions/_index.md#configure-automatic-summarization), which compacts conversation events. The supported source is `LONG_TERM`. Document-managed MemoryETL records are excluded from Summary View sources. +Summary Views use long-term memories. [Automatic summarization](/content/develop/ai/context-engine/agent-memory/sessions/_index.md#configure-automatic-summarization) summarizes conversation events within a session. The supported Summary View source is `LONG_TERM`. Document-managed MemoryETL records are excluded from Summary View sources. ## Prepare the service and identity @@ -25,13 +25,13 @@ Summary Views are available in Redis Cloud and enabled in self-managed deploymen The server assigns the definition's immutable `ownerId` from the caller's authenticated user ID. A create request cannot supply an owner field. -In on-prem deployments with ownership enforcement enabled, creating a view requires an authenticated user ID, including when an agent key is used. Use [delegated user identity](/content/operate/iris/agent-memory/self-managed/authentication.md#delegate-a-user-with-an-agent-key) and send the user token on every Summary View request: pass `http_headers={"X-Iris-User-Token": user_token}` to each Python call, or add `-H "X-Iris-User-Token: $USER_TOKEN"` to each cURL request. The verified user becomes the owner, so filter sources by that user's ID. +On a self-managed store with ownership enforcement enabled, creating a view requires an authenticated user ID, including when an agent key is used. Use [delegated user identity](/content/operate/iris/agent-memory/self-managed/authentication.md#delegate-a-user-with-an-agent-key) and send the user token on every Summary View request. Pass `http_headers={"X-Iris-User-Token": user_token}` to each Python call, or add `-H "X-Iris-User-Token: $USER_TOKEN"` to each cURL request. The verified user becomes the owner, so filter sources by that user's ID. -In on-prem deployments with `ownership.enabled: false`, agent keys without a user can create, refresh, and read views of either visibility. `ownerId` is empty when the caller has no authenticated user ID. +On a self-managed store with ownership enforcement disabled, agent keys without a user can create, refresh, and read views of either visibility. `ownerId` is empty when the caller has no authenticated user ID. Check the store's [effective ownership policy](/content/operate/iris/agent-memory/self-managed/authentication.md#server-side-ownership-enforcement) before choosing a visibility. ### Choose private or shared visibility -In on-prem deployments with ownership enforcement enabled: +On self-managed stores with ownership enforcement enabled: | Visibility | Who can read | Sources | |:-----------|:-------------|:--------| @@ -40,7 +40,7 @@ In on-prem deployments with ownership enforcement enabled: Shared does not mean a particular team. Enforce team membership in your backend or use separate stores and grants. -In on-prem deployments with enforcement off, both visibilities use store-level access without ownership checks. `PRIVATE` does not restrict readers, and `SHARED` views are not restricted to shared memories. Source selection for either visibility does not check record ownership or namespace scope, including personal namespace filters. `PRIVATE` does not replace backend authorization. A view records its source-access policy at creation. Changing on-prem enforcement requires replacing existing views and configuring server and worker alike. +With ownership enforcement disabled, every caller with store read access can read a `PRIVATE` view. Both `PRIVATE` and `SHARED` views can include personal memories. Your backend must authorize access to personal data. A view records its source-access policy at creation. Replace views whose policy differs from the store's effective policy after a change. Keep the server and worker configuration aligned. ## Create, refresh, and read a view @@ -77,9 +77,24 @@ Text output uses `value.text`; structured output uses `value.data`. Python outpu Result reads validate contributing source records. Deleted, changed, or newly inaccessible sources can cause old output to be withheld and repair to be requested. Repair is asynchronous; an old value need not remain available. +### Track refresh progress + +A result can include `refresh` while a newer attempt is outstanding. Use `value` and `stale` to decide whether to serve the cached result. Use `refresh.status` to inspect the attempt: + +| Status | Meaning | +|:-------|:--------| +| `QUEUED` | Work is waiting for a worker. | +| `RUNNING` | A worker holds the refresh lease. | +| `INTERRUPTED` | The worker's lease expired and another attempt can recover the work. | +| `FAILED` | The last attempt failed. Inspect the result's error and retry as appropriate. | + +`lastHeartbeatAt` shows worker activity. `lastProgressAt` updates as the worker processes sources and generates output. If a terminal failure leaves newer changes pending, a continuous view picks them up during reconciliation. For a manual view, request another refresh after addressing the failure. + +Repeated refresh requests for the same partition share a queued job. Changes during a build can queue one follow-up after it succeeds. An immediate manual refresh can bring a delayed job forward. A job that is already retrying keeps its backoff. + ## Filter and group sources -Use `filter` for owners, sessions, stable namespace IDs, topics, memory types, creation times, and typed attributes. `filter.op` defaults to `ALL`; `ANY` combines optional filters with OR. Exact partition scope and time-window restrictions apply separately, as do ownership checks in on-prem deployments. Legacy `namespace` labels are unsupported for Summary Views; use `namespaceId`. +Use `filter` for owners, sessions, stable namespace IDs, topics, memory types, creation times, and typed attributes. `filter.op` defaults to `ALL`; `ANY` combines optional filters with OR. Exact partition scope, time windows, and self-managed ownership checks apply independently. Use `namespaceId` to filter by namespace. `groupBy` accepts up to four distinct fields: `ownerId`, `sessionId`, `namespaceId`, and `memoryType`. A result read or `target: PARTITION` refresh must supply exactly those fields. Missing or extra scope fields are invalid. `groupBy: []` creates a singleton; omit all scope fields when reading it. @@ -94,7 +109,19 @@ For `groupBy: ["ownerId", "namespaceId"]`, use this partition refresh body: Send the same scope as query parameters on result reads. `target: FULL` reconciles current and previous partitions. -`evictionPolicy.maxPartitions` bounds grouped results within the deployment limit. Grouped views use the operator's partition limit when the policy is omitted; singleton views omit it. Matching source mutations make a scope recent; reads do not. Evicted scopes can return `COLD`. `timeWindowSeconds` selects sources by creation time in a rolling window; it does not change source retention. +`evictionPolicy.maxPartitions` bounds grouped results within the deployment limit. Grouped views use the operator's partition limit when the policy is omitted; singleton views omit it. Matching source mutations make a scope recent; reads do not. Evicted scopes can return `COLD`. + +`timeWindowSeconds` sets a rolling window for source selection. The default time basis, `createdAt`, uses the time when Agent Memory stored each memory. The window only affects which memories the view uses. + +Set `"timeBasis": "eventTime"` when you create the view and include a `timeWindowSeconds` value. For example, use `1209600` for a 14-day window. This keeps historical session imports out of a recent view. Agent Memory ranks eligible memories by event time before applying source limits. + +- For a session-derived memory, event time is the newest rendered message time from its recorded extraction sources. Send original message timestamps when importing sessions. +- For a new direct memory, event time is the memory's creation time. +- The view skips memories without a stored event time, including records written before the feature was available. Agent Memory does not backfill timestamps. + +Create a new view to choose a different time basis. On self-managed deployments, upgrade the Agent Memory control plane, data-plane servers, and workers before creating an event-time view. Disable event-time views before rolling back to older binaries. Older workers select sources by storage time. + +When a source used in a cached result ages out of the window, the result reports `stale: true`. Continuous views refresh at the next reconciliation. For a manual view, request a refresh. ## Choose structured output and continuous refresh @@ -147,7 +174,7 @@ This example updates the description, which does not trigger generation, and lis | Name or description | Does not trigger generation. | | Filter, output, or refresh policy | Increments `definitionVersion`. | | `groupBy` | Increments `definitionVersion` and replaces the partition layout. | -| Owner, visibility, or source | Cannot be changed. Create a new definition. | +| Owner, visibility, source, or time basis | Create a new definition to change these fields. | | `state: DISABLED` | Disables the view. Re-enabling requests refresh work. | `clearFilter: true` and `clearTimeWindow: true` remove those settings; do not also supply replacements. diff --git a/content/operate/iris/agent-memory/create-service.md b/content/operate/iris/agent-memory/create-service.md index 35ef05583a..7a45357a8a 100644 --- a/content/operate/iris/agent-memory/create-service.md +++ b/content/operate/iris/agent-memory/create-service.md @@ -21,7 +21,9 @@ Redis Agent Memory provides a persistent, structured memory layer that AI agents To create a Redis Agent Memory service, you will need a Redis Cloud database. If you don't have one, see [Create a database]({{< relref "/operate/rc/databases/create-database" >}}). -Redis Agent Memory doesn't support [Redis Flex]({{< relref "operate/rc/databases/create-database/create-flex-database">}}) databases, databases using [AWS PrivateLink]({{< relref "operate/rc/security/aws-privatelink">}}) connectivity, [Active-Active]({{< relref "/operate/rc/databases/active-active" >}}) databases, or databases with the [default user]({{< relref "/operate/rc/security/access-control/data-access-control/default-user" >}}) turned off. The console lists only the databases you can use. +Use an active Redis Cloud Essentials or Pro database running Redis 7.2 through 8.8. The database needs a public endpoint, an enabled [default user](/content/operate/rc/security/access-control/data-access-control/default-user.md) with a password, and vector search. If the database selector lists an unmet requirement, correct that setting or choose another database. + +Redis Agent Memory doesn't support [Redis Flex](/content/operate/rc/databases/create-database/create-flex-database.md), databases that use [AWS PrivateLink](/content/operate/rc/security/aws-privatelink.md), or [Active-Active](/content/operate/rc/databases/active-active/_index.md) databases. If the database you select has a Classless Inter-Domain Routing (CIDR) allow list, the console lists the Internet Protocol (IP) addresses to add to it so Agent Memory can reach the database. Add them under **Security** in the database's settings. The console also warns you if the database has Transport Layer Security (TLS) turned off. @@ -184,7 +186,7 @@ Custom detectors match patterns you write yourself, such as tenant IDs, internal You can define up to 32 custom detectors. -Direct API writes reject enabled patterns that expand to more than 1,024 compiled RE2 instructions. Repeated groups can exceed this limit even within the pattern's character limit. See [direct-write exclusions](/content/develop/ai/context-engine/agent-memory/long-term-memory.md#direct-write-exclusions) before enabling complex patterns. +Repeated groups can exceed the limit of 1,024 compiled RE2 instructions. Broad Unicode character classes and case-insensitive patterns can exceed the 64 KiB limit for compiled character ranges. If a write fails because of a pattern limit, reduce repetition, narrow the character classes, or disable the pattern. See [Direct-write exclusions](/content/develop/ai/context-engine/agent-memory/long-term-memory.md#direct-write-exclusions). #### On match {#on-match} diff --git a/content/operate/iris/agent-memory/self-managed/api-examples.md b/content/operate/iris/agent-memory/self-managed/api-examples.md index 1869d62403..cf9dfd3ce3 100644 --- a/content/operate/iris/agent-memory/self-managed/api-examples.md +++ b/content/operate/iris/agent-memory/self-managed/api-examples.md @@ -150,6 +150,24 @@ A store may define at most 32 custom detectors. Update an existing store's polic For what each mechanism does, how a match is handled, and which memory paths exclusions apply to, see [exclude sensitive data from automatic extraction]({{< relref "/develop/ai/context-engine/agent-memory/developer-guide#exclude-sensitive-data-from-automatic-extraction" >}}). +### Change ownership or extraction for a store + +Requires self-managed Redis Iris 1.1 or later. + +Send a `PATCH /iris/v1/agent-memory/stores/{storeId}` request with an authorized Control Plane credential. For example, this body inherits the ownership policy and pauses built-in extraction: + +```json +{ + "ownership": {"mode": "INHERIT"}, + "extractionEnabled": true, + "builtinExtractionEnabled": false +} +``` + +Both extraction switches default to true on store creation. Turning off `extractionEnabled` pauses built-in extraction, custom extraction, and long-term session recaps. It preserves the value of `builtinExtractionEnabled`. To pause only built-in extraction, leave `extractionEnabled` on and turn off `builtinExtractionEnabled`. Automatic summarization, direct writes, and document ingestion have independent controls. + +If the server or worker caches store settings, allow up to `metadata.cache_ttl` for a change to take effect. For example, with a cache time to live of `1m`, allow up to one minute. Queued jobs use the settings they read when they start. Jobs already running can finish. Omit any field you want to preserve. + ## Manage a service with the Control Plane SDK The same package supplies two independently configured clients: diff --git a/content/operate/iris/agent-memory/self-managed/authentication.md b/content/operate/iris/agent-memory/self-managed/authentication.md index cd720d4441..ef576b32ea 100644 --- a/content/operate/iris/agent-memory/self-managed/authentication.md +++ b/content/operate/iris/agent-memory/self-managed/authentication.md @@ -148,16 +148,32 @@ Operation mapping: | `write` | Add/delete session events, delete session memory, set session summary, set session property, create/update/delete long-term memory. | {{< /table-scrollable >}} +For a federated service subject that needs to read across owners, grant `read_all_owners` explicitly for the target store. This grant is read-only. Agent keys use their store grants and the store's ownership rules. + +### Authenticate with an Iris access token + +Requires self-managed Redis Iris 1.1 or later. + +Send the Iris access token in the `Authorization: Bearer` header. Use a token with the Data Plane audience and a principal with a grant for the target store. + +For tokens issued by an identity provider registered to a tenant, see [Configure a tenant identity provider](/content/operate/iris/identity-service/self-managed/authentication.md#configure-a-tenant-identity-provider). The issuer record supplies the tenant, and its `userIdClaim` supplies the ID Agent Memory uses for ownership. + ## Server-side ownership enforcement Store grants authorize access to a store. Ownership enforcement adds a check within that store: ordinary callers can access their own personal records and shared records. -This section applies to on-prem deployments. Ownership enforcement is off by default in the on-prem server, worker, and chart. Turn it on with `memory.memory.ownership.enabled: true` after you configure a user identity; see [Enable or change ownership enforcement](#enable-or-change-ownership-enforcement). +In self-managed Redis Iris 1.0.1, use the deployment setting `memory.memory.ownership.enabled`. It defaults to false. Configure a user identity before enabling enforcement. See [Enable or change ownership enforcement](#enable-or-change-ownership-enforcement). + +### Set ownership for one store + +Requires self-managed Redis Iris 1.1 or later. + +Set `ownership.mode` in the store create or update request. Use `ENABLED` or `DISABLED` to override the default. `INHERIT` uses the tenant default if configured, then the deployment setting. Read `ownership.enabled` and `ownership.source` in the response to check the effective policy. If the server or worker caches store settings, allow up to `metadata.cache_ttl` for the change to take effect. | Setting | Personal access | Shared access | | --- | --- | --- | -| `ownership.enabled: false` | Your trusted backend must authorize every read and write, including direct-ID requests. Owner fields and filters do not authenticate the user. | Your backend checks which shared namespaces the user may access. | -| `ownership.enabled: true` | The server compares the stored owner with the authenticated user ID. Search and list restrictions apply in addition to client filters. | Callers with the required store permission can access shared records. Shared scope does not enforce team membership. | +| Effective policy disabled | Your trusted backend must authorize every read and write, including direct-ID requests. Use verified identity for those checks. | Your backend checks which shared namespaces the user may access. | +| Effective policy enabled | The server compares the stored owner with the authenticated user ID. Search and list restrictions apply in addition to client filters. | Callers with the required store permission can access shared records. Apply team restrictions in your backend. | Keep application-specific checks in your backend in both modes. Use separate stores and grants if teams need separate server-enforced access. Worker credentials are for background services; do not give them to applications. @@ -174,7 +190,11 @@ With enforcement on: - A personal namespace child inherits its root's owner. - A caller without a user ID can access shared records within its grants, but cannot claim a named personal owner. Ownerless private records are hidden. -Agent keys created by `POST /v1/api-keys` have no user binding by default, and a key never copies its creator's identity. To bind a key to one user, set `identityService.apiKeys.userBinding.enabled: true` (default `false`) and send `userId` when you mint the key. The control token and a `suite_admin` can set any user ID; other callers can set only their own. The Data Plane then uses that user ID for the key's requests. For an application that acts for many users, use delegation instead. Configuring an OpenID Connect (OIDC) claim alone does not bind a key. +Agent keys have no user binding by default. To enable binding during key creation, set `identityService.apiKeys.userBinding.enabled: true`. A caller that can create keys for each target product can select any valid user ID in its authorized tenant. This includes a `product_admin` with permission for Agent Memory when the key grants access to Agent Memory only. + +On `POST /v1/api-keys`, send `userId` to select the exact owner ID. To use your application's user ID, send `applicationUserId` instead. For example, `"applicationUserId": "42"` produces `"userId": "app-42"`. When you supply an explicit `ownerId` or `actorId` in a memory request, use the effective `userId` from the key metadata. + +The key can read or write the selected user's private records within its store grants. Rotation keeps the binding, even when binding new keys is disabled. To change the user, create a new key and revoke the old one. For an application that acts for many users, [delegate the user on each request](#delegate-a-user-with-an-agent-key). An unbound key can pass store health checks and access allowed shared data while personal creation returns `403`. A successful health check does not establish a user identity. @@ -297,7 +317,7 @@ Before upgrading an existing deployment: 1. Compare stored personal owners with the verified user IDs your application will send. Resolve owner mismatches before enabling enforcement; the setting does not rewrite owners. 1. Configure delegation, then set `memory.memory.ownership.enabled: true` in chart-rendered values. For a bring-your-own file, use `ownership.enabled: true` at the root. 1. Apply the setting to both Data Plane servers and workers, then roll out those processes. `MEM_OWNERSHIP_ENABLED` overrides the file value; check both for conflicting settings. -1. Replace existing Summary Views when changing this setting. A view retains the source-access policy from its creation. +1. Replace each existing Summary View whose source-access policy differs from the store's new effective policy. A view retains the source-access policy from its creation. 1. Test two users: each can access their own personal records, neither can retrieve or search for the other's records, and both can access shared records allowed by their store grants. 1. Test an agent key without a user token: it must not retrieve personal records or create a session for a named owner. diff --git a/content/operate/iris/agent-memory/self-managed/configuration.md b/content/operate/iris/agent-memory/self-managed/configuration.md index 2970d27b39..aae2405597 100644 --- a/content/operate/iris/agent-memory/self-managed/configuration.md +++ b/content/operate/iris/agent-memory/self-managed/configuration.md @@ -64,6 +64,85 @@ explicitly when combining agent keys with worker or other authentication methods For ownership enforcement, use `memory.memory.ownership.enabled` in Helm values or `ownership.enabled` in a BYO Data Plane configuration file. `MEM_OWNERSHIP_ENABLED` overrides the file setting. Enabling this option does not bind agent keys to users or rewrite existing owners. +For stores that inherit the deployment policy, `MEM_OWNERSHIP_ENABLED` overrides the deployment fallback. See [Server-side ownership enforcement](/content/operate/iris/agent-memory/self-managed/authentication.md#server-side-ownership-enforcement) for store and tenant precedence. + +### Verify Redis Enterprise TLS + +Starting with self-managed Redis Iris 1.0.1, you can add `tls_server_name` to a `rediss://` URL for Metadata Redis, Store Redis, or Job Redis. Use the database Service host in the URL and a name covered by its Transport Layer Security (TLS) certificate in the parameter: + +```text +rediss://:?tls_server_name= +``` + +Agent Memory connects to the Service host and verifies the certificate against `tls_server_name`. Configure the trusted certificate authority as described in [Prerequisites](/content/operate/iris/agent-memory/self-managed/prerequisites.md). + +### Configure additional inference providers + +Requires self-managed Redis Iris 1.1 or later. + +| Provider | Supported roles | Configuration | +| --- | --- | --- | +| Cohere | Embeddings and language model generation | Use `cohere` for the embedding protocol and the Cohere OpenAI-compatible endpoint. Set the embedding dimension to match your model in the Data Plane and Control Plane. | +| Anthropic | Language model generation | Use `anthropic` with the Anthropic OpenAI-compatible endpoint. Configure a separate provider for embeddings. | +| Vertex AI | Embeddings | Use `vertex-ai` with a Google Cloud service account and the model's prediction endpoint. | + +For example, merge this fragment under `memory.memory` to use Cohere embeddings and an Anthropic model for built-in session extraction. Store the real keys in the overlay Secret: + +```yaml +embedding: + provider: cohere + models: + default_embedding_model: embed-v5.0-pro + dimensions: 2048 +embedders_connection_details: + cohere: + protocol: cohere + base_url: https://api.cohere.ai/compatibility/v1 + credentials: + type: static + api_key: +inference_providers: + anthropic: + endpoint: + base_url: https://api.anthropic.com/v1/ + auth_format: bearer +promote_session_memory: + strategies: + instruct: + llm: + provider: anthropic + credentials: + type: static + api_key: + models: + default_chat_model: +``` + +Set the Control Plane's `embedding.dimensions` to the same value when provisioning stores. Use this configuration on stores whose indexes match the chosen embedding model and dimensions. For structured generation, check the schema against the provider's supported keywords. Test extraction and structured Summary View output with your selected model before using them in production. + +#### Configure Vertex AI embeddings + +Merge this example under `memory.memory` in the suite values. Replace `` with your Google Cloud project ID. + +```yaml +embedding: + provider: vertex-ai + models: + default_embedding_model: gemini-embedding-001 + dimensions: 768 +embedders_connection_details: + vertex-ai: + protocol: vertex-ai + base_url: https://us-central1-aiplatform.googleapis.com/v1/projects//locations/us-central1/publishers/google/models/gemini-embedding-001:predict + embeddings_input_field: content + credentials: + type: gcp-service-account +``` + +Supply the Google Cloud service account key in the overlay Secret as `embedders_connection_details.vertex-ai.credentials.gcp.service_account_json`. Give the service account permission to call the prediction endpoint. Set the Control Plane's `embedding.dimensions` to match the Data Plane. Use a separate model for generation. + +With `embeddings_input_field: content`, Vertex AI rejects text over the model's input limit. Shorten or split it before retrying. The `text` mode uses the behavior of your custom endpoint. + ## Bring-your-own (BYO) configuration With BYO configuration, you supply each complete configuration file in your own Secret, and the @@ -310,6 +389,26 @@ For a bring-your-own configuration, place these fields at the file root instead Roll out both the server and worker. Confirm store health, then [create an extractor and submit a document](/content/develop/ai/context-engine/agent-memory/memory-etl.md). Setting `enabled: false` rejects new ingestions; it does not undo memories already written. +### Connect the console to the Data Plane + +Requires self-managed Redis Iris 1.1 or later. + +Keep the console's `memory-dp` route enabled and point it at the Agent Memory Data Plane service. Sign in with the operator credential configured for the console. In admin token mode, use the Agent Memory Control Plane admin token configured for the same release. Connect to the store to use Memory Inspector, Playground, the API explorer, and document extraction. + +If the console reports `Document ingestion is not enabled`, enable document ingestion on the server and worker using the settings in this section. Then verify that the store has an enabled extractor and that the worker can reach the configured model provider. + +## Combine queued automatic summarization requests + +Requires self-managed Redis Iris 1.1 or later. + +When built-in extraction is off, enable `background_jobs.redis.coalesce_session_summaries` to combine queued automatic summarization requests for the same session. Updates during a run can queue one follow-up. The setting defaults to `false`. + +Set it under `memory.memory` in the suite values or at the root of the Data Plane configuration. Upgrade the workers before enabling it on the servers that submit jobs. Before rolling back the workers, turn it off on those servers and wait for queued summarization jobs to finish. + +## Configure searchable session recaps + +Set `session_summary_view.enabled: true` under `memory.memory` in the suite values, or at the root of both the server and worker configuration files. Configure a chat model for `session_summary_view.llm` on the worker. Then enable `longTermMemory.sessionSummaryEnabled` for each intended store. See [Store searchable session recaps](/content/develop/ai/context-engine/agent-memory/sessions/_index.md#store-searchable-session-recaps). + ## Configure Summary Views {#enable-summary-views} Summary Views are enabled in self-managed deployments. Configure the server and worker with the same ownership setting, model provider, and explicit bounds. For chart-rendered configuration, merge these example values under `memory.memory`: diff --git a/content/operate/iris/agent-memory/self-managed/control-plane-api-reference/openapi-control-plane.json b/content/operate/iris/agent-memory/self-managed/control-plane-api-reference/openapi-control-plane.json index 38bb023b3a..782c3088c4 100644 --- a/content/operate/iris/agent-memory/self-managed/control-plane-api-reference/openapi-control-plane.json +++ b/content/operate/iris/agent-memory/self-managed/control-plane-api-reference/openapi-control-plane.json @@ -335,6 +335,12 @@ "minLength": 1, "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", "type": "string" + }, + "revision": { + "description": "Opaque revision returned on reads. Server assigned; ignored on creation.", + "maxLength": 64, + "minLength": 1, + "type": "string" } }, "required": [ @@ -345,6 +351,11 @@ }, "CreateStoreRequestContent": { "properties": { + "builtinExtractionEnabled": { + "default": true, + "description": "Enable built-in Instruct extraction. Defaults to true. When false,\ncustom extraction can still run if extractionEnabled is true.", + "type": "boolean" + }, "customMemoryTypes": { "description": "Custom memory types to register on the store. Optional; when omitted the\nstore uses only built-in memory types.", "items": { @@ -358,6 +369,11 @@ "extractionCadence": { "$ref": "#/components/schemas/ExtractionCadenceConfig" }, + "extractionEnabled": { + "default": true, + "description": "Enable automatic long-term memory extraction from sessions, including\nInstruct, custom types and opted-in session recaps. Defaults to true.\nMemoryETL document ingestion and direct memory writes are independent.", + "type": "boolean" + }, "extractionStrategy": { "$ref": "#/components/schemas/ExtractionStrategy" }, @@ -373,6 +389,9 @@ "minLength": 1, "type": "string" }, + "ownership": { + "$ref": "#/components/schemas/OwnershipConfigInput" + }, "shortMemory": { "$ref": "#/components/schemas/ShortMemoryConfigInput" }, @@ -389,6 +408,10 @@ "CreateStoreResponseContent": { "description": "Memory store configuration and status.", "properties": { + "builtinExtractionEnabled": { + "description": "Configured Instruct switch. Effective only when extractionEnabled=true.", + "type": "boolean" + }, "createdAt": { "description": "The UTC timestamp when the memory store was created.", "format": "date-time", @@ -408,6 +431,10 @@ "extractionCadence": { "$ref": "#/components/schemas/ExtractionCadenceConfig" }, + "extractionEnabled": { + "description": "Configured master switch for automatic session extraction.", + "type": "boolean" + }, "extractionStrategy": { "$ref": "#/components/schemas/ExtractionStrategy" }, @@ -426,6 +453,9 @@ "minLength": 1, "type": "string" }, + "ownership": { + "$ref": "#/components/schemas/OwnershipConfigStatus" + }, "shortMemory": { "$ref": "#/components/schemas/ShortMemoryConfigStatus" }, @@ -455,7 +485,9 @@ "longTermMemory", "name", "state", - "storeId" + "storeId", + "extractionEnabled", + "builtinExtractionEnabled" ], "type": "object" }, @@ -603,6 +635,12 @@ "minLength": 1, "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", "type": "string" + }, + "revision": { + "description": "Opaque revision returned on reads. Server assigned; ignored on creation.", + "maxLength": 64, + "minLength": 1, + "type": "string" } }, "required": [ @@ -1009,6 +1047,12 @@ "minLength": 1, "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", "type": "string" + }, + "revision": { + "description": "Opaque revision returned on reads. Server assigned; ignored on creation.", + "maxLength": 64, + "minLength": 1, + "type": "string" } }, "required": [ @@ -1020,6 +1064,10 @@ "GetStoreResponseContent": { "description": "Memory store configuration and status.", "properties": { + "builtinExtractionEnabled": { + "description": "Configured Instruct switch. Effective only when extractionEnabled=true.", + "type": "boolean" + }, "createdAt": { "description": "The UTC timestamp when the memory store was created.", "format": "date-time", @@ -1039,6 +1087,10 @@ "extractionCadence": { "$ref": "#/components/schemas/ExtractionCadenceConfig" }, + "extractionEnabled": { + "description": "Configured master switch for automatic session extraction.", + "type": "boolean" + }, "extractionStrategy": { "$ref": "#/components/schemas/ExtractionStrategy" }, @@ -1057,6 +1109,9 @@ "minLength": 1, "type": "string" }, + "ownership": { + "$ref": "#/components/schemas/OwnershipConfigStatus" + }, "shortMemory": { "$ref": "#/components/schemas/ShortMemoryConfigStatus" }, @@ -1086,7 +1141,9 @@ "longTermMemory", "name", "state", - "storeId" + "storeId", + "extractionEnabled", + "builtinExtractionEnabled" ], "type": "object" }, @@ -1590,6 +1647,96 @@ ], "type": "string" }, + "OwnershipConfigInput": { + "description": "Controls server-side ownership checks. INHERIT uses the tenant default, then ownership.enabled. Omitted on create means inherit; omitted on update leaves the setting unchanged. When enabled, agent keys need a bound userId or verified delegated user token to access personal content; keys without a user ID can access only shared content within their store grants. Existing ownerless records become hidden and Summary Views with a different ownership policy must be recreated. Disabling restores legacy access. Changes propagate through the metadata cache.", + "properties": { + "mode": { + "$ref": "#/components/schemas/OwnershipMode" + } + }, + "required": [ + "mode" + ], + "type": "object" + }, + "OwnershipConfigSource": { + "enum": [ + "STORE", + "TENANT", + "GLOBAL" + ], + "type": "string" + }, + "OwnershipConfigStatus": { + "properties": { + "enabled": { + "type": "boolean" + }, + "mode": { + "$ref": "#/components/schemas/OwnershipMode" + }, + "source": { + "$ref": "#/components/schemas/OwnershipConfigSource" + } + }, + "required": [ + "enabled", + "mode", + "source" + ], + "type": "object" + }, + "OwnershipMode": { + "enum": [ + "INHERIT", + "ENABLED", + "DISABLED" + ], + "type": "string" + }, + "PayloadTooLargeErrorResponseContent": { + "description": "The request payload exceeds the maximum supported size.", + "externalDocs": { + "description": "RFC 9457", + "url": "https://www.rfc-editor.org/rfc/rfc9457.html" + }, + "properties": { + "detail": { + "description": "A human-readable explanation specific to this occurrence of the problem.", + "type": "string" + }, + "instance": { + "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.", + "type": "string" + }, + "status": { + "default": 413, + "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.", + "format": "int32", + "type": "integer" + }, + "title": { + "description": "A short, human-readable summary of the problem\n type. It SHOULD NOT change from occurrence to occurrence of the\n problem, except for purposes of localization (e.g., using\n proactive content negotiation; see [RFC7231], Section 3.4).", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/PayloadTooLargeErrorType" + } + }, + "required": [ + "status", + "title", + "type" + ], + "type": "object" + }, + "PayloadTooLargeErrorType": { + "description": "Problem type URI for payload-too-large errors.", + "enum": [ + "/errors/payload-too-large" + ], + "type": "string" + }, "PreconditionFailedErrorResponseContent": { "description": "The write named an expected revision (expectedRevision or If-Match) that is no longer current. Read the resource again and retry.", "properties": { @@ -1896,6 +2043,10 @@ "StoreOutput": { "description": "Memory store configuration and status.", "properties": { + "builtinExtractionEnabled": { + "description": "Configured Instruct switch. Effective only when extractionEnabled=true.", + "type": "boolean" + }, "createdAt": { "description": "The UTC timestamp when the memory store was created.", "format": "date-time", @@ -1915,6 +2066,10 @@ "extractionCadence": { "$ref": "#/components/schemas/ExtractionCadenceConfig" }, + "extractionEnabled": { + "description": "Configured master switch for automatic session extraction.", + "type": "boolean" + }, "extractionStrategy": { "$ref": "#/components/schemas/ExtractionStrategy" }, @@ -1933,6 +2088,9 @@ "minLength": 1, "type": "string" }, + "ownership": { + "$ref": "#/components/schemas/OwnershipConfigStatus" + }, "shortMemory": { "$ref": "#/components/schemas/ShortMemoryConfigStatus" }, @@ -1962,7 +2120,9 @@ "longTermMemory", "name", "state", - "storeId" + "storeId", + "extractionEnabled", + "builtinExtractionEnabled" ], "type": "object" }, @@ -2186,6 +2346,12 @@ }, "UpdateMemoryTypeRequestContent": { "properties": { + "expectedRevision": { + "description": "The revision as last read. Omitted skips the client revision check.", + "maxLength": 64, + "minLength": 1, + "type": "string" + }, "extractionStrategy": { "$ref": "#/components/schemas/CustomExtractionStrategyUpdate" } @@ -2220,6 +2386,12 @@ "minLength": 1, "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", "type": "string" + }, + "revision": { + "description": "Opaque revision returned on reads. Server assigned; ignored on creation.", + "maxLength": 64, + "minLength": 1, + "type": "string" } }, "required": [ @@ -2230,9 +2402,17 @@ }, "UpdateStoreRequestContent": { "properties": { + "builtinExtractionEnabled": { + "description": "Enable built-in Instruct extraction independently of custom types.\nextractionEnabled=false overrides this switch without changing it.", + "type": "boolean" + }, "extractionCadence": { "$ref": "#/components/schemas/ExtractionCadenceConfig" }, + "extractionEnabled": { + "description": "Enable automatic long-term memory extraction from sessions. Disabling\nalso skips queued runs after settings propagate through the deployment's\nmetadata cache. Active runs may finish.\nMemoryETL, direct writes and session compaction are independent.", + "type": "boolean" + }, "longTermMemory": { "$ref": "#/components/schemas/LongTermMemoryConfigUpdate" }, @@ -2245,6 +2425,9 @@ "minLength": 1, "type": "string" }, + "ownership": { + "$ref": "#/components/schemas/OwnershipConfigInput" + }, "shortMemory": { "$ref": "#/components/schemas/ShortMemoryConfigInput" }, @@ -2257,6 +2440,10 @@ "UpdateStoreResponseContent": { "description": "Memory store configuration and status.", "properties": { + "builtinExtractionEnabled": { + "description": "Configured Instruct switch. Effective only when extractionEnabled=true.", + "type": "boolean" + }, "createdAt": { "description": "The UTC timestamp when the memory store was created.", "format": "date-time", @@ -2276,6 +2463,10 @@ "extractionCadence": { "$ref": "#/components/schemas/ExtractionCadenceConfig" }, + "extractionEnabled": { + "description": "Configured master switch for automatic session extraction.", + "type": "boolean" + }, "extractionStrategy": { "$ref": "#/components/schemas/ExtractionStrategy" }, @@ -2294,6 +2485,9 @@ "minLength": 1, "type": "string" }, + "ownership": { + "$ref": "#/components/schemas/OwnershipConfigStatus" + }, "shortMemory": { "$ref": "#/components/schemas/ShortMemoryConfigStatus" }, @@ -2323,7 +2517,9 @@ "longTermMemory", "name", "state", - "storeId" + "storeId", + "extractionEnabled", + "builtinExtractionEnabled" ], "type": "object" } @@ -4295,6 +4491,16 @@ }, "description": "ConflictError 409 response" }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" + } + } + }, + "description": "PreconditionFailedError 412 response" + }, "424": { "content": { "application/json": { @@ -4342,6 +4548,178 @@ } }, "/iris/v1/agent-memory/stores/{storeId}/memory-types/{memoryTypeName}": { + "delete": { + "description": "Unregister a custom memory type without deleting existing memories or Search\nindex fields. First disable its session extraction strategy and remove every\ndocument Extractor bound to it; otherwise this returns 409. The removed name\nis permanently reserved within this store to protect stored attribute schemas.\nRequests or extraction jobs already admitted with an older store configuration\nmay finish. This operation is not a write barrier or a data purge.\nAn optional expectedRevision protects against stale deletion (412 on mismatch).\nEven when omitted, a concurrent registry change may return 412; read and retry.", + "operationId": "RemoveMemoryType", + "parameters": [ + { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "in": "path", + "name": "storeId", + "required": true, + "schema": { + "description": "Server-generated store identifier: st_ followed by 32 lowercase hex characters.", + "maxLength": 35, + "minLength": 35, + "pattern": "^st_[0-9a-f]{32}$", + "type": "string" + } + }, + { + "description": "Name of a memory type or custom field (1-64 chars): a letter followed by letters, digits, underscores, or dashes.", + "in": "path", + "name": "memoryTypeName", + "required": true, + "schema": { + "description": "Name of a memory type or custom field (1-64 chars): a letter followed by letters, digits, underscores, or dashes.", + "maxLength": 64, + "minLength": 1, + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$", + "type": "string" + } + }, + { + "description": "The project. Not supported yet; omit it.", + "in": "query", + "name": "projectId", + "schema": { + "description": "The project. Not supported yet; omit it.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } + }, + { + "description": "The revision as last read. Omitted skips the client revision check.", + "in": "query", + "name": "expectedRevision", + "schema": { + "description": "The revision as last read. Omitted skips the client revision check.", + "maxLength": 64, + "minLength": 1, + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "RemoveMemoryType 204 response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestErrorResponseContent" + } + } + }, + "description": "BadRequestError 400 response" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthenticationErrorResponseContent" + } + } + }, + "description": "AuthenticationError 401 response" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenErrorResponseContent" + } + } + }, + "description": "ForbiddenError 403 response" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundErrorResponseContent" + } + } + }, + "description": "NotFoundError 404 response" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictErrorResponseContent" + } + } + }, + "description": "ConflictError 409 response" + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" + } + } + }, + "description": "PreconditionFailedError 412 response" + }, + "413": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PayloadTooLargeErrorResponseContent" + } + } + }, + "description": "PayloadTooLargeError 413 response" + }, + "424": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FailedDependencyErrorResponseContent" + } + } + }, + "description": "FailedDependencyError 424 response" + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnexpectedErrorResponseContent" + } + } + }, + "description": "UnexpectedError 500 response" + }, + "501": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotImplementedErrorResponseContent" + } + } + }, + "description": "NotImplementedError 501 response" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableErrorResponseContent" + } + } + }, + "description": "ServiceUnavailableError 503 response" + } + }, + "tags": [ + "memory-types" + ] + }, "get": { "description": "Get one of a store's custom memory types.", "operationId": "GetMemoryType", @@ -4573,6 +4951,16 @@ }, "description": "NotFoundError 404 response" }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreconditionFailedErrorResponseContent" + } + } + }, + "description": "PreconditionFailedError 412 response" + }, "424": { "content": { "application/json": { diff --git a/content/operate/iris/agent-memory/self-managed/deploy.md b/content/operate/iris/agent-memory/self-managed/deploy.md index 9faff82a30..089361509c 100644 --- a/content/operate/iris/agent-memory/self-managed/deploy.md +++ b/content/operate/iris/agent-memory/self-managed/deploy.md @@ -197,7 +197,7 @@ Then upgrade the release as in [Install or upgrade the release](#3-install-or-up To turn enforcement off again, set `memory.memory.ownership.enabled: false` and upgrade the same way. Records keep their owners. Before you turn it on for existing data, follow [Enable or change ownership enforcement](/content/operate/iris/agent-memory/self-managed/authentication.md#enable-or-change-ownership-enforcement). -The suite uses one static tenant, `global.iris.tenantId`. Every valid agent key and every valid user token from the configured issuer acts in that tenant, so Memory never returns the cross-tenant `403` that [Delegate a user with an agent key](/content/operate/iris/agent-memory/self-managed/authentication.md#delegate-a-user-with-an-agent-key) describes. See [Tenancy and identity provider limits](/content/operate/iris/self-managed/_index.md#tenancy-and-identity-provider-limits). +The single-tenant setup in this procedure uses `global.iris.tenantId`. Every valid agent key and user token from the configured issuer acts in that tenant. For releases that support multiple tenants, see [Use a tenant claim](/content/operate/iris/self-managed/_index.md#use-a-tenant-claim). ## 3. Install or upgrade the release diff --git a/content/operate/iris/agent-memory/self-managed/operations.md b/content/operate/iris/agent-memory/self-managed/operations.md index e5f444463c..895d74fb5b 100644 --- a/content/operate/iris/agent-memory/self-managed/operations.md +++ b/content/operate/iris/agent-memory/self-managed/operations.md @@ -106,6 +106,48 @@ kubectl -n rollout status deployment/redis-agent-memory-control To move from a standalone `redis-agent-memory` release or a preview chart, see [Move from a preview or standalone install](/content/operate/iris/self-managed/_index.md#move-from-a-preview-or-standalone-install). +## Collect and inspect audit records + +Requires self-managed Redis Iris 1.1 or later. + +Use the production logging profile to emit structured records to the container logs. Configure your collector to select logger `audit` or names ending in `.audit`. Collect records from Agent Memory and the Identity Service. Use `audit_product: memory` to find Memory events. + +Retain the JSON records in storage with access controls and monitor the collector for output failures, retries, buffer growth, and low disk space. Audit records bypass log sampling and use best-effort delivery. A service crash or collector failure can lose or repeat a record. + +Use `subject` and `user_id` to identify the authenticated actor. Use `store_id`, `resource_id`, and `owner_id` to identify the affected data when those fields are available. The `result` field is `allowed`, `denied`, or `failed`. An allowed mutation confirms persistence, while an allowed authorization event confirms the access check. + +Coverage includes authentication and authorization results, store and namespace changes, long-term memory writes, and document ingestion transitions. The following actions cover session and Summary View changes, expiry refresh, and authentication. + +| Actions | What they record | +| --- | --- | +| `session.create`, `session.event.create`, `session.delete`, `session.event.delete`, `session.events.delete`, `session.summary.update`, `session.property.update` | Committed session changes. Single-event operations can carry an `event_id`. | +| `summary_view.create`, `summary_view.update`, `summary_view.delete.begin`, `summary_view.delete` | Definition changes and deletion progress. | +| `summary_view.refresh.accept`, `summary_view.refresh.complete` | A newly accepted manual refresh or a committed result. | +| `summary_view.refresh.request` | A worker failed to prepare a refresh after accepting its target. | +| `maintenance.retry` | A confirmed change to which recovery attempt may run. Replaying a pending attempt adds no second mutation event. | +| `memory.ttl.refresh` | The outcome of an opted-in REST or Model Context Protocol (MCP) retrieval that reached expiry refresh. The event applies to the store and omits memory IDs, owner IDs, and payloads. `allowed` can mean no expiry changed. | +| `authenticate_delegated_user`, `authenticate_oidc`, `introspect_api_key`, `token.exchange` | Authentication and token exchange outcomes with verified identities and bounded reasons. | + +The token exchange endpoint emits one audit record for each well-formed request that reaches it, including requests it rate-limits. + +Use request logs and metrics for routine reads. For write retries, use the operation's idempotency contract. A confirmed mutation can have a follow-up failure event if later work failed. + +## Recover pending Summary View cleanup + +Requires self-managed Redis Iris 1.1 or later. + +If the content database is unreachable during store deletion, the control plane records pending cleanup in metadata Redis before it removes the store. Give the control plane read and write access to the `iris:memory:store-cleanup` hash. The hash uses your configured metadata namespace as its prefix. If the control plane cannot record pending cleanup, deletion fails and retains the store metadata. + +1. Restore access to the content database. +1. If the store is still present, retry deletion through the control plane. A successful cleanup completes its pending record. +1. If the store is gone and the record has no `completed_at` value, contact Redis support for cleanup of the deleted store. Provide the recorded store and database IDs. Keep database credentials in your secret store. + +## Investigate partial bulk writes + +Requires self-managed Redis Iris 1.1 or later. + +If bulk creation returns HTTP `201`, inspect the per-record `errors` before retrying. In the worker log, find the warning `partial failures in bulk create`. Use its `api_request_id` to find the matching Data Plane log entries. Check the failure stage to distinguish placement, admission, and persistence problems. The summary gives the created, failed, and omitted counts when the service caps individual warnings. + ## Release tests `helm test iris` creates a temporary store, mints a scoped agent key, calls the Data Plane with it, diff --git a/content/operate/iris/agent-memory/view-service.md b/content/operate/iris/agent-memory/view-service.md index fc94769dc9..a0294bdbac 100644 --- a/content/operate/iris/agent-memory/view-service.md +++ b/content/operate/iris/agent-memory/view-service.md @@ -82,6 +82,8 @@ The **Memory configuration** section shows the time-to-live (TTL) for memory sto | **Summarize after (messages)** | The number of messages a session can hold before older messages are summarized. Shown only when automatic summarization is enabled. _(Editable)_ | | **Keep most recent (messages)** | The number of most recent messages that are always kept in full and never summarized. Shown only when automatic summarization is enabled. _(Editable)_ | +Under **Long-Term Memory**, turn off **Background extraction** to pause all automatic session extraction. Turn off **Built-in extraction** to pause only built-in extraction and keep enabled custom types running. The console preserves your extraction settings while extraction is paused. Automatic summarization, direct writes, and MemoryETL continue under their own settings. + ### AI model and credentials {#ai-model-and-credentials} The **AI model and credentials** section appears when the service uses your model provider key. @@ -183,6 +185,8 @@ The view also shows **Latency by phase**, with charts for **Retrieval latency**, The **Token consumption** view shows how many large language model (LLM) and embedding tokens the service used, with a breakdown by feature, such as extraction and session summaries. Select **Export** to download the data as a comma-separated values (CSV) file. +To open the **Metrics** tab, you need the Redis Cloud permission `agent_memory_metrics_get`. Self-managed deployments use their own observability stack. + ## Create an API key {#create-an-api-key} Agents call the Agent Memory API with an API key that has access to the service. To create a key for one service, select **Create API key** or **Connect** in the service's [connect banner](#configuration-tab). To create a key that can reach several services, or to manage existing keys, use **Access & Identity**: @@ -197,3 +201,11 @@ Agents call the Agent Memory API with an API key that has access to the service. > The console shows the key's token only once, when you create it. Save it to a secure location before you close the page. If you lose it, create a new key. To remove an agent's access, delete its key in **Access & Identity**. + +### Bind a key to a user + +An account Owner or Manager with `agent_memory_token_update` can bind a new Agent Memory key to a user in the account through the Identity Service API. The caller needs permission to create keys for every product on the key. User binding for new keys is off by default. + +On `POST /v1/api-keys`, send either `userId` with the exact memory owner ID or `applicationUserId` with your application's ID. For example, `applicationUserId: "42"` produces the owner ID `app-42`. The key metadata returns the effective `userId` and, when supplied, `applicationUserId`. When a request supplies `ownerId` or `actorId`, use the effective `userId`. + +With ownership enforcement on, the key can read or write the selected user's private records within its store grants. Rotating the key preserves the user binding, even if new user bindings are disabled. diff --git a/content/operate/iris/identity-service/self-managed/authentication.md b/content/operate/iris/identity-service/self-managed/authentication.md index addc0071ae..0387094e0b 100644 --- a/content/operate/iris/identity-service/self-managed/authentication.md +++ b/content/operate/iris/identity-service/self-managed/authentication.md @@ -57,7 +57,7 @@ A data plane caches each key check. After you revoke a key, it can keep working ### Subject grants -The control API also has routes for subject grants, `/v1/subject-grants`. They have no effect in a `redis-iris` installation. By default the chart allows no subject-grant shape, so the Identity Service refuses new subject grants. The chart also gives no data plane the `subject-grant-lookup` operation, so no data plane reads them. IdP users get access from their roles in each service, and agents use agent keys. +Use the `/v1/subject-grants` routes to grant a verified token subject access to a service resource. The default `redis-iris` installation accepts no subject grants and gives data planes no permission to look them up. For a data plane configured to use subject grants, allow the grant's product, resource type, and actions in `identityService.subjectGrants.allowed`. Give the data plane's runtime credential `subject-grant-lookup`. ## Tenants @@ -65,7 +65,7 @@ A tenant is a boundary for keys, grants, and service data, such as one customer The Identity Service has no tenant object, and no API creates, lists, or deletes tenants. A tenant is only an ID that each key, grant, and service resource carries. -A `redis-iris` release serves one tenant, set once in `global.iris.tenantId`. The chart gives this ID to the Identity Service and to each service. To serve more than one tenant, install one release for each tenant, each in its own namespace. +In a fixed-tenant `redis-iris` release, `global.iris.tenantId` sets the tenant in the Identity Service and every service. The tables below apply to that setup. To serve multiple tenants in one release, see [Use a tenant claim](/content/operate/iris/self-managed/_index.md#use-a-tenant-claim). | Task | What to do | | --- | --- | @@ -167,6 +167,22 @@ The console sends the operator's access token to the Identity Service. The chart Don't use `GET /v1/api-keys` for this check: without a role, it returns `200` with an empty list. Keep the control token for recovery. +## Configure a tenant identity provider + +Requires self-managed Redis Iris 1.1 or later. + +Register an identity provider (IdP) to bind its issuer to one tenant. The service takes the tenant from the record. An issuer already configured directly on a service keeps using that service's settings. + +As a deployment admin, send `POST /v1/tenants//identity-providers` to the Identity Service control API. Set `name`, the token `issuer` and `audience`, and the provider's HTTPS `jwksUri`. The issuer and key set URL must match the provider's OpenID Connect discovery document exactly. + +- Set `roleClaims` to the claims that contain role values. The defaults are `roles` and `groups`. In `roleMappings`, map each accepted `claimValue` to an Iris `role`. For example, map `memory-admins` to `product_admin` for operators who manage resources in the tenant. +- Set `userIdClaim` to the claim that contains the stable memory owner ID. If you set it, each token must contain a valid string value in that claim. Without this setting, a data-plane token has no owner ID. +- To attach group IDs as identity metadata, set `groupsClaim` and add `groupMappings` entries with `claimValue` and `groupId`. Group mappings grant no permissions. + +To accept these tokens, enable `auth.tenant_identity_providers.enabled` in the service configuration. On the control plane, configure `auth.tenant_identity_providers.identity_service` with a runtime credential that can call `identity-provider-resolve`. Operators send the IdP token as a bearer token. Their mapped roles apply only to the record's tenant. `product_admin` is the highest role a tenant record can grant on a product control plane. + +For data-plane access, give its Identity Service runtime credential `identity-provider-resolve` and `subject-grant-lookup`. Create a [subject grant](#subject-grants) for the token's issuer and `sub` on each target resource. `userIdClaim` sets the memory owner identity. The grant lookup still uses `sub`. + ## Recover from a lockout - **Your IdP is down, or the role bindings are wrong.** Use the control token. It always works. diff --git a/content/operate/iris/identity-service/self-managed/operations.md b/content/operate/iris/identity-service/self-managed/operations.md index 4b1b506953..f4d3fa4a8f 100644 --- a/content/operate/iris/identity-service/self-managed/operations.md +++ b/content/operate/iris/identity-service/self-managed/operations.md @@ -59,7 +59,10 @@ This example gives an agent read and write access to one Agent Memory store. Optional fields: - `expiresAt`: when the key stops working, in Unix seconds. Without it, the key doesn't expire. -- `userId`: the user that owns the key. It needs `identityService.apiKeys.userBinding.enabled: true`. +- `userId`: the exact user ID to bind to the key. +- `applicationUserId`: the application user ID to bind. For example, `42` produces the effective `userId` `app-42`. + +Supply at most one of `userId` and `applicationUserId`. Both fields require `identityService.apiKeys.userBinding.enabled: true`. See [Match stored owners to authenticated users](/content/operate/iris/agent-memory/self-managed/authentication.md#match-stored-owners-to-authenticated-users) for permission and rotation rules. For the other services, change the grant: diff --git a/content/operate/iris/self-managed/_index.md b/content/operate/iris/self-managed/_index.md index 7a6ab0847b..75624ab9b0 100644 --- a/content/operate/iris/self-managed/_index.md +++ b/content/operate/iris/self-managed/_index.md @@ -504,7 +504,7 @@ Data in those databases is kept, except from Agent Memory `0.0.x` and Agent Play ## Tenancy and identity provider limits -A release has one tenant, one identity provider issuer, and one token audience. The chart takes each from `global.iris` and applies it to every service, so every key and token resolves to that tenant. +The single-tenant setup uses one tenant, one identity provider issuer, and one token audience. The chart takes each from `global.iris` and applies it to every service. - `global.iris.tenantId` becomes the tenant of every service and the Identity Service's `singleTenantID`. An empty value fails the schema check. - `global.iris.auth.oidc` supplies the issuer, JWKS URL, role claims, role mappings, and audience. @@ -519,9 +519,29 @@ A service value that sets any of these differently fails the render, and the err | `role_mappings`, `issuer`, or `jwks_uri` in a service OIDC block that differs from `global.iris.auth.oidc` | The suite derives them once for every service. | | `audience` in a service OIDC block that differs from `global.iris.auth.oidc.audience` | Every service accepts the one audience. | -To serve a second tenant or issuer, install another release in its own namespace. +In the single-tenant setup, install another release in its own namespace to serve a second tenant or issuer. -Because a release has one tenant, every valid agent key and every valid token from the configured issuer acts in `global.iris.tenantId`. No request can name another tenant, so the suite never refuses a request as cross-tenant. +In this mode, each valid agent key and user token acts in `global.iris.tenantId`. + +### Use a tenant claim + +Requires self-managed Redis Iris 1.1 or later. + +Set `global.iris.auth.oidc.tenantIdClaim` to the identity provider's tenant claim. Remove the fixed tenant settings, including `global.iris.tenantId` and product `tenantId` values. Configure the issuer and audience for that release. + +Agent keys and grants belong to a tenant. Create a key in the tenant that owns its target store. When granting access using the Identity Service control token, name the grant's tenant. Static admin tokens use the reserved `_system` tenant by default. Use your identity provider to administer stores in a user tenant. Tenant claim values that start with an underscore are reserved. + +Agent Memory, Agent Playbooks, Lens, Context Gateway, and Intent Router can all run in this mode. If you enable Playbook extraction, its shared worker has read access to Memory stores across tenants. Each extraction job uses the Playbook's tenant. The control plane checks whether each binding's memory source is accessible using the requesting operator's credential. Use separate releases if the worker must have access to only one tenant. + +#### Switch from a fixed tenant + +1. If you use Lens, drain the fixed instance's pending spans before upgrading. Retain or export any data you need, then revoke the keys for that instance. +1. Upgrade with the tenant claim settings. Configure the identity provider to keep issuing the original tenant ID to users who need their existing stores and other resources. Existing keys keep their tenant. +1. Sign in to Lens as a user of each tenant to create that tenant's instance. Issue keys for the new instances and update the telemetry exporters. The old instance and its data stay in storage. + +To return to a fixed tenant, roll back to the previous Helm revision. Keys from other tenants stop working. Lens resumes processing the original fixed instance. Its per-tenant instances stay separate. Issue replacement keys for the original instance if you revoked them. + +Self-managed Redis Iris 1.0.1 uses the single-tenant setup. ## Not supported in this release @@ -530,4 +550,4 @@ Because a release has one tenant, every valid agent key and every valid token fr | FIPS profile (`global.security.profile: fips`) | The install fails. Planned for `1.1`. | | Helm 4 | Planned for `1.1`. | | Standalone product chart installs | Published as dependencies of `redis-iris` only. | -| More than one tenant, issuer, or audience per release | A release has one of each. An empty `global.iris.tenantId` fails the install. See [Tenancy and identity provider limits](#tenancy-and-identity-provider-limits). | +| More than one tenant, issuer, or audience per release | Redis Iris 1.0.1 uses one of each. See [Tenancy and identity provider limits](#tenancy-and-identity-provider-limits). | diff --git a/local_examples/iris/agent-memory/long_term_memory_update/long_term_memory_update.py b/local_examples/iris/agent-memory/long_term_memory_update/long_term_memory_update.py index 603d316251..ec746f491e 100644 --- a/local_examples/iris/agent-memory/long_term_memory_update/long_term_memory_update.py +++ b/local_examples/iris/agent-memory/long_term_memory_update/long_term_memory_update.py @@ -1,5 +1,7 @@ # EXAMPLE: iris_agent_memory_long_term_memory_update # HIDE_START +from uuid import uuid4 + from redis_iris.agent_memory import AgentMemory OWNER_ID = "quickstart-user" @@ -15,18 +17,51 @@ # STEP_START ltm-get current = memory.client.get_long_term_memory(memory_id=MEMORY_ID) -print(current.text, current.topics, current.updated_at) +print(current.text, current.topics, current.updated_at, current.revision) # STEP_END # STEP_START ltm-patch +patch_key = str(uuid4()) updated = memory.client.update_long_term_memory( memory_id=MEMORY_ID, text="The user prefers an aisle seat on long flights.", topics=["travel", "flights"], + expected_revision=current.revision, + idempotency_key=patch_key, ) print(updated.text, updated.topics, updated.updated_at) # STEP_END +# STEP_START ltm-put +replace_key = str(uuid4()) +replaced = memory.client.upsert_long_term_memory( + memory_id=MEMORY_ID, + text="The user prefers an aisle seat.", + owner_id=OWNER_ID, + topics=["travel"], + expected_revision=updated.revision, + idempotency_key=replace_key, +) +print(replaced.created) +# STEP_END + +# STEP_START ltm-stale-revision +from redis_agent_memory.errors import AgentMemoryError + +try: + memory.client.update_long_term_memory( + memory_id=MEMORY_ID, + text="The user prefers a window seat on short flights.", + expected_revision=current.revision, + idempotency_key=str(uuid4()), + ) +except AgentMemoryError as error: + if error.status_code != 412: + raise + latest = memory.client.get_long_term_memory(memory_id=MEMORY_ID) + print("Review the current record before reapplying the change:", latest.text) +# STEP_END + # HIDE_START memory.delete([MEMORY_ID]) # HIDE_END