AWS bedrock-agentcore documentation change
Summary
Complete restructuring of memory documentation: removed filesystem content, added detailed sections on managed memory, BYO memory, context truncation strategies, and actor-based memory scoping. Updated CLI examples and added strategy descriptions.
Security assessment
The changes focus on feature enhancements and documentation reorganization. There is no evidence of security vulnerability fixes or incident response. The actor ID scoping improves isolation but is presented as a feature enhancement rather than a security patch.
Diff
diff --git a/bedrock-agentcore/latest/devguide/harness-memory.md b/bedrock-agentcore/latest/devguide/harness-memory.md index 4da818f2e..f235d8b08 100644 --- a//bedrock-agentcore/latest/devguide/harness-memory.md +++ b//bedrock-agentcore/latest/devguide/harness-memory.md @@ -7 +7 @@ -Add memoryLong-term memory retrievalFilesystem +How memory worksManaged memory (default)Add existing memory (BYO)Disable memoryPer-user memory scoping with actor IDLong-term memory retrievalContext truncation @@ -9 +9 @@ Add memoryLong-term memory retrievalFilesystem -# Persist memory and filesystem +# Memory @@ -11 +11 @@ Add memoryLong-term memory retrievalFilesystem -The harness persists state at two layers: conversation state in [AgentCore Memory](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html), and file state on the agent’s filesystem. +The harness automatically persists conversation state in [AgentCore Memory](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html). On every invocation, the conversation is saved, scoped by session ID (and additionally by actor ID, if provided). On subsequent invocations with the same session ID, the agent’s history is loaded from Memory before it reasons - it remembers what happened in previous turns, even after the underlying microVM session has expired. You do not need to pass previous messages yourself; just send the new message. @@ -13 +13 @@ The harness persists state at two layers: conversation state in [AgentCore Memor -**Memory.** Attach an [AgentCore Memory](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html) instance to the harness and every invocation saves the conversation automatically, scoped by session ID (and additionally by actor ID, if provided). On subsequent invocations with the same session ID, the agent’s history is loaded from Memory before it reasons, so it remembers what happened in previous turns, even after the underlying microVM session has expired. You do not need to pass previous messages yourself; just send the new message. +## How memory works @@ -15 +15 @@ The harness persists state at two layers: conversation state in [AgentCore Memor - * **Short-term memory** captures raw events (messages, tool calls) within a session. + * **Short-term memory** captures raw events (messages, tool calls) within a session. This is what gives the agent continuity across turns. @@ -19 +19 @@ The harness persists state at two layers: conversation state in [AgentCore Memor - * **Actor ID** \- identifies the entity interacting with the agent (a user, another agent, or a system). Memory events are scoped by actorId + sessionId, so each actor has isolated memory. Long-term retrieval uses actorId as a template variable in namespace paths (e.g. /summary/{actorId}/{sessionId}/), mapping to the configured memory strategies. + * **Actor ID** identifies the entity interacting with the agent (a user, another agent, or a system). Memory events are scoped by actorId + sessionId, so each actor has isolated memory. Long-term retrieval uses actorId as a template variable in namespace paths (e.g. `/summary/{actorId}/{sessionId}/`), mapping to the configured memory strategies. @@ -24 +24 @@ The harness persists state at two layers: conversation state in [AgentCore Memor -**Filesystem.** If enabled, each session runs in a Firecracker microVM with a working filesystem. Files written during a session persist through the session’s lifetime. For state that needs to outlast a single session, mount S3-backed storage through [AgentCore Runtime file system configurations](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-filesystem-configurations.html). +## Managed memory (default) @@ -26 +26,3 @@ The harness persists state at two layers: conversation state in [AgentCore Memor -## Add memory +By default, the harness provisions an [AgentCore Memory](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html) instance automatically with sensible defaults (semantic + summarization strategies, 30-day event expiry). You don’t need to create or configure anything - memory just works. + +To customize the managed memory at create time: @@ -29,0 +32,16 @@ The harness persists state at two layers: conversation state in [AgentCore Memor +AWS CLI/boto3 + + + + aws bedrock-agentcore-control create-harness \ + --harness-name "MyHarness" \ + --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \ + --memory '{"managedMemoryConfiguration": {"strategies": ["SEMANTIC", "SUMMARIZATION", "USER_PREFERENCE"], "eventExpiryDuration": 60}}' + +To update strategies on an existing harness: + + + aws bedrock-agentcore-control update-harness \ + --harness-id "MyHarness-UuFdkQoXSL" \ + --memory '{"optionalValue": {"managedMemoryConfiguration": {"strategies": ["SEMANTIC", "SUMMARIZATION", "USER_PREFERENCE", "EPISODIC"]}}}' + @@ -33 +51 @@ AgentCore CLI -When you create a harness with `agentcore create`, long-term memory is enabled by default - the CLI creates a memory resource and wires it to the harness automatically. To skip it, pass `--no-harness-memory`: +Memory is enabled by default when you create a harness: @@ -36 +53,0 @@ When you create a harness with `agentcore create`, long-term memory is enabled b - # Create with memory (default) @@ -37,0 +55,4 @@ When you create a harness with `agentcore create`, long-term memory is enabled b + agentcore deploy + +To skip managed memory: + @@ -39 +59,0 @@ When you create a harness with `agentcore create`, long-term memory is enabled b - # Create without memory @@ -42 +62 @@ When you create a harness with `agentcore create`, long-term memory is enabled b -After creation, deploy to provision the memory resource: +Managed memory is fully managed by the harness: @@ -43,0 +64 @@ After creation, deploy to provision the memory resource: + * Strategy configuration is controlled through `UpdateHarness`. You can still read/write events and query records directly through the Memory APIs. @@ -45 +66,3 @@ After creation, deploy to provision the memory resource: - agentcore deploy + * Managed memory cannot be deleted directly through the Memory APIs. To turn managed memory into a regular AgentCore memory resource, you can disassociate it from the harness in two ways: + + * Use `UpdateHarness` to switch to BYO (`agentCoreMemoryConfiguration`) or disabled. @@ -47 +70 @@ After creation, deploy to provision the memory resource: -To scope memory to a specific user, pass `--actor-id` at invoke time. Each actor gets isolated memory - the agent remembers that user’s context even across different sessions: + * Pass `deleteManagedMemory=false` on deletion to disassociate instead - `DeleteHarness` cascade-deletes the managed memory by default. @@ -50,5 +72,0 @@ To scope memory to a specific user, pass `--actor-id` at invoke time. Each actor - # Session 1: user Alice asks a question - agentcore invoke --harness research-agent \ - --session-id "$(uuidgen)" \ - --actor-id alice \ - "Research tropical vacations under $3k" @@ -56,5 +73,0 @@ To scope memory to a specific user, pass `--actor-id` at invoke time. Each actor - # Session 2 (new session): Alice's memory carries over - agentcore invoke --harness research-agent \ - --session-id "$(uuidgen)" \ - --actor-id alice \ - "What did we decide about the Portugal option?" @@ -62 +75 @@ To scope memory to a specific user, pass `--actor-id` at invoke time. Each actor -Continue a conversation within the same session by reusing the same session ID: +### Available strategies @@ -63,0 +77,6 @@ Continue a conversation within the same session by reusing the same session ID: +Strategy | Description +---|--- +`SEMANTIC` | Extracts factual knowledge from conversations, retrievable via semantic search. +`SUMMARIZATION` | Creates running summaries of conversations, scoped by actor and session. +`USER_PREFERENCE` | Captures user preferences and settings expressed during conversations. +`EPISODIC` | Records significant events and experiences as discrete episodes. @@ -65,7 +84,5 @@ Continue a conversation within the same session by reusing the same session ID: - SESSION_ID="$(uuidgen)" - agentcore invoke --harness research-agent \ - --session-id "$SESSION_ID" \ - "Research tropical vacations under $3k" - agentcore invoke --harness research-agent \ - --session-id "$SESSION_ID" \ - "What did we decide about the Portugal option?" +## Add existing memory (BYO) + +If you need advanced configuration beyond what managed memory provides - custom namespace templates, KMS encryption, or shared memory across multiple harnesses - attach an existing [AgentCore Memory](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html) instance instead. + +###### Example @@ -91 +108,8 @@ Attach it to the harness: -Reuse the same `runtimeSessionId` across invocations and the agent recalls prior turns from Memory, even after the microVM session expires. +AgentCore CLI + + + + agentcore create --name myagent --memory-arn "arn:aws:bedrock-agentcore:us-west-2:123456789012:memory/MyMemory-abc123" + agentcore deploy + +## Disable memory @@ -93 +117,10 @@ Reuse the same `runtimeSessionId` across invocations and the agent recalls prior -To scope memory to a specific user, pass `actorId` at invoke time: +To disable memory entirely: + + + aws bedrock-agentcore-control update-harness \ + --harness-id "MyHarness-UuFdkQoXSL" \ + --memory '{"optionalValue": {"disabled": {}}}' + +## Per-user memory scoping with actor ID + +Pass `actorId` at invoke time to scope memory to a specific user. Each actor gets isolated short-term and long-term memory: @@ -103,2 +135,0 @@ To scope memory to a specific user, pass `actorId` at invoke time: -The `actorId` determines whose memory is loaded. Long-term memory strategies (semantic, summarization, etc.) use the actorId to scope extracted knowledge - each actor gets their own isolated memory namespace. For more details on configuring long-term memory, see [configuring long-term memory strategies](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/long-term-configuring-built-in-strategies.html). - @@ -107 +138 @@ The `actorId` determines whose memory is loaded. Long-term memory strategies (se -When you attach a Memory instance that has active strategies (semantic, user preference, episodic, etc.), the harness automatically derives a retrieval configuration from those strategies. This means long-term memory retrieval works out of the box - you don’t need to manually specify a `retrievalConfig`. +When a harness has active memory strategies (managed or BYO), retrieval works automatically - the harness derives a retrieval configuration from the Memory instance’s active strategies. On each invocation, the agent queries relevant long-term memories and injects them into the conversation context before reasoning. @@ -109 +140 @@ When you attach a Memory instance that has active strategies (semantic, user pre -**How it works:** +**Default behavior:** @@ -111 +142 @@ When you attach a Memory instance that has active strategies (semantic, user pre - * When you create or update a harness with a Memory ARN, the service reads the Memory instance’s active strategies and automatically configures retrieval for each strategy’s namespaces with default parameters (`topK=10`, `relevanceScore=0.2`). + * Retrieval is configured automatically with default parameters (`topK=10`, `relevanceScore=0.2`) for each active strategy’s namespace. @@ -113 +144 @@ When you attach a Memory instance that has active strategies (semantic, user pre - * On each invocation, the agent queries these namespaces for relevant long-term memories and injects them into the conversation context before reasoning. + * No manual configuration needed for either managed or BYO memory. @@ -118 +149 @@ When you attach a Memory instance that has active strategies (semantic, user pre -**Override the defaults:** If you explicitly provide a `retrievalConfig` in the memory configuration, your values take priority and no automatic derivation occurs. This lets you customize which namespaces are queried, adjust `topK` or `relevanceScore`, or disable retrieval for specific strategies. +**Override the defaults:** If you explicitly provide a `retrievalConfig` in the BYO memory configuration, your values take priority and no automatic derivation occurs. This lets you customize which namespaces are queried, adjust `topK` or `relevanceScore`, or disable retrieval for specific strategies. @@ -127,5 +158 @@ When you attach a Memory instance that has active strategies (semantic, user pre -If you update your Memory instance’s strategies (add or remove) after creating the harness, call `UpdateHarness` to refresh the retrieval configuration. Invocations will continue to work with the previous configuration until updated. - -## Filesystem - -The harness mounts persistent storage at paths you specify. Files written to these mounts survive session termination and are visible to later invocations. +If you update your BYO Memory instance’s strategies (add or remove) after attaching it to a harness, call `UpdateHarness` to refresh the retrieval configuration. For managed memory, strategy changes through `UpdateHarness` refresh the configuration automatically. @@ -133 +160 @@ The harness mounts persistent storage at paths you specify. Files written to the -A harness supports three filesystem types: +## Context truncation @@ -135 +162 @@ A harness supports three filesystem types: - * **Session storage** \- service-managed, per-session storage that persists across stop/resume cycles for the same `runtimeSessionId`. No VPC required. +When conversation history grows beyond the model’s context window, the harness applies a truncation strategy. Configure this on the harness or override per invocation. @@ -137 +164 @@ A harness supports three filesystem types: - * **Amazon EFS access point** \- bring-your-own EFS file system, shared across sessions and agents. VPC required. + * **`sliding_window` ** (default) - keeps the most recent N messages. Simple and predictable. @@ -139 +166 @@ A harness supports three filesystem types: - * **Amazon S3 Files access point** \- bring-your-own S3 Files file system that syncs bidirectionally with an S3 bucket. VPC required. + * **`summarization` ** \- compresses older messages into a summary, preserving more context in fewer tokens. @@ -140,0 +168 @@ A harness supports three filesystem types: + * **`none` ** \- no truncation. Use only if you manage context size yourself. @@ -144,21 +171,0 @@ A harness supports three filesystem types: -For prerequisites (VPC networking, IAM permissions, security groups), type comparison, limits, and lifecycle behavior, see [File system configurations for AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-filesystem-configurations.html). The same requirements apply to harnesses. - -### Session storage - -Files written to the mount path persist across stop/resume cycles when you invoke with the same `runtimeSessionId`. - -###### Example - -AgentCore CLI - - - - # At create time - agentcore create --name myagent --session-storage /mnt/data/ - - # Or add to an existing harness - agentcore add harness --name my-agent --session-storage /mnt/data/ - agentcore deploy - -AWS CLI/boto3 - @@ -169,69 +176 @@ AWS CLI/boto3 - --environment '{"agentCoreRuntimeEnvironment": {"filesystemConfigurations": [{"sessionStorage": {"mountPath": "/mnt/data/"}}]}}' - -### Amazon EFS access point - -Attach an EFS access point ARN at a mount path under `/mnt`. Data persists in your account and can be shared with other harnesses or agent runtimes that mount the same access point. - -###### Example - -AWS CLI/boto3