Agent Memory — seus agentes lembram dos contatos

Agent Memory é a camada que permite aos seus agentes lembrar de conversas anteriores com o mesmo contato. Sem ela, cada conversa começa do zero — o usuário tem que repetir nome, preferências, histórico. Com ela, o agente entra ciente do que já foi trocado antes.

Diferente de:

• Session variables — vivem durante uma sessão só. Começa nova sessão, perde tudo.
• Knowledge base (RAG) — documentos estáticos da empresa. Não personaliza por contato.
• Inbox — histórico textual das mensagens. Rico mas bruto; o agente ainda teria que ler tudo.

Memory é estruturado e focado: fatos pontuais sobre o contato, gravados com chave e tipo, consultáveis em milissegundos.

Quando Memory ajuda

• SDR — lembra quais produtos o lead demonstrou interesse, onde parou no funil
• Suporte — recupera reclamações anteriores sem usuário ter que contar tudo de novo
• Atendimento pós-venda — "seu último pedido foi X em março, chegou ok?"
• Clínicas / consultórios — datas de consulta, prefere agendamento de manhã, alergia a Y
• Concierge / assistente pessoal — cidade favorita, restaurante preferido, fuso horário

Como funciona

Cada memória é uma linha no banco com:

Escopo compartilhado por default. Se o mesmo contato fala com SDR hoje e com Suporte amanhã, ambos agentes veem as memórias. Isso evita o usuário repetir "eu já falei que meu CPF é tal" pra cada agente. Se precisar isolar, basta passar agent_id específico.

Como os agentes usam

Toda vez que o agente recebe uma mensagem, a plataforma:

1. Identifica o contato pelo canal+identifier.
2. Consulta as últimas 20 memórias dele.
3. Injeta um bloco no system prompt com as memórias organizadas por tipo.

Exemplo do que o agente enxerga antes da resposta:

# Memória do contato
Você já conversou com esta pessoa antes.

## Fatos conhecidos deste contato
- nome_preferido: Maria
- cpf: 123.456.789-00
- ultimo_pedido: Pedido #4521 entregue em 02/04/2026

## Preferências observadas
- horario_contato: prefere manhã
- canal_comunicacao: WhatsApp

Além disso o agente tem a tool lembrar_do_contato sempre disponível. Ações:

• listar — puxa tudo que já sabe sobre o contato
• salvar — grava novo fato com chave + valor + tipo

Exemplos práticos de uso

SDR que qualifica lead

Prompt do agente:

Quando o lead informar o orçamento ou prazo, SEMPRE salve como memória
("orcamento_mensal" ou "prazo_decisao"). Antes de qualificar, USE a tool
para listar memórias e evite refazer perguntas que já foram respondidas.

Na segunda conversa, o SDR não pergunta de novo o orçamento — ele usa o que está em memória.

Suporte pós-venda

Se o usuário reclamar de um produto, salve como memória com kind="interaction"
e chave tipo "reclamacao_<mes>_<ano>". Em conversas futuras, consulte o
histórico antes de assumir que é a primeira vez.

Concierge

Quando o usuário mencionar preferências (restaurante, hotel, horário, cidade),
salve com kind="preference". Use essas preferências em recomendações futuras.

Gerenciar memórias manualmente

Em Contatos → [contato] → aba Memória IA:

• Veja todas as memórias do contato, com tipo, data e valor formatado
• Apague uma individual (ícone de lixeira)
• Botão "Esquecer tudo" — apaga todas as memórias do contato de uma vez. Útil pra atender solicitação de esquecimento sob LGPD.

Limites e boas práticas

• Máximo 20 memórias carregadas no contexto por conversa. Se tiver 50, as 20 mais recentes entram; as outras ficam disponíveis só via tool lembrar_do_contato.
• Não guarde tudo. Instruir o agente a gravar só o que vale lembrar depois — gosto, histórico, dado de identificação. Dispositivo da conversa atual não precisa virar memória.
• Nada sensível em memória a não ser que a compliance permita. Ela fica visível pra qualquer owner/admin do workspace na UI de contatos.
• TTL — use expires_at pra campanhas ou contextos que envelhecem. Ex: "cliente em teste grátis até DD/MM" pode expirar junto com o teste.
• Canais cruzados — hoje memória é por canal (phone ≠ instagram_id ≠ session_id do widget). Se o mesmo humano falar por dois canais, são dois contatos distintos no banco. Unificação cross-canal fica pra futuro.

LGPD / direito ao esquecimento

Quando um usuário solicita esquecimento:

1. Vá em Contatos → encontre o contato → aba Memória IA → Esquecer tudo.
2. Clique em Excluir na lista de contatos pra apagar o contato em si.
3. Os dados cascateiam via FK — registro removido em todas as tabelas relacionadas.

O audit log (/dashboard/auditoria) mantém registro da ação pra compliance.