Graphiti: Der temporale Wissensgraph, der Agenten ein Zeitgedächtnis verleiht

Graphiti: Der temporale Wissensgraph, der Agenten ein Zeitgedächtnis verleiht

Fragen Sie einen Wissensgraphen „Was gilt gerade jetzt?“, erstarren die meisten. Sie wurden zum Indexierungszeitpunkt erstellt, enthalten eine Momentaufnahme — und veralten stillschweigend, sobald sich ein Fakt ändert. Das mag für ein Dokumentenkorpus funktionieren, das sich nie selbst bearbeitet. Für einen KI-Agenten, der sich merken muss, dass "Kendra loved Adidas shoes as of March 2026" — und sich dann im April daran erinnert, dass sie zu Nike gewechselt hat, ist es ein Ausschlusskriterium. Graphiti ist das Framework, das genau für dieses Problem entwickelt wurde: temporale Wissensgraphen , in denen jeder Fakt einen Gültigkeitszeitraum trägt und sich der Graph mit der Welt weiterentwickelt.

Dieser Artikel beleuchtet, was ein Kontextgraph eigentlich ist, warum die temporale Nachverfolgung den Unterschied zwischen einer Demo und einem robusten Agenten ausmacht, wie sich Graphiti im Vergleich zu statischem GraphRAG schlägt — und vor allem: einen lauffähigen Docker Compose Stack, den Sie noch heute starten können, um es selbst auszuprobieren.

Was ein Kontextgraph ist — und warum „temporal“ der entscheidende Punkt ist

Ein Kontextgraph ist ein temporaler Graph aus Entitäten, Beziehungen und Fakten. Das klassische Beispiel aus der Graphiti-Dokumentation lautet: "Kendra loves Adidas shoes (as of March 2026)." Im Gegensatz zu einem herkömmlichen Wissensgraphen trägt jeder Fakt in einem Kontextgraphen einen Gültigkeitszeitraum: wann er wahr wurde und wann (falls überhaupt) er überholt wurde. Entitäten entwickeln sich im Laufe der Zeit weiter, mit aktualisierten Zusammenfassungen. Und alles lässt sich auf Episoden — die Rohdaten, aus denen es entstanden ist — zurückverfolgen.

Die vier Komponenten, aus denen ein Kontextgraph besteht (aus dem Graphiti-README):

• Entitäten (Knoten) — Personen, Produkte, Richtlinien, Konzepte — mit Zusammenfassungen, die sich im Laufe der Zeit weiterentwickeln.
• Fakten / Beziehungen (Kanten) — Tripel (Entität → Beziehung → Entität) mit temporalen Gültigkeitszeiträumen.
• Episoden (Herkunft) — die Rohdaten, wie sie aufgenommen wurden, der Ground-Truth-Stream. Jeder abgeleitete Fakt lässt sich darauf zurückführen.
• Benutzerdefinierte Typen (Ontologie) — vom Entwickler definierte Entitäts- und Kantentypen über Pydantic-Modelle.

Das Wort, das die Hauptarbeit leistet, ist temporal. Wenn sich Informationen ändern, macht Graphiti die alte Tatsache ungültig, anstatt sie zu löschen. Sie können abfragen, was jetzt wahr ist oder was zu einem beliebigen Zeitpunkt in der Vergangenheit wahr war. Diese eine Designentscheidung ist es, die den Graphen zu einem Gedächtnis statt zu einem Cache macht.

Warum statisches GraphRAG für Agenten nicht ausreicht

Der GraphRAG-Ansatz, den Microsoft populär gemacht hat (arXiv:2404.16130), ist in einer Sache brillant: Er verwandelt einen großen statischen Korpus in einen abfragbaren Graphen mit Community-Zusammenfassungen, sodass Sie korpusweite „Sensemaking“-Fragen stellen können. Doch er ist batchorientiert und statisch. Sie indexieren einmal, fassen zusammen, und der Graph spiegelt den Korpus so wider, wie er zum Zeitpunkt der Indexierung war. Das Graphiti-README zieht den Vergleich direkt:

