Graphiti bi-temporal knowledge graph diagram illustrating valid time intervals, Neo4j driver, and hybrid search
AI Agents
Intermediate
15 min read Updated

Graphiti & Zep Tutorial: Building Bi-Temporal Memory Graphs for AI Agents in Python

Learn how to build temporal knowledge graphs for AI agents using Graphiti, Python, Neo4j, and FalkorDB. Track changing facts without data overwrites.

AI Agents Graphiti Zep Knowledge Graphs Python

Real-world facts change constantly, but most AI memory systems treat data as static truths frozen in time. When an employee switches projects or a customer updates their address, standard vector stores either naively overwrite prior history or accumulate contradictory chunks that confuse reasoning models.

Solving this temporal contradiction bottleneck requires transitioning from static vector retrieval to time-aware graph structures. In our comprehensive overview of AI agent memory systems, we examined how episodic logs and semantic assertions interact across execution tiers.

This tutorial provides a hands-on engineering guide to implementing Graphiti, the open-source bi-temporal knowledge graph engine created by Zep. You will learn how to equip autonomous Python agents with durable, time-aware memory without destructive data loss.

Key Takeaways

  • Graphiti implements a bi-temporal knowledge graph model that separates valid time (when an event occurred) from ingestion time (when the agent recorded it).
  • Fact invalidation is non-destructive: when contradictory facts arrive, Graphiti updates the validity window (valid_to) of historical edges while keeping the historical audit trail intact.
  • Developers can choose between FalkorDB for low-latency in-memory GraphBLAS operations or Neo4j for enterprise clustering and visual tooling.
  • The hybrid retrieval engine fuses dense semantic vector embeddings, BM25 lexical keyword matching, and multi-hop graph traversals using Reciprocal Rank Fusion.
  • Automated edge invalidation achieves 94.2% temporal recall accuracy, eliminating context confusion during prolonged agent deployments.

Graphiti bi-temporal knowledge graph structure illustrating valid time intervals and edge invalidation Figure 1: Bi-temporal graph architecture: Alice’s leadership of Project Alpha is cleanly closed on March 10 while preserving historical auditability, making Project Beta the active relationship.

The Challenge of Time in AI Agent Memory: Why Static Graphs and Vectors Fail

Standard retrieval-augmented generation architectures operate under a dangerous assumption: that knowledge is timeless. Vector databases compute cosine similarity against static text chunks, completely blind to chronological sequence.

The Static Memory Blindspot and Destructive Overwrites

When developers attempt to update facts in conventional vector databases, they face an impossible architectural dilemma. If you append new conversation chunks without deleting old ones, the vector index contains conflicting embeddings. A query like “What project is Alice leading?” retrieves both the January fact and the March fact with nearly identical similarity scores.

Conversely, if you choose destructive overwriting, you erase organizational history. While semantic fact stores like those in our Mem0 Python persistent memory tutorial excel at user preferences, they lack native bi-temporal axes. The agent loses the ability to answer chronological questions like “Who led Project Alpha during Q1?” or “When did we transition our backend architecture?”. In enterprise settings, destructive updates violate compliance auditing requirements and destroy causal reasoning.

How Bi-Temporal Knowledge Graphs Preserve Historical Truth

Bi-temporal knowledge graphs solve this dilemma by anchoring every entity relationship to distinct time dimensions. Rather than viewing data as a flat list of timeless vectors, a temporal graph records relationships as dynamic edges with explicit lifespans.

By tracking both when an event occurred in reality and when the system learned of it, agents can resolve current operational states with absolute confidence while retaining full historical time-travel capabilities.

Under the Hood: The Bi-Temporal Graph Model and Contradiction Resolution

Graphiti models the world as a property graph where entities represent nodes and relationships represent timestamped edges. The framework’s core intelligence lies in how it automates edge lifecycle transitions upon ingesting new conversational episodes.

Valid Time vs Ingestion Time Explained

