Zep - Engenharia de Contexto e Memória para Agentes
Zep é uma camada de memória e engenharia de contexto para agentes AI. Construída no mecanismo de grafo de conhecimento temporal Graphiti, ela ingere histórico de conversa e dados de negócio, os funde em um grafo consultável que rastreia como fatos mudam com o tempo, e retorna contexto relevante e governado com baixa latência para fundamentar respostas de agente. Oferece um núcleo de código aberto e um serviço em nuvem gerenciado (SOC 2 / HIPAA), com SDKs para Python, TypeScript e Go.
Instalação / Setup
| Alvo | Comando |
|---|
| Python SDK | pip install zep-cloud (nuvem) |
| TypeScript SDK | npm install @getzep/zep-cloud |
| Auto-hospedado (Community Edition) | execute via Docker Compose do projeto |
| Chave API | export ZEP_API_KEY=... |
Conceitos Principais
| Termo | Significado |
|---|
| Usuário | Um usuário final que o agente serve |
| Thread | Uma sessão de conversa para um usuário |
| Grafo | O grafo de conhecimento temporal de um usuário/grupo |
| Fato | Um relacionamento consciente de tempo no grafo |
| Bloco de contexto | Contexto montado, pronto para injetar |
Usuários e Threads
from zep_cloud.client import Zep
zep = Zep(api_key="...")
zep.user.add(user_id="nick", email="nick@example.com")
zep.thread.create(thread_id="t1", user_id="nick")
| Chamada | Descrição |
|---|
user.add(...) | Crie um usuário |
thread.create(...) | Inicie uma thread de conversa |
thread.add_messages(...) | Anexe mensagens (auto-ingeridas no grafo) |
user.delete(...) | Remova um usuário e seus dados |
Adicionando Memória
zep.thread.add_messages(
thread_id="t1",
messages=[{"role": "user", "content": "Me mudei para Berlim.", "name": "Nick"}],
)
# Adicione dados de negócio não-chat diretamente ao grafo
zep.graph.add(user_id="nick", type="text",
data="Nick''s subscription tier is Pro.")
| Chamada | Descrição |
|---|
thread.add_messages(...) | Ingira turnos de conversa |
graph.add(...) | Adicione texto/JSON arbitrário ao grafo |
| Ingestão | Entidades/fatos extraídos e marcados com timestamp automaticamente |
Recuperando Contexto
# Obtenha um bloco de contexto montado para o prompt
memory = zep.thread.get_user_context(thread_id="t1")
print(memory.context) # string pronta para injetar de fatos relevantes
# Ou consulte o grafo diretamente
edges = zep.graph.search(user_id="nick", query="onde Nick mora?")
| Chamada | Retorna |
|---|
thread.get_user_context(...) | Um bloco de contexto sintetizado |
graph.search(...) | Fatos/arestas ou nós correspondentes à consulta |
| Escopo de busca | arestas (fatos), nós (entidades) ou episódios |
Por Que Temporal
Porque Zep é baseado em grafo e consciente de tempo, atualizações contraditórias não sobrescrevem cegamente — fatos antigos recebem invalid_at definido com um timestamp e novos são registrados, então o agente obtém a verdade atual enquanto o histórico permanece consultável.
| Capacidade | Benefício |
|---|
| Invalidação de fato | Contexto atual permanece preciso |
| Proveniência | Rastreie fatos de volta à sua origem |
| Recuperação governada | Contexto de baixa latência e permissionado |
| Cross-sessão | Memória persiste entre threads |
Workflows Comuns
# O loop do agente com memória Zep
zep.thread.add_messages(thread_id="t1", messages=user_turn)
context = zep.thread.get_user_context(thread_id="t1").context
# prepend `context` ao seu prompt de sistema LLM, depois gere
Zep vs Outras Camadas de Memória
| Aspecto | Zep | Mem0 | armazenador vetorial bruto |
|---|
| Modelo | Grafo temporal (Graphiti) | Multi-tier | Embeddings apenas |
| Fatos temporais | Sim | Limitado | Não |
| Montagem de contexto | Bloco integrado | Recuperação | Manual |
| Melhor para | Memória de agente em produção | Personalização | Recall simples |
Recursos
