graphiti/.serena/memories/code_structure.md

Graphiti Codebase Structure

Root Directory Layout

graphiti/
├── graphiti_core/          # Core library (main Python package)
├── server/                 # FastAPI REST API service
├── mcp_server/             # Model Context Protocol server for AI assistants
├── tests/                  # Test suite (unit and integration tests)
├── examples/               # Example implementations and use cases
├── images/                 # Documentation images and assets
├── signatures/             # CLA signatures
├── .github/                # GitHub Actions workflows
├── pyproject.toml          # Project configuration and dependencies
├── Makefile                # Development commands
├── README.md               # Main documentation
├── CLAUDE.md               # Claude Code assistant instructions
├── CONTRIBUTING.md         # Contribution guidelines
└── docker-compose.yml      # Docker configuration

Core Library (graphiti_core/)

Main Components

• graphiti.py: Main entry point containing the Graphiti class that orchestrates all functionality
• nodes.py: Core node/entity data structures
• edges.py: Core edge/relationship data structures
• graphiti_types.py: Type definitions
• errors.py: Custom exception classes
• helpers.py: Utility helper functions
• graph_queries.py: Graph query definitions
• decorators.py: Function decorators
• tracer.py: OpenTelemetry tracing support

Subdirectories

• driver/: Database drivers for Neo4j, FalkorDB, Kuzu, Neptune
• llm_client/: LLM clients for OpenAI, Anthropic, Gemini, Groq
• embedder/: Embedding clients for various providers (OpenAI, Voyage, local models)
• cross_encoder/: Cross-encoder models for reranking
• search/: Hybrid search implementation with configurable strategies
• prompts/: LLM prompts for entity extraction, deduplication, summarization
• utils/: Maintenance operations, bulk processing, datetime handling
• models/: Pydantic models for data structures
• migrations/: Database migration scripts
• telemetry/: Analytics and telemetry code

Server (server/)

• graph_service/main.py: FastAPI application entry point
• routers/: API endpoint definitions (ingestion, retrieval)
• dto/: Data Transfer Objects for API contracts
• Has its own Makefile for server-specific commands

MCP Server (mcp_server/)

• graphiti_mcp_server.py: Model Context Protocol server implementation
• docker-compose.yml: Containerized deployment with Neo4j
• Has its own pyproject.toml and dependencies

Tests (tests/)

• Unit tests: Standard pytest tests
• Integration tests: Files with _int suffix (require database connections)
• evals/: End-to-end evaluation scripts
• conftest.py: Pytest configuration and fixtures (at root level)

Key Classes

From graphiti_core/graphiti.py:

• Graphiti: Main orchestrator class
• AddEpisodeResults: Results from adding episodes
• AddBulkEpisodeResults: Results from bulk episode operations
• AddTripletResults: Results from adding triplets

Configuration Files

• pyproject.toml: Main project configuration (dependencies, build system, tool configs)
• pytest.ini: Pytest configuration
• .env.example: Example environment variables
• docker-compose.yml: Docker setup for development
• docker-compose.test.yml: Docker setup for testing