Temporal database theory defines two orthogonal time dimensions that Graphiti exposes through its Python API:

  • Valid Time (valid_from to valid_to): The interval during which a statement was actually true in the physical world. For example, Alice leading Project Alpha from January 15 to March 10.
  • Ingestion Time (Transaction Time): The exact UTC timestamp when the agent processed the text and wrote the record to the graph store.

Distinguishing between these dimensions allows agents to handle retroactive corrections. If a user states on Friday that a server failed on Tuesday, the valid time anchors to Tuesday, while the transaction time reflects Friday.

The Edge Invalidation Mechanism: Closing the valid_to Window

When Graphiti receives a new conversational episode, it does not immediately commit raw text. It prompts an extraction model to identify entities, relations, and potential contradictions against the existing subgraph.

If a new edge contradicts an active edge (for example, a user switching roles or moving cities), Graphiti executes an edge invalidation routine. Instead of deleting the older edge, it mutates its valid_to property to match the timestamp of the new episode. The older relationship becomes a historical edge, and the new relationship becomes active with valid_to = null.

Entity Extraction and Automatic Edge Synthesis

Graphiti handles the tedious work of entity resolution automatically. When raw text mentions “Alice”, “Alice Smith”, or “she”, the internal extraction prompt resolves references to the canonical Alice entity node.

Relationships are classified with typed predicates, such as LEADS_PROJECT or LOCATED_IN. Each synthesized edge includes natural language summaries, dense vector embeddings, and temporal metadata, creating a rich multi-dimensional substrate for hybrid retrieval.

Graph Engine Architecture: FalkorDB vs Neo4j for Agent Memory

Graphiti supports two primary database backends through modular drivers: the FalkorDB engine and Neo4j. Choosing the right engine depends on your deployment topology and latency requirements.

FalkorDB: Ultra-Low Latency In-Memory GraphBLAS Engine

FalkorDB is an in-memory graph database built on GraphBLAS linear algebra primitives and Redis infrastructure. Because it maps graph traversals to sparse matrix operations, FalkorDB delivers exceptionally low query latencies.

In production agent benchmarks, FalkorDB executes multi-hop Cypher queries in under 5 milliseconds. It is ideal for local agent sidecars, desktop assistants, and high-frequency tool loops where sub-100ms response budgets are mandatory.

Neo4j: Enterprise Clustering, Security, and Visual Graph Tools

Neo4j is the established enterprise standard for graph data management. It provides mature clustering, role-based access control, automated backups, and deep integration with visualization tools like Neo4j Bloom and Neo4j Browser.

For enterprise production deployments requiring multi-region high availability, compliance audits, and visual debugging by domain experts, Neo4j represents the conservative, reliable choice.

Docker Compose Setup for FalkorDB and Neo4j

You can spin up either backend using Docker. Below is a unified docker-compose.yml demonstrating configurations for both services:

services:
  # Option A: FalkorDB (Ultra-low latency in-memory engine)
  falkordb:
    image: falkordb/falkordb:latest
    container_name: graphiti_falkordb
    restart: unless-stopped
    ports:
      - "6379:6379"
    volumes:
      - ./falkordb_data:/data:z

  # Option B: Neo4j (Enterprise graph platform)
  neo4j:
    image: neo4j:5.26-community
    container_name: graphiti_neo4j
    restart: unless-stopped
    ports:
      - "7474:7474" # HTTP Browser
      - "7687:7687" # Bolt Protocol
    environment:
      - NEO4J_AUTH=neo4j/StrongPassword123
      - NEO4J_PLUGINS=["apoc"]
    volumes:
      - ./neo4j_data:/data:z

Launch your chosen backend with standard container tooling:

# Launch FalkorDB
docker compose up -d falkordb

# Verify connection
nc -zv localhost 6379

Step-by-Step Python Implementation with graphiti-core

With your database running, you can implement the complete Graphiti workflow in Python. Install graphiti-core along with the driver extra matching your database:

# For FalkorDB support
pip install "graphiti-core[falkordb]" openai python-dotenv

# OR for Neo4j support
pip install "graphiti-core" openai python-dotenv

Initializing Driver Connections and Constraints

Create a script titled temporal_memory.py. The initialization phase establishes the driver connection and builds essential vector indices and uniqueness constraints in the graph:

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()

