Graphiti: A Framework for Building and Querying Real-Time Knowledge Graphs 167

What is Graphiti?

Graphiti is a framework for building and querying knowledge graphs with time-aware capabilities, making it ideal for dynamic environments. Unlike traditional Retrieval-Augmented Generation (RAG) methods, Graphiti can integrate user interactions, structured and unstructured data, and external information in real time to generate a queryable graph. Its advantages lie in supporting real-time data updates, efficient retrieval, and accurate historical queries without the need to recompute the entire graph, making it well-suited for developing interactive, context-aware applications.

Key Features of Graphiti

• Real-Time Incremental Updates: Capable of integrating new data fragments immediately without the need for batch recomputation.

• Dual Temporal Data Model: Explicitly tracks event occurrence time and ingestion time, supporting precise point-in-time queries.

• Efficient Hybrid Retrieval: Combines semantic embeddings, keyword search (BM25), and graph traversal to achieve low-latency queries without relying on large language models (LLMs) for summarization.

• Custom Entity Definition: Supports the creation of flexible ontologies and custom entities through simple Pydantic models.

• Scalability: Effectively manages large datasets through parallel processing, suitable for enterprise environments.

• Integration with Multiple LLMs: Supports LLM providers such as Openai, Anthropic, and Groq, offering flexible LLM inference and embedding options.

• MCP Server: Provides a FastAPI-based API service that supports interaction with the knowledge graph via the MCP protocol, including features for event management, entity management, and relationship handling.
  

Why Choose Graphiti

• It can update data in real time, adapting to dynamically changing environments.

• Supports precise point-in-time queries, making it convenient to trace historical information.

• Fast retrieval speed, without relying on complex language models.

• Customizable data structures to meet specific needs.

• Efficiently handles large volumes of data, suitable for enterprise-level applications.

Installation and Usage of Graphiti

Installing Graphiti

First, ensure your system meets the installation requirements and install the necessary dependencies:

• Python: Make sure your system has Python 3.10 or higher installed.

• Neo4j: Install the Neo4j database, version 5.26 or higher. You can use Neo4j Desktop to simplify the installation and management process.

• OpenAI API Key: If you plan to use OpenAI for LLM inference and embeddings, you will need a valid OpenAI API Key.

You can use pip or poetry to install the Graphiti core library:

pip install graphiti-core
# 或者
poetry add graphiti-core

Initializing Graphiti

Initialize a Graphiti instance in your code and connect to the Neo4j database:

from graphiti_core import Graphiti
graphiti = Graphiti("bolt://localhost:7687", "neo4j", "password")

Building Indices and Constraints

Before adding data, initialize the graph database and build Graphiti's indices and constraints:

await graphiti.build_indices_and_constraints()

Adding Data

Use the add_episode method to add data to the knowledge graph. Each data fragment is called an "episode":

from graphiti_core.nodes import EpisodeType
from datetime import datetime, timezone
episodes = [
"Kamala Harris is the Attorney General of California. She was previously the district attorney for San Francisco.",
"As AG, Harris was in office from January 3, 2011 – January 3, 2017"
]
for i, episode in enumerate(episodes):
await graphiti.add_episode(
name=f"Freakonomics Radio {i}",
episode_body=episode,
source=EpisodeType.text,
source_description="podcast",
reference_time=datetime.now(timezone.utc)
)

Querying Data

Use the search method to query the knowledge graph, combining semantic similarity and keyword search:

results = await graphiti.search('Who was the California Attorney General?')

Custom Queries

You can customize queries as needed, for example, by specifying a center node to prioritize results closer to that node:

await graphiti.search('Who was the California Attorney General?', center_node_uuid)

Closing the Connection

After completing the chat state management, close the Graphiti connection:

graphiti.close()

Using the MCP Server

Graphiti provides an MCP server that can be interacted with through FastAPI. You can deploy this server and use the MCP protocol to interact with the knowledge graph:

1. Clone or download the Graphiti repository.

2. Run the MCP server:

uvicorn graphiti.mcp_server.main:app --reload

3. Use the MCP protocol in your AI assistant to communicate with the server.

Using Azure OpenAI

If you want to use Azure OpenAI, you need to configure the corresponding client and embedder:

from openai import AsyncAzureOpenAI
from graphiti_core import Graphiti
from graphiti_core.llm_client import OpenAIClient
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
api_key = "<your-api-key>"
api_version = "<your-api-version>"
azure_endpoint = "<your-azure-endpoint>"
azure_openai_client = AsyncAzureOpenAI(api_key=api_key, api_version=api_version, azure_endpoint=azure_endpoint)
graphiti = Graphiti(
"bolt://localhost:7687",
"neo4j",
"password",
llm_client=OpenAIClient(client=azure_openai_client),
embedder=OpenAIEmbedder(config=OpenAIEmbedderConfig(embedding_model="text-embedding-3-small"), client=azure_openai_client)
)

Make sure to replace the placeholder values with your actual Azure OpenAI credentials and specify the correct embedding model name.

Advantages of Graphiti

• Compared to other technologies, Graphiti has clear advantages in handling dynamic data, real-time updates, and query speed.

• Provides server implementation for easy integration with other systems.

• Supports multiple environment configurations and integration with other services.

Related Links

Paper: https://arxiv.org/abs/2501.13956

GitHub Repository: https://github.com/getzep/graphiti