GraphRAG dient der statischen Dokumentzusammenfassung; Graphiti ist für dynamische, sich weiterentwickelnde temporale Wissensgraphen. GraphRAG ist batchorientiert; Graphiti ist kontinuierlich und inkrementell. GraphRAG erfasst einfache Zeitstempel; Graphiti führt eine explizite bitemporale Nachverfolgung mit automatischer Faktinvalidierung durch.

Für einen Agenten, der mit sich weiterentwickelnden, realen Daten arbeitet — sich ändernde Nutzerpräferenzen, sich ändernde Produktstatus, überarbeitete Richtlinien — ist ein statischer Graph ein Risiko. Der Agent zieht Schlüsse aus einer Momentaufnahme, die bereits falsch ist. Graphitis Antwort darauf ist inkrementeller Graphaufbau: Neue Daten werden sofort integriert, ohne Batch-Neuberechnung, und der Graph entwickelt sich in Echtzeit weiter, während Episoden eingespielt werden.

Das Retrieval-Modell: hybrid, nicht nur semantisch

Graphitis Retrieval ist hybrid — es kombiniert semantische Embeddings, Keyword-Suche (BM25) und Graph-Traversierung. Das README betont, dass dies eine bewusste Entscheidung ist, um die Abhängigkeit von LLM-Zusammenfassungen zur Abfragezeit zu vermeiden:

Hybrides Retrieval: kombiniert semantische Embeddings, Keyword-Suche (BM25) und Graph-Traversierung für latenzarme, präzise Abfragen ohne Abhängigkeit von LLM-Zusammenfassungen.

Der praktische Nutzen liegt in der Latenz. Die Vergleichstabelle im README gibt die Abfragelatenz von GraphRAG mit „Sekunden bis zu mehreren zehn Sekunden“ an (weil zur Abfragezeit ein LLM über Community-Zusammenfassungen läuft), während Graphiti typischerweise „unter einer Sekunde“ benötigt. Für einen Agenten, der mitten im Gespräch etwas nachschlagen muss, ist dieser Unterschied der zwischen einem flüssigen Assistenten und einer Pause.

Vorgegebene und gelernte Ontologie

Eine subtile, aber wichtige Fähigkeit: Graphiti unterstützt sowohl vorgegebene als auch gelernte Ontologien. Sie können Entitäts- und Kantentypen vorab über Pydantic-Modelle definieren (vorgegeben) oder die Struktur aus Ihren Daten emergieren lassen (gelernt). Die Formulierung im README lautet: „Einfach beginnen, weiterentwickeln, sobald Muster sichtbar werden.“ Das ist der pragmatische Mittelweg zwischen starrem Schema und Wildwuchs — Sie erhalten Typsicherheit, wo Sie sie brauchen, und Flexibilität, wo nicht.

Der Stack: eigene Graphdatenbank einbinden

Graphiti ist das Open-Source-Framework im Kern der Context-Infrastruktur von Zep, aber es ist bewusst selbst gehostet und mit eigener Datenbank. Das README listet die unterstützten Backends auf:

• Neo4j 5.26 — das Flaggschiff, am besten dokumentierte Backend.
• FalkorDB 1.1.2 — eine Redis-kompatible Graphdatenbank, einfach in Docker auszuführen.
• Amazon Neptune — Neptune Database oder Neptune Analytics + OpenSearch Serverless für Volltextsuche.
• Kuzu 0.11.2 — veraltet (Upstream nicht mehr gewartet); neue Projekte sollten Neo4j oder FalkorDB verwenden.

Die Installation erfolgt mit einem einzigen Befehl: pip install graphiti-core (oder uv add graphiti-core), mit Extras für jedes Backend — graphiti-core[falkordb], graphiti-core[neptune]und optionalen Extras für LLM-Anbieter wie graphiti-core[anthropic] oder graphiti-core[google-genai].

