Memória de agente

Memória de curto prazo

A memória de curto prazo (STM) armazena o histórico bruto de conversas em ordem cronológica. A plataforma registra cada mudança em tempo real conforme ela ocorre. Quando seu agente exige contexto de conversa imediato de voltas recentes, ele lê do STM.

Das voltas da conversa para a memória

O Atlas Agent Engine converte a conversa em memória durável por meio de um ciclo de vida de três estágios:

• Gravação de volta: à medida que o agente interage com os usuários, a plataforma registra cada volta na memória de curto prazo.

• Geração de snapshot: quando uma sessão atinge uma contagem de mensagens configurada ou um limite ocioso, um processo em segundo plano compila o histórico da conversa em um snapshot resumido.

• Extração de LLM: um grandes modelos de linguagem (LLM) analisa o snapshot e extrai conhecimento durável para os tipos apropriados de memória de longo prazo.

Como a extração é executada de forma assíncrona, o registro nunca bloqueia a resposta do agente. O conhecimento extraído de uma sessão fica disponível na memória de longo prazo para conversas subsequentes, em vez de na próxima curva imediata. As mudanças recentes permanecem imediatamente disponíveis por meio da memória de curto prazo, e o conhecimento extraído aparece logo em seguida.

Memória de longo prazo

A memória de longo prazo persiste entre sessões e mantém o conhecimento durável destituído de conversas. A plataforma cria memória de longo prazo destilando memória de curto prazo ou por meio de gravações diretas.

Para agentes implantados na plataforma, a plataforma registra automaticamente conversas como memória de curto prazo e destila memória de longo prazo a partir delas, embora os agentes possam escrever na memória de longo prazo diretamente quando necessário. Aplicativos externos normalmente gravam em memória de curto prazo usando o Kit de Desenvolvimento de Software (SDK) para a destilação da plataforma. Eles também podem escrever diretamente na memória de longo prazo, por meio do SDK ou do Protocolo de Contexto do Modelo de memória (MCP).

Memória semântica

A memória semântica armazena informações rotuladas sobre um usuário ou um aplicação. Um fato é o conhecimento que permanece relevante além da conversa que o produz. Por exemplo, um fato pode capturar o aeroporto de origem de um usuário ou sua preferência por assentos na janela.

O Atlas Agent Engine cria memória semântica por meio de extração de background e gravações diretas:

• Extração em segundo plano: extrai fato de snapshots de conversas e consolida informações duplicadas ou atualizadas ao longo do tempo.

• Escritas diretas: salve um fato com save_semantic(label=..., text=...).

Para recuperar um fato, use get_semantic para procurá-lo por rótulo ou search_semantic para encontrar detalhes por significado. A memória semântica é incluída por padrão no build_context, portanto, os eventos relevantes aparecem no contexto que seu agente recupera.

O exemplo a seguir salva um fato, o recupera por rótulo e pesquisa o chat por significado:

from agentic_platform_memory import (
    Memory,
    MemoryRequestContext,
)
memory = Memory(
    api_key="<your-access-token>",
    project_id="<your-project-id>",
)
chat = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_123",
    )
)
chat.save_semantic(
    label="home-airport",
    text="The user's home airport is Boston.",
)
fact = chat.get_semantic("home-airport")
hits = chat.search_semantic("home airport")

Memória capsular

A memória fragmentada armazena conversas anteriores como períodos resumidos. Um capítulo captura o que aconteceu em uma conversa, incluindo as decisões feitas e os resultados que se seguiram. A memória fragmentada responde ao que um agente deve saber sobre as interações anteriores de um usuário.

O Atlas Agent Engine cria memória fragmentada por meio de extração de background e gravações diretas:

• Extraçãode background: extrai eventos e seus participantes de snapshots de conversas.

• Escritas diretas: salve um capítulo com save_episode(title=..., content=...).

Os eventos persistem nas conversas. Um agente pode se lembrar do que aconteceu em uma conversa durante uma conversa posterior.

Para recuperar capítulos, use search_episodes para encontrá-los por significado ou list_episodes para listar os capítulos de um usuário. A memória capsódica é uma das fontes padrão em build_context, portanto, capítulos relevantes são incluídos.

O exemplo a seguir salva um capítulo, pesquisa ele e lista os capítulos de um usuário:

from agentic_platform_memory import (
    Memory,
    MemoryRequestContext,
)
memory = Memory(
    api_key="<your-access-token>",
    project_id="<your-project-id>",
)
chat = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_123",
    )
)
chat.save_episode(
    title="Vacation planning",
    content="Planned a summer trip to Lisbon.",
)
episodes = chat.search_episodes("trip to Lisbon")
recent = chat.list_episodes()

Memória processual

