Graphiti

Graphiti

AI エージェントのためのリアルタイム知識グラフを構築

:star: より多くの開発者に知ってもらい、Graphiti コミュニティを成長させるため、ご協力ください。このリポジトリにスターを付けてください！

ヒント

Graphiti 用の新しい MCP サーバーをご覧ください！Claude、Cursor、その他の MCP クライアントに、ナレッジグラフを活用した強力なメモリを提供します。

Graphiti は、動的な環境で動作する AI エージェントに特化した、時間的な変化を考慮した知識グラフを構築・検索するためのフレームワークです。従来の検索拡張生成（RAG）手法とは異なり、Graphiti はユーザーとのやり取り、構造化・非構造化の企業データ、外部情報を、一貫性のある検索可能なグラフに継続的に統合します。このフレームワークは、グラフ全体を再計算することなく、段階的なデータ更新、効率的な検索、正確な履歴検索に対応しており、対話型でコンテキストを認識する AI アプリケーションの開発に適しています。

Graphiti は次の用途に活用できます。

• 動的なユーザーとのやり取りやビジネスデータを統合し、維持します。
• エージェントの状態に基づく推論やタスクの自動化を支援します。
• セマンティック検索、キーワード検索、グラフベースの検索手法を使って、複雑に変化するデータを検索します。

知識グラフとは、「ケンドラはアディダスの靴が好き」のような、相互につながった事実のネットワークです。それぞれの事実は「トリプレット」であり、2 つのエンティティ（ノード）である「ケンドラ」と「アディダスの靴」、そしてそれらの関係（エッジ）である「好き」で表されます。知識グラフは、情報検索の分野で広く研究されてきました。Graphiti の独自性は、変化する関係に対応し、履歴のコンテキストを維持しながら、自律的に知識グラフを構築できる点にあります。

Graphiti と Zep Memory

Graphiti は、AI エージェント向けのZep のメモリレイヤーの中核を担っています。

Graphiti を活用することで、Zep がエージェントメモリの最先端であることを実証しました。

論文：Zep: エージェントメモリのための時間的知識グラフアーキテクチャをお読みください。

Graphiti のオープンソース化を実現でき、AI メモリアプリケーションにとどまらない可能性を秘めていると考えています。

## Graphiti を使う理由

従来の RAG アプローチは、バッチ処理や静的なデータ要約に依存することが多く、頻繁に変化するデータには非効率です。Graphiti は、以下を提供してこうした課題に対応します。

• リアルタイムの増分更新： バッチで再計算することなく、新しいエピソードデータを即座に統合します。
• バイテンポラルデータモデル： イベントの発生時刻と取り込み時刻を明示的に追跡し、特定の時点における正確なクエリを可能にします。
• 効率的なハイブリッド検索： セマンティック埋め込み、キーワード（BM25）、グラフ走査を組み合わせ、LLM による要約に依存せず、低レイテンシーのクエリを実現します。
• カスタムエンティティ定義： 柔軟なオントロジーの作成に対応し、シンプルな Pydantic モデルで開発者定義のエンティティをサポートします。
• スケーラビリティ： 並列処理で大規模なデータセットを効率的に管理できるため、エンタープライズ環境に適しています。

Graphiti と GraphRAG の比較

項目	GraphRAG	Graphiti
主な用途	静的なドキュメントの要約	動的なデータ管理
データの処理方法	バッチ指向の処理	継続的な増分更新
ナレッジ構造	エンティティクラスターとコミュニティ要約	エピソードデータ、セマンティックエンティティ、コミュニティ
検索方法	順次的な LLM 要約	セマンティック、キーワード、グラフベースのハイブリッド検索
適応性	低	高
時間情報の扱い	基本的なタイムスタンプ追跡	明示的なバイテンポラル追跡
矛盾の処理	LLM による要約判断	時間エッジの無効化
クエリのレイテンシー	数秒から数十秒	通常は 1 秒未満
カスタムエンティティタイプ	なし	あり、カスタマイズ可能
スケーラビリティ	中程度	高、大規模なデータセット向けに最適化

Graphiti は、動的かつ頻繁に更新されるデータセットの課題に対応するために特化して設計されており、リアルタイムのやり取りや正確な過去時点のクエリが求められるアプリケーションに特に適しています。

インストール

要件：

• Python 3.10 以降
• Neo4j 5.26 以降（埋め込みのストレージバックエンドとして使用）
• OpenAI API キー（LLM の推論と埋め込みに使用）

重要

Graphiti は、Structured Output に対応する LLM サービス（OpenAI や Gemini など）で最もよく動作します。 ほかのサービスを使用すると、出力スキーマが正しくならず、取り込みに失敗する場合があります。特に、 小規模なモデルを使用する場合に問題となります。

オプション：

• Google Gemini、Anthropic、または Groq の API キー（代替 LLM プロバイダーに使用）

ヒント

Neo4j を最も簡単にインストールする方法は、Neo4j Desktop を利用することです。Neo4j インスタンスとデータベースを管理するための、使いやすい インターフェースが提供されています。

pip install graphiti-core

または

poetry add graphiti-core

オプションの LLM プロバイダーは、追加機能としてインストールすることもできます。

# Install with Anthropic support
pip install graphiti-core[anthropic]

# Install with Groq support
pip install graphiti-core[groq]

# Install with Google Gemini support
pip install graphiti-core[google-genai]

# Install with multiple providers
pip install graphiti-core[anthropic,groq,google-genai]

クイックスタート

重要

Graphiti は LLM 推論と埋め込みに OpenAI を使用します。環境に OPENAI_API_KEY が設定されていることを確認してください。 Anthropic と Groq による LLM 推論にも対応しています。また、OpenAI 互換 API を介して、その他の LLM プロバイダーも利用できる場合があります。

