Install & Compatibility
Where this runs
tested against v0.29.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
16/20 runs
✓ 11.88s
py 3.11
16/20 runs
✓ 10.48s
py 3.9
✕ build_error
✕ build_error
235MB installed
● package 235MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Graphiti
✓ from graphiti_core import Graphiti
EpisodeType
✓ from graphiti_core.nodes import EpisodeType
This quickstart demonstrates how to initialize Graphiti with a FalkorDB backend, build necessary indices, add a text-based episode, and perform a natural language search. It requires a running FalkorDB instance and an OpenAI API key set in your environment.
import asyncio
import os
from datetime import datetime
from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType
# Ensure OPENAI_API_KEY and FALKORDB_URI are set in your environment
# Example: export OPENAI_API_KEY="sk-..."
# Example: docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest
async def main():
# Initialize Graphiti with FalkorDB driver (default to localhost)
graphiti = Graphiti(
uri=os.environ.get('FALKORDB_URI', "falkor://localhost:6379")
)
# Build indices (run once during setup)
print("Building indices and constraints...")
await graphiti.build_indices_and_constraints()
print("Indices built.")
# Add an episode (information to be stored in the graph)
episode_body = (
"Alice met Bob at the AI conference in San Francisco on March 15, 2024. "
"They discussed the latest developments in graph databases and decided "
"to collaborate on a new project using Graphiti and FalkorDB."
)
print("Adding episode...")
await graphiti.add_episode(
name="Conference Meeting",
episode_body=episode_body,
episode_type=EpisodeType.text,
reference_time=datetime(2024, 3, 15),
source_description="Conference notes"
)
print("Episode added.")
# Search the knowledge graph
print("Searching the graph...")
search_results = await graphiti.search(
query="What did Alice and Bob discuss?",
num_results=3
)
print("\nSearch Results:")
if search_results:
for i, result in enumerate(search_results):
print(f"- Result {i+1}: {result.node.summary}")
else:
print("No search results found.")
# Close the connection
await graphiti.close()
print("Connection closed.")
if __name__ == "__main__":
# Set a dummy API key if not already set, for local testing without network
if not os.environ.get('OPENAI_API_KEY'):
print("Warning: OPENAI_API_KEY environment variable not set. Using a dummy key.")
os.environ['OPENAI_API_KEY'] = 'dummy-key-for-test'
asyncio.run(main())
Debug
Known issues
breakingGraphiti-core versions prior to 0.28.2 contain a Cypher injection vulnerability. It is critical to update to 0.28.2 or later to mitigate this security risk.fixUpgrade to `graphiti-core>=0.28.2`.
affects: <0.28.2
breakingVersion 0.28.1 replaced the `diskcache` dependency with a `sqlite-based cache` to resolve a CVE. If your application directly interacted with `diskcache` or relied on specific `diskcache` configurations, this change might require adjustments.fixReview cache implementations and migrate any direct `diskcache` interactions to the new `sqlite-based` mechanism or other supported caching strategies.
affects: All versions before 0.28.1 if using diskcache features.
gotchaGraphiti defaults to using OpenAI for LLM inference and embedding. An `OPENAI_API_KEY` environment variable must be set for the library to function correctly unless an alternative LLM provider is explicitly configured and installed (e.g., `graphiti-core[anthropic]`).fixSet the `OPENAI_API_KEY` environment variable or install and configure an alternative LLM provider as described in the documentation.
affects: All versions
gotchaVersion 0.28.0 introduced a 'driver operations architecture redesign'. Users with custom database drivers or those who extensively customized database interactions might need to review and update their implementations to align with the new architecture.fixConsult the release notes and documentation for 0.28.0 to understand the new driver architecture and adapt custom implementations.
affects: Pre-0.28.0 custom driver implementations
gotchaGraphiti is designed for high concurrency in its ingestion pipelines. By default, concurrency is set low to prevent LLM Provider 429 (Rate Limit) errors. If performance is critical, increase concurrency via the `SEMAPHORE_LIMIT` environment variable.fixAdjust the `SEMAPHORE_LIMIT` environment variable to a higher value after carefully considering the rate limits of your LLM provider and your application's requirements.
affects: All versions
gotchaGraphiti requires an external graph database (e.g., Neo4j, FalkorDB, Kuzu, Amazon Neptune) to operate. Ensure a compatible database is running and accessible with the correct connection parameters.fixSet up and connect to a supported graph database as detailed in the Graphiti documentation. Use the `uri` parameter in the `Graphiti` constructor.
affects: All versions
gotchaDue to `graphiti-core`'s asynchronous nature and persistent connections, integrating it directly into applications with incompatible concurrency models (e.g., certain web frameworks) can lead to 'Event loop is closed' errors. For production, isolating `graphiti-core` in its own process, such as via a dedicated API service, is recommended for stability.fixConsider deploying `graphiti-core` operations within a separate process or microservice, accessed via an HTTP API, to maintain event loop integrity and stability of the main application.
affects: All versions
Errors
Common errors & fixes
error: externally-managed-environment
This error occurs when `pip` attempts to install packages system-wide in a Python environment managed by the operating system, which is prevented by PEP 668 on many modern Linux distributions.
fixCreate and activate a virtual environment before installing `graphiti-core`: `python3 -m venv .venv && source .venv/bin/activate && pip install graphiti-core`.
AttributeError: 'KuzuDriver' object has no attribute '_database'
When using `KuzuDriver` (or potentially `NeptuneDriver`) with `Graphiti.add_episode` and a `group_id`, the driver object is missing the internal `_database` attribute expected by `graphiti-core` for database switching logic.
fixThis is a bug in `graphiti-core` that requires an update to a patched version. As a temporary workaround, you might manually set `driver._database = driver.default_group_id or 'default'` on the `KuzuDriver` instance after initialization, but upgrading is the recommended long-term fix.
ValueError: too many values to unpack (expected 2)
This error occurs in `Graphiti.add_episode()` when `update_communities=True` (the default). The `update_communities` internal function returns a list of tuples, but the subsequent unpacking expects exactly two values, leading to a `ValueError` if the number of extracted entities is not precisely two.
fixThis is a bug in `graphiti-core` (specifically in version 0.28.2) that requires an update to a patched version of the library. If community updates are not critical, you might set `update_communities=False` in `add_episode` as a temporary measure.
openai.OpenAIError: The api_key client option must be set (HINT: set the `OPENAI_API_KEY` environment variable or pass `api_key` to the client)
`graphiti-core` defaults to using OpenAI for LLM inference and embeddings. This error indicates that the `OPENAI_API_KEY` environment variable is not set or that the `Graphiti` instance was not explicitly configured with an alternative LLM client and its corresponding API key.
fixSet the `OPENAI_API_KEY` environment variable: `export OPENAI_API_KEY='your_openai_api_key'`. Alternatively, if using a different LLM provider, ensure you explicitly pass the correct `llm_client` and `embedder` configurations when initializing `Graphiti`.
RuntimeError: Future attached to a different loop
`graphiti-core` is an asynchronous library. When it's integrated into another sophisticated asynchronous framework (like Google ADK), its internal asynchronous operations and event loop management can conflict with the host application's event loop, leading to runtime instability.
fixTo ensure stability in complex asynchronous applications, it is recommended to isolate `graphiti-core` in its own dedicated process, often as a separate API service, rather than integrating it directly into the main application's event loop.
Upgrade
Version history
0.29.2latest on PyPI · released Jun 8, 2026
Audit
Dependencies
pythonrequiredRequired Python version.
falkordboptionalOptional graph database backend. Install with `[falkordb]` extra.
kuzuoptionalOptional graph database backend. Install with `[kuzu]` extra.
amazon-neptuneoptionalOptional graph database backend. Install with `[neptune]` extra.
openairequiredDefault LLM provider for inference and embedding. Requires `OPENAI_API_KEY`.
anthropicoptionalOptional LLM provider. Install with `[anthropic]` extra.
groqoptionalOptional LLM provider. Install with `[groq]` extra.
google-genaioptionalOptional LLM provider. Install with `[google-genai]` extra.