Die LLM-Anforderung: strukturierte Ausgabe zählt

Graphiti ist auf LLM-Dienste angewiesen, die zuverlässig strukturierte Ausgabe (JSON-Schema) für die Extraktion und Deduplizierung von Entitäten und Kanten einhalten. Das README ist in diesem Punkt unmissverständlich:

Graphiti funktioniert am besten mit LLM-Diensten, die Structured Output unterstützen (wie OpenAI, Anthropic und Gemini). Die Nutzung anderer Dienste kann zu fehlerhaften Ausgabeschemata und Ingestionsfehlern führen. Dies ist besonders problematisch bei kleineren Modellen.

Standardmäßig wird OpenAI sowohl für LLM-Inferenz als auch für Embeddings verwendet, daher ist ein OPENAI_API_KEY der schnellste Weg. Es unterstützt aber auch OpenAI-kompatible Endpunkte — DeepSeek, Together, OpenRouter und lokale Server wie Ollama, vLLM und llama.cpp — über OpenAIGenericClientDie praktische Regel aus der Dokumentation: Verwenden Sie das leistungsfähigste Modell, das Sie ausführen können, da sehr kleine Modelle häufig JSON ausgeben, das nicht dem Schema entspricht — was zu Extraktionsfehlern führt.

Ein lauffähiger Docker Compose Stack

Der schnellste Weg, Graphiti in Aktion zu sehen, ist das offizielle FastAPI-Server-Image, zepai/graphiti:latest, verbunden mit einem Neo4j-Container. Das offizielle Server-README zeigt das Muster, und das Repository selbst docker-compose.yml enthält die Healthchecks und Profile. Hier ist ein in sich geschlossener, herunterladbarer Stack, der Neo4j und die Graphiti-API mit Healthcheck und persistentem Speicher startet:

# docker-compose.yml — Graphiti temporal knowledge graph stack
# Usage:  export OPENAI_API_KEY=sk-...  &&  docker compose up -d
# API:    http://localhost:8000/docs   (Swagger UI)
# Neo4j:  http://localhost:7474        (browser, neo4j/password)

services:
  graphiti:
    image: zepai/graphiti:latest
    container_name: graphiti
    ports:
      - "8000:8000"
    depends_on:
      neo4j:
        condition: service_healthy
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - NEO4J_URI=bolt://neo4j:${NEO4J_PORT:-7687}
      - NEO4J_USER=${NEO4J_USER:-neo4j}
      - NEO4J_PASSWORD=${NEO4J_PASSWORD:-password}
      - PORT=8000
      - db_backend=neo4j
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/healthcheck')"]
      interval: 10s
      timeout: 5s
      retries: 3
    restart: unless-stopped

  neo4j:
    image: neo4j:5.26.2
    container_name: graphiti-neo4j
    ports:
      - "7474:7474"          # HTTP browser
      - "${NEO4J_PORT:-7687}:${NEO4J_PORT:-7687}"  # Bolt
    volumes:
      - neo4j_data:/data
    environment:
      - NEO4J_AUTH=${NEO4J_USER:-neo4j}/${NEO4J_PASSWORD:-password}
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:${NEO4J_PORT:-7474} || exit 1"]
      interval: 1s
      timeout: 10s
      retries: 10
      start_period: 3s
    restart: unless-stopped

volumes:
  neo4j_data:

Die Healthchecks sind wichtig: Der API-Container wartet, bis Neo4j betriebsbereit ist, bevor er startet, und die API stellt ihren eigenen /healthcheck Endpunkt bereit, sodass Sie bestätigen können, dass der gesamte Stack läuft. Der neo4j_data Volume speichert Ihren Graphen über Container-Neustarts hinweg.

Der Quickstart, in Code

