Projeto de Sistema de Memória
A memória fornece a camada de persistência que permite aos agentes manter continuidade entre sessões e raciocinar sobre conhecimento acumulado. Agentes simples dependem inteiramente do contexto para memória, perdendo todo o estado quando as sessões terminam. Agentes sofisticados implementam arquiteturas de memória em camadas que equilibram as necessidades imediatas de contexto com a retenção de conhecimento de longo prazo. A evolução de armazenamentos vetoriais para grafos de conhecimento e, em seguida, para grafos de conhecimento temporais representa um investimento crescente em memória estruturada para melhor recuperação e raciocínio.
Quando Ativar
Ative esta skill quando:
- Construir agentes que devem persistir conhecimento entre sessões
- Escolher entre frameworks de memória (Mem0, Zep/Graphiti, Letta, LangMem, Cognee)
- Precisar manter consistência de entidades entre conversas
- Implementar raciocínio sobre conhecimento acumulado
- Projetar arquiteturas de memória que escalam em produção
- Avaliar sistemas de memória com benchmarks (LoCoMo, LongMemEval, DMR)
- Construir memória dinâmica com extração automática de entidades/relacionamentos e memória auto-melhorável (Cognee)
Não ative esta skill para trabalhos adjacentes de outras skills:
- Rascunhos baseados em arquivos, logs de execução e offloading de saída de ferramentas:
filesystem-context. - Compactação de conversas ou resumos de handoff legíveis por humanos:
context-compression. - Mascaramento, cache de prefixo, orçamentos de tokens ou escopo de recuperação dentro de uma trajetória:
context-optimization. - Modelos formais de crença/desejo/intenção sobre estado RDF:
bdi-mental-states.
Conceitos Principais
Pense na memória como um espectro, desde a janela de contexto volátil até o armazenamento persistente. Use por padrão a camada mais simples que atenda às necessidades de recuperação, porque evidências de benchmark sugerem que a complexidade da ferramenta importa menos do que a recuperação confiável para algumas cargas de trabalho de memória (claim-memory-locomo-filesystem-baseline). Adicione estrutura (grafos, validade temporal) somente quando a qualidade da recuperação degradar ou o agente precisar de raciocínio de múltiplos saltos, travessia de relacionamentos ou consultas de viagem no tempo.
Tópicos Detalhados
Panorama de Frameworks de Produção
Selecione um framework com base no padrão de recuperação dominante que o agente requer. Use esta tabela para restringir a lista, depois valide com os dados de benchmark abaixo.
| Framework | Arquitetura | Melhor Para | Trade-off |
|---|---|---|---|
| Mem0 | Armazenamento vetorial + memória de grafo, backends plugáveis | Sistemas multi-tenant, integrações amplas | Menos especializado para multi-agente |
| Zep/Graphiti | Grafo de conhecimento temporal, modelo bi-temporal | Empresas que exigem modelagem de relacionamentos + raciocínio temporal | Recursos avançados bloqueados em nuvem |
| Letta | Memória autoeditável com armazenamento em camadas (in-context/core/archival) | Introspecção completa do agente, serviços com estado | Complexidade para casos de uso simples |
| Cognee | Grafo semântico multicamadas via pipeline ECL personalizável com Tarefas personalizáveis | Memória de agente em evolução que se adapta e aprende; raciocínio de múltiplos saltos | Processamento mais pesado na ingestão |
| LangMem | Ferramentas de memória para fluxos de trabalho LangGraph | Equipes já usando LangGraph | Fortemente acoplado ao LangGraph |
| Sistema de arquivos | Arquivos simples com convenções de nomenclatura | Agentes simples, prototipagem | Sem pesquisa semântica, sem relacionamentos |
Escolha Zep/Graphiti quando o agente precisar de modelagem bi-temporal (rastreando tanto quando os eventos ocorreram quanto quando foram ingeridos) porque seu grafo de conhecimento de três camadas (episódio, entidade semântica, subgrafos comunitários) é excelente em consultas temporais. Escolha Mem0 quando a prioridade for rapidez na produção com infraestrutura gerenciada. Escolha Letta quando o agente precisar de introspecção profunda por meio de seu Ambiente de Desenvolvimento de Agentes. Escolha Cognee quando o agente precisar construir grafos semânticos multicamadas densos — ele organiza chunks de texto e tipos de entidade como nós com arestas de relacionamento detalhadas, e cada peça central (ingestão, extração de entidades, pós-processamento, recuperação) é personalizável.
Comparação de Desempenho com Benchmarks
Consulte esses benchmarks para definir expectativas, mas trate-os como sinais específicos de fonte para dimensões de recuperação, e não como rankings absolutos. Nenhum benchmark único é definitivo.
| Sistema | Precisão DMR | LoCoMo | HotPotQA (múltiplos saltos) | Latência |
|---|---|---|---|---|
| Cognee | — | — | Pontuação alta publicada | Variável |
| Zep (Temporal KG) | Pontuação alta publicada | — | Faixa média entre métricas | Baixa latência relatada |
| Letta (sistema de arquivos) | — | Linha de base do sistema de arquivos publicada | — | — |
| Mem0 | — | Linha de base de ferramenta especializada publicada | Inferior em uma comparação | — |
| MemGPT | Pontuação alta publicada | — | — | Variável |
| GraphRAG | Faixa média/alta publicada | — | — | Variável |
| Linha de base RAG vetorial | Faixa inferior publicada | — | — | Rápido |
Principais conclusões: compare sistemas de memória pela forma de recuperação, não pela marca. Use números de benchmark como evidência datada que deve ser reavaliada antes de fazer afirmações sobre o produto; a regra de design estável é começar superficial, medir a qualidade da recuperação e adicionar estrutura semântica ou de grafo somente quando uma camada mais simples falhar.
Camadas de Memória (Pontos de Decisão)
Escolha a camada de memória mais superficial que satisfaça o requisito de persistência. Cada camada mais profunda adiciona custo de infraestrutura e complexidade operacional, então só aumente quando a camada mais superficial não puder atender à necessidade de recuperação ou durabilidade.
| Camada | Persistência | Implementação | Quando Usar |
|---|---|---|---|
| De trabalho | Apenas janela de contexto | Rascunho no prompt do sistema | Sempre — otimize com posições favorecidas pela atenção |
| Curto prazo | Escopo da sessão | Sistema de arquivos, cache em memória | Resultados intermediários de ferramentas, estado da conversa |
| Longo prazo | Entre sessões | Armazenamento chave-valor → BD de grafos | Preferências do usuário, conhecimento de domínio, registros de entidades |
| Entidade | Entre sessões | Registro de entidades + propriedades | Manter identidade ("João Silva" = mesma pessoa em várias conversas) |
| Grafo Temporal (Temporal KG) | Entre sessões + histórico | Grafo com intervalos de validade | Fatos que mudam ao longo do tempo, consultas de viagem no tempo, prevenção de conflitos de contexto |
Estratégias de Recuperação
Combine a estratégia de recuperação com a forma da consulta. A pesquisa semântica lida bem com consultas factuais diretas, mas degrada em raciocínio de múltiplos saltos; a travessia baseada em entidades lida com consultas "tudo sobre X", mas exige estrutura de grafo; a filtragem temporal lida com fatos mutáveis, mas requer metadados de validade. Quando a precisão é primordial e o orçamento de infraestrutura permite, combine estratégias em recuperação híbrida.
| Estratégia | Quando Usar | Limitação |
|---|---|---|
| Semântica (similaridade de embeddings) | Consultas factuais diretas | Degrada em raciocínio de múltiplos saltos |
| Baseada em entidades (travessia de grafo) | "Conte-me tudo sobre X" | Requer estrutura de grafo |
| Temporal (filtro de validade) | Fatos mudam ao longo do tempo | Requer metadados de validade |
| Híbrida (semântico + palavra-chave + grafo) | Melhor precisão geral | Mais infraestrutura |
Abordagens híbridas reduzem o contexto ativo recuperando apenas subgrafos ou memórias relevantes. O Cognee implementa recuperação híbrida por meio de vários modos de pesquisa em armazenamentos de grafo, vetorial e relacional, permitindo que os agentes selecionem a estratégia de recuperação que se ajusta ao tipo de consulta, em vez de usar uma abordagem única.
Consolidação de Memória
Execute a consolidação periodicamente para evitar crescimento ilimitado, porque o acúmulo descontrolado de memória degrada a qualidade da recuperação ao longo do tempo. Invalide, mas não descarte — preservar o histórico é importante para consultas temporais que precisam reconstruir estados passados. Acione a consolidação com base em limites de contagem de memória, qualidade degradada de recuperação ou intervalos agendados. Consulte a Referência de Implementação para obter código de consolidação funcional.
Orientação Prática
Escolhendo uma Arquitetura de Memória
Comece com a camada viável mais simples e adicione complexidade somente quando a qualidade da recuperação degradar. A maioria dos agentes não precisa de um grafo de conhecimento temporal no primeiro dia. Siga este caminho de escalonamento:
- Prototipagem: Use memória baseada em sistema de arquivos. Armazene fatos como JSON estruturado com carimbos de data/hora. Isso valida o comportamento do agente antes de se comprometer com a infraestrutura.
- Escala: Mude para Mem0 ou um armazenamento vetorial com metadados quando o agente precisar de pesquisa semântica e isolamento multi-tenant, porque a consulta baseada em arquivos não pode lidar com consultas de similaridade.
- Raciocínio complexo: Adicione Zep/Graphiti quando o agente precisar de travessia de relacionamentos, validade temporal ou síntese entre sessões. O Graphiti usa vínculos estruturados com relações genéricas, mantendo os grafos simples e fáceis de raciocinar; o Cognee constrói grafos semânticos multicamadas mais densos com arestas de relacionamento detalhadas — escolha com base em se o agente precisa de modelagem bi-temporal (Graphiti) ou estruturas de conhecimento interconectadas mais ricas (Cognee).
- Controle total: Use Letta ou Cognee quando o agente precisar autogerenciar sua própria memória com introspecção profunda, porque esses frameworks expõem operações de memória como ações de primeira classe do agente.
Integração com Contexto
Carregue memórias just-in-time em vez de pré-carregar tudo, porque cargas úteis de contexto grandes são caras e degradam a qualidade da atenção. Coloque as memórias recuperadas em posições favorecidas pela atenção (início ou fim do contexto) para maximizar sua influência na geração.
Recuperação de Erros
Lide com falhas de recuperação de forma elegante porque os sistemas de memória são inerentemente ruidosos. Aplique estas estratégias de recuperação em ordem:
- Recuperação vazia: Recorra a uma pesquisa mais ampla (remover filtro de entidade, ampliar intervalo de tempo). Se ainda estiver vazio, peça esclarecimento ao usuário.
- Resultados desatualizados: Verifique os carimbos de data/hora
valid_until. Se a maioria dos resultados estiver expirada, acione a consolidação antes de tentar novamente. - Fatos conflitantes: Prefira o fato com o
valid_frommais recente. Exiba o conflito ao usuário se a confiança for baixa. - Falha de armazenamento: Coloque as gravações em fila para repetição. Nunca bloqueie a resposta do agente em uma gravação de memória.
Exemplos
Exemplo 1: Integração Mem0
from mem0 import Memory
m = Memory()
m.add("Usuário prefere modo escuro e Python 3.12", user_id="alice")
m.add("Usuário mudou para modo claro", user_id="alice")
# Recupera a preferência atual (modo claro), não a desatualizada
resultados = m.search("Qual tema o usuário prefere?", user_id="alice")
Exemplo 2: Consulta Temporal
# Rastrear entidade com períodos de validade
graph.create_temporal_relationship(
source_id=nodo_usuario,
rel_type="MORA_EM",
target_id=nodo_endereco,
valid_from=datetime(2024, 1, 15),
valid_until=datetime(2024, 9, 1), # mudou-se
)
# Consulta: Onde o usuário morava em 1 de março de 2024?
resultados = graph.query_at_time(
{"type": "MORA_EM", "source_label": "Usuário"},
query_time=datetime(2024, 3, 1)
)
Exemplo 3: Ingestão e Pesquisa de Memória Cognee
import cognee
from cognee.modules.search.types import SearchType
# Ingerir e construir grafo de conhecimento
await cognee.add("./docs/")
await cognee.add("quaisquer dados")
await cognee.cognify()
# Enriquecer memória
await cognee.memify()
# O agente recupera contexto ciente de relacionamentos
resultados = await cognee.search(
query_text="Qualquer consulta para sua memória",
query_type=SearchType.GRAPH_COMPLETION,
)
Diretrizes
- Comece com memória baseada em sistema de arquivos; adicione complexidade somente quando a qualidade da recuperação exigir
- Rastreie validade temporal para qualquer fato que possa mudar ao longo do tempo
- Use recuperação híbrida (semântico + palavra-chave + grafo) para melhor precisão
- Consolide memórias periodicamente — invalide, mas não descarte
- Projete para falha de recuperação: sempre tenha um fallback quando a consulta de memória não retornar nada
- Considere as implicações de privacidade da memória persistente (políticas de retenção, direitos de exclusão)
- Avalie seu sistema de memória com LoCoMo ou LongMemEval antes e depois das alterações
- Monitore o crescimento da memória e a latência de recuperação em produção
Armadilhas
- Entulhar tudo no contexto: Carregar todas as memórias disponíveis no prompt é caro e degrada a qualidade da atenção. Use recuperação just-in-time com filtragem de relevância.
- Ignorar validade temporal: Fatos ficam desatualizados. Sem rastreamento de validade, informações desatualizadas envenenam o contexto e o agente age com suposições erradas.
- Superengenharia precoce: Memória simples baseada em sistema de arquivos pode superar ferramentas mais especializadas em alguns benchmarks (claim-memory-locomo-filesystem-baseline). Adicione sofisticação somente quando abordagens simples falharem de forma demonstrável.
- Sem estratégia de consolidação: O crescimento ilimitado da memória degrada a qualidade da recuperação ao longo do tempo. Defina limites de contagem de memória ou intervalos agendados para acionar a consolidação.
- Incompatibilidade de modelo de embedding: Escrever memórias com um modelo de embedding e ler com outro produz recuperação ruim porque os espaços vetoriais não são intercambiáveis. Fixe um único modelo de embedding para cada armazenamento de memória e re-embedde todas as entradas se o modelo mudar.
- Rigidez do esquema de grafo: Esquemas de grafo excessivamente estruturados (tipos de nó rígidos, rótulos de relacionamento fixos) quebram quando o domínio evolui. Prefira tipos de relação genéricos e sacos de propriedades flexíveis para que novos tipos de entidade não exijam migrações de esquema.
- Envenenamento por memória desatualizada: Memórias antigas que contradizem o estado atual corrompem o comportamento do agente silenciosamente. Implemente políticas de expiração ou decaimento de confiança para que o agente despriorize fatos antigos e explicite contradições quando detectadas.
- Incompatibilidade memória-contexto: Recuperar memórias que são tematicamente relacionadas, mas contextualmente erradas (por exemplo, uma memória sobre "Python" a cobra quando o agente está discutindo Python a linguagem). Mitigue incluindo metadados de sessão ou domínio nas entradas de memória e filtrando-os durante a recuperação.
Integração
Esta skill é proprietária da memória semântica persistente. Skills adjacentes são proprietárias de armazenamento de rascunhos, compactação e táticas de contexto:
filesystem-context: rascunhos baseados em arquivos, logs e execução simples
… [truncado para tradução]