graphiti

KO | EN

gitlite — search

#react #typescript #llm #golang #machine-learning #linux #docker #macos #windows #cli #kubernetes #security #mcp #open-source

(★ 30,164)

AI 에이전트를 위한 실시간 지식 그래프 구축

파일 탐색기

최종 버전 다운로드 (.zip)

- - bug_report.md
- - setup-triage-labels.sh
- - ai-moderator.yml
  - cla.yml
  - codeql.yml
  - lint.yml
  - mcp-server-tests.yml
  - release-graphiti-core.yml
  - release-mcp-server.yml
  - release-server-container.yml
  - server-tests.yml
  - socket-firewall-connectivity.yml
  - typecheck.yml
  - unit_tests.yml
- dependabot.yml
- pull_request_template.md
- secret_scanning.yml
- - .env.example
  - azure_openai_neo4j.py
  - README.md
- - manybirds_products.json
- - runner.ipynb
  - runner.py
- - .env.example
  - gliner2_neo4j.py
  - README.md
- - agent.ipynb
  - tinybirds-jess.png
- - .env.example
  - otel_stdout_example.py
  - pyproject.toml
  - README.md
  - uv.lock
- - podcast_runner.py
  - podcast_transcript.txt
  - transcript_parser.py
- - dense_vs_normal_ingestion.py
  - quickstart_falkordb.py
  - quickstart_neo4j.py
  - quickstart_neptune.py
  - README.md
  - requirements.txt
- - parser.py
  - runner.py
  - woo.txt
- - __init__.py
  - bge_reranker_client.py
  - client.py
  - gemini_reranker_client.py
  - openai_reranker_client.py
- - __init__.py
  - driver.py
  - falkordb_driver.py
  - kuzu_driver.py
  - neo4j_driver.py
  - neptune_driver.py
  - query_executor.py
  - record_parsers.py
- - __init__.py
  - azure_openai.py
  - client.py
  - gemini.py
  - openai.py
  - voyage.py
- - __init__.py
  - anthropic_client.py
  - azure_openai_client.py
  - cache.py
  - client.py
  - config.py
  - errors.py
  - gemini_client.py
  - gliner2_client.py
  - groq_client.py
  - openai_base_client.py
  - openai_client.py
  - openai_generic_client.py
  - token_tracker.py
  - utils.py
- - __init__.py
- - __init__.py
- - __init__.py
  - edges.py
  - nodes.py
- - __init__.py
  - dedupe_edges.py
  - dedupe_nodes.py
  - eval.py
  - extract_edges.py
  - extract_nodes.py
  - extract_nodes_and_edges.py
  - lib.py
  - models.py
  - prompt_helpers.py
  - snippets.py
  - summarize_nodes.py
  - summarize_sagas.py
- - __init__.py
  - search.py
  - search_config.py
  - search_config_recipes.py
  - search_filters.py
  - search_helpers.py
  - search_utils.py
- - __init__.py
  - telemetry.py
- - __init__.py
  - bulk_utils.py
  - content_chunking.py
  - datetime_utils.py
  - text_utils.py
- __init__.py
- decorators.py
- edges.py
- errors.py
- graph_queries.py
- graphiti.py
- graphiti_types.py
- helpers.py
- nodes.py
- py.typed
- tracer.py
- arxiv-screenshot.png
- graphiti-graph-intro.gif
- graphiti-intro-slides-stock-2.gif
- simple_graph.svg
- - config-docker-falkordb-combined.yaml
  - config-docker-falkordb.yaml
  - config-docker-neo4j.yaml
  - config.yaml
  - mcp_config_stdio_example.json
- - build-standalone.sh
  - build-with-version.sh
  - docker-compose-falkordb.yml
  - docker-compose-neo4j.yml
  - docker-compose.yml
  - Dockerfile
  - Dockerfile.standalone
  - github-actions-example.yml
  - README-falkordb-combined.md
  - README.md
- - cursor_rules.md
- - __init__.py
  - graphiti_mcp_server.py
- - __init__.py
  - conftest.py
  - pytest.ini
  - README.md
  - run_tests.py
  - test_async_operations.py
  - test_comprehensive_integration.py
  - test_configuration.py
  - test_core_parity.py
  - test_cross_encoder_factory.py
  - test_factories.py
  - test_falkordb_config.py
  - test_falkordb_integration.py
  - test_fixtures.py
  - test_http_integration.py
  - test_integration.py
  - test_live_falkordb_int.py
  - test_mcp_integration.py
  - test_mcp_transports.py
  - test_stdio_simple.py
  - test_stress_load.py
- .env.example
- .python-version
- main.py
- pyproject.toml
- pytest.ini
- README.md
- uv.lock
- - __init__.py
  - config.py
  - main.py
  - zep_graphiti.py
- - test_live_falkordb_int.py
- .env.example
- Makefile
- pyproject.toml
- README.md
- uv.lock
- - cla.json
- driver-operations-redesign.md
- - test_bge_reranker_client_int.py
  - test_gemini_reranker_client.py
- - __init__.py
  - test_falkordb_driver.py
  - test_falkordb_ops_routing.py
- - embedder_fixtures.py
  - test_gemini.py
  - test_openai.py
  - test_voyage.py
