cb4e187aed
* Implement telemetry feature for anonymous usage statistics collection in Graphiti; update Dockerfile CMD format for better signal handling; adjust Neo4j URI and healthcheck in docker-compose.yml; add new dependencies in pyproject.toml and poetry.lock. * remove duplicated properties * Update Dockerfile CMD to use JSON array format for improved signal handling * remove tommlib dep only in 3.11 * Delete server/graph_service/logging_config.py
133 lines
4.2 KiB
Markdown
133 lines
4.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Graphiti is a Python framework for building temporally-aware knowledge graphs designed for AI agents. It enables real-time incremental updates to knowledge graphs without batch recomputation, making it suitable for dynamic environments.
|
|
|
|
Key features:
|
|
|
|
- Bi-temporal data model with explicit tracking of event occurrence times
|
|
- Hybrid retrieval combining semantic embeddings, keyword search (BM25), and graph traversal
|
|
- Support for custom entity definitions via Pydantic models
|
|
- Integration with Neo4j and FalkorDB as graph storage backends
|
|
|
|
## Development Commands
|
|
|
|
### Main Development Commands (run from project root)
|
|
|
|
```bash
|
|
# Install dependencies
|
|
uv sync --extra dev
|
|
|
|
# Format code (ruff import sorting + formatting)
|
|
make format
|
|
|
|
# Lint code (ruff + mypy type checking)
|
|
make lint
|
|
|
|
# Run tests
|
|
make test
|
|
|
|
# Run all checks (format, lint, test)
|
|
make check
|
|
```
|
|
|
|
### Server Development (run from server/ directory)
|
|
|
|
```bash
|
|
cd server/
|
|
# Install server dependencies
|
|
uv sync --extra dev
|
|
|
|
# Run server in development mode
|
|
uvicorn graph_service.main:app --reload
|
|
|
|
# Format, lint, test server code
|
|
make format
|
|
make lint
|
|
make test
|
|
```
|
|
|
|
### MCP Server Development (run from mcp_server/ directory)
|
|
|
|
```bash
|
|
cd mcp_server/
|
|
# Install MCP server dependencies
|
|
uv sync
|
|
|
|
# Run with Docker Compose
|
|
docker-compose up
|
|
```
|
|
|
|
## Code Architecture
|
|
|
|
### Core Library (`graphiti_core/`)
|
|
|
|
- **Main Entry Point**: `graphiti.py` - Contains the main `Graphiti` class that orchestrates all functionality
|
|
- **Graph Storage**: `driver/` - Database drivers for Neo4j and FalkorDB
|
|
- **LLM Integration**: `llm_client/` - Clients for OpenAI, Anthropic, Gemini, Groq
|
|
- **Embeddings**: `embedder/` - Embedding clients for various providers
|
|
- **Graph Elements**: `nodes.py`, `edges.py` - Core graph data structures
|
|
- **Search**: `search/` - Hybrid search implementation with configurable strategies
|
|
- **Prompts**: `prompts/` - LLM prompts for entity extraction, deduplication, summarization
|
|
- **Utilities**: `utils/` - Maintenance operations, bulk processing, datetime handling
|
|
|
|
### Server (`server/`)
|
|
|
|
- **FastAPI Service**: `graph_service/main.py` - REST API server
|
|
- **Routers**: `routers/` - API endpoints for ingestion and retrieval
|
|
- **DTOs**: `dto/` - Data transfer objects for API contracts
|
|
|
|
### MCP Server (`mcp_server/`)
|
|
|
|
- **MCP Implementation**: `graphiti_mcp_server.py` - Model Context Protocol server for AI assistants
|
|
- **Docker Support**: Containerized deployment with Neo4j
|
|
|
|
## Testing
|
|
|
|
- **Unit Tests**: `tests/` - Comprehensive test suite using pytest
|
|
- **Integration Tests**: Tests marked with `_int` suffix require database connections
|
|
- **Evaluation**: `tests/evals/` - End-to-end evaluation scripts
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
- `OPENAI_API_KEY` - Required for LLM inference and embeddings
|
|
- `USE_PARALLEL_RUNTIME` - Optional boolean for Neo4j parallel runtime (enterprise only)
|
|
- Provider-specific keys: `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `GROQ_API_KEY`, `VOYAGE_API_KEY`
|
|
|
|
### Database Setup
|
|
|
|
- **Neo4j**: Version 5.26+ required, available via Neo4j Desktop
|
|
- **FalkorDB**: Version 1.1.2+ as alternative backend
|
|
|
|
## Development Guidelines
|
|
|
|
### Code Style
|
|
|
|
- Use Ruff for formatting and linting (configured in pyproject.toml)
|
|
- Line length: 100 characters
|
|
- Quote style: single quotes
|
|
- Type checking with MyPy is enforced
|
|
|
|
### Testing Requirements
|
|
|
|
- Run tests with `make test` or `pytest`
|
|
- Integration tests require database connections
|
|
- Use `pytest-xdist` for parallel test execution
|
|
|
|
### LLM Provider Support
|
|
|
|
The codebase supports multiple LLM providers but works best with services supporting structured output (OpenAI, Gemini). Other providers may cause schema validation issues, especially with smaller models.
|
|
|
|
### MCP Server Usage Guidelines
|
|
|
|
When working with the MCP server, follow the patterns established in `mcp_server/cursor_rules.md`:
|
|
|
|
- Always search for existing knowledge before adding new information
|
|
- Use specific entity type filters (`Preference`, `Procedure`, `Requirement`)
|
|
- Store new information immediately using `add_memory`
|
|
- Follow discovered procedures and respect established preferences
|