graphiti - Moses Yebei

The Problem

AI agents that need up‑to‑date contextual memory must continuously ingest new facts while preserving historic state. Traditional RAG pipelines rebuild an index on every change, which is costly and loses temporal nuance. Developers need a library that can incrementally mutate a knowledge graph, expose time‑aware queries, and stay runnable inside containerised services.

What This Does

graphiti_core/ implements the graph model, drivers for Neo4j/FalkorDB/Neptune, and LLM client adapters. The driver entry point lives in graphiti_core/driver/driver.py, exposing run, __aenter__, and execute_write. High‑level orchestration is in graphiti_core/graphiti.py (initialisation, telemetry, provider selection). Example scripts such as examples/azure-openai/azure_openai_neo4j.py and examples/quickstart/quickstart_falkordb.py demonstrate end‑to‑end ingestion and query flows. A separate MCP server (mcp_server/main.py) wraps the core as a HTTP service, while server/graph_service/main.py provides a minimal GraphQL API.

How It Is Wired

Execution can start from three places:

MCP server – mcp_server/main.py creates a Graphiti instance, calls initialize_graphiti, then runs lifespan (see server/graph_service/main.py line 12) which reaches 39 functions.
Standalone example – examples/azure-openai/azure_openai_neo4j.py runs main (line 68) and traverses 371 functions, ultimately invoking execute_query → database driver.
Direct library use – importing graphiti_core/graphiti.py and calling Graphiti() executes build_indices_and_constraints → execute_query.

All routes converge on the query executor (graphiti_core/driver/query_executor.py) and the core node/edge models (graphiti_core/nodes.py, graphiti_core/edges.py). The call graph shows:

execute_query is invoked 48 × from delete, 47 × from save, and 45 × from various getter methods.
EntityNode is referenced from 67 distinct callers, making it the widest‑impact symbol.
Graphiti itself is called from 33 places, including the MCP server and example scripts.