- - eval_cli.py
  - eval_e2e_graph_building.py
  - pytest.ini
  - utils.py
- - test_anthropic_client.py
  - test_anthropic_client_int.py
  - test_azure_openai_client.py
  - test_cache.py
  - test_client.py
  - test_errors.py
  - test_gemini_client.py
  - test_openai_client.py
  - test_openai_generic_client.py
  - test_token_tracker.py
- - test_concatenate_episodes.py
  - test_content_chunking.py
- helpers_test.py
- test_add_triplet.py
- test_edge_db_queries.py
- test_edge_int.py
- test_entity_exclusion_int.py
- test_graphiti_int.py
- test_graphiti_mock.py
- test_handle_multiple_group_ids.py
- test_node_int.py
- test_node_label_security.py
- test_text_utils.py
.env.example
.gitignore
AGENTS.md
CLAUDE.md
CODE_OF_CONDUCT.md
conftest.py
CONTRIBUTING.md
depot.json
docker-compose.test.yml
docker-compose.yml
Dockerfile
ellipsis.yaml
LICENSE
Makefile
OTEL_TRACING.md
py.typed
pyproject.toml
pytest.ini
README.md
SECURITY.md
uv.lock
Zep-CLA.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">
Graphiti
</h1>
<h2 align="center">AI 에이전트를 위한 시계열 컨텍스트 그래프 구축</h2>

