# AgentCore 記憶體入門
<a name="memory-get-started"></a>

Amazon Bedrock Amazon Bedrock AgentCore 記憶體可讓您建立和管理 AgentCore 記憶體資源，以存放 AI 代理器的對話內容。此入門會引導您安裝相依性和實作短期和長期記憶體功能。這些指示使用 AgentCore CLI。

步驟如下：

1. 建立包含語意策略的 AgentCore 記憶體

1. 將事件 （對話歷史記錄） 寫入記憶體資源

1. 從長期記憶體擷取記憶體記錄

如需其他範例，請參閱 [Amazon Bedrock 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 記憶體，請安裝相依性、建立 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
```

AgentCore CLI 提供建立和管理記憶體資源的命令。使用 `agentcore add memory`建立記憶體，並在其中`agentcore deploy`佈建記憶體 AWS。對於事件操作和工作階段管理，請使用 AWS Python SDK (Boto3) `bedrock-agentcore` ()。

**注意**  
AgentCore CLI 可協助您建立和部署記憶體資源。如需完整的 Amazon Bedrock AgentCore 記憶體操作集，請參閱 Boto3 文件：[bedrock-agentcore-control](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control.html) 和 [bedrock-agentcore](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. 輸入記憶體名稱：  
![記憶體精靈：輸入名稱](http://docs.aws.amazon.com/zh_tw/bedrock-agentcore/latest/devguide/images/tui/memory-add-name.png)

1. 選取**語意**策略，然後確認：  
![記憶體精靈：選取 SEMANTIC 策略](http://docs.aws.amazon.com/zh_tw/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
)
```

儲存有關使用者的重要資訊可能是長期記憶體。客服人員可以使用長期記憶體，而不是完整的對話歷史記錄，以確保 LLMs不會因內容而超載。

## 將記憶體新增至現有代理程式
<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)。