Graphiti - Grafi di Conoscenza Temporali per Agenti
Graphiti (di Zep) è un framework open-source per costruire e interrogare grafi di conoscenza temporali per agenti IA. A differenza di un grafo statico, Graphiti traccia come i fatti cambiano nel tempo: ogni arco porta intervalli di validità, quindi il grafo sa non solo cosa è vero ma quando era vero, preservando la provenienza e la storia. Acquisisce i dati in modo incrementale — gli episodi vengono aggiunti senza ricompilare l”intero grafo — rendendolo ben adatto a memoria che deve ragionare su fatti in evoluzione.
Requisiti
- Un database di grafi: Neo4j o FalkorDB
- Un provider LLM (OpenAI, Anthropic, ecc.) per l”estrazione di entità/relazioni
- Python 3.10+
Installazione
| Metodo | Comando |
|---|
| pip | pip install graphiti-core |
| Con FalkorDB | pip install "graphiti-core[falkordb]" |
| Imposta le chiavi | export OPENAI_API_KEY=... e variabili d”ambiente del DB di grafi |
| Verifica | python -c "import graphiti_core; print('ok')" |
Concetti Principali
| Termine | Significato |
|---|
| Episodio | Un”unità di dati acquisiti (messaggio, testo, JSON) |
| Nodo | Un”entità estratta dagli episodi |
| Arco (fatto) | Una relazione con validità temporale (valid_at/invalid_at) |
| Bi-temporale | Traccia sia il tempo dell”evento che il tempo di acquisizione |
| Community | Cluster di entità correlate |
Inizializza e Aggiungi Episodi
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 si è unito ad Acme come CTO nel 2024.",
source=EpisodeType.text,
reference_time=datetime.now(),
source_description="chat",
)
asyncio.run(main())
| Chiamata | Descrizione |
|---|
Graphiti(uri, user, pass) | Connettiti al DB di grafi |
build_indices_and_constraints() | Setup schema una sola volta |
add_episode(...) | Acquisisce dati; entità/archi estratti automaticamente |
add_episode_bulk(...) | Acquisizione batch |
Ricerca della Memoria
# Ricerca ibrida: semantica + BM25 + grafo, rirranking
results = await graphiti.search("Dove lavora Nick?")
for r in results:
print(r.fact, r.valid_at)
| Ricerca | Comportamento |
|---|
search(query) | Ricerca ibrida (semantica + parola chiave + grafo) di archi |
| Ricerca di nodi | Recupera entità |
| Rirranking | Opzioni RRF / distanza-grafo / cross-encoder |
| Nodo centrale | Bias dei risultati attorno a un”entità specifica |
Ragionamento Temporale
Il differenziatore: quando un fatto cambia, Graphiti non lo cancella — lo contrassegna come non valido e aggiunge uno nuovo, quindi la storia è preservata.
| Capacità | Uso |
|---|
| Invalidazione dei fatti | I fatti vecchi ottengono invalid_at impostato quando contraddetti |
| Query point-in-time | ”Cosa era vero alla data X?” |
| Provenienza | Traccia un fatto alla sua episodio di origine |
| Tipi di entità personalizzati | Definisci modelli Pydantic per l”estrazione tipizzata |
Integrazione
| Target | Come |
|---|
| Zep | Graphiti è il motore sotto il servizio di memoria di Zep |
| Framework di agenti | Usa come strumento di memoria/recupero |
| MCP | Server Graphiti MCP espone la memoria agli agenti |
| Personalizzato | Interroga il grafo direttamente per il contesto |
Flussi di Lavoro Comuni
# Memoria dell''agente che sopravvive a fatti che cambiano
await graphiti.add_episode(name="e1", episode_body="Nick usa Postgres.", ...)
# più tardi, il fatto cambia:
await graphiti.add_episode(name="e2", episode_body="Nick è migrato a SQLite.", ...)
# Graphiti invalida il fatto Postgres e registra quello SQLite con il tempo
ctx = await graphiti.search("Quale database usa Nick adesso?")
Graphiti vs Altri Framework di Memoria
| Aspetto | Graphiti | Cognee | Mem0 |
|---|
| Punto di forza principale | Fatti temporali/bi-temporali | Ragionamento grafo-nativo ECL | Personalizzazione |
| Cronologia | Preservato con orari di validità | Snapshot di grafi | Focalizzato su recente |
| Backend | Neo4j / FalkorDB | Multi-store | Vettore/grafo/KV |
| Migliore per | Fatti che cambiano nel tempo | Ragionamento grafo locale | Memoria conversazionale |
Risorse
