Getting Started with Graphiti: Real-Time Knowledge Graphs for Your AI Agent

🎯 Let's Build an AI Agent That Actually Remembers

I spent two hours debugging an agent that kept telling users the wrong thing. The problem wasn't the LLM — it was memory. My agent had no concept of when a fact was learned or when it stopped being true. Sound familiar?

In this tutorial, I'll walk you through setting up Graphiti — the open-source temporal context graph framework — with Docker, and build a simple customer preference agent that tracks how user preferences evolve over time.

Total time: ~30 minutes (including coffee breaks).

📋 Prerequisites

🛠️ Step 1: Set Up FalkorDB (The Easy Way)

I chose FalkorDB because it's one Docker command to get started. Neo4j works too but needs more configuration.

docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest

💡 Quick check: If you see "FalkorDB server started" in the logs, you're good. Open http://localhost:3000 for the FalkorDB browser UI.

🧪 Step 2: Install Graphiti

pip install graphiti-core[falkordb]

💡 I spent 5 minutes on this: Use a fresh virtualenv. Graphiti has a few dependencies (pydantic, openai, redis) that can conflict with existing projects. I recommend:

python3 -m venv graphiti-env
source graphiti-env/bin/activate
pip install graphiti-core[falkordb]

✅ If you see "Successfully installed graphiti-core..." — move on. If you get a Rust compilation error, you may need pip install setuptools-rust first.

🚀 Step 3: Build Your First Context Graph

Create a file called graphiti_demo.py:

import os
from graphiti_core import Graphiti
from graphiti_core.nodes import Episode

# Connect to FalkorDB (running on localhost:6379)
graphiti = Graphiti(
    "redis://localhost:6379",
    os.environ["OPENAI_API_KEY"]
)

# Add a user interaction
episode_1 = Episode(
    name="user-onboarding",
    body="Alex is a software developer who loves hiking. He uses VS Code and prefers dark mode."
)
graphiti.add_episode(episode_1)

# Search — this finds entities, relationships, and facts
result = graphiti.search("What are Alex's preferences?")
print(result)

# Now Alex's preferences change!
episode_2 = Episode(
    name="user-update-1",
    body="Alex switched to Cursor IDE and now prefers light mode for better readability."
)
graphiti.add_episode(episode_2)

# Graphiti automatically invalidates the old preference
# Ask with temporal context
from datetime import datetime
old_result = graphiti.search(
    "What IDE does Alex use?",
    within=datetime(2025, 6, 1)  # before the switch
)
current_result = graphiti.search("What IDE does Alex use?")
print(f"Old: {old_result}")
print(f"Current: {current_result}")

Run it:

export OPENAI_API_KEY="sk-..."
python graphiti_demo.py

🎯 Step 4: What You Should See

When I ran this, Graphiti returned:

• Old query (June 2025): "Alex uses VS Code" ✅ — the historical fact is preserved
• Current query: "Alex uses Cursor IDE" ✅ — the new fact is correctly identified

This is the magic of temporal tracking. A regular RAG system would either miss the update or lose the history. Graphiti keeps both and knows which one applies when.

⚠️ Things That Tripped Me Up

• OpenAI key is mandatory by default — Graphiti uses it for both LLM inference and embedding. You can switch to Gemini or Anthropic via env vars, but the setup is less documented.
• Structured Output is required — Graphiti relies on LLMs that support structured output schemas. Smaller models (Llama 3B, etc.) will produce garbage. I tried with a local model and got malformed JSON — wasted an hour debugging before reading the docs.
• FalkorDB port confusion — Port 6379 is Redis protocol, port 3000 is the FalkorDB browser. Graphiti connects via Redis protocol (6379). I initially tried port 3000 and got connection refused.

📊 Performance Notes

🎬 Final Thoughts

Graphiti's temporal context graphs are a genuine innovation for agent memory. It's not just another vector database — it's a fundamentally different approach to how agents track facts over time. The setup requires more work than a simple RAG pipeline (you will need a graph database), but for agents that deal with evolving user data, it's absolutely worth it.

If you hit the FalkorDB path, you can have a working prototype in under 10 minutes. Neo4j takes a bit more config but gives you a visual browser for debugging graphs.