A memória de procedimentos armazena procedimentos reutilizáveis: os fluxos de trabalho passo a passo que um agente segue para concluir uma tarefa específica. Um procedimento captura como fazer algo, como comparar opções de voo ou processar uma solicitação de Reembolso.

O Atlas Agent Engine cria memória processual por meio de extração de background e gravações diretas:

• Extração em segundo plano: extrai procedimentos reutilizáveis de instantâneos de conversas.

• Escritas diretas: salve um procedimento com save_procedure(procedure=..., description=..., content=...).

Para recuperar procedimentos, use discover_procedures para encontrar candidatos por query ou get_procedure para carregar o procedimento completo por nome. A memória processual requer opt-in explícito em build_context, não os padrões semântica e episódica.

O exemplo a seguir salva um procedimento e o recupera:

from agentic_platform_memory import (
    Memory,
    MemoryRequestContext,
)
memory = Memory(
    api_key="<your-access-token>",
    project_id="<your-project-id>",
)
chat = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_123",
    )
)
chat.save_procedure(
    procedure="compare-flights",
    description="Compare flight options.",
    content="Rank flights by price, stops, and total travel time.",
)
candidates = chat.discover_procedures("compare flights")
full = chat.get_procedure("compare-flights")

Memória taxativa

A memória taxativa armazena os termos do domínio e suas definições. Um termo define o significado de uma palavra dentro de um domínio, como o que é um red-eye no gerenciamento de viagens. Ao contrário das memória com escopo de usuário, a memória taxativa é o conhecimento de domínio compartilhado disponível entre todos os usuários e conversas em um projeto.

O Atlas Agent Engine cria memória tagonômica por meio de extração de background e gravações diretas:

• Extração em segundo plano: extrai termos e seus domínios de instantâneos de conversas.

• Escritas diretas: salve um termo com save_taxonomic(domain=..., term=..., definition=...).

Para recuperar um termo, use get_taxonomic_term para procurá-lo por domínio e termo ou search_taxonomic para encontrar termos por significado. Use list_domains para listar os domínios que seu projeto possui. A memória geoespacial requer opt-in explícito em build_context.

O exemplo a seguir salva um termo, lê e pesquisa por ele:

from agentic_platform_memory import (
    Memory,
    MemoryRequestContext,
)
memory = Memory(
    api_key="<your-access-token>",
    project_id="<your-project-id>",
)
chat = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_123",
    )
)
chat.save_taxonomic(
    domain="airline",
    term="red-eye",
    definition="An overnight flight that lands the next morning.",
)
definition = chat.get_taxonomic_term("airline", "red-eye")
matches = chat.search_taxonomic("overnight flight", domain="airline")
domains = chat.list_domains()

Distinção entre tipos

Se as informações parecerem abranger várias categorias, avalie onde elas se enquadram nesses limites operacionais:

• Fato versus evento (semântica versus epsódica): a memória semântica armazena um estado ou uma verdade atual, como o assento preferido de um viagnte ou o aeroporto de origem. A memória fragmentada armazena a Narrativa histórica da interação em que essa preferência foi discutida ou usada, como uma conversa anterior sobre reserva de voo.

• Conhecimento versus Execução (Semântica versus Processual): a memória semântica fornece fatores que o agente se lembra, como limites de franquia de carga. A memória de procedimentos fornece instruções que o agente executa, como a sequência de etapas necessárias para pesquisar e comparar strings.

• Contexto do usuário versus padrões de domínio (semântica versus imposto): a memória semântica rastreia detalhes específicos do usuário, como o nível de programa de milhagem de um viageiro. A memória geoespacial define a terminologia padrão compartilhada por todo o projeto, como os critérios de classificação que definem um nível de classe média ou um voo de olhos fechados.

Combinando tipos de memória

Os tipos de memória são complementares em vez de mutuamente exclusivos. Um único agente geralmente consulta vários tipos de memória dentro do mesmo fluxo de trabalho. Por exemplo, um agente de agendamento de viagens pode fazer referência a:

• Memória semântica para lembrar o aeroporto de origem de um viageiro, a preferência de assentos e o número de milhagem.

• Memória de capítulos para revisar discussões, roteiros reservados e cancelamentos de viagens anteriores.

• Memória de procedimento para executar o fluxo de trabalho passo a passo para comparar opções de voo ou remarcar uma conexão cancelada.

• Memória aproximada para interpretar a terminologia do setor da companhia aérea, como open-jaw routing, layover ou red-eye.

Se seus dados não se ajustarem a nenhum dos quatro tipos integrados, você poderá declarar tipos de memória personalizados. Para saber como, consulte Declarar tipos de memória personalizada no guia Adicionar memória ao seu agente.