Database interaction occurs in graphiti_core/driver/driver.py → driver‑specific execute_write → the underlying client (self.client.execute). LLM calls are routed through graphiti_core/llm_client/*_client.py, e.g., anthropic_client.py's _resolve_max_tokens. File I/O appears only in the cache (graphiti_core/llm_client/cache.py) and a few example helpers.

Circular imports involve graphiti_core/nodes.py, graphiti_core/driver/driver.py, and graphiti_core/edges.py (21 high‑risk cycles). The hub module graphiti_core/nodes.py is imported by 70 other modules, so any change there has a large blast radius.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/graphiti
cd graphiti

# Build the container (Dockerfile present)
docker build -t graphiti:latest .

# Run the MCP server (environment variables defined in .env.example)
docker run -p 8000:8000 --env-file .env.example graphiti:latest \
    python -m mcp_server.main

For a quick local test without Docker, install the core with UV (pinning required by pyproject.toml):

uv pip install -e .
python examples/quickstart/quickstart_falkordb.py

The examples expect a running Neo4j/FalkorDB instance; connection strings are read from the .env.example files in each example folder.

Real‑World Use

A customer building a conversational sales assistant can run the MCP server alongside their product catalog DB. Each new chat turn is sent to /ingest (router in server/graph_service/routers/ingest.py), which creates EntityNode and EntityEdge objects, stores them via the Neo4j driver, and immediately makes them searchable through /search. Temporal queries (e.g., “what did the user say last week?”) are answered without re‑indexing the whole graph.

Code Health & Issues

Critical – Privileged PR checkout – .github/workflows/release-server-container.yml checks out PR code with repository secrets.
Critical – Secrets in PR‑triggered workflow – same file exposes DOCKERHUB_USERNAME/TOKEN.
High – Pin third‑party actions – actions referenced by tag (e.g., astral-sh/setup-uv@v3).
Medium – Base image not pinned – Dockerfile uses python:3.12-slim without digest.
Medium – No dependency‑vulnerability scan – CI lacks a dependency-review-action.
Medium – Large binary in repo – tests/evals/data/longmemeval_oracle.json (14.7 MiB).
Low – Missing job timeouts – .github/workflows/codeql.yml lacks timeout-minutes.

Measured static analysis also uncovered:

Import cycle (high) – graphiti_core/nodes.py, driver/driver.py, edges.py.
Deep nesting (high) – up to 7‑level indentation in nodes.py.
Oversized file (high) – nodes.py > 900 lines.
Hub module (high) – nodes.py imported by 70 modules.
Broad exception handling (medium) – generic except: in graphiti.py.
Duplicated code blocks (high) – identical 6‑line snippets across multiple examples.

The Bottom Line

Graphiti supplies a concrete Python stack for real‑time, temporally aware knowledge graphs, with ready‑made drivers and an MCP server. The code base is functional but suffers from high coupling (import cycles, hub modules) and several security‑related CI misconfigurations that must be fixed before production use. Teams comfortable with Python, Docker, and Neo4j‑style graphs will find the library usable after addressing the highlighted health concerns.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

326 files

Python236
YAML25
Markdown21
JSON5
TOML4
Jupyter Notebook2

DockerLangChainNeo4j

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["graphiti_core 151 modules"] g1["tests 33 modules"] g2["mcp_server 28 modules"] g3["examples 11 modules"] g4["server 11 modules"] g1 -->|97| g0 g3 -->|34| g0 g2 -->|22| g0 g4 -->|8| g0

Module dependencies

The 10 most depended-upon modules of 235, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_graphiti_core_nodes["nodes"] n1_graphiti_core_driver_driver["driver"] n2_i_core_driver_query_executor["query_executor"] n3_graphiti_core_edges["edges"] n4_graphiti_core_errors["errors"] n5_graphiti_core_helpers["helpers"] n6_models_nodes_node_db_queries["node_db_queries"] n7_models_edges_edge_db_queries["edge_db_queries"] n8_i_core_driver_record_parsers["record_parsers"] n9_phiti_core_llm_client_config["config"] n1_graphiti_core_driver_driver --> n2_i_core_driver_query_executor n8_i_core_driver_record_parsers --> n3_graphiti_core_edges n8_i_core_driver_record_parsers --> n5_graphiti_core_helpers n8_i_core_driver_record_parsers --> n0_graphiti_core_nodes n3_graphiti_core_edges --> n1_graphiti_core_driver_driver n3_graphiti_core_edges --> n4_graphiti_core_errors n3_graphiti_core_edges --> n5_graphiti_core_helpers n3_graphiti_core_edges --> n7_models_edges_edge_db_queries n3_graphiti_core_edges --> n0_graphiti_core_nodes n5_graphiti_core_helpers --> n1_graphiti_core_driver_driver n5_graphiti_core_helpers --> n4_graphiti_core_errors n7_models_edges_edge_db_queries --> n1_graphiti_core_driver_driver n6_models_nodes_node_db_queries --> n1_graphiti_core_driver_driver n0_graphiti_core_nodes --> n1_graphiti_core_driver_driver n0_graphiti_core_nodes --> n4_graphiti_core_errors n0_graphiti_core_nodes --> n5_graphiti_core_helpers n0_graphiti_core_nodes --> n6_models_nodes_node_db_queries classDef cyc stroke:#ef4444,stroke-width:2px; class n0_graphiti_core_nodes,n1_graphiti_core_driver_driver,n3_graphiti_core_edges,n5_graphiti_core_helpers,n6_models_nodes_node_db_queries,n7_models_edges_edge_db_queries cyc;

Findings

LowDependencies declared without a lockfile - non-reproducible builds examples/opentelemetry/pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

critical2

high1

medium3

low1

Do not check out pull request code in a privileged workflowcritical

.github/workflows/release-server-container.yml

privileged trigger checks out the untrusted ref

This is the most reliably exploited Actions pattern: anyone opening a pull request gets code execution with your repository secrets.

Fix: Split into an unprivileged pull_request build and a workflow_run job that only consumes its artifact.

Keep secrets out of workflows a fork can triggercritical2 occurrences

.github/workflows/release-server-container.yml

DOCKERHUB_USERNAME, DOCKERHUB_TOKEN (publish or cloud scope)

Contributor-controlled input reaches a job holding a publish token or cloud credential, so a pull request becomes credential exfiltration.

Fix: Move secret-using steps into a workflow_run job that never checks out pull request code, or gate on an environment with required reviewers.

Pin third-party GitHub Actions to a commit SHAhigh6 occurrences

.github/workflows

astral-sh/setup-uv@v3, pypa/gh-action-pypi-publish@release/v1, docker/login-action@v3, depot/setup-action@v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Pin the container base image by digestmedium

Dockerfile

python:3.12-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium

tests/evals/data/longmemeval_data/longmemeval_oracle.json

1 blobs over 5MB: longmemeval_oracle.json 14.7MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/codeql.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.