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.

1. 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.

1. 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".

When NOT to Use

• One-shot batch ingestion. Process the corpus once, build the graph,

done. Incremental pattern is overhead.

• Static knowledge base. No updates means no incremental anything.
• Adversarial entity resolution (bot accounts, evasion). Default

fuzzy-match heuristic is too permissive; use a hardened resolver with domain rules.

• Very small graph ( 80% "new" on a mature graph.

Either the graph is bootstrapping (early days, expected) or canonical/ alias resolution is broken (mature, anomalous).

• Fuzzy match rate > 30% on a mature graph. Aliases are missing.

Add the canonical aliases as exact matches; reserve fuzzy for genuinely unknown variants.

• Entity-resolved-to-existing but the existing node's type doesn't match.

Resolution is confusing person-named-Apple with company-named-Apple. Add type-aware resolution; never collapse across types.

Non-Negotiable Verification

1. Run the benchmark battery. python cli.py benchmark must report:

• touched_nodes count is independent of graph size (10-node graph and

1000-node graph produce the same touched_nodes for the same episode)

• canonical / alias / fuzzy / new resolution methods all exercised
• locality invariant: % nodes changed < 10% for the test workload
• round-trip serialize/deserialize preserves graph state

1. Run the DevOps scenario. python cli.py scenario incident-stream

must process 20 incident-update episodes, with touched_nodes per episode << total graph size.

1. Verify CLI help. python cli.py --help exits 0 and prints SKILL.md.

Security Posture

• Prompt injection. Episodes are untrusted input (chat turns, incident

feeds). Extraction and resolution treat episode text as data - nothing is executed - but an adversarial episode can plant false entities or alias itself onto an existing node to corrupt what the graph "knows". Type-aware resolution and the resolution-method log are the audit surface; review high-impact merges.

• Data exfiltration. Episode content is persisted into the durable graph -

sensitive facts mentioned once stay retrievable indefinitely. No network calls or file writes in the skill itself; apply retention policy at the graph store.

• Privilege escalation. No shell invocation, no eval. The escalation path

is graph poisoning: a crafted episode that resolves onto a trusted node inherits that node's standing in downstream reasoning. Keep the locality check (touched_nodes) as a blast-radius bound and gate bulk merges.

Source Attribution

Distilled from Agentic GraphRAG (O'Reilly, by Anthony Alcaraz and Sam Julien), Chapter 4 — Graphiti Pattern section + Example 4-8. Production anchor: Zep Graphiti.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AnthonyAlcaraz
• Source: AnthonyAlcaraz/agentic-graph-rag-skills
• License: MIT
• Homepage: https://www.oreilly.com/library/view/agentic-graphrag/9798341623163/

Install and usage instructions live in the source repository linked above.