记忆是如何工作的托管内存添加现有内存 (BYO)禁用内存 Per-user 使用演员 ID 进行内存范围界定 Long-term 记忆检索上下文截断

内存

启用内存后，安全带将在AgentCore 内存中保持对话状态。在使用相同会话 ID 的后续调用中，代理会在启动之前加载存储的历史记录。

记忆是如何工作的

Short-term 内存捕获会话中的原始事件（消息、工具调用）。这就是使代理在各个回合之间保持连续性的原因。
Long-term 记忆通过可配置的策略（语义、摘要、用户偏好、情景或自定义）提取持久的知识，并使其可在以后的会话中通过语义搜索进行检索。
Actor ID 标识与代理交互的实体（用户、其他代理或系统）。内存事件的作用域由 actorId + SessionId 控制，因此每个 actor 都有独立的内存。 Long-term 检索使用 ActorId 作为命名空间路径（例如/summary/{actorId}/{sessionId}/）中的模板变量，映射到配置的内存策略。

托管内存

当您直接使用服务 API 创建工具并省略内存配置时，该服务会提供托管内存。 AgentCore CLI 使用不同的默认值：除非您选择托管内存或现有内存资源，否则新的 CLI 线束会禁用内存。

内存充电

安全带本身不收取额外费用。Managed M AgentCore emory 对短期事件、存储的长期内存记录和检索请求收取标准内存费用。为避免持续的内存充电，请在创建安全带时禁用内存。有关更多信息，请参阅了解安全带成本和亚马逊 Bedrock AgentCore 定价。

要在创建时自定义托管内存，请执行以下操作：

例

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}}'

要更新现有安全带的策略，请执行以下操作：


aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --memory '{"optionalValue": {"managedMemoryConfiguration": {"strategies": ["SEMANTIC", "SUMMARIZATION", "USER_PREFERENCE", "EPISODIC"]}}}'

AgentCore CLI

创建一个空项目，然后添加一个带有托管内存的工具包：


agentcore create --project-name MyHarnessProject --no-agent
cd MyHarnessProject
agentcore add harness \
  --name myagent \
  --memory-mode managed \
  --memory-strategies SEMANTIC,SUMMARIZATION \
  --memory-event-expiry-days 30
agentcore deploy

默认情况下，内存处于禁用状态。要在没有内存的情况下创建安全带，请运行以下命令而不是前面的agentcore add harness命令：


agentcore add harness --name myagent --no-memory

Interactive

在项目目录agentcore中运行，选择添加，然后选择Harn ess 。该向导包括一个记忆步骤。

在 “内存” 步骤中，选择 “无永久内存” 或 “启用” 为安全带创建永久内存。
当内存处于启用状态时，“高级” 设置中会出现一个额外的内存调整选项。使用空格将其启用并按 Enter 来调整检索。
（可选）设置消息数量、检索前 K 和相关性分数（可以跳过每个分数）。

确认向导，然后运行agentcore deploy进行申请。

托管内存完全由线束管理：

策略配置通过以下方式控制UpdateHarness。您仍然可以直接通过内存 API 来查询 read/write 事件和记录。
无法直接通过内存 API 删除托管内存。要将托管内存转换为常规 AgentCore 内存资源，可以通过两种方式将其与工具断开关联：
- 用于切换UpdateHarness到 BYO (agentCoreMemoryConfiguration) 或禁用。
- 改为传递deleteManagedMemory=false删除权限以取消关联-默认DeleteHarness情况下，级联删除托管内存。

可用策略

Strategy	说明
`SEMANTIC`	从对话中提取事实知识，可通过语义搜索检索。
`SUMMARIZATION`	按参与者和会话范围创建持续的对话摘要。
`USER_PREFERENCE`	捕获对话期间表达的用户偏好和设置。
`EPISODIC`	将重要事件和经历记录为离散的情节。

添加现有内存 (BYO)

如果您需要超出托管内存所提供的高级配置（自定义命名空间模板、KMS 加密或跨多个线束的共享内存），请改为连接现有AgentCore 内存实例。

例

禁用内存

要完全禁用内存：


aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --memory '{"optionalValue": {"disabled": {}}}'

Per-user 使用演员 ID 进行内存范围界定

actorId在调用时传递，将内存范围限定为特定用户。每个演员都有孤立的短期和长期记忆：


response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    actorId="user-123",
    messages=[{"role": "user", "content": [{"text": "What do you remember about my preferences?"}]}],
)

Long-term 记忆检索

当安全带具有活动内存策略（托管或 BYO）时，系统会自动进行检索——该工具从内存实例的活动策略中派生检索配置。每次调用时，代理都会查询相关的长期记忆，并在推理之前将其注入对话上下文中。

默认行为：

使用每个活动策略的命名空间的默认参数 (topK=10,relevanceScore=0.2) 自动配置检索。
无需手动配置托管内存或 BYO 内存。

覆盖默认值：如果您在 BYO 内存配置retrievalConfig中明确提供了，则优先考虑您的值，不会发生自动推导。这使您可以自定义查询哪些命名空间，调整topK或relevanceScore禁用特定策略的检索。


aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --memory '{"optionalValue": {"agentCoreMemoryConfiguration": {"arn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:memory/MyMemory-abc123", "retrievalConfig": {"/facts/{actorId}/": {"topK": 5, "relevanceScore": 0.5, "strategyId": "FactExtractor-abc123"}}}}}'

重要

如果您在将 BYO Memory 实例连接到安全带后更新其策略（添加或移除），请调用UpdateHarness刷新检索配置。对于托管内存，通过自动UpdateHarness刷新配置来更改策略。

上下文截断

当对话历史超出模型的上下文窗口时，该工具会应用截断策略。在每次调用时在安全带上进行配置或覆盖。

sliding_window（默认）-保留最新的 N 条消息。简单且可预测。
summarization-将较旧的消息压缩为摘要，以更少的标记保留更多上下文。
none-没有截断。仅当你自己管理上下文大小时才使用。


aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --truncation '{"strategy": "sliding_window", "slidingWindowConfig": {"numMessages": 30}}'

了解更多：AgentCore 记忆、创建内存存储、长期记忆策略。

内存