Skip to main content

​
What is a Knowledge Graph?

A knowledge graph is a network of interconnected facts represented as triplets—each consisting of two entities (nodes) and their relationship (edge). For example, the fact “Kendra loves Adidas shoes” becomes:
  • Source Node: Kendra (entity)
  • Edge: loves (relationship)
  • Target Node: Adidas shoes (entity)
Knowledge graphs enable AI agents to reason about complex, interconnected information by representing it as a queryable network rather than isolated documents.

​
The Graphiti Approach

While traditional knowledge graphs have been used extensively for information retrieval, Graphiti introduces a unique approach tailored for AI agents:

​
Autonomous Graph Building

Graphiti autonomously constructs knowledge graphs from unstructured and structured data without requiring manual schema definition. When you add an episode (a unit of information), Graphiti:
  1. Extracts entities using LLMs to identify people, places, organizations, and custom entity types
  2. Identifies relationships between entities with semantic meaning
  3. Resolves duplicates by detecting when new information refers to existing entities
  4. Updates the graph incrementally without batch recomputation

​
Temporal Awareness

Unlike traditional static graphs, Graphiti maintains a temporal dimension: 
class EntityEdge(Edge):
    fact: str  # The relationship described as a fact
    valid_at: datetime | None  # When the fact became true
    invalid_at: datetime | None  # When the fact stopped being true
    expired_at: datetime | None  # When the edge was superseded
This enables:
  • Point-in-time queries: “Who was the Attorney General in 2015?”
  • Tracking evolving relationships: “When did Alice start working at Acme Corp?”
  • Handling contradictions: New information can invalidate old facts without deletion
Graphiti tracks both when facts occurred in the real world (valid_at/invalid_at) and when they were ingested into the system (created_at/expired_at). This bi-temporal model is crucial for accurate historical reasoning.

​
Graph Structure

A Graphiti knowledge graph consists of several node and edge types:

​
Node Types

TypePurposeExample
EntityNodeRepresents real-world entitiesPeople, places, organizations, concepts
EpisodicNodeStores raw input dataChat messages, documents, JSON data
CommunityNodeGroups related entitiesTopic clusters discovered through graph analysis
SagaNodeOrganizes sequential episodesConversation threads, event sequences

​
Edge Types

TypeConnectsPurpose
EntityEdge (RELATES_TO)Entity → EntitySemantic relationships with facts
EpisodicEdge (MENTIONS)Episode → EntityLinks raw data to extracted entities
CommunityEdge (HAS_MEMBER)Community → EntityMembership in topic clusters
HasEpisodeEdgeSaga → EpisodeSaga membership
NextEpisodeEdgeEpisode → EpisodeSequential ordering

​
Knowledge Representation Example

Consider this episode: 
await graphiti.add_episode(
    name="Career Update",
    episode_body="Kamala Harris is the Attorney General of California. "
                 "She was previously the district attorney for San Francisco.",
    source=EpisodeType.text,
    reference_time=datetime.now(timezone.utc),
)
Graphiti extracts: Entities:
  • Node: “Kamala Harris” (Person)
  • Node: “California” (Location)
  • Node: “San Francisco” (Location)
  • Node: “Attorney General” (Position)
  • Node: “District Attorney” (Position)
Relationships:
  • Edge: Kamala Harris → holds position → Attorney General
    • Fact: “Kamala Harris is the Attorney General of California”
  • Edge: Kamala Harris → previously held → District Attorney
    • Fact: “She was previously the district attorney for San Francisco”
Episode Link:
  • EpisodicEdge: “Career Update” → mentions → “Kamala Harris”

​
Why Graphiti vs Traditional Approaches

​
vs. RAG (Retrieval-Augmented Generation)

Traditional RAG systems retrieve document chunks based on semantic similarity. Graphiti goes further:
  • Structured relationships: Instead of text chunks, retrieve specific facts with context
  • Graph traversal: Find related information by following edges
  • Temporal queries: Filter by when facts were true, not just when documents were created
  • Contradiction handling: Automatically invalidates outdated information

​
vs. GraphRAG

AspectGraphRAGGraphiti
Data HandlingBatch-orientedContinuous, incremental
Primary UseStatic document summarizationDynamic data management
RetrievalSequential LLM summarizationHybrid semantic + keyword + graph
Temporal HandlingBasic timestampsBi-temporal tracking
Query LatencySeconds to tens of secondsSub-second
Custom TypesNoYes, via Pydantic models

​
Real-Time Incremental Updates

One of Graphiti’s key advantages is real-time processing: 
# Add new information instantly
result = await graphiti.add_episode(
    name="Latest News",
    episode_body="Kamala Harris became Vice President in January 2021.",
    reference_time=datetime(2021, 1, 20, tzinfo=timezone.utc),
)

# Graphiti automatically:
# 1. Recognizes "Kamala Harris" as an existing entity
# 2. Creates a new relationship for the VP role
# 3. Invalidates the Attorney General edge (expired_at = 2021-01-20)
# 4. Makes the new information immediately searchable
Graphiti’s incremental updates make it ideal for AI agents that need to maintain accurate, up-to-date knowledge without costly batch reprocessing.
Graphiti combines three search methods for comprehensive retrieval:
  1. Semantic search: Vector similarity on embedded facts and entity names
  2. Keyword search: BM25 full-text search for precise term matching
  3. Graph traversal: Navigate relationships to find connected information
# Hybrid search example
results = await graphiti.search(
    "Who was California's Attorney General before becoming VP?",
    center_node_uuid=kamala_node.uuid,  # Focus on related entities
    num_results=10
)

​
Group IDs for Multi-Tenancy

Graphiti supports partitioning graphs by group_id, enabling:
  • Multi-user applications: Separate knowledge graphs per user
  • Organizational hierarchies: Team-level or project-level graphs
  • Access control: Query only the groups a user has permission for
# Add episode to a specific group
await graphiti.add_episode(
    name="User Message",
    episode_body="Alice started working on Project Phoenix",
    group_id="user_123",
    reference_time=datetime.now(timezone.utc),
)

# Search within a group
results = await graphiti.search(
    "What is Alice working on?",
    group_ids=["user_123"]
)

​
Next Steps

Temporal Model

Learn about Graphiti’s bi-temporal data model

Episodes

Understand episodes as units of information

Nodes and Edges

Explore the graph schema in detail

Communities

Discover community detection for topic clustering

Build docs developers (and LLMs) love

Get started for freeTalk to us