[![Lint](https://github.com/getzep/Graphiti/actions/workflows/lint.yml/badge.svg?style=flat)](https://github.com/getzep/Graphiti/actions/workflows/lint.yml)
[![Unit Tests](https://github.com/getzep/Graphiti/actions/workflows/unit_tests.yml/badge.svg)](https://github.com/getzep/Graphiti/actions/workflows/unit_tests.yml)
[![MyPy Check](https://github.com/getzep/Graphiti/actions/workflows/typecheck.yml/badge.svg)](https://github.com/getzep/Graphiti/actions/workflows/typecheck.yml)

[![GitHub Repo stars](https://img.shields.io/github/stars/getzep/graphiti)](https://github.com/getzep/graphiti/stargazers)
[![arXiv](https://img.shields.io/badge/arXiv-2501.13956-b31b1b.svg?style=flat)](https://arxiv.org/abs/2501.13956)
[![Release](https://img.shields.io/github/v/release/getzep/graphiti?style=flat&label=Release&color=limegreen)](https://github.com/getzep/graphiti/releases)

</div>
<div align="center">

</div>

> [!NOTE]
> **채용 중입니다!** 신뢰할 수 있고 개인화된, 빠른 프로덕션 AI 에이전트를 구동하는 컨텍스트 그래프를 함께 만들어 가세요.
> 저희와 함께 성장할 Engineer 및 Developer Relations 담당자를 찾고 있습니다. [채용 공고 보기](https://www.getzep.com/careers/).

⭐ *더 많은 개발자에게 알리고 Graphiti 커뮤니티를 성장시킬 수 있도록 도와주세요. 이 저장소에 Star를 눌러주세요!*

&nbsp;

> [!TIP]
> 새로운 [Graphiti용 MCP 서버](mcp_server/README.md)를 확인해 보세요! Claude, Cursor 및 기타 MCP 클라이언트에 시계열 인식 능력을 갖춘 강력한 컨텍스트 그래프 기반 메모리를 제공합니다.

Graphiti는 AI 에이전트를 위한 시계열 컨텍스트 그래프를 구축하고 쿼리하기 위한 프레임워크입니다. 정적인 지식 그래프와 달리, Graphiti의 컨텍스트 그래프는 시간이 지남에 따라 사실이 어떻게 변화하는지 추적하고, 소스 데이터에 대한 출처(provenance)를 유지하며, 규정된(prescribed) 온톨로지와 학습된(learned) 온톨로지를 모두 지원합니다. 이를 통해 계속해서 변화하는 실제 데이터에서 작동하는 에이전트에 최적화된 기능을 제공합니다.

전통적인 검색 증강 생성(RAG) 방법과 달리, Graphiti는 사용자 상호작용, 정형 및 비정형 엔터프라이즈 데이터, 외부 정보를 일관되고 쿼리 가능한 그래프로 지속적으로 통합합니다. 이 프레임워크는 그래프 전체를 다시 계산할 필요 없이 증분 데이터 업데이트, 효율적인 검색, 정밀한 과거 쿼리를 지원하므로, 인터랙티브하고 컨텍스트를 인식하는 AI 애플리케이션 개발에 적합합니다.

Graphiti를 사용하여 다음을 수행할 수 있습니다:

- 모든 상호작용에 따라 진화하며, 현재 무엇이 사실인지와 이전에는 무엇이 사실이었는지를 추적하는 컨텍스트 그래프 구축.
- 단순한 문서 청크나 가공되지 않은 채팅 기록 대신, 풍부하고 구조화된 컨텍스트를 에이전트에게 제공.
- 하이브리드 검색(시맨틱 + 키워드 + 그래프 탐색)을 통해 시간, 의미, 관계를 가로질러 쿼리.

&nbsp;

&nbsp;

## 컨텍스트 그래프(Context Graph)란 무엇인가요?

**컨텍스트 그래프**는 엔티티, 관계, 사실의 시계열 그래프입니다. 예를 들어 *"Kendra는 Adidas 신발을 좋아한다 (2026년 3월 기준)"*와 같은 형태입니다. 전통적인 지식 그래프와 달리, 컨텍스트 그래프의 각 사실은 유효 윈도우(validity window)를 가집니다. 즉, 언제 사실이 되었는지, 그리고 (만약 그렇다면) 언제 대체되었는지를 기록합니다. 엔티티는 업데이트된 요약과 함께 시간이 지남에 따라 진화합니다. 모든 내용은 이를 생성한 원시 데이터인 **에피소드(episodes)**로 추적됩니다.

Graphiti의 독특한 점은 비정형 및 정형 데이터로부터 자율적으로 컨텍스트 그래프를 구축하고, 전체 시계열 이력을 보존하면서 변화하는 관계를 처리하는 능력에 있습니다.

컨텍스트 그래프는 다음 요소를 포함합니다:

| 구성 요소 | 저장 내용 |
|-----------|---------------|
| **Entities** (노드) | 사람, 제품, 정책, 개념 — 시간이 지남에 따라 진화하는 요약 포함 |
| **Facts / Relationships** (엣지) | 시계열 유효 윈도우를 가진 트리플렛 (Entity → Relationship → Entity) |
| **Episodes** (출처) | 수집된 원시 데이터 — 근거가 되는 진실 스트림. 모든 파생 사실은 여기로 추적됨 |
| **Custom Types** (온톨로지) | Pydantic 모델을 통해 개발자가 정의한 엔티티 및 엣지 유형 |

## Graphiti와 Zep

Graphiti는 AI 에이전트를 위한 [Zep](https://www.getzep.com)의 컨텍스트 인프라 핵심에 있는 오픈소스 시계열 컨텍스트 그래프 엔진입니다. Zep은 대규모로 컨텍스트 그래프를 관리하여, 프로덕션 에이전트 배포를 위한 거버넌스가 적용된 저지연 컨텍스트 검색 및 조립 기능을 제공합니다.

내부적으로 Zep은 수백만 개의 컨텍스트 그래프와 저지연 검색을 위해 구축된 독자적인 그래프 데이터베이스인 [Context Graph Engine](https://www.getzep.com/platform/context-graph-engine/)으로 구동되므로, 프로덕션 배포 시 별도의 서드파티 그래프 데이터베이스가 필요하지 않습니다.

우리는 Graphiti를 사용하여 Zep이 [에이전트 메모리의 최첨단(State of the Art)](https://blog.getzep.com/state-of-the-art-agent-memory/)임을 입증했습니다.

논문을 읽어보세요: [Zep: A Temporal Knowledge Graph Architecture for Agent Memory](https://arxiv.org/abs/2501.13956).

우리는 Graphiti가 메모리 애플리케이션을 넘어 컨텍스트 그래프 엔진으로서 큰 잠재력을 가지고 있다고 믿으며, 이를 오픈소스로 공개하게 되어 기쁩니다.

## Zep vs Graphiti

| 비교 항목 | Zep | Graphiti |
|--------|-----|---------|
| **정체성** | AI 에이전트를 위한 관리형 컨텍스트 그래프 인프라 | 오픈소스 시계열 컨텍스트 그래프 엔진 |
| **컨텍스트 그래프** | 거버넌스가 적용된 방대한 양의 사용자/엔티티별 컨텍스트 그래프 관리 | 개별 컨텍스트 그래프 구축 및 쿼리 |
| **그래프 데이터베이스** | 독자적인 [Context Graph Engine](https://www.getzep.com/platform/context-graph-engine/) — 수백만 개의 그래프와 저지연 검색을 위해 구축; 서드파티 벤더 불필요 | 사용자가 직접 서드파티 그래프 데이터베이스 선택 및 연결 |
| **사용자 및 대화 관리** | 사용자, 스레드, 메시지 저장소 내장 | 직접 구축 필요 |
| **검색 및 성능** | 대규모 환경에서 200ms 미만의 성능을 내는 사전 설정된 프로덕션 준비 검색 | 커스텀 구현 필요; 설정에 따라 성능이 달라짐 |
| **개발자 도구** | 그래프 시각화, 디버그 로그, API 로그 대시보드; Python, TypeScript, Go SDK 제공 | 직접 도구 구축 필요 |
| **엔터프라이즈 기능** | SLA, 지원, 보안 보장 | 자체 관리 |
| **배포** | 완전 관리형 또는 고객사 클라우드 | 셀프 호스팅 전용 |

### 선택 가이드

보안, 성능, 지원이 내장된 턴키 방식의 엔터프라이즈급 플랫폼을 원하신다면 **Zep**을 선택하세요.

유연한 OSS 코어를 원하며 주변 시스템을 직접 구축하고 운영하는 것이 편하시다면 **Graphiti**를 선택하세요.

## 왜 Graphiti인가요?

전통적인 RAG 접근 방식은 종종 배치 처리와 정적 데이터 요약에 의존하므로, 빈번하게 변경되는 데이터에 대해 비효율적입니다. Graphiti는 다음과 같은 기능을 통해 이러한 과제를 해결합니다:

- **시계열 사실 관리(Temporal Fact Management):** 사실은 유효 윈도우를 가집니다. 정보가 변경되면 오래된 사실은 삭제되지 않고 무효화됩니다. 현재 무엇이 사실인지, 또는 특정 시점에 무엇이 사실이었는지 쿼리할 수 있습니다.
- **에피소드 및 출처(Episodes & Provenance):** 모든 엔티티와 관계는 이를 생성한 에피소드(원시 데이터)로 추적됩니다. 파생된 사실부터 소스까지 전체 리니지(lineage)를 제공합니다.
- **규정 및 학습 온톨로지(Prescribed & Learned Ontology):** Pydantic 모델을 통해 엔티티와 엣지 유형을 미리 정의하거나(규정), 데이터로부터 구조가 자연스럽게 나타나도록 할 수 있습니다(학습). 간단하게 시작하여 패턴이 나타남에 따라 발전시키세요.
- **증분 그래프 구축(Incremental Graph Construction):** 배치 재계산 없이 새 데이터가 즉시 통합됩니다. 에피소드가 수집됨에 따라 그래프가 실시간으로 진화합니다.
- **하이브리드 검색(Hybrid Retrieval):** 시맨틱 임베딩, 키워드(BM25), 그래프 탐색을 결합하여 LLM 요약에 의존하지 않고도 저지연, 고정밀 쿼리를 수행합니다.
- **확장성(Scalability):** 병렬 처리와 플러그 가능한 그래프 백엔드를 통해 대규모 데이터셋을 효율적으로 관리하며, 엔터프라이즈 워크로드에 적합합니다.

## Graphiti vs. GraphRAG

| 비교 항목 | GraphRAG | Graphiti |
|--------|----------|---------|
| **주요 용도** | 정적 문서 요약 | 에이전트를 위한 동적, 진화하는 컨텍스트 |
| **데이터 처리** | 배치 중심 처리 | 지속적, 증분 업데이트 |
| **지식 구조** | 엔티티 클러스터 및 커뮤니티 요약 | 시계열 컨텍스트 그래프 — 엔티티, 유효 윈도우를 가진 사실, 에피소드, 커뮤니티 |
| **검색 방법** | 순차적 LLM 요약 | 하이브리드 시맨틱, 키워드 및 그래프 기반 검색 |
| **적응성** | 낮음 | 높음 |
| **시계열 처리** | 기본적인 타임스탬프 추적 | 자동 사실 무효화를 포함한 명시적 이중 시계열(bi-temporal) 추적 |
| **모순 처리** | LLM 기반 요약 판단 | 시계열 이력을 보존한 자동 사실 무효화 |
| **쿼리 지연 시간** | 수 초에서 수십 초 | 일반적으로 1초 미만 |
| **커스텀 엔티티 유형** | 지원 안 함 | 지원 함, Pydantic 모델을 통해 사용자 정의 가능 |
| **확장성** | 보통 | 높음, 대규모 데이터셋에 최적화 |

Graphiti는 특히 동적이고 빈번하게 업데이트되는 데이터셋의 과제를 해결하도록 설계되었으며, 실시간 상호작용과 정밀한 과거 쿼리가 필요한 애플리케이션에 매우 적합합니다.

## 설치 방법

요구 사항:

- Python 3.10 이상
- Neo4j 5.26 / FalkorDB 1.1.2 / Amazon Neptune Database Cluster 또는 Neptune Analytics Graph + Amazon OpenSearch Serverless 컬렉션 (전문 검색 백엔드로 사용) / Kuzu 0.11.2 (**지원 중단**, 아래 참고)
- OpenAI API 키 (Graphiti는 LLM 추론 및 임베딩의 기본값으로 OpenAI를 사용합니다)

> [!IMPORTANT]
> Graphiti는 구조화된 출력(Structured Output)을 지원하는 LLM 서비스(OpenAI, Anthropic, Gemini 등)에서 가장 잘 작동합니다. 다른 서비스를 사용할 경우 출력 스키마가 부정확하거나 수집 실패가 발생할 수 있습니다. 이는 특히 작은 모델을 사용할 때 더 두드러집니다.

선택 사항:

- Google Gemini, Anthropic 또는 Groq API 키 (대체 LLM 제공자용)

> [!TIP]
> Neo4j를 설치하는 가장 간단한 방법은 [Neo4j Desktop](https://neo4j.com/download/)을 이용하는 것입니다. Neo4j 인스턴스와 데이터베이스를 관리할 수 있는 사용자 친화적인 인터페이스를 제공합니다.
> 또는 Docker를 통해 FalkorDB를 온프레미스로 사용하고 퀵스타트 예제로 즉시 시작할 수 있습니다:
> ```
> docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest
> ```

```bash
pip install graphiti-core
```

또는

```bash
uv add graphiti-core
```

### FalkorDB 지원 설치

그래프 데이터베이스 백엔드로 FalkorDB를 사용할 계획이라면, FalkorDB 엑스트라와 함께 설치하세요:

```bash
pip install graphiti-core[falkordb]

# 또는 uv 사용 시
uv add graphiti-core[falkordb]

# 또는 임베디드 버전 (Python 3.12+ 필요)
pip install graphiti-core[falkordblite]
# 또는 uv 사용 시
uv add graphiti-core[falkordblite]
```

### Kuzu 지원 설치

> [!WARNING]
> **Kuzu는 지원이 중단(deprecated)**되었으며 향후 릴리스에서 제거될 예정입니다. 업스트림 Kuzu 프로젝트가 더 이상 유지 관리되지 않습니다. 새 프로젝트는 Neo4j 또는 FalkorDB를 사용하시기 바랍니다. 드라이버는 현재 제공되지만 `DeprecationWarning`이 발생합니다.

그래프 데이터베이스 백엔드로 Kuzu를 사용할 계획이라면, Kuzu 엑스트라와 함께 설치하세요:

```bash
pip install graphiti-core[kuzu]

# 또는 uv 사용 시
uv add graphiti-core[kuzu]
```

### Amazon Neptune 지원 설치

그래프 데이터베이스 백엔드로 Amazon Neptune을 사용할 계획이라면, Amazon Neptune 엑스트라와 함께 설치하세요:

```bash
pip install graphiti-core[neptune]

# 또는 uv 사용 시
uv add graphiti-core[neptune]
```

### 선택적 LLM 제공자를 엑스트라로 설치할 수 있습니다:

```bash
# 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]

# Amazon Neptune 설치
pip install graphiti-core[neptune]
```

## 기본 낮은 동시성 설정; LLM 제공자 429 속도 제한 오류

Graphiti의 수집 파이프라인은 높은 동시성을 위해 설계되었습니다. 기본적으로 LLM 제공자의 429 속도 제한(Rate Limit) 오류를 방지하기 위해 동시성 설정이 낮게 되어 있습니다. Graphiti의 속도가 느리다고 느껴진다면 아래 설명에 따라 동시성을 높여주세요.

동시성은 `SEMAPHORE_LIMIT` 환경 변수로 제어됩니다. 기본적으로 `SEMAPHORE_LIMIT`은 `10`개의 동시 작업으로 설정되어 LLM 제공자의 `429` 속도 제한 오류를 방지합니다. 만약 이러한 오류가 발생한다면 이 값을 더 낮추십시오.

사용 중인 LLM 제공자가 더 높은 처리량을 허용한다면, `SEMAPHORE_LIMIT`을 높여 에피소드 수집 성능을 향상시킬 수 있습니다.

## 퀵스타트

> [!IMPORTANT]
> Graphiti는 기본적으로 LLM 추론 및 임베딩에 OpenAI를 사용합니다. 환경 변수에 `OPENAI_API_KEY`가 설정되어 있는지 확인하세요.
> Anthropic, Gemini, Groq에 대한 지원도 제공됩니다. 호스팅된 OpenAI 호환 API(DeepSeek, Together, OpenRouter 등) 및 로컬 서버(Ollama, vLLM, llama.cpp, LM Studio)는 OpenAI 호환 엔드포인트를 통해 사용할 수 있습니다. 자세한 내용은 [OpenAI 호환 제공자 및 로컬 LLM으로 Graphiti 사용하기](#using-graphiti-with-openai-compatible-providers-and-local-llms)를 참조하세요.

전체 작동 예제는 examples 디렉토리의 [Quickstart Example](examples/quickstart/README.md)을 참조하세요. 퀵스타트에서는 다음 내용을 다룹니다:

1. Neo4j, Amazon Neptune, FalkorDB 또는 Kuzu 데이터베이스 연결
2. Graphiti 인덱스 및 제약 조건 초기화
3. 그래프에 에피소드 추가 (텍스트 및 구조화된 JSON 모두)
4. 하이브리드 검색을 사용하여 관계(엣지) 검색
5. 그래프 거리를 사용하여 검색 결과 리랭킹
6. 사전 정의된 검색 레시피를 사용하여 노드 검색

이 예제는 각 기능에 대한 명확한 설명과 함께 상세히 문서화되어 있으며, 설정 방법과 다음 단계가 포함된 포괄적인 README를 제공합니다.

### Docker Compose로 실행하기

Docker Compose를 사용하여 필요한 서비스를 빠르게 시작할 수 있습니다:

- **Neo4j Docker:**

```bash
  docker compose up
  ```

이 명령은 Neo4j Docker 서비스와 관련 구성 요소를 시작합니다.

- **FalkorDB Docker:**

```bash
  docker compose --profile falkordb up
  ```

이 명령은 FalkorDB Docker 서비스와 관련 구성 요소를 시작합니다.

## MCP 서버

`mcp_server` 디렉토리에는 Graphiti를 위한 Model Context Protocol (MCP) 서버 구현이 포함되어 있습니다. 이 서버를 통해 AI 어시스턴트가 MCP 프로토콜을 사용하여 Graphiti의 컨텍스트 그래프 기능과 상호작용할 수 있습니다.

MCP 서버의 주요 기능은 다음과 같습니다:

- 에피소드 관리 (추가, 조회, 삭제)
- 엔티티 관리 및 관계 처리
- 시맨틱 및 하이브리드 검색 기능
- 관련 데이터 정리를 위한 그룹 관리
- 그래프 유지 관리 작업

MCP 서버는 Neo4j와 함께 Docker를 사용하여 배포할 수 있어, AI 어시스턴트 워크플로우에 Graphiti를 쉽게 통합할 수 있습니다.

상세 설정 방법 및 사용 예제는 [MCP 서버 README](mcp_server/README.md)를 참조하세요.

## REST 서비스

`server` 디렉토리에는 Graphiti API와 상호작용하기 위한 API 서비스가 포함되어 있습니다. 이 서비스는 FastAPI를 사용하여 구축되었습니다.

자세한 내용은 [server README](server/README.md)를 참조하세요.

## 선택적 환경 변수

Neo4j 및 OpenAI 호환 자격 증명 외에도 Graphiti에는 몇 가지 선택적 환경 변수가 있습니다. Anthropic이나 Voyage 모델과 같이 지원되는 특정 모델을 사용하는 경우, 필요한 환경 변수가 설정되어 있어야 합니다.

### 데이터베이스 설정

데이터베이스 이름은 드라이버 생성자에서 직접 설정됩니다:

- **Neo4j**: 데이터베이스 이름은 기본적으로 `neo4j`입니다 (Neo4jDriver에 하드코딩됨).
- **FalkorDB**: 데이터베이스 이름은 기본적으로 `default_db`입니다 (FalkorDriver에 하드코딩됨).

v0.17.0부터는 데이터베이스 설정을 커스텀해야 하는 경우, 데이터베이스 드라이버를 인스턴스화하여 `graph_driver` 파라미터를 통해 Graphiti 생성자에 전달할 수 있습니다.

#### 커스텀 데이터베이스 이름을 사용하는 Neo4j

```python
from graphiti_core import Graphiti
from graphiti_core.driver.neo4j_driver import Neo4jDriver

# 커스텀 데이터베이스 이름으로 Neo4j 드라이버 생성
driver = Neo4jDriver(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    database="my_custom_database"  # 커스텀 데이터베이스 이름
)

# 드라이버를 Graphiti에 전달
graphiti = Graphiti(graph_driver=driver)
```

#### 커스텀 데이터베이스 이름을 사용하는 FalkorDB

```python
from graphiti_core import Graphiti
from graphiti_core.driver.falkordb_driver import FalkorDriver

# 커스텀 데이터베이스 이름으로 FalkorDB 드라이버 생성
driver = FalkorDriver(
    host="localhost",
    port=6379,
    username="falkor_user",  # 선택 사항
    password="falkor_password",  # 선택 사항
    database="my_custom_graph"  # 커스텀 데이터베이스 이름
)

# 또는 임베디드 FalkorDB Lite 사용 (Python 3.12+ 필요)
# from redislite.async_falkordb_client import AsyncFalkorDB
# falkordb_client = AsyncFalkorDB(dbfilename='/path/to/database.db')
# driver = FalkorDriver(falkor_db=falkordb_client)

# 드라이버를 Graphiti에 전달
graphiti = Graphiti(graph_driver=driver)
```

#### Kuzu

> [!WARNING]
> Kuzu는 **지원 중단(deprecated)**되었으며(업스트림 프로젝트 유지 관리 중단), 향후 릴리스에서 제거될 예정입니다. Neo4j 또는 FalkorDB를 권장합니다.

```python
from graphiti_core import Graphiti
from graphiti_core.driver.kuzu_driver import KuzuDriver

# Kuzu 드라이버 생성
driver = KuzuDriver(db="/tmp/graphiti.kuzu")

# 드라이버를 Graphiti에 전달
graphiti = Graphiti(graph_driver=driver)
```

#### Amazon Neptune

```python
from graphiti_core import Graphiti
from graphiti_core.driver.neptune_driver import NeptuneDriver

# Neptune 드라이버 생성
driver = NeptuneDriver(
    host='<NEPTUNE_ENDPOINT>',
    aoss_host='<AMAZON_OPENSEARCH_SERVERLESS_HOST>',
    port=8182,      # 선택 사항, 기본값 8182
    aoss_port=443,  # 선택 사항, 기본값 443
)

# 드라이버를 Graphiti에 전달
graphiti = Graphiti(graph_driver=driver)
```

새로운 그래프 백엔드를 기여하시겠습니까? [그래프 드라이버 추가하기](CONTRIBUTING.md#adding-a-graph-driver)를 참조하세요.

## Azure OpenAI로 Graphiti 사용하기

Graphiti는 Azure의 OpenAI v1 API 호환 레이어를 사용하여 LLM 추론 및 임베딩 모두에 대해 Azure OpenAI를 지원합니다.

### 퀵스타트

```python
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의 v1 API 엔드포인트를 사용하여 표준 OpenAI 클라이언트로 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-5-mini", small_model="gpt-5-mini")  # Azure 배포 이름
)
embedder_client = AzureOpenAIEmbedderClient(
    azure_client=azure_client,
    model="text-embedding-3-small"  # Azure 임베딩 배포 이름
)

# Azure OpenAI 클라이언트로 Graphiti 초기화
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=llm_client,
    embedder=embedder_client,
)

# 이제 Azure OpenAI와 함께 Graphiti를 사용할 수 있습니다.
```

**주요 포인트:**

- Azure의 v1 API 엔드포인트 형식(`https://your-resource-name.openai.azure.com/openai/v1/`)과 함께 표준 `AsyncOpenAI` 클라이언트를 사용하세요.
- 배포 이름(예: `gpt-5-mini`, `text-embedding-3-small`)은 실제 Azure OpenAI 배포 이름과 일치해야 합니다.
- 전체 작동 예제는 `examples/azure-openai/`를 참조하세요.

플레이스홀더 값을 실제 Azure OpenAI 자격 증명 및 배포 이름으로 변경하시기 바랍니다.

## Google Gemini로 Graphiti 사용하기

Graphiti는 LLM 추론, 임베딩, 교차 인코딩/리랭킹(cross-encoding/reranking)에 대해 Google의 Gemini 모델을 지원합니다. Gemini를 사용하려면 LLM 클라이언트, 임베더 및 교차 인코더를 Google API 키로 설정해야 합니다.

Graphiti 설치:

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

# 또는

pip install "graphiti-core[google-genai]"
```

```python
from graphiti_core import Graphiti
from graphiti_core.llm_client.gemini_client import GeminiClient, LLMConfig
from graphiti_core.embedder.gemini import GeminiEmbedder, GeminiEmbedderConfig
from graphiti_core.cross_encoder.gemini_reranker_client import GeminiRerankerClient

# Google API 키 설정
api_key = "<your-google-api-key>"

# Gemini 클라이언트로 Graphiti 초기화
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"
        )
    ),
    cross_encoder=GeminiRerankerClient(
        config=LLMConfig(
            api_key=api_key,
            model="gemini-2.5-flash-lite"
        )
    )
)

# 이제 모든 구성 요소에 Google Gemini를 사용하여 Graphiti를 사용할 수 있습니다.
```

Gemini 리랭커는 기본적으로 비용 효율적이고 저지연 분류 작업에 최적화된 `gemini-2.5-flash-lite` 모델을 사용합니다. 이는 OpenAI 리랭커와 동일한 불리언 분류 방식을 사용하며, Gemini의 로그 확률(log probabilities) 기능을 활용하여 구절의 관련성을 순위 매깁니다.

## OpenAI 호환 제공자 및 로컬 LLM으로 Graphiti 사용하기

Graphiti는 `OpenAIGenericClient`를 통해 LLM 추론을 위한 모든 OpenAI 호환 `/v1` 엔드포인트를 사용할 수 있습니다. 여기에는 **호스팅 제공자**(DeepSeek, Together, OpenRouter, Fireworks 등)와 **로컬 서버**(Ollama, vLLM, llama.cpp, LM Studio)가 모두 포함됩니다. 로컬 서버는 개인정보 보호가 중요한 애플리케이션이나 API 비용을 절감하려는 경우에 이상적입니다. 아래 예제는 Ollama를 사용하며, 다른 제공자의 경우 `base_url`을 해당 엔드포인트로 지정하고 적절한 `api_key`와 `model`을 설정하십시오.

**참고:** 이러한 엔드포인트에는 `OpenAIClient`가 아닌 `OpenAIGenericClient`를 사용하세요. 이 클라이언트는 더 높은 기본 최대 토큰 제한(8K 대신 16K)으로 로컬 모델에 최적화되어 있으며, 호환 제공자 간에 구조화된 출력을 처리합니다.

모델 설치:

```bash
ollama pull deepseek-r1:7b # LLM
ollama pull nomic-embed-text # embeddings
```

```python
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
from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient

# Ollama LLM 클라이언트 설정
llm_config = LLMConfig(
    api_key="ollama",  # Ollama는 실제 API 키가 필요 없지만, 플레이스홀더가 필요합니다.
    model="deepseek-r1:7b",
    small_model="deepseek-r1:7b",
    base_url="http://localhost:11434/v1",  # Ollama의 OpenAI 호환 엔드포인트
)

llm_client = OpenAIGenericClient(config=llm_config)

# Ollama 클라이언트로 Graphiti 초기화
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=llm_client,
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            api_key="ollama",  # 플레이스홀더 API 키
            embedding_model="nomic-embed-text",
            embedding_dim=768,
            base_url="http://localhost:11434/v1",
        )
    ),
    cross_encoder=OpenAIRerankerClient(client=llm_client, config=llm_config),
)

# 이제 로컬 Ollama 모델과 함께 Graphiti를 사용할 수 있습니다.
```

Ollama가 실행 중(`ollama serve`)인지, 그리고 사용하려는 모델을 풀(pull) 했는지 확인하세요.

### 구조화된 출력 및 작은 모델

Graphiti는 엔티티/엣지 추출 및 중복 제거를 위해 구조화된(JSON) 출력에 의존하며, 이를 안정적으로 지원하는 모델과 제공자(OpenAI, Anthropic, Gemini)에서 가장 잘 작동합니다. OpenAI 호환 제공자, 특히 작거나 로컬 모델의 경우 신뢰도가 다를 수 있으므로 `OpenAIGenericClient`는 `structured_output_mode`를 제공합니다:

- `"json_schema"` (기본값): `response_format`을 통해 네이티브 구조화된 출력을 요청합니다. 제약된 디코딩(constrained decoding)을 통해 스키마를 강제하는 유능한 모델 및 제공자에 가장 적합합니다.
- `"json_object"`: 단순 JSON 모드를 요청하고 프롬프트에 스키마를 직접 삽입합니다. `json_schema`를 안정적으로 지원하지 않는 제공자/모델(예: `json_schema` 요청을 수락하지만 실제로 출력을 제한하지 않는 일부 로컬 서버)의 경우 `json_object`가 *더* 안정적일 수 있습니다.

작거나 로컬 모델을 사용할 때:

- 실행 가능한 가장 성능 좋은 모델을 사용하세요. 매우 작은 모델은 요청된 스키마와 일치하지 않는 JSON을 자주 생성하며, 이는 추출 실패로 나타납니다.
- 마크다운 ` ```json ` 코드 펜스로 감싸진 응답은 자동으로 제거됩니다.
- `SEMAPHORE_LIMIT`을 낮게 유지하세요(위의 [동시성 설정](#default-to-low-concurrency-llm-provider-429-rate-limit-errors) 참조). 로컬 서버 및 일부 제공자는 동시성 제한이 있습니다.

## 문서

- [가이드 및 API 문서](https://help.getzep.com/graphiti).
- [퀵스타트](https://help.getzep.com/graphiti/graphiti/quick-start)
- [LangChain의 LangGraph와 Graphiti로 에이전트 구축하기](https://help.getzep.com/graphiti/integrations/lang-graph-agent)

## 텔레메트리(Telemetry)

Graphiti는 프레임워크가 어떻게 사용되는지 이해하고 모두를 위해 개선하기 위해 익명 사용 통계를 수집합니다. 투명성이 중요하다고 믿기에, 수집하는 항목과 이유를 정확히 설명합니다.

### 수집 항목

Graphiti 인스턴스를 초기화할 때 다음 내용을 수집합니다:

- **익명 식별자**: `~/.cache/graphiti/telemetry_anon_id`에 로컬로 저장되는 무작위 생성 UUID
- **시스템 정보**: 운영 체제, Python 버전 및 시스템 아키텍처
- **Graphiti 버전**: 사용 중인 버전
- **설정 선택 사항**:
  - LLM 제공자 유형 (OpenAI, Azure, Anthropic 등)
  - 데이터베이스 백엔드 (Neo4j, FalkorDB, Kuzu, Amazon Neptune Database 또는 Neptune Analytics)
  - 임베더 제공자 (OpenAI, Azure, Voyage 등)

### 수집하지 않는 항목

우리는 귀하의 개인정보 보호를 위해 최선을 다하고 있습니다. 다음 내용은 **절대로** 수집하지 않습니다:

- 개인 정보 또는 식별자
- API 키 또는 자격 증명
- 실제 데이터, 쿼리 또는 그래프 내용
- IP 주소 또는 호스트 이름
- 파일 경로 또는 시스템 특정 정보
- 에피소드, 노드 또는 엣지의 모든 내용

### 데이터 수집 이유

이 정보는 다음을 돕습니다:

- 가장 인기 있는 설정을 파악하여 지원 및 테스트 우선순위를 결정
- 개발 노력을 집중할 LLM 및 데이터베이스 제공자 식별
- 로드맵 가이드를 위한 채택 패턴 추적
- 다양한 Python 버전 및 운영 체제 간의 호환성 보장

이 익명 정보를 공유함으로써 커뮤니티의 모두를 위해 Graphiti를 개선하는 데 도움을 주게 됩니다.

### 텔레메트리 코드 확인

텔레메트리 코드는 [여기서](graphiti_core/telemetry/telemetry.py) 확인할 수 있습니다.

### 텔레메트리 비활성화 방법

텔레메트리는 **옵트아웃(opt-out)** 방식이며 언제든지 비활성화할 수 있습니다. 수집을 중단하려면 다음 방법 중 하나를 사용하세요:

**방법 1: 환경 변수**

```bash
export GRAPHITI_TELEMETRY_ENABLED=false
```

**방법 2: 쉘 프로필에 설정**

```bash
# bash 사용자의 경우 (~/.bashrc 또는 ~/.bash_profile)
echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.bashrc

# zsh 사용자의 경우 (~/.zshrc)
echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.zshrc
```

**방법 3: 특정 Python 세션에서 설정**

```python
import os

os.environ['GRAPHITI_TELEMETRY_ENABLED'] = 'false'

# 그 다음 평소처럼 Graphiti를 초기화하세요
from graphiti_core import Graphiti

graphiti = Graphiti(...)
```

테스트 실행 중에는 (`pytest`가 감지되면) 텔레메트리가 자동으로 비활성화됩니다.

### 기술 세부 사항

- 텔레메트리는 익명 분석 수집을 위해 PostHog를 사용합니다.
- 모든 텔레메트리 작업은 조용히 실패(fail silently)하도록 설계되었습니다. 즉, 애플리케이션을 중단시키거나 Graphiti 기능에 영향을 주지 않습니다.
- 익명 ID는 로컬에 저장되며 개인 정보와 연결되지 않습니다.

## 기여하기

코드, 문서 작성, GitHub Issue 해결, 또는 GitHub에서 다른 사용자를 돕는 등 모든 형태의 기여를 환영하고 감사하게 생각합니다. 코드 기여에 대한 자세한 가이드라인은 [CONTRIBUTING](CONTRIBUTING.md)을 참조하세요.

## 지원

질문, 버그 보고 또는 Graphiti에 대한 논의를 위해 [GitHub issue](https://github.com/getzep/graphiti/issues)를 생성해 주세요.

graphiti

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

graphiti

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README