Graphiti — темпоральные графы знаний для AI-агентов

Graphiti — открытый Python-фреймворк для построения темпоральных графов знаний, или context graphs, для AI-агентов. Его разрабатывает компания Zep, лицензия — Apache-2.0. Проект активно растёт: сейчас у него больше 31 тысячи звёзд на GitHub.

Обычные графы знаний статичны: они фиксируют факты на момент загрузки и не следят за изменениями. Graphiti строит графы, которые меняются вместе с данными. Каждый факт в таком графе имеет срок действия: когда он стал правдой и когда перестал. Это важно для агентов, которые работают с живыми данными: профилями пользователей, документами компании, новостями.

Почему обычный RAG не справляется

Классический RAG хорошо работает со статичными документами. Данные обрабатываются пакетами, а суммаризация выполняется заранее. Если данные меняются часто, приходится пересчитывать весь индекс или граф. Это долго и дорого.

Graphiti решает задачу иначе. Новые данные добавляются в граф сразу, без пакетной пересборки. При этом старые факты не удаляются: они помечаются как недействительные и остаются в истории. Отсюда два важных свойства. Агент всегда видит актуальное состояние мира. И он может спросить, что было правдой в любой момент прошлого.

Что такое контекстный граф

Контекстный граф — это граф сущностей, связей и фактов с привязкой ко времени. Пример факта: «Кендра любит кроссовки Adidas (по состоянию на март 2026 года)». У каждого факта есть окно валидности: когда он стал истинным и когда его заменил другой факт. Сущности тоже меняются со временем: их описания обновляются.

Состав контекстного графа:

Ключевая особенность Graphiti — фреймворк сам строит такой граф из неструктурированных и структурированных данных. Он обрабатывает меняющиеся связи и сохраняет полную историю.

Ключевые возможности

• Управление фактами во времени. Факты имеют окна валидности. Когда информация меняется, старый факт помечается недействительным, но не удаляется. Можно запросить актуальное состояние или состояние на любую дату.
• Эпизоды и происхождение данных. Каждая сущность и связь ссылается на эпизод — исходные данные, из которых они получены. Полная цепочка от факта до источника.
• Заданная и выведенная онтология. Типы сущностей и рёбер можно задать заранее через Pydantic-модели. Или позволить структуре вырасти из данных. Начать просто и усложнять по мере появления закономерностей.
• Инкрементальное построение. Новые данные встраиваются в граф сразу. Пересчитывать всё заново не нужно.
• Гибридный поиск. Поиск объединяет векторные вложения, ключевые слова (BM25) и обход графа. Результаты переранжируются по расстоянию в графе. Задержка обычно меньше секунды, обращения к LLM не требуется.
• Масштабируемость. Параллельная обработка и подключаемые графовые бэкенды для больших объёмов данных.

Graphiti против GraphRAG

GraphRAG — известный подход, который строит граф поверх статичного набора документов. Graphiti решает другую задачу: динамичные, постоянно обновляемые данные.

Установка

Понадобятся Python 3.10 или новее, графовая база данных и API-ключ LLM. По умолчанию Graphiti использует OpenAI как LLM-провайдер и для эмбеддингов. Графовых бэкенда четыре: Neo4j 5.26, FalkorDB 1.1.2, Amazon Neptune (в связке с Amazon OpenSearch Serverless) и Kuzu. Kuzu объявлен устаревшим: upstream-проект больше не поддерживается, для новых проектов лучше выбрать Neo4j или FalkorDB.

pip install graphiti-core

Для FalkorDB есть дополнительный вариант — встраиваемая версия FalkorDB Lite:

pip install graphiti-core[falkordb]
pip install graphiti-core[falkordblite]  # требует Python 3.12+

Альтернативные LLM-провайдеры ставятся как extras: graphiti-core[anthropic], graphiti-core[groq], graphiti-core[google-genai] или несколько сразу.

Быстрее всего поднять графовую базу через Docker Compose:

docker compose up                      # Neo4j
docker compose --profile falkordb up  # FalkorDB

Быстрый старт

Гайды и API-документация живут на help.getzep.com. Полный рабочий пример — в репозитории, в каталоге examples/quickstart. Он показывает основной цикл работы:

1. Подключение к Neo4j, Amazon Neptune, FalkorDB или Kuzu.
2. Инициализация индексов и ограничений.
3. Добавление эпизодов — текста и структурированного JSON.
4. Гибридный поиск по связям.
5. Переранжирование результатов по расстоянию в графе.
6. Поиск узлов через готовые рецепты поиска (search recipes).

Имя базы данных настраивается через драйвер. Например, так создаётся драйвер Neo4j с нестандартной базой:

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

driver = Neo4jDriver(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    database="my_custom_database"
)

graphiti = Graphiti(graph_driver=driver)

Работа с LLM-провайдерами

Graphiti лучше всего работает с провайдерами, которые надёжно поддерживают structured output: OpenAI, Anthropic, Gemini. Без корректного JSON извлечение сущностей ломается, особенно на маленьких моделях.

Через OpenAIGenericClient можно подключить любой OpenAI-совместимый endpoint. Это и облачные провайдеры (DeepSeek, Together, OpenRouter, Fireworks), и локальные серверы (Ollama, vLLM, llama.cpp, LM Studio). Локальные модели удобны там, где важна приватность или не хочется платить за API.

У OpenAIGenericClient есть параметр structured_output_mode. Значение json_schema (по умолчанию) запрашивает нативный структурированный вывод. Значение json_object запрашивает обычный JSON-режим и подставляет схему прямо в промпт. Второй вариант иногда надёжнее для провайдеров, которые формально принимают json_schema, но реально не следуют схеме.

Скорость загрузки эпизодов управляется переменной окружения SEMAPHORE_LIMIT. По умолчанию она равна 10 одновременным операциям — это защита от ошибок 429 у LLM-провайдера. Если провайдер допускает большую нагрузку, значение можно увеличить.

MCP-сервер и REST-сервис

В репозитории есть два готовых сервиса для интеграции.

MCP-сервер в каталоге mcp_server позволяет AI-ассистентам работать с графом через протокол MCP. Он умеет управлять эпизодами (добавление, чтение, удаление), сущностями и связями, выполнять семантический и гибридный поиск, группировать связанные данные и обслуживать граф. Разворачивается через Docker вместе с Neo4j. Подробности — в README MCP-сервера.

REST-сервис в каталоге server построен на FastAPI и открывает Graphiti API по HTTP. Описание — в README сервера.

Zep и Graphiti

Graphiti — открытая основа платформы Zep. Zep — это управляемая инфраструктура контекстных графов: собственный движок Context Graph Engine, готовый поиск с задержкой меньше 200 мс, дашборд с визуализацией графа, SLA и поддержка. Graphiti — это OSS-фреймворк, где графовую базу, инструменты и эксплуатацию вы собираете сами.

Правило выбора простое. Нужен готовый продукт с гарантиями — берите Zep. Нужен гибкий открытый код и контроль над инфраструктурой — берите Graphiti.

Подход команды описан в статье Zep: A Temporal Knowledge Graph Architecture.

Телеметрия

Graphiti собирает анонимную статистику использования: случайный идентификатор, версию ОС и Python, выбор LLM-провайдера и графового бэкенда. Содержимое графа, API-ключи и персональные данные не собираются. Телеметрию можно отключить переменной окружения:

export GRAPHITI_TELEMETRY_ENABLED=false

Код телеметрии открыт, его можно посмотреть в репозитории.