Graphiti - Gráficos de Conocimiento Temporal para Agentes
Graphiti (por Zep) es un marco de código abierto para construir y consultar gráficos de conocimiento temporal para agentes IA. A diferencia de un gráfico estático, Graphiti rastrea cómo cambian los hechos con el tiempo: cada arista lleva intervalos de validez, así el gráfico sabe no solo qué es verdadero sino cuándo fue verdadero, preservando procedencia e historia. Ingiere datos incrementalmente — los episodios se agregan sin recomputar todo el gráfico — lo que lo hace bien adaptado a la memoria que debe razonar sobre hechos en evolución.
Requisitos
- Una base de datos de gráficos: Neo4j o FalkorDB
- Un proveedor LLM (OpenAI, Anthropic, etc.) para extracción de entidades/relaciones
- Python 3.10+
Instalación
| Método | Comando |
|---|
| pip | pip install graphiti-core |
| Con FalkorDB | pip install "graphiti-core[falkordb]" |
| Establecer claves | export OPENAI_API_KEY=... y variables de entorno de BD de gráficos |
| Verificar | python -c "import graphiti_core; print('ok')" |
Conceptos Principales
| Término | Significado |
|---|
| Episodio | Una unidad de datos ingeridos (mensaje, texto, JSON) |
| Nodo | Una entidad extraída de episodios |
| Arista (hecho) | Una relación con tiempo de validez (valid_at/invalid_at) |
| Bi-temporal | Rastrea tanto el tiempo del evento como el tiempo de ingesta |
| Comunidad | Clústeres de entidades relacionadas |
Inicializar y Agregar Episodios
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 joined Acme as CTO in 2024.",
source=EpisodeType.text,
reference_time=datetime.now(),
source_description="chat",
)
asyncio.run(main())
| Llamada | Descripción |
|---|
Graphiti(uri, user, pass) | Conectar a la BD de gráficos |
build_indices_and_constraints() | Configuración de esquema de una sola vez |
add_episode(...) | Ingerir datos; entidades/aristas extraídas automáticamente |
add_episode_bulk(...) | Ingesta por lotes |
Búsqueda de Memoria
# Búsqueda híbrida: semántica + BM25 + gráfico, reordenada
results = await graphiti.search("Where does Nick work?")
for r in results:
print(r.fact, r.valid_at)
| Búsqueda | Comportamiento |
|---|
search(query) | Búsqueda de aristas híbrida (semántica + palabra clave + gráfico) |
| Búsqueda de nodos | Recuperar entidades |
| Reordenamiento | Opciones de RRF / distancia de gráfico / cross-encoder |
| Nodo central | Sesgar resultados alrededor de una entidad específica |
Razonamiento Temporal
El diferenciador: cuando un hecho cambia, Graphiti no lo borra — marca la arista anterior como inválida y agrega la nueva, así el historial se preserva.
| Capacidad | Uso |
|---|
| Invalidación de hechos | Los hechos antiguos obtienen invalid_at establecido cuando se contradicen |
| Consultas en un punto en el tiempo | ”¿Qué era verdadero a partir de la fecha X?” |
| Procedencia | Rastrear un hecho a su episodio de origen |
| Tipos de entidades personalizados | Definir modelos Pydantic para extracción tipificada |
Integración
| Destino | Cómo |
|---|
| Zep | Graphiti es el motor bajo el servicio de memoria de Zep |
| Marcos de agentes | Usar como herramienta de memoria/recuperación |
| MCP | El servidor MCP de Graphiti expone memoria a agentes |
| Personalizado | Consultar el gráfico directamente para contexto |
Flujos de Trabajo Comunes
# Memoria de agente que sobrevive a hechos cambiantes
await graphiti.add_episode(name="e1", episode_body="Nick uses Postgres.", ...)
# más tarde, el hecho cambia:
await graphiti.add_episode(name="e2", episode_body="Nick migrated to SQLite.", ...)
# Graphiti invalida el hecho de Postgres y registra el de SQLite con tiempo
ctx = await graphiti.search("What database does Nick use now?")
Graphiti vs Otros Marcos de Memoria
| Aspecto | Graphiti | Cognee | Mem0 |
|---|
| Fortaleza principal | Hechos temporal/bi-temporal | ECL nativo de gráfico | Personalización |
| Historial | Preservado con tiempos de validez | Snapshots de gráfico | Enfoque reciente |
| Backend | Neo4j / FalkorDB | Multi-tienda | Vector/gráfico/KV |
| Mejor para | Hechos que cambian con el tiempo | Razonamiento de gráfico local | Memoria conversacional |
Recursos
