# 开始使用内 AgentCore 存
<a name="memory-get-started"></a>

Amazon Bedrock AgentCore Amazon Bedrock Memory 允许您创建和管理存储人工智能代理对话上下文的 AgentCore 内存资源。本入门指南将指导您安装依赖项以及实现短期和长期内存功能。这些说明使用 AgentCore CLI。

步骤如下所示：

1. 创建包含语义策略的 AgentCore 内存

1. 将事件（对话历史记录）写入内存资源

1. 从长期记忆中检索记忆记录

有关其他示例，请参阅 [Amazon 基岩 AgentCore 内存示例](memory-examples.md)。

## 先决条件
<a name="memory-prerequisites"></a>

在开始之前，请确保你有：
+  AWS 已配置凭据的@@ **账户** (`aws configure`)
+  已@@ **安装 Python 3.10\+**
+ Node.js 已安装 18 个以上（用于 AgentCore CLI）

要开始使用 Amazon Bedrock Amazon Bedrock AgentCore Memory，请安装依赖项、创建 AgentCore CLI 项目并设置虚拟环境。以下命令可以直接在终端中运行。

```
pip install bedrock-agentcore
npm install -g @aws/agentcore
agentcore create --name agentcore-memory-quickstart --no-agent
cd agentcore-memory-quickstart
python -m venv .venv
source .venv/bin/activate
```

C AgentCore LI 提供用于创建和管理内存资源的命令。`agentcore add memory`用于创建内存，然后在中`agentcore deploy`置备内存 AWS。要进行事件操作和会话管理，请使用 AWS Python 软件开发工具包 (Boto3) (`bedrock-agentcore`)。