Sobald der Stack läuft, besteht der Kern-Workflow aus: Verbinden, Episoden hinzufügen, suchen. Der offizielle Quickstart (examples/quickstart) zeigt die Struktur. Sie initialisieren Graphiti mit Neo4j, fügen Episoden als Text oder strukturiertes JSON hinzu, und das Framework extrahiert automatisch Entitäten und Beziehungen:

from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType

# Connect to Neo4j and set up Graphiti indices
graphiti = Graphiti("bolt://localhost:7687", "neo4j", "password")

# Add an episode (text) — Graphiti extracts entities + relationships
await graphiti.add_episode(
    name="Freakonomics Radio 0",
    episode_body="Kamala Harris is the Attorney General of California.",
    source=EpisodeType.text,
    source_description="podcast transcript",
)

# Hybrid search: semantic + BM25 + graph traversal
results = await graphiti.search("Who was the California Attorney General?")
for r in results:
    print(r.fact, r.valid_at, r.invalid_at)

Die Suchergebnisse enthalten valid_at und invalid_at — das zeitliche Gültigkeitsfenster. Das ist die gesamte These in einer Zeile: Die Antwort kommt mit wann sie gültig war, nicht nur, was sie war.

Zep vs. Graphiti: Wann welches verwenden

Graphiti ist der Open-Source-Kern; Zep ist die darauf aufbauende verwaltete Plattform. Das README beschreibt die Aufteilung klar:

• Wählen Sie Zep, wenn Sie eine schlüsselfertige, unternehmensreife Plattform mit integrierter Sicherheit, Performance und Support wünschen — verwaltete Kontextgraphen, Retrieval in unter 200 ms im großen Maßstab, ein Dashboard sowie SDKs für Python, TypeScript und Go.
• Wählen Sie Graphiti, wenn Sie einen flexiblen Open-Source-Kern bevorzugen und bereit sind, das umgebende System selbst aufzubauen und zu betreiben.

Die zugrundeliegende Architektur ist im Zep-Paper „Zep: A Temporal Knowledge Graph Architecture“ (arXiv:2501.13956) dokumentiert, das lesenswert ist, wenn Sie die vollständige Designbegründung für bi-temporales Tracking und Fakt-Invalidierung nachvollziehen möchten.

Das Fazit

Statische Wissensgraphen sind eine Momentaufnahme; Agenten brauchen ein Gedächtnis. Graphitis Beitrag besteht darin, „was wann galt“ als erstklassige Abfrage zu etablieren — Fakten tragen Gültigkeitsfenster, alte Fakten werden invalidiert statt gelöscht, und alles lässt sich auf die Roh-Episoden zurückführen, aus denen es entstand. Für jeden Agenten, der mit sich ändernden Realweltdaten arbeitet, ist das der Unterschied zwischen Schlussfolgern über ein lebendiges Gedächtnis und Schlussfolgern über einen veralteten Cache. Der oben stehende Docker Compose Stack bringt Ihnen in wenigen Minuten einen laufenden temporalen Wissensgraphen — und der Quickstart zeigt, wie wenig Code nötig ist, um ihn zu füttern.

Quellen

• Graphiti-Repository (README, Architektur, Quickstart, docker-compose): https://github.com/getzep/graphiti
• Zep-Paper — „Zep: A Temporal Knowledge Graph Architecture“ (arXiv): https://arxiv.org/abs/2501.13956
• Graphiti-Server-README (zepai/graphiti-Image, compose-Pattern): https://github.com/getzep/graphiti/tree/main/server
• Graphiti-Schnellstart-Beispiel: https://github.com/getzep/graphiti/tree/main/examples/quickstart
• Graphiti-Anleitungen & API-Dokumentation: https://help.getzep.com/graphiti
• Microsoft-GraphRAG-Paper (für den statisch-vs.-temporal-Kontrast): https://arxiv.org/abs/2404.16130