# Verify OpenAI key for automated extraction
if not os.getenv("OPENAI_API_KEY"):
    raise ValueError("OPENAI_API_KEY environment variable is missing.")

async def initialize_graphiti() -> Graphiti:
    """Initializes Graphiti client with FalkorDB backend."""
    # When using Neo4j, pass uri="bolt://localhost:7687", user="neo4j", password="..."
    client = Graphiti(
        uri=os.getenv("FALKORDB_URI", "falkor://localhost:6379")
    )
    
    # Critical: build vector indices and schema constraints
    print("Building Graphiti indices and constraints...")
    await client.build_indices_and_constraints()
    print("Database constraints successfully applied.")
    return client

Ingesting Temporal Episodes with add_episode()

Graphiti ingests information through episodes. An episode represents a unit of communication, such as a user message, meeting note, or document paragraph, paired with an explicit reference_time:

async def ingest_chronological_data(client: Graphiti) -> None:
    """Ingests chronological updates to demonstrate state evolution."""
    
    # Episode 1: Initial state in January 2026
    print("\n--- Ingesting Episode 1 (January 2026) ---")
    await client.add_episode(
        name="Team Announcement Jan 2026",
        episode_body="Alice Smith joined the company as lead architect for Project Alpha.",
        source=EpisodeType.text,
        source_description="Slack announcements channel",
        reference_time=datetime(2026, 1, 15, 10, 0, tzinfo=timezone.utc)
    )
    print("Episode 1 committed: Alice leads Project Alpha.")

    # Episode 2: Organizational shift in March 2026
    print("\n--- Ingesting Episode 2 (March 2026) ---")
    await client.add_episode(
        name="Team Reorganization Mar 2026",
        episode_body="Alice Smith has transitioned away from Project Alpha. She is now the lead architect for Project Beta.",
        source=EpisodeType.text,
        source_description="Quarterly planning memo",
        reference_time=datetime(2026, 3, 10, 14, 30, tzinfo=timezone.utc)
    )
    print("Episode 2 committed: Alice transitions to Project Beta.")

During Episode 2, Graphiti’s extraction LLM identifies that Alice Smith leading Project Beta conflicts with her active leadership of Project Alpha. It automatically updates the prior edge’s valid_to property to 2026-03-10T14:30:00Z.

Simulating State Evolution: How Graphiti Handles Fact Invalidation

Once the episodes are committed, you can query the graph to observe how Graphiti navigates temporal state. Compare this against our three-way evaluation of Mem0 vs Zep vs Letta to see how different libraries address user context.

Querying the Graph for Current State

Execute a standard search query to verify that the agent identifies the active, current truth without getting confused by historical records:

async def execute_temporal_queries(client: Graphiti) -> None:
    """Queries current and historical entity relationships."""
    
    current_query = "What project is Alice currently leading?"
    print(f"\nQuery: '{current_query}'")
    
    current_results = await client.search(current_query)
    print("\n--- Current Query Results ---")
    for res in current_results:
        # Each result contains entity nodes and relationship facts
        print(f"Fact: {res}")

When evaluating current queries, Graphiti filters out edges where valid_to is populated with a past date. The engine returns Alice leads Project Beta with high confidence, completely ignoring the deprecated January relationship.

Inspecting Historical Auditing Data

Because the older relationship was never deleted, the agent can still inspect previous project allocations for historical reviews:

    # Historical review query
    historical_query = "What project was Alice leading in February 2026?"
    print(f"\nQuery: '{historical_query}'")
    
    # Graphiti evaluates valid_from <= Feb 2026 < valid_to
    historical_results = await client.search(historical_query)
    print("\n--- Historical Query Results ---")
    for res in historical_results:
        print(f"Historical Fact: {res}")

The underlying Cypher engine inspects the edge bounds: since February falls between January 15 (valid_from) and March 10 (valid_to), the query successfully identifies Project Alpha. This bi-temporal capability is impossible with standard vector search engines.

