graphiti-incremental-update

Graphiti Incremental-Update

Overview

A naive add-to-graph implementation re-extracts entities across the whole corpus, re-computes embeddings, and re-clusters everything every time new content arrives. At millions-of-nodes scale this is fatal: update latency grows with graph size, and the agent ends up waiting for re-indexing instead of reasoning.

Graphiti (Zep) ships a different pattern (Ch4 Example 4-8):

1. Extract entities and relationships only from the new episode. No backfill, no full-corpus re-pass.
2. Entity-resolve: match each extracted entity against existing graph nodes by canonical name, then alias, then fuzzy/embedding similarity. If matched, reuse the existing node id. If not, create new.
3. Incremental-update: modify only the touched neighborhood. New edges, possibly updated node metadata, no global re-clustering.

The chapter quote: "incremental_update modifies only the impacted neighborhood: the few nodes and edges touched by the new entities and relationships. The rest of the graph stays untouched, which keeps write operations predictably fast."

The retrieval side mirrors this: instead of one big query over everything, run parallel partial queries (vector / graph walk / keyword) targeting recent / specific / textual subsets, then merge. Production-grade Reciprocal Rank Fusion lives in a sibling skill; this skill is the ingestion side.

When to Use

• Memory graph that grows continuously (every interaction adds nodes)
• DevOps incident streams: new alerts, new deployments, new comments arriving every few seconds
• Customer-support agents where each ticket is an "episode" — entities (customer, product, issue type) resolve to existing nodes, new edges are added
• Multi-agent systems where each agent contributes new content to a shared graph and no agent should block on full-graph re-processing

Phrases: "incremental update", "don't re-process the whole graph", "entity resolution", "deduplicate against existing nodes", "Graphiti pattern", "add an episode".