完全に動作するサンプルについては、examples ディレクトリのクイックスタートの例を参照してください。クイックスタートでは、次の内容を紹介しています。

1. Neo4j データベースへの接続
2. Graphiti のインデックスと制約の初期化
3. エピソードのグラフへの追加（テキストと構造化 JSON の両方）
4. ハイブリッド検索による関係（エッジ）の検索
5. グラフ距離を使用した検索結果の再ランク付け
6. 定義済みの検索レシピを使用したノードの検索

この例では各機能についてわかりやすく説明しており、セットアップ手順と次のステップを記載した包括的な README も含まれています。

MCP サーバー

mcp_server ディレクトリには、Graphiti 用の Model Context Protocol（MCP）サーバー実装が含まれています。このサーバーを使うと、AI アシスタントは MCP プロトコルを通じて Graphiti のナレッジグラフ機能を利用できます。

MCP サーバーの主な機能は次のとおりです。

• エピソード管理（追加、取得、削除）
• エンティティ管理と関係の処理
• セマンティック検索およびハイブリッド検索機能
• 関連データを整理するためのグループ管理
• グラフの保守操作

MCP サーバーは Neo4j とともに Docker を使ってデプロイできるため、Graphiti を AI アシスタントのワークフローに簡単に統合できます。

詳しいセットアップ手順と使用例については、MCP サーバーの READMEを参照してください。

REST サービス

server ディレクトリには、Graphiti API とやり取りするための API サービスが含まれています。FastAPI を使用して構築されています。

詳しくは、サーバーの READMEを参照してください。

任意の環境変数

Neo4j と OpenAi 互換の認証情報に加えて、Graphiti にはいくつかの任意の環境変数もあります。 Anthropic や Voyage のモデルなど、サポート対象のモデルを使用する場合は、必要な環境変数を 設定する必要があります。

USE_PARALLEL_RUNTIME は任意のブール型変数です。検索クエリの一部で Neo4j の並列ランタイム機能を有効にする場合は、true に設定できます。 この機能は Neo4j Community エディションおよび小規模な AuraDB インスタンスではサポートされていないため、 デフォルトでは無効になっています。

Azure OpenAI で Graphiti を使用する

Graphiti は LLM 推論と埋め込みの両方で Azure OpenAI をサポートしています。Azure OpenAI を使用するには、Azure OpenAI の認証情報を使って LLM クライアントと埋め込みモデルの両方を設定する必要があります。

from openai import AsyncAzureOpenAI
from graphiti_core import Graphiti
from graphiti_core.llm_client import OpenAIClient
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient

# Azure OpenAI configuration
api_key = "<your-api-key>"
api_version = "<your-api-version>"
azure_endpoint = "<your-azure-endpoint>"

# Create Azure OpenAI client for LLM
azure_openai_client = AsyncAzureOpenAI(
    api_key=api_key,
    api_version=api_version,
    azure_endpoint=azure_endpoint
)

# Initialize Graphiti with Azure OpenAI clients
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=OpenAIClient(
        client=azure_openai_client
    ),
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            embedding_model="text-embedding-3-small"  # Use your Azure deployed embedding model name
        ),
        client=azure_openai_client
    ),
    # Optional: Configure the OpenAI cross encoder with Azure OpenAI
    cross_encoder=OpenAIRerankerClient(
        client=azure_openai_client
    )
)

# Now you can use Graphiti with Azure OpenAI

プレースホルダーの値を実際の Azure OpenAI 認証情報に置き換え、Azure OpenAI サービスにデプロイされている正しい埋め込みモデル名を指定してください。

Google Gemini で Graphiti を使用する

Graphiti は LLM 推論と埋め込みの両方で Google の Gemini モデルをサポートしています。Gemini を使用するには、Google API キーを使って LLM クライアントと埋め込みモデルの両方を設定する必要があります。

Graphiti をインストールします。

poetry add "graphiti-core[google-genai]"

# or

uv add "graphiti-core[google-genai]"

from graphiti_core import Graphiti
from graphiti_core.llm_client.gemini_client import GeminiClient, LLMConfig
from graphiti_core.embedder.gemini import GeminiEmbedder, GeminiEmbedderConfig

# Google API key configuration
api_key = "<your-google-api-key>"

# Initialize Graphiti with Gemini clients
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=GeminiClient(
        config=LLMConfig(
            api_key=api_key,
            model="gemini-2.0-flash"
        )
    ),
    embedder=GeminiEmbedder(
        config=GeminiEmbedderConfig(
            api_key=api_key,
            embedding_model="embedding-001"
        )
    )
)

# Now you can use Graphiti with Google Gemini

ドキュメント

• ガイドと API ドキュメント。
• クイックスタート
• LangChain の LangGraph と Graphiti を使ったエージェントの構築

ステータスとロードマップ

Graphiti は現在も活発に開発されています。次の取り組みを進めながら、API の安定性を維持することを目指しています。

• カスタムグラフスキーマのサポート：
  • エピソードの取り込み時に、開発者が独自に定義したノードクラスとエッジクラスを指定できるようにする
  • 特定のユースケースに合わせた、より柔軟なナレッジ表現を可能にする
• より堅牢で設定可能なオプションによる検索機能の強化
• Graphiti MCP サーバー
• 信頼性を確保し、エッジケースを検出するためのテストカバレッジの拡充

貢献

コード、ドキュメント、GitHub Issues への対応、Graphiti Discord チャンネルでの質問への回答など、あらゆる形での貢献を歓迎し、感謝しています。コードへの貢献に関する詳しいガイドラインについては、CONTRIBUTING をご覧ください。

サポート

Zep Discord サーバーに参加し、#Graphiti チャンネルにお越しください！