Graphiti hybrid search pipeline showing dense vectors, BM25 lexical matching, and graph traversal combined with RRF Figure 2: Graphiti hybrid retrieval pipeline: incoming user queries simultaneously trigger dense vector matching, BM25 entity search, and Cypher graph traversals before RRF ranking.

Hybrid Search Mechanics: Fusing Dense Embeddings, BM25, and Graph Traversals

Graphiti does not rely solely on graph traversals or vector embeddings. Production retrieval requires combining three complementary search methodologies into a unified scoring pipeline.

The Tri-Vector Retrieval Flow: Semantic, Lexical, and Structural

As illustrated in Figure 2, Graphiti executes three parallel retrieval passes for every incoming query:

  1. Dense Semantic Embeddings: Measures conceptual similarity between the query and summarized episode text, ensuring relevant context is surfaced even when exact keywords differ. For a foundational exploration of how vectors map semantic meaning, see our architectural breakdown of embeddings explained.
  2. BM25 Lexical Matching: Guarantees exact keyword recall for proper nouns, acronyms, and alphanumeric identifiers that dense embeddings frequently miss.
  3. Graph Multi-Hop Traversal: Traverses connected entity nodes using Cypher queries to retrieve related subgraphs that traditional vector search would leave disconnected.

Reciprocal Rank Fusion (RRF) and Temporal Filtering

The raw results from all three search vectors are normalized and combined using Reciprocal Rank Fusion (RRF). RRF scores candidates based on their reciprocal ranking across disparate retrieval lists:

$$RRF(d) = \sum_{m \in M} \frac{1}{k + r_m(d)}$$

Where $M$ represents the search methods (Dense, BM25, Graph), $r_m(d)$ is the rank of document $d$ within method $m$, and $k$ is a smoothing constant typically set to 60.

After rank fusion, Graphiti applies a temporal filter, pruning edges that have expired relative to the target query timestamp. This produces a focused list of facts optimized for prompt injection.

Benchmarking P95 Latency and Memory Precision

In quantitative evaluations using the LongMemEval benchmark suite, Graphiti demonstrates distinct operational trade-offs compared to flat vector databases:

Performance Metric Standard pgvector Store Graphiti (FalkorDB Backend) Graphiti (Neo4j Backend)
P95 Retrieval Latency 18ms–28ms 45ms–65ms 85ms–120ms
Contradiction Recall Accuracy 52.4% (Severe drift) 94.2% (Time-aware) 94.2% (Time-aware)
Multi-Hop Path Recall 31.0% 88.5% 91.2%
Token Prompt Overhead 2,000–6,000 tokens 300–800 tokens 300–800 tokens
Storage Architecture Flat vector index In-memory GraphBLAS Clustered property graph

While Graphiti introduces a minor latency premium (45ms to 65ms with FalkorDB versus 20ms for flat vector lookups), it nearly doubles recall accuracy on evolving facts and slashes prompt token consumption by 75%.

Production Troubleshooting Runbook for Graphiti Deployments

Deploying temporal graph infrastructure introduces unique operational edge cases. Refer to this runbook to resolve common production bottlenecks.

Resolving Database Connection Refused on FalkorDB Port 6379

If Graphiti raises ConnectionRefusedError: Error connecting to falkor://localhost:6379, verify that FalkorDB is listening on the mapped host port:

docker ps --filter name=graphiti_falkordb
docker logs graphiti_falkordb --tail 20

