> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/getzep/graphiti/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Build your first knowledge graph in minutes

## Overview

This quickstart demonstrates how to build a temporally-aware knowledge graph with Graphiti. You'll learn how to:

* Connect to a graph database
* Add episodes (data) to your knowledge graph
* Search for relationships and entities
* Use graph-based reranking for contextual results

<Info>
  This guide uses Neo4j as the graph database backend. Graphiti also supports FalkorDB, Kuzu, and Amazon Neptune.
</Info>

## Prerequisites

Before you begin, ensure you have:

* Python 3.10 or higher
* A graph database running (Neo4j, FalkorDB, Kuzu, or Amazon Neptune)
* An OpenAI API key

<Tip>
  The simplest way to get started is with [Neo4j Desktop](https://neo4j.com/download/) or FalkorDB via Docker:

  ```bash theme={null}
  docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest
  ```
</Tip>

## Step 1: Install Graphiti

Install Graphiti using your preferred package manager:

<CodeGroup>
  ```bash pip theme={null}
  pip install graphiti-core
  ```

  ```bash uv theme={null}
  uv add graphiti-core
  ```

  ```bash poetry theme={null}
  poetry add graphiti-core
  ```
</CodeGroup>

## Step 2: Set Up Environment Variables

Create a `.env` file or export environment variables:

```bash .env theme={null}
# Required for LLM and embeddings
OPENAI_API_KEY=your_openai_api_key

# Neo4j connection (adjust if using different backend)
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password
```

<Warning>
  Keep your API keys secure. Never commit them to version control.
</Warning>

## Step 3: Initialize Graphiti

Create a new Python file and initialize your Graphiti instance:

```python quickstart.py theme={null}
import asyncio
import os
from datetime import datetime, timezone
from dotenv import load_dotenv
from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType

load_dotenv()

# Get connection parameters from environment
neo4j_uri = os.environ.get('NEO4J_URI', 'bolt://localhost:7687')
neo4j_user = os.environ.get('NEO4J_USER', 'neo4j')
neo4j_password = os.environ.get('NEO4J_PASSWORD', 'password')

async def main():
    # Initialize Graphiti with Neo4j connection
    graphiti = Graphiti(neo4j_uri, neo4j_user, neo4j_password)
    
    try:
        # Your code goes here
        pass
    finally:
        # Always close the connection
        await graphiti.close()
        print('Connection closed')

if __name__ == '__main__':
    asyncio.run(main())
```

<Note>
  Graphiti defaults to using OpenAI for LLM inference and embeddings. Set `OPENAI_API_KEY` in your environment.
</Note>

## Step 4: Add Episodes to Your Graph

Episodes are the primary units of information in Graphiti. They can be text or structured JSON and are automatically processed to extract entities and relationships.

<Steps>
  <Step title="Define Your Episodes">
    Create a list of episodes with both text and JSON content:

    ```python theme={null}
    episodes = [
        {
            'content': 'Kamala Harris is the Attorney General of California. '
                      'She was previously the district attorney for San Francisco.',
            'type': EpisodeType.text,
            'description': 'podcast transcript',
        },
        {
            'content': 'As AG, Harris was in office from January 3, 2011 – January 3, 2017',
            'type': EpisodeType.text,
            'description': 'podcast transcript',
        },
        {
            'content': {
                'name': 'Gavin Newsom',
                'position': 'Governor',
                'state': 'California',
                'previous_role': 'Lieutenant Governor',
            },
            'type': EpisodeType.json,
            'description': 'podcast metadata',
        },
    ]
    ```
  </Step>

  <Step title="Add Episodes to the Graph">
    Process each episode and add it to your knowledge graph:

    ```python theme={null}
    import json

    for i, episode in enumerate(episodes):
        await graphiti.add_episode(
            name=f'Podcast Episode {i}',
            episode_body=episode['content'] 
                if isinstance(episode['content'], str) 
                else json.dumps(episode['content']),
            source=episode['type'],
            source_description=episode['description'],
            reference_time=datetime.now(timezone.utc),
        )
        print(f"Added episode {i}: {episode['type'].value}")
    ```

    Graphiti automatically:

    * Extracts entities (nodes) like "Kamala Harris" and "California"
    * Identifies relationships (edges) like "is Attorney General of"
    * Creates embeddings for semantic search
    * Tracks temporal information
  </Step>
</Steps>

## Step 5: Search Your Knowledge Graph

Now that you've added data, you can search for information using hybrid search that combines semantic similarity and keyword matching.

### Basic Search

Search for relationships (edges) in your graph:

```python theme={null}
print("\nSearching for: 'Who was the California Attorney General?'")
results = await graphiti.search('Who was the California Attorney General?')

# Print search results
print('\nSearch Results:')
for result in results:
    print(f'Fact: {result.fact}')
    if result.valid_at:
        print(f'Valid from: {result.valid_at}')
    if result.invalid_at:
        print(f'Valid until: {result.invalid_at}')
    print('---')
```

<Info>
  The `search()` method performs hybrid search combining:

  * Semantic similarity using embeddings
  * BM25 keyword matching
  * Graph-based retrieval
</Info>

### Graph-Aware Reranking

For more contextually relevant results, use a center node to rerank search results based on their graph distance:

```python theme={null}
if results and len(results) > 0:
    # Get the source node UUID from the top result
    center_node_uuid = results[0].source_node_uuid
    
    print(f'\nReranking with center node: {center_node_uuid}')
    
    reranked_results = await graphiti.search(
        'Who was the California Attorney General?',
        center_node_uuid=center_node_uuid
    )
    
    print('\nReranked Search Results:')
    for result in reranked_results:
        print(f'Fact: {result.fact}')
        print('---')
```

<Tip>
  Graph-based reranking prioritizes results that are closer in the graph structure to a specific node, giving you more contextually relevant information.
</Tip>

### Node Search with Recipes

Graphiti provides predefined search recipes optimized for different scenarios:

```python theme={null}
from graphiti_core.search.search_config_recipes import NODE_HYBRID_SEARCH_RRF

# Configure a node search recipe
node_search_config = NODE_HYBRID_SEARCH_RRF.model_copy(deep=True)
node_search_config.limit = 5

# Execute the node search
node_results = await graphiti._search(
    query='California Governor',
    config=node_search_config,
)

print('\nNode Search Results:')
for node in node_results.nodes:
    print(f'Node Name: {node.name}')
    print(f'Summary: {node.summary[:100]}...')
    print(f'Labels: {", ".join(node.labels)}')
    print('---')
```

## Complete Example

Here's the full working example:

```python quickstart.py theme={null}
import asyncio
import json
import os
from datetime import datetime, timezone
from dotenv import load_dotenv

from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType
from graphiti_core.search.search_config_recipes import NODE_HYBRID_SEARCH_RRF

load_dotenv()

neo4j_uri = os.environ.get('NEO4J_URI', 'bolt://localhost:7687')
neo4j_user = os.environ.get('NEO4J_USER', 'neo4j')
neo4j_password = os.environ.get('NEO4J_PASSWORD', 'password')

async def main():
    # Initialize Graphiti
    graphiti = Graphiti(neo4j_uri, neo4j_user, neo4j_password)
    
    try:
        # Define episodes
        episodes = [
            {
                'content': 'Kamala Harris is the Attorney General of California. '
                          'She was previously the district attorney for San Francisco.',
                'type': EpisodeType.text,
                'description': 'podcast transcript',
            },
            {
                'content': 'As AG, Harris was in office from January 3, 2011 – January 3, 2017',
                'type': EpisodeType.text,
                'description': 'podcast transcript',
            },
            {
                'content': {
                    'name': 'Gavin Newsom',
                    'position': 'Governor',
                    'state': 'California',
                },
                'type': EpisodeType.json,
                'description': 'podcast metadata',
            },
        ]
        
        # Add episodes
        for i, episode in enumerate(episodes):
            await graphiti.add_episode(
                name=f'Podcast Episode {i}',
                episode_body=episode['content'] 
                    if isinstance(episode['content'], str) 
                    else json.dumps(episode['content']),
                source=episode['type'],
                source_description=episode['description'],
                reference_time=datetime.now(timezone.utc),
            )
            print(f"Added episode {i}")
        
        # Search for edges
        print("\nSearching: 'Who was the California Attorney General?'")
        results = await graphiti.search('Who was the California Attorney General?')
        
        for result in results:
            print(f'Fact: {result.fact}')
            print('---')
        
        # Search with reranking
        if results:
            center_node_uuid = results[0].source_node_uuid
            reranked = await graphiti.search(
                'Who was the California Attorney General?',
                center_node_uuid=center_node_uuid
            )
            print(f'\nReranked results: {len(reranked)} found')
        
        # Node search
        node_config = NODE_HYBRID_SEARCH_RRF.model_copy(deep=True)
        node_config.limit = 5
        
        node_results = await graphiti._search(
            query='California Governor',
            config=node_config,
        )
        
        print(f'\nNode search results: {len(node_results.nodes)} found')
        for node in node_results.nodes:
            print(f'- {node.name}')
    
    finally:
        await graphiti.close()

if __name__ == '__main__':
    asyncio.run(main())
```

## Next Steps

Now that you have a working knowledge graph:

<CardGroup cols={2}>
  <Card title="Explore Different Backends" icon="database" href="/installation#graph-database-backends">
    Try FalkorDB, Kuzu, or Amazon Neptune
  </Card>

  <Card title="Use Different LLM Providers" icon="brain" href="/installation#llm-providers">
    Configure Anthropic, Google Gemini, or Ollama
  </Card>

  <Card title="Custom Entity Types" icon="code" href="/guides/custom-entities">
    Define domain-specific entities and relationships
  </Card>

  <Card title="Advanced Search" icon="magnifying-glass" href="/guides/search">
    Learn about search recipes and filtering
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Database connection errors">
    Ensure your graph database is running:

    **Neo4j**: Check Neo4j Desktop and verify your DBMS is started

    **FalkorDB**: Verify Docker container is running with `docker ps`

    **Connection refused**: Double-check URI, username, and password in your environment variables
  </Accordion>

  <Accordion title="OpenAI API errors">
    * Verify `OPENAI_API_KEY` is set correctly
    * Check you have sufficient API credits
    * Ensure you're using a supported model (defaults to `gpt-4o-mini`)
  </Accordion>

  <Accordion title="429 Rate Limit Errors">
    Graphiti defaults to low concurrency (`SEMAPHORE_LIMIT=10`) to avoid rate limits. If you still encounter 429 errors:

    ```bash theme={null}
    export SEMAPHORE_LIMIT=5
    ```

    If your LLM provider allows higher throughput, increase this value for better performance.
  </Accordion>

  <Accordion title="Graph not found errors">
    The Neo4j driver defaults to the `neo4j` database. To use a different database:

    ```python theme={null}
    from graphiti_core.driver.neo4j_driver import Neo4jDriver

    driver = Neo4jDriver(
        uri=neo4j_uri,
        user=neo4j_user,
        password=neo4j_password,
        database="your_db_name"
    )
    graphiti = Graphiti(graph_driver=driver)
    ```
  </Accordion>
</AccordionGroup>