Graphiti - 에이전트용 시간 지식 그래프 치트시트

Graphiti - 에이전트용 시간 지식 그래프 치트시트

Graphiti (by Zep)는 AI 에이전트를 위해 시간 지식 그래프를 구축하고 쿼리하기 위한 오픈소스 프레임워크입니다. 정적 그래프와 달리, Graphiti는 사실이 시간에 따라 어떻게 변하는지 추적합니다. 각 엣지는 유효성 간격을 수반하므로 그래프는 단순히 무엇이 참인지뿐만 아니라 언제 참이었는지를 알고, 전파를 보존합니다. 데이터를 증분적으로 수집합니다(에피소드는 전체 그래프 재계산 없이 추가됨). 이는 진화하는 사실에 대해 추론해야 하는 메모리에 이상적입니다.

요구사항

• 그래프 데이터베이스: Neo4j 또는 FalkorDB
• LLM 제공자 (OpenAI, Anthropic 등) 엔티티/관계 추출용
• Python 3.10+

설치

방법	명령어
pip	pip install graphiti-core
FalkorDB 포함	pip install "graphiti-core[falkordb]"
키 설정	export OPENAI_API_KEY=... 및 그래프 DB 환경 변수
검증	python -c "import graphiti_core; print('ok')"

핵심 개념

용어	의미
Episode	수집된 데이터의 단위 (메시지, 텍스트, JSON)
Node	에피소드에서 추출된 엔티티
Edge (fact)	유효성 시간 (valid_at/invalid_at)을 갖는 관계
Bi-temporal	이벤트 시간과 수집 시간 모두 추적
Community	관련 엔티티의 클러스터

초기화 및 에피소드 추가

from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType
import asyncio

async def main():
    graphiti = Graphiti("bolt://localhost:7687", "neo4j", "password")
    await graphiti.build_indices_and_constraints()

    await graphiti.add_episode(
        name="msg1",
        episode_body="Nick joined Acme as CTO in 2024.",
        source=EpisodeType.text,
        reference_time=datetime.now(),
        source_description="chat",
    )

asyncio.run(main())

호출	설명
Graphiti(uri, user, pass)	그래프 DB에 연결
build_indices_and_constraints()	일회성 스키마 설정
add_episode(...)	데이터 수집; 엔티티/엣지 자동 추출
add_episode_bulk(...)	배치 수집

메모리 검색

# 하이브리드 검색: 시맨틱 + BM25 + 그래프, 재정렬
results = await graphiti.search("Where does Nick work?")
for r in results:
    print(r.fact, r.valid_at)

검색	동작
search(query)	하이브리드 (시맨틱 + 키워드 + 그래프) 엣지 검색
Node search	엔티티 검색
Reranking	RRF / 그래프 거리 / 크로스 인코더 옵션
Center node	특정 엔티티 주변 결과 편향

시간 추론

차이점: 사실이 변하면, Graphiti는 이전 사실을 삭제하지 않습니다. 이전 엣지를 무효로 표시하고 새 사실을 기록하여 히스토리가 보존됩니다.

기능	사용
사실 무효화	모순되면 이전 사실이 invalid_at으로 설정
시점 쿼리	”날짜 X 기준으로 무엇이 참이었는가?”
전파	사실을 소스 에피소드로 추적
커스텀 엔티티 타입	유형 추출을 위한 Pydantic 모델 정의

통합

대상	방법
Zep	Graphiti는 Zep 메모리 서비스 엔진
에이전트 프레임워크	메모리/검색 도구로 사용
MCP	Graphiti MCP 서버는 에이전트에 메모리 노출
커스텀	컨텍스트를 위해 그래프 직접 쿼리

일반적인 워크플로우

# 변화하는 사실을 견디는 에이전트 메모리
await graphiti.add_episode(name="e1", episode_body="Nick uses Postgres.", ...)
# 나중에 사실이 변함:
await graphiti.add_episode(name="e2", episode_body="Nick migrated to SQLite.", ...)
# Graphiti는 Postgres 사실을 무효화하고 시간 정보와 함께 SQLite를 기록
ctx = await graphiti.search("What database does Nick use now?")

Graphiti vs 다른 메모리 프레임워크

측면	Graphiti	Cognee	Mem0
핵심 강점	시간/양시간 사실	그래프 네이티브 ECL	개인화
히스토리	유효성 시간으로 보존	그래프 스냅샷	최근 중심
백엔드	Neo4j / FalkorDB	다중 저장소	벡터/그래프/KV
최고의 용도	시간에 따라 변하는 사실	로컬 그래프 추론	대화 메모리

리소스

• GitHub Repository
• Official Documentation
• Zep (managed service)