AI Agent의 Long Term Memory는 사용자와의 상호작용을 기억하고 학습하는 핵심 요소입니다. 하지만 기존의 RAG(Retrieval-Augmented Generation) 방식은 변화하는 정보를 효과적으로 처리하기 어려웠습니다. Graphiti는 이러한 문제를 해결하기 위해 탄생한 시간 인식(Temporal-Aware) 지식 그래프 프레임워크입니다.
Graphiti는 Zep의 컨텍스트 엔지니어링 플랫폼의 핵심을 구성하며, State of the Art 수준의 Agent Memory를 제공합니다. 특히 Microsoft의 GraphRAG와 달리, 실시간으로 변화하는 데이터를 효과적으로 처리할 수 있도록 설계되었습니다.
Graphiti란?
Graphiti는 동적으로 진화하는 지식 그래프를 구축하고 쿼리할 수 있는 오픈소스 프레임워크입니다. 지식 그래프는 “Kendra는 Adidas 신발을 좋아한다”와 같은 사실들의 네트워크로, 두 개의 엔티티(노드)와 그들 간의 관계(엣지)로 구성된 “triplet” 형태로 표현됩니다.
Graphiti의 핵심 특징
1. 시간 인식 (Temporal Awareness)
- 사실과 관계의 변화를 시간에 따라 추적
- 그래프 엣지에 시간 메타데이터 포함
- 특정 시점의 상태를 정확하게 쿼리 가능
2. 에피소드 처리 (Episodic Processing)
- 데이터를 개별 에피소드로 수집
- 데이터 출처 유지
- 점진적 엔티티 및 관계 추출 지원
3. 하이브리드 검색 (Hybrid Search)
- 시맨틱 검색과 BM25 전체 텍스트 검색 결합
- 중심 노드로부터의 거리로 결과 재정렬
- 서브 세컨드 수준의 빠른 쿼리 성능
4. 커스텀 엔티티 타입
- Pydantic 모델을 통한 도메인별 엔티티 정의
- 유연한 온톨로지 생성
- 특수 사용 사례에 맞춘 지식 표현
5. 확장성 (Scalability)
- 대규모 데이터셋을 위한 병렬 처리
- 이벤트 연대기 유지
- 기업 환경에 적합한 효율적 관리
Graphiti vs. GraphRAG 비교
| 측면 | GraphRAG | Graphiti |
|---|---|---|
| 주요 용도 | 정적 문서 요약 | 동적 데이터 관리 |
| 데이터 처리 | 배치 지향 처리 | 연속적, 점진적 업데이트 |
| 지식 구조 | 엔티티 클러스터 & 커뮤니티 요약 | 에피소드 데이터, 시맨틱 엔티티, 커뮤니티 |
| 검색 방법 | 순차적 LLM 요약 | 하이브리드 시맨틱, 키워드, 그래프 기반 검색 |
| 시간 처리 | 기본 타임스탬프 추적 | 명시적 양방향 시간 추적 |
| 모순 처리 | LLM 기반 요약 판단 | 시간적 엣지 무효화 |
| 쿼리 지연시간 | 수초~수십초 | 일반적으로 서브 세컨드 |
| 커스텀 엔티티 | 지원 안함 | 지원 |
| 확장성 | 중간 | 높음 |
설치 환경
시스템 요구사항
필수 사항:
- Python 3.10 이상
- 데이터베이스 (다음 중 하나):
- Neo4j 5.26 이상
- FalkorDB 1.1.2 (Redis 기반)
- Kuzu 0.11.2
- Amazon Neptune Database 또는 Neptune Analytics Graph
- OpenAI API 키 (또는 다른 LLM 제공자)
선택 사항:
- Google Gemini, Anthropic, Groq API 키 (대체 LLM 제공자)
Neo4j 설치
가장 간단한 방법은 Neo4j Desktop을 사용하는 것입니다:
- Neo4j Desktop 다운로드
- 사용자 친화적 인터페이스로 Neo4j 인스턴스 관리
FalkorDB 빠른 시작
Docker로 즉시 시작 가능:
docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest
설치 방법
기본 설치
pip install graphiti-core
또는 uv 사용:
uv add graphiti-core
데이터베이스별 설치
FalkorDB 사용:
pip install graphiti-core[falkordb]
# 또는
uv add graphiti-core[falkordb]
Kuzu 사용:
pip install graphiti-core[kuzu]
# 또는
uv add graphiti-core[kuzu]
Amazon Neptune 사용:
pip install graphiti-core[neptune] # 또는 uv add graphiti-core[neptune]
LLM 제공자별 설치
# Anthropic 지원 pip install graphiti-core[anthropic] # Groq 지원 pip install graphiti-core[groq] # Google Gemini 지원 pip install graphiti-core[google-genai] # 여러 제공자 동시 설치 pip install graphiti-core[anthropic,groq,google-genai] # FalkorDB와 LLM 제공자 함께 설치 pip install graphiti-core[falkordb,anthropic,google-genai]
사용 방법
기본 사용법
from graphiti_core import Graphiti
from datetime import datetime
# Graphiti 초기화 (Neo4j 사용)
graphiti = Graphiti(
uri="bolt://localhost:7687",
user="neo4j",
password="your_password"
)
# 인덱스 및 제약조건 초기화
await graphiti.build_indices_and_constraints()
# 에피소드 추가
episode_text = """
John met Sarah at the conference in San Francisco.
They discussed AI and machine learning for two hours.
"""
await graphiti.add_episode(
name="Conference Meeting",
episode_body=episode_text,
source_description="User conversation",
reference_time=datetime.now()
)
# 검색 수행
results = await graphiti.search(
query="Who did John meet?",
num_results=5
)
for result in results:
print(f"Score: {result.score}")
print(f"Fact: {result.fact}")
Azure OpenAI 사용
from openai import AsyncOpenAI
from graphiti_core import Graphiti
from graphiti_core.llm_client.azure_openai_client import AzureOpenAILLMClient
from graphiti_core.llm_client.config import LLMConfig
from graphiti_core.embedder.azure_openai import AzureOpenAIEmbedderClient
# Azure OpenAI 클라이언트 초기화
azure_client = AsyncOpenAI(
base_url="https://your-resource-name.openai.azure.com/openai/v1/",
api_key="your-api-key",
)
# LLM 및 Embedder 클라이언트 생성
llm_client = AzureOpenAILLMClient(
azure_client=azure_client,
config=LLMConfig(model="gpt-4o-mini", small_model="gpt-4o-mini")
)
embedder_client = AzureOpenAIEmbedderClient(
azure_client=azure_client,
model="text-embedding-3-small"
)
# Graphiti 초기화
graphiti = Graphiti(
"bolt://localhost:7687",
"neo4j",
"password",
llm_client=llm_client,
embedder=embedder_client,
)
Google Gemini 사용
from graphiti_core import Graphiti
from graphiti_core.llm_client.gemini_client import GeminiClient, LLMConfig
from graphiti_core.embedder.gemini import GeminiEmbedder, GeminiEmbedderConfig
# Gemini 클라이언트로 Graphiti 초기화
graphiti = Graphiti(
"bolt://localhost:7687",
"neo4j",
"password",
llm_client=GeminiClient(
config=LLMConfig(
api_key="your-google-api-key",
model="gemini-2.0-flash"
)
),
embedder=GeminiEmbedder(
config=GeminiEmbedderConfig(
api_key="your-google-api-key",
embedding_model="embedding-001"
)
)
)
Ollama (로컬 LLM) 사용
from graphiti_core import Graphiti
from graphiti_core.llm_client.config import LLMConfig
from graphiti_core.llm_client.openai_generic_client import OpenAIGenericClient
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
# Ollama LLM 설정
llm_config = LLMConfig(
api_key="ollama",
model="deepseek-r1:7b",
small_model="deepseek-r1:7b",
base_url="http://localhost:11434/v1",
)
llm_client = OpenAIGenericClient(config=llm_config)
# Graphiti 초기화
graphiti = Graphiti(
"bolt://localhost:7687",
"neo4j",
"password",
llm_client=llm_client,
embedder=OpenAIEmbedder(
config=OpenAIEmbedderConfig(
api_key="ollama",
embedding_model="nomic-embed-text",
embedding_dim=768,
base_url="http://localhost:11434/v1",
)
)
)
다양한 데이터베이스 사용
FalkorDB:
from graphiti_core.driver.falkordb_driver import FalkorDriver
driver = FalkorDriver(
host="localhost",
port=6379,
username="falkor_user",
password="falkor_password",
database="my_custom_graph"
)
graphiti = Graphiti(graph_driver=driver)
Kuzu:
from graphiti_core.driver.kuzu_driver import KuzuDriver
driver = KuzuDriver(db="/tmp/graphiti.kuzu")
graphiti = Graphiti(graph_driver=driver)
Amazon Neptune:
from graphiti_core.driver.neptune_driver import NeptuneDriver
driver = NeptuneDriver(
host="<NEPTUNE_ENDPOINT>",
aoss_host="<OPENSEARCH_HOST>",
port=8182,
aoss_port=443
)
graphiti = Graphiti(graph_driver=driver)
MCP Server 활용 방법
MCP(Model Context Protocol) Server는 Graphiti의 지식 그래프 기능을 Claude Desktop, Cursor, VS Code 등의 AI 어시스턴트에 연결할 수 있게 해주는 실험적 구현체입니다.
MCP Server 주요 기능
- 에피소드 관리: 텍스트, 메시지, JSON 데이터 추가/조회/삭제
- 엔티티 관리: 엔티티 노드 및 관계 검색/관리
- 검색 기능: 사실 및 노드 요약에 대한 시맨틱 및 하이브리드 검색
- 그룹 관리: group_id를 통한 멀티 사용자 시나리오 데이터 조직화
- 그래프 유지보수: 그래프 초기화 및 인덱스 재구축
MCP Server 설치 및 실행
1. 저장소 클론:
git clone https://github.com/getzep/graphiti.git
cd graphiti/mcp_server
2. 의존성 설치:
uv sync
3. 환경 변수 설정 (.env 파일):
# LLM 설정 OPENAI_API_KEY=your_openai_api_key MODEL_NAME=gpt-4o-mini # 데이터베이스 설정 (Neo4j 예시) NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=your_neo4j_password # 텔레메트리 비활성화 (선택사항) GRAPHITI_TELEMETRY_ENABLED=false
4. 서버 실행:
# 기본 실행
uv run graphiti_mcp_server.py
# 커스텀 옵션으로 실행
uv run graphiti_mcp_server.py --model gpt-4o-mini --transport sse --group-id my-project
Claude Desktop 연결
Claude Desktop 설정 파일에 다음 내용 추가:
{
"mcpServers": {
"graphiti-context": {
"transport": "stdio",
"command": "/path/to/uv",
"args": [
"run",
"--directory",
"/path/to/graphiti/mcp_server",
"graphiti_mcp_server.py",
"--transport",
"stdio"
],
"env": {
"OPENAI_API_KEY": "your_api_key",
"MODEL_NAME": "gpt-4o-mini",
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USER": "neo4j",
"NEO4J_PASSWORD": "your_password"
}
}
}
}
Cursor IDE 연결
SSE 전송 방식 사용:
{
"mcpServers": {
"graphiti-context": {
"url": "http://localhost:8000/sse"
}
}
}
사용 가능한 MCP 도구
AI 어시스턴트에서 사용할 수 있는 도구들:
add_episode: 지식 그래프에 에피소드 및 상호작용 저장search_facts: 관련 사실 및 관계 검색search_nodes: 엔티티 요약 및 정보 검색get_episodes: 컨텍스트를 위한 최근 에피소드 검색delete_episode: 그래프에서 에피소드 제거clear_graph: 지식 그래프 완전 초기화
Docker로 MCP 서버 배포
# Docker Compose로 실행 (데이터베이스 + MCP 서버)
docker compose up
기존 LTM과의 차이점
1. 시간 추적 능력
기존 방식:
- 단순 타임스탬프 기록
- 변경 이력 추적 어려움
- 과거 시점 쿼리 불가능
Graphiti:
- 양방향 시간 추적 (발생 시간 + 기록 시간)
- 관계의 생명주기 명시적 추적
- 특정 시점의 정확한 상태 쿼리 가능
2. 데이터 처리 방식
기존 방식:
- 배치 처리 중심
- 전체 재계산 필요
- 실시간 업데이트 어려움
Graphiti:
- 점진적 업데이트
- 에피소드 단위 처리
- 실시간 데이터 통합
3. 검색 성능
기존 방식:
- LLM 기반 순차 요약
- 수초~수십초 소요
- 확장성 제한
Graphiti:
- 하이브리드 검색 (시맨틱 + 키워드 + 그래프)
- 서브 세컨드 응답
- 대규모 데이터셋 효율적 처리
4. 모순 처리
기존 방식:
- LLM 판단에 의존
- 일관성 유지 어려움
Graphiti:
- 시간적 엣지 무효화
- 자동 모순 해결
- 변경 이력 완전 보존
5. 커스터마이징
기존 방식:
- 고정된 스키마
- 도메인 특화 어려움
Graphiti:
- Pydantic 모델 기반 커스텀 엔티티
- 유연한 온톨로지
- 도메인별 최적화 가능
성능 최적화
동시성 제어
Graphiti는 높은 동시성을 위해 설계되었지만, LLM 제공자의 rate limit을 고려하여 기본값은 낮게 설정되어 있습니다.
# 환경 변수로 동시성 조절 (기본값: 10)
export SEMAPHORE_LIMIT=20
텔레메트리
Graphiti는 개선을 위해 익명 사용 통계를 수집합니다 (개인정보는 수집하지 않음).
비활성화 방법:
export GRAPHITI_TELEMETRY_ENABLED=false
수집 정보:
- 익명 식별자 (로컬 저장)
- 시스템 정보 (OS, Python 버전)
- Graphiti 버전
- 설정 선택 (LLM 제공자, 데이터베이스 등)
수집하지 않는 정보:
- 개인 정보
- API 키
- 실제 데이터, 쿼리, 그래프 내용
- IP 주소
실전 활용 예제
1. 고객 상호작용 추적
# 고객과의 대화 기록
await graphiti.add_episode(
name="Customer Support Call",
episode_body="""
Customer John reported a billing issue.
Account was charged twice for subscription.
Issue resolved with refund processed.
""",
source_description="Support ticket #12345",
reference_time=datetime.now()
)
# 고객 이력 검색
history = await graphiti.search(
query="What issues did John report?",
num_results=10
)
2. 프로젝트 관리
# 프로젝트 마일스톤 기록
await graphiti.add_episode(
name="Project Update",
episode_body="""
Project Alpha moved to testing phase.
Lead developer Sarah completed core features.
Expected launch date: March 2024.
""",
source_description="Project management system",
reference_time=datetime.now()
)
# 프로젝트 상태 조회
status = await graphiti.search(
query="What is the current status of Project Alpha?",
num_results=5
)
3. 개인 비서 AI
# 사용자 선호도 학습
await graphiti.add_episode(
name="User Preferences",
episode_body="""
User prefers morning meetings before 10 AM.
Likes Italian food for business lunches.
Allergic to seafood.
""",
source_description="User profile",
reference_time=datetime.now()
)
# 선호도 기반 추천
recommendations = await graphiti.search(
query="What type of restaurant should I book for lunch?",
num_results=3
)
문서 및 리소스
- 공식 문서: https://help.getzep.com/graphiti
- GitHub 저장소: https://github.com/getzep/graphiti
- 빠른 시작 가이드: Quick Start 문서
- LangGraph Agent 통합: LangGraph 통합 가이드
- Discord 커뮤니티: Zep Discord #Graphiti 채널
라이선스 및 지원
Graphiti는 Apache-2.0 라이선스로 배포되는 오픈소스 프로젝트입니다. 커뮤니티 기여를 환영하며, 버그 리포트, 기능 요청, 코드 기여 등 모든 형태의 참여를 장려합니다.
결론
Graphiti는 AI Agent의 Long Term Memory를 위한 메모리 레이어에 대한 또하나의 대안입니다. 시간 인식 지식 그래프를 통해 변화하는 정보를 효과적으로 관리하고, 하이브리드 검색으로 빠르고 정확한 검색을 제공하며, 유연한 커스터마이징으로 다양한 도메인에 적용할 수 있습니다.
LTM를 오픈소스 레벨에서 다뤄보고 싶다면 Graphiti를 활용해보시기 바랍니다.
답글 남기기