**注意**  
C AgentCore LI 可帮助您创建和部署内存资源。[有关完整的 Amazon Bedrock AgentCore Memory 操作，请参阅 Boto3 文档：[基岩代理核心控制和基岩](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control.html)代理核心。](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore.html)

 **完整示例：**查看演示步骤 1-3 的 [Amazon Bedrock AgentCore 示例](https://github.com/awslabs/amazon-bedrock-agentcore-samples/tree/main/01-tutorials)。

## 步骤 1：创建内 AgentCore 存
<a name="memory-create-resource"></a>

您需要 AgentCore 存储器才能开始为代理存储信息。默认情况下，记忆事件（我们称之为短期记忆）可以写入 AgentCore 内存。为了提取见解并将其放入长期记忆记录中，资源需要一种*记忆策略，该策略*是一种配置，用于定义应如何处理对话数据以及要提取哪些信息（例如事实、偏好或摘要）。

在此步骤中，您将使用语义策略创建 AgentCore 内存，以便可以同时使用短期和长期内存。这将需要 2-3 分钟。您也可以在 AWS 控制台中创建 AgentCore 内存资源。

使用语义策略创建内存：

**Example**  

1. 

   ```
   agentcore add memory --name CustomerSupportSemantic --strategies SEMANTIC
   agentcore deploy
   ```

1. 运行打开 `agentcore` TUI，然后选择**添加**并选择**内存**：

1. 输入内存名称：  
![内存向导：输入名称](https://docs.aws.amazon.com/zh_cn/bedrock-agentcore/latest/devguide/images/tui/memory-add-name.png)

1. 选择**语义**策略，然后确认：  
![记忆向导：选择语义策略](https://docs.aws.amazon.com/zh_cn/bedrock-agentcore/latest/devguide/images/tui/memory-add-strategies.png)

   然后运行`agentcore deploy`在中配置内存 AWS。

部署完成后，验证内存是否已创建：

```
agentcore status
```

## 步骤 2：将事件写入内存
<a name="memory-write-events"></a>

您可以将事件作为短期 AgentCore 记忆写入记忆中，并提取长期记忆的见解。

将事件写入内存有多种用途。首先，事件内容（最常见的对话历史记录）存储为短期记忆。其次，相关的见解是从事件中提取的，并作为长期记忆的一部分写入记忆记录中。

创建事件需要内存资源 ID、参与者 ID 和会话 ID。在此步骤中，您将创建三个事件，模拟最终用户和聊天机器人之间的消息。

```
import boto3
from bedrock_agentcore.memory import MemorySessionManager
from bedrock_agentcore.memory.constants import ConversationalMessage, MessageRole

control_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')

# Retrieve the memory created in Step 1
response = control_client.list_memories()
memory = response['memories'][0]
memory_id = memory['id']

# Create a session to store memory events
session_manager = MemorySessionManager(
    memory_id=memory_id,
    region_name="us-west-2")

session = session_manager.create_memory_session(
    actor_id="User1",
    session_id="OrderSupportSession1"
)

# Write memory events (conversation turns)
session.add_turns(
    messages=[
        ConversationalMessage(
            "Hi, how can I help you today?",
            MessageRole.ASSISTANT)],
)

session.add_turns(
    messages=[
        ConversationalMessage(
            "Hi, I am a new customer. I just made an order, but it hasn't arrived. The Order number is #35476",
            MessageRole.USER)],
)

session.add_turns(
    messages=[
        ConversationalMessage(
            "I'm sorry to hear that. Let me look up your order.",
            MessageRole.ASSISTANT)],
)
```

写好特定演员的事件（回合）后，你可以获取这些事件（回合）。

```
# Get the last k turns in the session
turns = session.get_last_k_turns(k=5)

for turn in turns:
    print(f"Turn: {turn}")
```

在这种情况下，您可以看到演员和会话的最后三个事件。

## 步骤 3：从长期记忆中检索记录
<a name="memory-retrieve-records"></a>

将事件写入内存资源后，对它们进行了分析，并将有用的信息发送到长期存储器。由于存储器包含语义长期记忆策略，因此系统会提取和存储事实信息。

您可以使用以下命令列出所有内存记录：

```
# List all memory records
memory_records = session.list_long_term_memory_records(
    namespace_path="/"
)

for record in memory_records:
    print(f"Memory record: {record}")
    print("--------------------------------------------------------------------")
```

或者在语义搜索中询问最相关的信息：

```
# Perform a semantic search
memory_records = session.search_long_term_memories(
    query="can you summarize the support issue",
    namespace_path="/",
    top_k=3
)
```

有关用户的重要信息可能存储在长期记忆中。代理可以使用长期记忆而不是完整的对话历史记录来确保 LLM 的上下文不会过载。

## 向现有代理添加内存
<a name="memory-add-to-existing-agent"></a>

如果您在没有内存的情况下创建了 Strands 代理，并且想稍后再添加，请按照以下步骤操作：

1. 向项目添加内存资源：

   ```
   agentcore add memory --name MyMemory --strategies SEMANTIC,SUMMARIZATION
   agentcore deploy
   ```

1. 在代理中创建`memory/`目录：

   ```
   mkdir -p app/MyAgent/memory
   ```

1. 创建`app/MyAgent/memory/session.py`：

   ```
   import os
   from typing import Optional
   from bedrock_agentcore.memory.integrations.strands.config import AgentCoreMemoryConfig, RetrievalConfig
   from bedrock_agentcore.memory.integrations.strands.session_manager import AgentCoreMemorySessionManager
   
   MEMORY_ID = os.getenv("MEMORY_MYMEMORY_ID")
   REGION = os.getenv("AWS_REGION")
   
   def get_memory_session_manager(session_id: str, actor_id: str) -> Optional[AgentCoreMemorySessionManager]:
       if not MEMORY_ID:
           return None
   
       retrieval_config = {
           f"/users/{actor_id}/facts": RetrievalConfig(top_k=3, relevance_score=0.5),
           f"/summaries/{actor_id}/{session_id}": RetrievalConfig(top_k=3, relevance_score=0.5)
       }
   
       return AgentCoreMemorySessionManager(
           AgentCoreMemoryConfig(
               memory_id=MEMORY_ID,
               session_id=session_id,
               actor_id=actor_id,
               retrieval_config=retrieval_config,
           ),
           REGION
       )
   ```

1. 更新您的会话管理器`main.py`以使用会话管理器：

   ```
   from memory.session import get_memory_session_manager
   
   @app.entrypoint
   async def invoke(payload, context):
       session_id = getattr(context, 'session_id', 'default-session')
       user_id = getattr(context, 'user_id', 'default-user')
   
       agent = Agent(
           model=load_model(),
           session_manager=get_memory_session_manager(session_id, user_id),
           system_prompt="You are a helpful assistant.",
       )
   
       response = agent(payload.get("prompt"))
       return response
   ```

1. 部署更新的项目：

   ```
   agentcore deploy
   ```

**注意**  
每个内存资源都有一个环境变量`MEMORY_<NAME>_ID`（大写，带下划线），该变量在部署后自动在代理的运行时环境中可用。

## 资源清理
<a name="memory-cleanup"></a>

当你使用完内存资源后，你可以将其删除：

```
agentcore remove memory --name CustomerSupportSemantic
agentcore deploy
```

## 后续步骤
<a name="memory-next-steps"></a>

请考虑以下事项：
+  在你的内存资源中@@ [添加另一种策略](long-term-enabling-long-term-memory.md#long-term-adding-strategies-to-existing-memory)。
+  [启用可观察性](memory-observability.md)以更深入地了解内存的工作原理
+ 请看更多[示例](memory-examples.md)。