Graphiti - Grafos de Conhecimento Temporal para Agentes
Graphiti (por Zep) é um framework de código aberto para construção e consulta de grafos de conhecimento temporal para agentes AI. Ao contrário de um grafo estático, Graphiti rastreia como fatos mudam com o tempo: cada aresta carrega intervalos de validade, então o grafo sabe não apenas o que é verdadeiro, mas quando era verdadeiro, preservando proveniência e histórico. Ele ingere dados incrementalmente — episódios são adicionados sem recomputar todo o grafo — tornando-o bem adequado para memória que deve raciocinar sobre fatos em evolução.
Requisitos
- Um banco de dados de grafo: Neo4j ou FalkorDB
- Um provedor de LLM (OpenAI, Anthropic, etc.) para extração de entidade/relacionamento
- Python 3.10+
Instalação
| Método | Comando |
|---|
| pip | pip install graphiti-core |
| Com FalkorDB | pip install "graphiti-core[falkordb]" |
| Defina chaves | export OPENAI_API_KEY=... e variáveis de env de BD de grafo |
| Verificar | python -c "import graphiti_core; print('ok')" |
Conceitos Principais
| Termo | Significado |
|---|
| Episódio | Uma unidade de dados ingeridos (mensagem, texto, JSON) |
| Nó | Uma entidade extraída de episódios |
| Aresta (fato) | Um relacionamento com validade de tempo (valid_at/invalid_at) |
| Bi-temporal | Rastreia tempo de evento e tempo de ingestão |
| Comunidade | Clusters de entidades relacionadas |
Inicializar e Adicionar Episódios
from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType
import asyncio
async def main():
graphiti = Graphiti("bolt://localhost:7687", "neo4j", "password")
await graphiti.build_indices_and_constraints()
await graphiti.add_episode(
name="msg1",
episode_body="Nick ingressou na Acme como CTO em 2024.",
source=EpisodeType.text,
reference_time=datetime.now(),
source_description="chat",
)
asyncio.run(main())
| Chamada | Descrição |
|---|
Graphiti(uri, user, pass) | Conecte ao BD de grafo |
build_indices_and_constraints() | Setup de schema único |
add_episode(...) | Ingira dados; entidades/arestas extraídas automaticamente |
add_episode_bulk(...) | Ingestão em lote |
Procurando Memória
# Busca híbrida: semântica + BM25 + grafo, rerankeado
results = await graphiti.search("Onde Nick trabalha?")
for r in results:
print(r.fact, r.valid_at)
| Busca | Comportamento |
|---|
search(query) | Busca de aresta híbrida (semântica + palavra-chave + grafo) |
| Busca de nó | Recupere entidades |
| Reranking | Opções RRF / distância de grafo / cross-encoder |
| Nó central | Viés de resultados em torno de uma entidade específica |
Raciocínio Temporal
O diferencial: quando um fato muda, Graphiti não o deleta — marca a aresta anterior como inválida e adiciona a nova, então o histórico é preservado.
| Capacidade | Uso |
|---|
| Invalidação de fato | Fatos antigos recebem invalid_at definido quando contraditos |
| Consultas point-in-time | ”O que era verdadeiro em data X?” |
| Proveniência | Rastreie um fato de volta ao seu episódio de origem |
| Tipos de entidade customizados | Defina modelos Pydantic para extração tipada |
Integração
| Alvo | Como |
|---|
| Zep | Graphiti é o mecanismo por trás do serviço de memória do Zep |
| Frameworks de agente | Use como ferramenta de memória/recuperação |
| MCP | Servidor MCP do Graphiti expõe memória para agentes |
| Custom | Consulte o grafo diretamente para contexto |
Workflows Comuns
# Memória de agente que sobrevive a fatos em mudança
await graphiti.add_episode(name="e1", episode_body="Nick usa Postgres.", ...)
# depois, o fato muda:
await graphiti.add_episode(name="e2", episode_body="Nick migrou para SQLite.", ...)
# Graphiti invalida o fato Postgres e registra o SQLite com horário
ctx = await graphiti.search("Qual banco de dados Nick usa agora?")
Graphiti vs Outros Frameworks de Memória
| Aspecto | Graphiti | Cognee | Mem0 |
|---|
| Força principal | Fatos temporal/bi-temporal | Raciocínio de grafo-nativo ECL | Personalização |
| Histórico | Preservado com tempos de validade | Snapshots de grafo | Focado no recente |
| Backend | Neo4j / FalkorDB | Multi-store | Vetor/grafo/KV |
| Melhor para | Fatos que mudam com o tempo | Raciocínio de grafo local | Memória conversacional |
Recursos