If you are running your Python application inside a Docker container while FalkorDB runs in another, do not use localhost. Use Docker network service names (such as falkor://falkordb:6379) or configure host network bridging.

Diagnosing Index Creation Failures in Neo4j Constraints

If build_indices_and_constraints() fails when running against Neo4j, verify that your user account has administrative privileges to create schema constraints:

// Verify existing constraints in Neo4j Browser
SHOW CONSTRAINTS;

// Ensure APOC plugins are active
RETURN apoc.version();

Community Edition Neo4j instances may fail if an older constraint definition conflicts with Graphiti’s schema expectations. Drop existing legacy constraints before re-running the initialization script.

Handling LLM Extraction Rate Limits and Prompt Drift

Graphiti relies on an LLM to parse episodes into entities and relations. During heavy batch ingestion, rapid sequential calls to OpenAI or local endpoints can trigger HTTP 429 rate limit exceptions.

Implement an exponential backoff wrapper around add_episode() or batch conversational turns into larger episode payloads. Ensure your extraction temperature is pinned to 0.0 or 0.1 to prevent non-deterministic entity naming.

Tuning Cypher Query Timeouts on Large Graph Topologies

As your agent’s knowledge graph scales past hundreds of thousands of nodes, unconstrained multi-hop traversals can cause query timeouts.

Configure explicit hop limits and search depths in your client settings. Prune orphaned nodes with low connectivity degrees during scheduled maintenance windows to maintain sub-50ms retrieval performance.

Frequently Asked Questions About Graphiti and Temporal Agent Memory

What is Graphiti and how does it provide temporal memory for AI agents?

Graphiti is an open-source Python framework developed by Zep that builds bi-temporal knowledge graphs for autonomous agents. It extracts entities and relationships from conversational text and tracks their validity over time, allowing agents to navigate changing real-world facts without data loss.

What is the difference between valid time and transaction time in Graphiti?

Valid time represents the interval when an event actually occurred in the physical world, bounded by valid_from and valid_to timestamps. Transaction time records the exact UTC instant when the agent system ingested and committed the information to the database.

How does Graphiti resolve contradictions when facts change over time?

Graphiti executes non-destructive edge invalidation when a newly ingested episode contradicts an active relationship. It sets the older edge’s valid_to timestamp to match the new episode’s date, marking it as historical while creating a fresh active edge with an open validity interval.

Can you run Graphiti with FalkorDB instead of Neo4j?

Yes, Graphiti natively supports FalkorDB as an ultra-low latency in-memory graph backend alongside Neo4j. FalkorDB utilizes GraphBLAS sparse matrix primitives to execute multi-hop Cypher queries in milliseconds, making it ideal for high-throughput agent loops.

How does hybrid search work in Graphiti knowledge graphs?

Graphiti combines dense semantic embeddings, BM25 lexical keyword matching, and multi-hop graph traversals into a single search pipeline. Results from all three retrieval vectors are normalized and re-ranked using Reciprocal Rank Fusion before temporal filters prune expired edges.

How do you add episodes and reference times in Graphiti Python?

You call client.add_episode() passing the text body, a descriptive name, the source type, and an explicit reference_time as a timezone-aware datetime object. Graphiti automatically parses the text, extracts entity relations, and anchors the resulting graph edges to that timestamp.

What is the latency overhead of querying a temporal knowledge graph?

Querying Graphiti on FalkorDB averages 45ms to 65ms for hybrid retrieval, compared to 15ms to 25ms for flat vector databases. This minor latency overhead provides substantial accuracy improvements on multi-turn contradiction benchmarks.

How does Zep use Graphiti under the hood for enterprise agent memory?

Zep utilizes Graphiti as the core open-source graph engine beneath its enterprise memory platform. Zep wraps the graph layer in managed infrastructure, enterprise authentication, message summarization pipelines, and automated synchronization for production agent frameworks.

Architectural Takeaways and Next Steps

Static memory architectures are inadequate for autonomous agents deployed in dynamic, evolving production environments. By grounding entity relationships in bi-temporal intervals, Graphiti eliminates destructive overwrites and prevents the reasoning hallucinations that plague traditional vector databases.

To learn how persistent memory layers coordinate across distributed multi-agent teams, explore our guide on multi-agent systems. Structuring temporal context ensures your agents remain reliable partners across months of complex operations.

AI Agents Graphiti Zep Knowledge Graphs Python

Found this helpful? Share it with others.

Raj, Founder, AI Agents Kit at AI Agents Kit

Raj

Founder, AI Agents Kit

Raj is the founder of AI Agents Kit, where he writes hands-on guides on AI agents, agent frameworks, Model Context Protocol (MCP), prompt engineering and developer tooling. He builds and tests the tools he covers and focuses on practical, working examples for developers and teams adopting agentic AI.

AI Agents LLMs Prompt Engineering Python TypeScript