# Comece a usar a AgentCore Memória
<a name="memory-get-started"></a>

Amazon Bedrock O Amazon Bedrock AgentCore Memory permite criar e gerenciar recursos de AgentCore memória que armazenam o contexto da conversa para seus agentes de IA. Esta introdução orienta você na instalação de dependências e na implementação de recursos de memória de curto e longo prazo. As instruções usam a AgentCore CLI.

As etapas são:

1. Crie uma AgentCore memória contendo uma estratégia semântica

1. Grave eventos (histórico de conversas) no recurso de memória

1. Recupere registros de memória da memória de longo prazo

Para outros exemplos, consulte [exemplos do Amazon Bedrock AgentCore Memory](memory-examples.md).

## Pré-requisitos
<a name="memory-prerequisites"></a>

Antes de começar, verifique se você tem:
+  ** AWS Conta** com credenciais configuradas () `aws configure`
+  **Python 3.10\+ instalado**
+ Node.js 18\+ instalados (para a AgentCore CLI)

Para começar a usar o Amazon Bedrock Amazon Bedrock AgentCore Memory, instale as dependências, crie um projeto de AgentCore CLI e configure um ambiente virtual. Os comandos abaixo podem ser executados diretamente no terminal.

```
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
```

A AgentCore CLI fornece comandos para criar e gerenciar recursos de memória. Use `agentcore add memory` para criar uma memória e `agentcore deploy` provisioná-la AWS. Para operações de eventos e gerenciamento de sessões, use o AWS Python SDK (Boto3) (). `bedrock-agentcore`

**nota**  
A AgentCore CLI ajuda você a criar e implantar recursos de memória. [Para ver o conjunto completo de operações da Amazon Bedrock AgentCore Memory, consulte a documentação do Boto3: bedrock-agentcore-control e [bedrock-agentcore](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)

 **Exemplo completo:** veja os exemplos do [Amazon Bedrock que demonstram AgentCore as](https://github.com/awslabs/amazon-bedrock-agentcore-samples/tree/main/01-tutorials) etapas 1 a 3.

## Etapa 1: criar uma AgentCore memória
<a name="memory-create-resource"></a>

Você precisa de uma AgentCore memória para começar a armazenar informações para seu agente. Por padrão, os eventos de memória (que chamamos de memória de curto prazo) podem ser gravados em uma AgentCore memória. Para que os insights sejam extraídos e colocados em registros de memória de longo prazo, o recurso requer uma *estratégia de memória*, que é uma configuração que define como os dados conversacionais devem ser processados e quais informações extrair (como fatos, preferências ou resumos).

Nesta etapa, você cria uma AgentCore memória com uma estratégia semântica para que tanto a memória de curto quanto a de longo prazo possam ser utilizadas. Isso levará de 2 a 3 minutos. Você também pode criar recursos de AgentCore memória no AWS console.

Crie memória com estratégia semântica:

**Example**  

1. 

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

1. Execute `agentcore` para abrir a TUI, selecione **adicionar** e escolha **Memória**:

1. Digite o nome da memória:  
![Assistente de memória: insira o nome](http://docs.aws.amazon.com/pt_br/bedrock-agentcore/latest/devguide/images/tui/memory-add-name.png)

1. Selecione a estratégia **semântica** e confirme:  
![Assistente de memória: selecione a estratégia SEMÂNTICA](http://docs.aws.amazon.com/pt_br/bedrock-agentcore/latest/devguide/images/tui/memory-add-strategies.png)

   Em seguida, execute `agentcore deploy` para provisionar a memória AWS.

Após a implantação, verifique se a memória foi criada:

```
agentcore status
```

## Etapa 2: gravar eventos na memória
<a name="memory-write-events"></a>

Você pode gravar eventos em uma AgentCore memória como memória de curto prazo e extrair insights para a memória de longo prazo.

Gravar eventos na memória tem vários propósitos. Primeiro, o conteúdo do evento (geralmente o histórico de conversas) é armazenado como memória de curto prazo. Em segundo lugar, insights relevantes são extraídos de eventos e gravados em registros de memória como parte da memória de longo prazo.

O ID do recurso de memória, o ID do ator e o ID da sessão são necessários para criar um evento. Nesta etapa, você cria três eventos, simulando mensagens entre um usuário final e um bot de bate-papo.

```
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)],
)
```

Você pode obter eventos (turnos) para um ator específico depois de terem sido escritos.

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

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

Nesse caso, você pode ver os últimos três eventos do ator e da sessão.

## Etapa 3: recuperar registros da memória de longo prazo
<a name="memory-retrieve-records"></a>

Depois que os eventos foram gravados no recurso de memória, eles foram analisados e as informações úteis foram enviadas para a memória de longo prazo. Como a memória contém uma estratégia semântica de memória de longo prazo, o sistema extrai e armazena informações factuais.

Você pode listar todos os registros de memória com:

```
# 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("--------------------------------------------------------------------")
```

Ou peça as informações mais relevantes como parte de uma pesquisa semântica:

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

É provável que informações importantes sobre o usuário estejam armazenadas na memória de longo prazo. Os agentes podem usar memória de longo prazo em vez de um histórico completo de conversas para garantir que os LLMs não estejam sobrecarregados com o contexto.

## Adicionando memória a um agente existente
<a name="memory-add-to-existing-agent"></a>

Se você criou um agente Strands sem memória e deseja adicioná-lo posteriormente, siga estas etapas:

1. Adicione um recurso de memória ao seu projeto:

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

1. Crie o `memory/` diretório em seu agente:

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

1. Crie`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. Atualize seu `main.py` para usar o gerenciador de sessões:

   ```
   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. Implante o projeto atualizado:

   ```
   agentcore deploy
   ```

**nota**  
Cada recurso de memória recebe uma variável de ambiente `MEMORY_<NAME>_ID` (maiúscula, com sublinhados) que fica automaticamente disponível no ambiente de execução do seu agente após a implantação.

## Limpeza
<a name="memory-cleanup"></a>

Quando terminar de usar o recurso de memória, você poderá excluí-lo:

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

## Próximas etapas
<a name="memory-next-steps"></a>

Considere o seguinte:
+  [Adicione outra estratégia](long-term-enabling-long-term-memory.md#long-term-adding-strategies-to-existing-memory) ao seu recurso de memória.
+  [Permita a observabilidade](memory-observability.md) para obter mais visibilidade de como a memória está funcionando
+ Veja mais [exemplos](memory-examples.md).