{"owner":"getzep","repo":"graphiti","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md"],"skills":{"AGENTS.md":"# Repository Guidelines\n\n## Project Structure & Module Organization\nGraphiti's core library lives under `graphiti_core/`, split into domain modules such as `nodes.py`, `edges.py`, `models/`, and `search/` for retrieval pipelines. Database drivers in `graphiti_core/driver/` support Neo4j, FalkorDB, and Neptune (plus a deprecated Kuzu driver). Additional core modules include `cross_encoder/` (reranking via BGE, OpenAI, and Gemini), `telemetry/` (OpenTelemetry tracing), `namespaces/` (namespace management), and `migrations/` (database migrations). Service adapters and API glue reside in `server/graph_service/`, while the MCP integration lives in `mcp_server/` (with its own `src/`, `tests/`, `config/`, and `docker/` subdirectories). Shared assets sit in `images/` and `examples/`. Tests cover the core package via `tests/`, with configuration in `conftest.py`, `pytest.ini`, and Docker compose files for optional services. Specifications live in `spec/` and type signatures in `signatures/`. Tooling manifests live at the repo root, including `pyproject.toml`, `Makefile`, and deployment compose files.\n\n## Build, Test, and Development Commands\n- `make install`: install the dev environment (`uv sync --extra dev`).\n- `make format`: run `ruff` to sort imports and apply the canonical formatter.\n- `make lint`: execute `ruff` plus `pyright` type checks against `graphiti_core`.\n- `make test`: run unit tests only, excluding integration tests and disabling non-Neo4j drivers (`DISABLE_FALKORDB=1 DISABLE_KUZU=1 DISABLE_NEPTUNE=1 uv run pytest -m \"not integration\"`).\n- `make check`: run format, lint, and test in sequence.\n- `uv run pytest tests/path/test_file.py`: target a specific module or test selection.\n- `docker-compose -f docker-compose.test.yml up`: provision local graph/search dependencies for integration flows.\n\n## Coding Style & Naming Conventions\nPython code uses 4-space indentation, 100-character lines, and prefers single quotes as configured in `pyproject.toml`. Modules, files, and functions stay snake_case; Pydantic models in `graphiti_core/models` use PascalCase with explicit type hints. Keep side-effectful code inside drivers or adapters (`graphiti_core/driver`, `graphiti_core/cross_encoder`, `graphiti_core/utils`) and rely on pure helpers elsewhere. Run `make format` before committing to normalize imports and docstring formatting.\n\n## Testing Guidelines\nAuthor tests alongside features under `tests/`, naming files `test_<feature>.py` and functions `test_<behavior>`. Integration test files use the `_int` suffix (e.g., `test_edge_int.py`, `test_node_int.py`). Use `@pytest.mark.integration` for database-reliant scenarios so CI can gate them; `make test` excludes these by default. Async tests run automatically via `asyncio_mode = auto` in `pytest.ini`. Reproduce regressions with a failing test first and validate fixes via `uv run pytest -k \"pattern\"`. Start required backing services through `docker-compose.test.yml` when running integration suites locally. The `mcp_server/` has its own separate test suite under `mcp_server/tests/`.\n\n## Commit & Pull Request Guidelines\nCommits use an imperative, present-tense summary (for example, `add async cache invalidation`) optionally suffixed with the PR number as seen in history (`(#927)`). Squash fixups and keep unrelated changes isolated. Pull requests should include: a concise description, linked tracking issue, notes about schema or API impacts, and screenshots or logs when behavior changes. Confirm `make lint` and `make test` pass locally, and update docs or examples when public interfaces shift.\n\n## Cursor Cloud specific instructions\n\nDependencies are installed by the startup update script (`uv sync` in the repo root, `server/`, and `mcp_server/`). `uv` lives at `~/.local/bin`; if it is not on `PATH`, prefix commands with `PATH=\"$HOME/.local/bin:$PATH\"`. Set `GRAPHITI_TELEMETRY_ENABLED=false` when running anything to avoid PostHog network calls.\n\n### Graph databases (Neo4j + FalkorDB via Docker)\nDocker has no systemd here — start the daemon manually once per VM: `sudo dockerd > /tmp/dockerd.log 2>&1 &`. Then start the DBs on the host network exactly as CI does (see `.github/workflows/unit_tests.yml`):\n- `sudo docker run -d --name falkordb --network host falkordb/falkordb:latest` (port 6379)\n- `sudo docker run -d --name neo4j --network host -e NEO4J_AUTH=neo4j/testpass -e NEO4J_PLUGINS='[\"apoc\"]' neo4j:5.26-community` (bolt 7687, http 7474)\n\n### Tests (non-obvious)\n- `make test` does NOT set `DISABLE_NEO4J`, so the `graph_driver` fixture stays parametrized on Neo4j and the suite REQUIRES a reachable Neo4j at `bolt://localhost:7687`. With no Neo4j, those tests hang on the driver's connection retry (not an env bug). Run it as `NEO4J_PASSWORD=testpass make test`.\n- `tests/test_add_triplet.py` has pre-existing failures (its mock embedder doesn't stub `create_batch`, so `zip(strict=True)` raises). CI never runs this file, so ignore those 11 failures — they are unrelated to environment setup.\n- The authoritative, fully-green no-DB unit gate is the CI command in `.github/workflows/unit_tests.yml` (`DISABLE_NEO4J=1 DISABLE_FALKORDB=1 DISABLE_KUZU=1 DISABLE_NEPTUNE=1` plus the `--ignore` list). The DB-backed unit tests are the `database-integration-tests` job in the same file (needs Neo4j + FalkorDB, uses mock LLMs, no API key).\n- `server/` and `mcp_server/` test suites are live end-to-end tests marked `integration`; they self-skip with exit code 5 when `OPENAI_API_KEY` is unset. This skip is expected, not a failure.\n\n### Running the services (dev mode)\nAll three run without a valid OpenAI key for startup/health only; real ingest/search (LLM extraction + embeddings) needs a real `OPENAI_API_KEY`.\n- REST API (`server/`): `OPENAI_API_KEY=<placeholder-or-real> DB_BACKEND=falkordb FALKORDB_HOST=localhost FALKORDB_PORT=6379 uv run uvicorn graph_service.main:app --reload --port 8000`. Health at `/healthcheck`, Swagger at `/docs`. `Settings` requires `OPENAI_API_KEY` to be present (any value) or startup fails.\n- MCP server (`mcp_server/`): `OPENAI_API_KEY=<...> FALKORDB_URI=redis://localhost:6379 uv run python main.py --transport http --host 0.0.0.0 --port 8001 --database-provider falkordb`. Serves streamable HTTP MCP at `/mcp/` (use port 8001 if 8000 is taken by the REST server).\n\n### Backend gotcha\nThe FalkorDB async driver drops the connection (\"Connection closed by server\") when Graphiti issues concurrent queries on one connection (e.g. the gather inside `Graphiti.search`). For local hybrid-search work, prefer the Neo4j backend, which handles concurrent queries reliably.\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nGraphiti 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.\n\nKey features:\n\n- Bi-temporal data model with explicit tracking of event occurrence times\n- Hybrid retrieval combining semantic embeddings, keyword search (BM25), and graph traversal\n- Support for custom entity definitions via Pydantic models\n- Integration with Neo4j and FalkorDB as graph storage backends\n- Optional OpenTelemetry distributed tracing support\n\n## Development Commands\n\n### Main Development Commands (run from project root)\n\n```bash\n# Install dependencies\nuv sync --extra dev\n\n# Format code (ruff import sorting + formatting)\nmake format\n\n# Lint code (ruff + pyright type checking)\nmake lint\n\n# Run tests\nmake test\n\n# Run all checks (format, lint, test)\nmake check\n```\n\n### Server Development (run from server/ directory)\n\n```bash\ncd server/\n# Install server dependencies\nuv sync --extra dev\n\n# Run server in development mode\nuvicorn graph_service.main:app --reload\n\n# Format, lint, test server code\nmake format\nmake lint\nmake test\n```\n\n### MCP Server Development (run from mcp_server/ directory)\n\n```bash\ncd mcp_server/\n# Install MCP server dependencies\nuv sync\n\n# Run with Docker Compose\ndocker-compose up\n```\n\n## Code Architecture\n\n### Core Library (`graphiti_core/`)\n\n- **Main Entry Point**: `graphiti.py` - Contains the main `Graphiti` class that orchestrates all functionality\n- **Graph Storage**: `driver/` - Database drivers for Neo4j and FalkorDB\n- **LLM Integration**: `llm_client/` - Clients for OpenAI, Anthropic, Gemini, Groq\n- **Embeddings**: `embedder/` - Embedding clients for various providers\n- **Graph Elements**: `nodes.py`, `edges.py` - Core graph data structures\n- **Search**: `search/` - Hybrid search implementation with configurable strategies\n- **Prompts**: `prompts/` - LLM prompts for entity extraction, deduplication, summarization\n- **Utilities**: `utils/` - Maintenance operations, bulk processing, datetime handling\n\n### Server (`server/`)\n\n- **FastAPI Service**: `graph_service/main.py` - REST API server\n- **Routers**: `routers/` - API endpoints for ingestion and retrieval\n- **DTOs**: `dto/` - Data transfer objects for API contracts\n\n### MCP Server (`mcp_server/`)\n\n- **MCP Implementation**: `graphiti_mcp_server.py` - Model Context Protocol server for AI assistants\n- **Docker Support**: Containerized deployment with Neo4j\n\n## Testing\n\n- **Unit Tests**: `tests/` - Comprehensive test suite using pytest\n- **Integration Tests**: Tests marked with `_int` suffix require database connections\n- **Evaluation**: `tests/evals/` - End-to-end evaluation scripts\n\n## Configuration\n\n### Environment Variables\n\n- `OPENAI_API_KEY` - Required for LLM inference and embeddings\n- `USE_PARALLEL_RUNTIME` - Optional boolean for Neo4j parallel runtime (enterprise only)\n- Provider-specific keys: `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `GROQ_API_KEY`, `VOYAGE_API_KEY`\n\n### Database Setup\n\n- **Neo4j**: Version 5.26+ required, available via Neo4j Desktop\n  - Database name defaults to `neo4j` (hardcoded in Neo4jDriver)\n  - Override by passing `database` parameter to driver constructor\n- **FalkorDB**: Version 1.1.2+ as alternative backend\n  - Database name defaults to `default_db` (hardcoded in FalkorDriver)\n  - Override by passing `database` parameter to driver constructor\n\n## Development Guidelines\n\n### Code Style\n\n- Use Ruff for formatting and linting (configured in pyproject.toml)\n- Line length: 100 characters\n- Quote style: single quotes\n- Type checking with Pyright is enforced\n- Main project uses `typeCheckingMode = \"basic\"`, server uses `typeCheckingMode = \"standard\"`\n\n### Testing Requirements\n\n- Run tests with `make test` or `pytest`\n- Integration tests require database connections and are marked with `_int` suffix\n- Use `pytest-xdist` for parallel test execution\n- Run specific test files: `pytest tests/test_specific_file.py`\n- Run specific test methods: `pytest tests/test_file.py::test_method_name`\n- Run only integration tests: `pytest tests/ -k \"_int\"`\n- Run only unit tests: `pytest tests/ -k \"not _int\"`\n\n### LLM Provider Support\n\nThe 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.\n\n#### Current LLM Models (as of November 2025)\n\n**OpenAI Models:**\n- **GPT-5 Family** (Reasoning models, require temperature=0):\n  - `gpt-5-mini` - Fast reasoning model\n  - `gpt-5-nano` - Smallest reasoning model\n- **GPT-4.1 Family** (Standard models):\n  - `gpt-4.1` - Full capability model\n  - `gpt-4.1-mini` - Efficient model for most tasks\n  - `gpt-4.1-nano` - Lightweight model\n- **Legacy Models** (Still supported):\n  - `gpt-4o` - Previous generation flagship\n  - `gpt-4o-mini` - Previous generation efficient\n\n**Anthropic Models:**\n- **Claude 4.5 Family** (Latest):\n  - `claude-sonnet-4-5-latest` - Flagship model, auto-updates\n  - `claude-sonnet-4-5-20250929` - Pinned Sonnet version from September 2025\n  - `claude-haiku-4-5-latest` - Fast model, auto-updates\n- **Claude 3.7 Family**:\n  - `claude-3-7-sonnet-latest` - Auto-updates\n  - `claude-3-7-sonnet-20250219` - Pinned version from February 2025\n- **Claude 3.5 Family**:\n  - `claude-3-5-sonnet-latest` - Auto-updates\n  - `claude-3-5-sonnet-20241022` - Pinned version from October 2024\n  - `claude-3-5-haiku-latest` - Fast model\n\n**Google Gemini Models:**\n- **Gemini 2.5 Family** (Latest):\n  - `gemini-2.5-pro` - Flagship reasoning and multimodal\n  - `gemini-2.5-flash` - Fast, efficient\n- **Gemini 2.0 Family**:\n  - `gemini-2.0-flash` - Experimental fast model\n- **Gemini 1.5 Family** (Stable):\n  - `gemini-1.5-pro` - Production-stable flagship\n  - `gemini-1.5-flash` - Production-stable efficient\n\n**Note**: Model names like `gpt-5-mini`, `gpt-4.1`, and `gpt-4.1-mini` used in this codebase are valid OpenAI model identifiers. The GPT-5 family are reasoning models that require `temperature=0` (automatically handled in the code).\n\n### MCP Server Usage Guidelines\n\nWhen working with the MCP server, follow the patterns established in `mcp_server/cursor_rules.md`:\n\n- Always search for existing knowledge before adding new information\n- Use specific entity type filters (`Preference`, `Procedure`, `Requirement`)\n- Store new information immediately using `add_memory`\n- Follow discovered procedures and respect established preferences"},"files":{"AGENTS.md":"# Repository Guidelines\n\n## Project Structure & Module Organization\nGraphiti's core library lives under `graphiti_core/`, split into domain modules such as `nodes.py`, `edges.py`, `models/`, and `search/` for retrieval pipelines. Database drivers in `graphiti_core/driver/` support Neo4j, FalkorDB, and Neptune (plus a deprecated Kuzu driver). Additional core modules include `cross_encoder/` (reranking via BGE, OpenAI, and Gemini), `telemetry/` (OpenTelemetry tracing), `namespaces/` (namespace management), and `migrations/` (database migrations). Service adapters and API glue reside in `server/graph_service/`, while the MCP integration lives in `mcp_server/` (with its own `src/`, `tests/`, `config/`, and `docker/` subdirectories). Shared assets sit in `images/` and `examples/`. Tests cover the core package via `tests/`, with configuration in `conftest.py`, `pytest.ini`, and Docker compose files for optional services. Specifications live in `spec/` and type signatures in `signatures/`. Tooling manifests live at the repo root, including `pyproject.toml`, `Makefile`, and deployment compose files.\n\n## Build, Test, and Development Commands\n- `make install`: install the dev environment (`uv sync --extra dev`).\n- `make format`: run `ruff` to sort imports and apply the canonical formatter.\n- `make lint`: execute `ruff` plus `pyright` type checks against `graphiti_core`.\n- `make test`: run unit tests only, excluding integration tests and disabling non-Neo4j drivers (`DISABLE_FALKORDB=1 DISABLE_KUZU=1 DISABLE_NEPTUNE=1 uv run pytest -m \"not integration\"`).\n- `make check`: run format, lint, and test in sequence.\n- `uv run pytest tests/path/test_file.py`: target a specific module or test selection.\n- `docker-compose -f docker-compose.test.yml up`: provision local graph/search dependencies for integration flows.\n\n## Coding Style & Naming Conventions\nPython code uses 4-space indentation, 100-character lines, and prefers single quotes as configured in `pyproject.toml`. Modules, files, and functions stay snake_case; Pydantic models in `graphiti_core/models` use PascalCase with explicit type hints. Keep side-effectful code inside drivers or adapters (`graphiti_core/driver`, `graphiti_core/cross_encoder`, `graphiti_core/utils`) and rely on pure helpers elsewhere. Run `make format` before committing to normalize imports and docstring formatting.\n\n## Testing Guidelines\nAuthor tests alongside features under `tests/`, naming files `test_<feature>.py` and functions `test_<behavior>`. Integration test files use the `_int` suffix (e.g., `test_edge_int.py`, `test_node_int.py`). Use `@pytest.mark.integration` for database-reliant scenarios so CI can gate them; `make test` excludes these by default. Async tests run automatically via `asyncio_mode = auto` in `pytest.ini`. Reproduce regressions with a failing test first and validate fixes via `uv run pytest -k \"pattern\"`. Start required backing services through `docker-compose.test.yml` when running integration suites locally. The `mcp_server/` has its own separate test suite under `mcp_server/tests/`.\n\n## Commit & Pull Request Guidelines\nCommits use an imperative, present-tense summary (for example, `add async cache invalidation`) optionally suffixed with the PR number as seen in history (`(#927)`). Squash fixups and keep unrelated changes isolated. Pull requests should include: a concise description, linked tracking issue, notes about schema or API impacts, and screenshots or logs when behavior changes. Confirm `make lint` and `make test` pass locally, and update docs or examples when public interfaces shift.\n\n## Cursor Cloud specific instructions\n\nDependencies are installed by the startup update script (`uv sync` in the repo root, `server/`, and `mcp_server/`). `uv` lives at `~/.local/bin`; if it is not on `PATH`, prefix commands with `PATH=\"$HOME/.local/bin:$PATH\"`. Set `GRAPHITI_TELEMETRY_ENABLED=false` when running anything to avoid PostHog network calls.\n\n### Graph databases (Neo4j + FalkorDB via Docker)\nDocker has no systemd here — start the daemon manually once per VM: `sudo dockerd > /tmp/dockerd.log 2>&1 &`. Then start the DBs on the host network exactly as CI does (see `.github/workflows/unit_tests.yml`):\n- `sudo docker run -d --name falkordb --network host falkordb/falkordb:latest` (port 6379)\n- `sudo docker run -d --name neo4j --network host -e NEO4J_AUTH=neo4j/testpass -e NEO4J_PLUGINS='[\"apoc\"]' neo4j:5.26-community` (bolt 7687, http 7474)\n\n### Tests (non-obvious)\n- `make test` does NOT set `DISABLE_NEO4J`, so the `graph_driver` fixture stays parametrized on Neo4j and the suite REQUIRES a reachable Neo4j at `bolt://localhost:7687`. With no Neo4j, those tests hang on the driver's connection retry (not an env bug). Run it as `NEO4J_PASSWORD=testpass make test`.\n- `tests/test_add_triplet.py` has pre-existing failures (its mock embedder doesn't stub `create_batch`, so `zip(strict=True)` raises). CI never runs this file, so ignore those 11 failures — they are unrelated to environment setup.\n- The authoritative, fully-green no-DB unit gate is the CI command in `.github/workflows/unit_tests.yml` (`DISABLE_NEO4J=1 DISABLE_FALKORDB=1 DISABLE_KUZU=1 DISABLE_NEPTUNE=1` plus the `--ignore` list). The DB-backed unit tests are the `database-integration-tests` job in the same file (needs Neo4j + FalkorDB, uses mock LLMs, no API key).\n- `server/` and `mcp_server/` test suites are live end-to-end tests marked `integration`; they self-skip with exit code 5 when `OPENAI_API_KEY` is unset. This skip is expected, not a failure.\n\n### Running the services (dev mode)\nAll three run without a valid OpenAI key for startup/health only; real ingest/search (LLM extraction + embeddings) needs a real `OPENAI_API_KEY`.\n- REST API (`server/`): `OPENAI_API_KEY=<placeholder-or-real> DB_BACKEND=falkordb FALKORDB_HOST=localhost FALKORDB_PORT=6379 uv run uvicorn graph_service.main:app --reload --port 8000`. Health at `/healthcheck`, Swagger at `/docs`. `Settings` requires `OPENAI_API_KEY` to be present (any value) or startup fails.\n- MCP server (`mcp_server/`): `OPENAI_API_KEY=<...> FALKORDB_URI=redis://localhost:6379 uv run python main.py --transport http --host 0.0.0.0 --port 8001 --database-provider falkordb`. Serves streamable HTTP MCP at `/mcp/` (use port 8001 if 8000 is taken by the REST server).\n\n### Backend gotcha\nThe FalkorDB async driver drops the connection (\"Connection closed by server\") when Graphiti issues concurrent queries on one connection (e.g. the gather inside `Graphiti.search`). For local hybrid-search work, prefer the Neo4j backend, which handles concurrent queries reliably.\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nGraphiti 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.\n\nKey features:\n\n- Bi-temporal data model with explicit tracking of event occurrence times\n- Hybrid retrieval combining semantic embeddings, keyword search (BM25), and graph traversal\n- Support for custom entity definitions via Pydantic models\n- Integration with Neo4j and FalkorDB as graph storage backends\n- Optional OpenTelemetry distributed tracing support\n\n## Development Commands\n\n### Main Development Commands (run from project root)\n\n```bash\n# Install dependencies\nuv sync --extra dev\n\n# Format code (ruff import sorting + formatting)\nmake format\n\n# Lint code (ruff + pyright type checking)\nmake lint\n\n# Run tests\nmake test\n\n# Run all checks (format, lint, test)\nmake check\n```\n\n### Server Development (run from server/ directory)\n\n```bash\ncd server/\n# Install server dependencies\nuv sync --extra dev\n\n# Run server in development mode\nuvicorn graph_service.main:app --reload\n\n# Format, lint, test server code\nmake format\nmake lint\nmake test\n```\n\n### MCP Server Development (run from mcp_server/ directory)\n\n```bash\ncd mcp_server/\n# Install MCP server dependencies\nuv sync\n\n# Run with Docker Compose\ndocker-compose up\n```\n\n## Code Architecture\n\n### Core Library (`graphiti_core/`)\n\n- **Main Entry Point**: `graphiti.py` - Contains the main `Graphiti` class that orchestrates all functionality\n- **Graph Storage**: `driver/` - Database drivers for Neo4j and FalkorDB\n- **LLM Integration**: `llm_client/` - Clients for OpenAI, Anthropic, Gemini, Groq\n- **Embeddings**: `embedder/` - Embedding clients for various providers\n- **Graph Elements**: `nodes.py`, `edges.py` - Core graph data structures\n- **Search**: `search/` - Hybrid search implementation with configurable strategies\n- **Prompts**: `prompts/` - LLM prompts for entity extraction, deduplication, summarization\n- **Utilities**: `utils/` - Maintenance operations, bulk processing, datetime handling\n\n### Server (`server/`)\n\n- **FastAPI Service**: `graph_service/main.py` - REST API server\n- **Routers**: `routers/` - API endpoints for ingestion and retrieval\n- **DTOs**: `dto/` - Data transfer objects for API contracts\n\n### MCP Server (`mcp_server/`)\n\n- **MCP Implementation**: `graphiti_mcp_server.py` - Model Context Protocol server for AI assistants\n- **Docker Support**: Containerized deployment with Neo4j\n\n## Testing\n\n- **Unit Tests**: `tests/` - Comprehensive test suite using pytest\n- **Integration Tests**: Tests marked with `_int` suffix require database connections\n- **Evaluation**: `tests/evals/` - End-to-end evaluation scripts\n\n## Configuration\n\n### Environment Variables\n\n- `OPENAI_API_KEY` - Required for LLM inference and embeddings\n- `USE_PARALLEL_RUNTIME` - Optional boolean for Neo4j parallel runtime (enterprise only)\n- Provider-specific keys: `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `GROQ_API_KEY`, `VOYAGE_API_KEY`\n\n### Database Setup\n\n- **Neo4j**: Version 5.26+ required, available via Neo4j Desktop\n  - Database name defaults to `neo4j` (hardcoded in Neo4jDriver)\n  - Override by passing `database` parameter to driver constructor\n- **FalkorDB**: Version 1.1.2+ as alternative backend\n  - Database name defaults to `default_db` (hardcoded in FalkorDriver)\n  - Override by passing `database` parameter to driver constructor\n\n## Development Guidelines\n\n### Code Style\n\n- Use Ruff for formatting and linting (configured in pyproject.toml)\n- Line length: 100 characters\n- Quote style: single quotes\n- Type checking with Pyright is enforced\n- Main project uses `typeCheckingMode = \"basic\"`, server uses `typeCheckingMode = \"standard\"`\n\n### Testing Requirements\n\n- Run tests with `make test` or `pytest`\n- Integration tests require database connections and are marked with `_int` suffix\n- Use `pytest-xdist` for parallel test execution\n- Run specific test files: `pytest tests/test_specific_file.py`\n- Run specific test methods: `pytest tests/test_file.py::test_method_name`\n- Run only integration tests: `pytest tests/ -k \"_int\"`\n- Run only unit tests: `pytest tests/ -k \"not _int\"`\n\n### LLM Provider Support\n\nThe 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.\n\n#### Current LLM Models (as of November 2025)\n\n**OpenAI Models:**\n- **GPT-5 Family** (Reasoning models, require temperature=0):\n  - `gpt-5-mini` - Fast reasoning model\n  - `gpt-5-nano` - Smallest reasoning model\n- **GPT-4.1 Family** (Standard models):\n  - `gpt-4.1` - Full capability model\n  - `gpt-4.1-mini` - Efficient model for most tasks\n  - `gpt-4.1-nano` - Lightweight model\n- **Legacy Models** (Still supported):\n  - `gpt-4o` - Previous generation flagship\n  - `gpt-4o-mini` - Previous generation efficient\n\n**Anthropic Models:**\n- **Claude 4.5 Family** (Latest):\n  - `claude-sonnet-4-5-latest` - Flagship model, auto-updates\n  - `claude-sonnet-4-5-20250929` - Pinned Sonnet version from September 2025\n  - `claude-haiku-4-5-latest` - Fast model, auto-updates\n- **Claude 3.7 Family**:\n  - `claude-3-7-sonnet-latest` - Auto-updates\n  - `claude-3-7-sonnet-20250219` - Pinned version from February 2025\n- **Claude 3.5 Family**:\n  - `claude-3-5-sonnet-latest` - Auto-updates\n  - `claude-3-5-sonnet-20241022` - Pinned version from October 2024\n  - `claude-3-5-haiku-latest` - Fast model\n\n**Google Gemini Models:**\n- **Gemini 2.5 Family** (Latest):\n  - `gemini-2.5-pro` - Flagship reasoning and multimodal\n  - `gemini-2.5-flash` - Fast, efficient\n- **Gemini 2.0 Family**:\n  - `gemini-2.0-flash` - Experimental fast model\n- **Gemini 1.5 Family** (Stable):\n  - `gemini-1.5-pro` - Production-stable flagship\n  - `gemini-1.5-flash` - Production-stable efficient\n\n**Note**: Model names like `gpt-5-mini`, `gpt-4.1`, and `gpt-4.1-mini` used in this codebase are valid OpenAI model identifiers. The GPT-5 family are reasoning models that require `temperature=0` (automatically handled in the code).\n\n### MCP Server Usage Guidelines\n\nWhen working with the MCP server, follow the patterns established in `mcp_server/cursor_rules.md`:\n\n- Always search for existing knowledge before adding new information\n- Use specific entity type filters (`Preference`, `Procedure`, `Requirement`)\n- Store new information immediately using `add_memory`\n- Follow discovered procedures and respect established preferences"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Repository Guidelines\n\n## Project Structure & Module Organization\nGraphiti's core library lives under `graphiti_core/`, split into domain modules such as `nodes.py`, `edges.py`, `models/`, and `search/` for retrieval pipelines. Database drivers in `graphiti_core/driver/` support Neo4j, FalkorDB, and Neptune (plus a deprecated Kuzu driver). Additional core modules include `cross_encoder/` (reranking via BGE, OpenAI, and Gemini), `telemetry/` (OpenTelemetry tracing), `namespaces/` (namespace management), and `migrations/` (database migrations). Service adapters and API glue reside in `server/graph_service/`, while the MCP integration lives in `mcp_server/` (with its own `src/`, `tests/`, `config/`, and `docker/` subdirectories). Shared assets sit in `images/` and `examples/`. Tests cover the core package via `tests/`, with configuration in `conftest.py`, `pytest.ini`, and Docker compose files for optional services. Specifications live in `spec/` and type signatures in `signatures/`. Tooling manifests live at the repo root, including `pyproject.toml`, `Makefile`, and deployment compose files.\n\n## Build, Test, and Development Commands\n- `make install`: install the dev environment (`uv sync --extra dev`).\n- `make format`: run `ruff` to sort imports and apply the canonical formatter.\n- `make lint`: execute `ruff` plus `pyright` type checks against `graphiti_core`.\n- `make test`: run unit tests only, excluding integration tests and disabling non-Neo4j drivers (`DISABLE_FALKORDB=1 DISABLE_KUZU=1 DISABLE_NEPTUNE=1 uv run pytest -m \"not integration\"`).\n- `make check`: run format, lint, and test in sequence.\n- `uv run pytest tests/path/test_file.py`: target a specific module or test selection.\n- `docker-compose -f docker-compose.test.yml up`: provision local graph/search dependencies for integration flows.\n\n## Coding Style & Naming Conventions\nPython code uses 4-space indentation, 100-character lines, and prefers single quotes as configured in `pyproject.toml`. Modules, files, and functions stay snake_case; Pydantic models in `graphiti_core/models` use PascalCase with explicit type hints. Keep side-effectful code inside drivers or adapters (`graphiti_core/driver`, `graphiti_core/cross_encoder`, `graphiti_core/utils`) and rely on pure helpers elsewhere. Run `make format` before committing to normalize imports and docstring formatting.\n\n## Testing Guidelines\nAuthor tests alongside features under `tests/`, naming files `test_<feature>.py` and functions `test_<behavior>`. Integration test files use the `_int` suffix (e.g., `test_edge_int.py`, `test_node_int.py`). Use `@pytest.mark.integration` for database-reliant scenarios so CI can gate them; `make test` excludes these by default. Async tests run automatically via `asyncio_mode = auto` in `pytest.ini`. Reproduce regressions with a failing test first and validate fixes via `uv run pytest -k \"pattern\"`. Start required backing services through `docker-compose.test.yml` when running integration suites locally. The `mcp_server/` has its own separate test suite under `mcp_server/tests/`.\n\n## Commit & Pull Request Guidelines\nCommits use an imperative, present-tense summary (for example, `add async cache invalidation`) optionally suffixed with the PR number as seen in history (`(#927)`). Squash fixups and keep unrelated changes isolated. Pull requests should include: a concise description, linked tracking issue, notes about schema or API impacts, and screenshots or logs when behavior changes. Confirm `make lint` and `make test` pass locally, and update docs or examples when public interfaces shift.\n\n## Cursor Cloud specific instructions\n\nDependencies are installed by the startup update script (`uv sync` in the repo root, `server/`, and `mcp_server/`). `uv` lives at `~/.local/bin`; if it is not on `PATH`, prefix commands with `PATH=\"$HOME/.local/bin:$PATH\"`. Set `GRAPHITI_TELEMETRY_ENABLED=false` when running anything to avoid PostHog network calls.\n\n### Graph databases (Neo4j + FalkorDB via Docker)\nDocker has no systemd here — start the daemon manually once per VM: `sudo dockerd > /tmp/dockerd.log 2>&1 &`. Then start the DBs on the host network exactly as CI does (see `.github/workflows/unit_tests.yml`):\n- `sudo docker run -d --name falkordb --network host falkordb/falkordb:latest` (port 6379)\n- `sudo docker run -d --name neo4j --network host -e NEO4J_AUTH=neo4j/testpass -e NEO4J_PLUGINS='[\"apoc\"]' neo4j:5.26-community` (bolt 7687, http 7474)\n\n### Tests (non-obvious)\n- `make test` does NOT set `DISABLE_NEO4J`, so the `graph_driver` fixture stays parametrized on Neo4j and the suite REQUIRES a reachable Neo4j at `bolt://localhost:7687`. With no Neo4j, those tests hang on the driver's connection retry (not an env bug). Run it as `NEO4J_PASSWORD=testpass make test`.\n- `tests/test_add_triplet.py` has pre-existing failures (its mock embedder doesn't stub `create_batch`, so `zip(strict=True)` raises). CI never runs this file, so ignore those 11 failures — they are unrelated to environment setup.\n- The authoritative, fully-green no-DB unit gate is the CI command in `.github/workflows/unit_tests.yml` (`DISABLE_NEO4J=1 DISABLE_FALKORDB=1 DISABLE_KUZU=1 DISABLE_NEPTUNE=1` plus the `--ignore` list). The DB-backed unit tests are the `database-integration-tests` job in the same file (needs Neo4j + FalkorDB, uses mock LLMs, no API key).\n- `server/` and `mcp_server/` test suites are live end-to-end tests marked `integration`; they self-skip with exit code 5 when `OPENAI_API_KEY` is unset. This skip is expected, not a failure.\n\n### Running the services (dev mode)\nAll three run without a valid OpenAI key for startup/health only; real ingest/search (LLM extraction + embeddings) needs a real `OPENAI_API_KEY`.\n- REST API (`server/`): `OPENAI_API_KEY=<placeholder-or-real> DB_BACKEND=falkordb FALKORDB_HOST=localhost FALKORDB_PORT=6379 uv run uvicorn graph_service.main:app --reload --port 8000`. Health at `/healthcheck`, Swagger at `/docs`. `Settings` requires `OPENAI_API_KEY` to be present (any value) or startup fails.\n- MCP server (`mcp_server/`): `OPENAI_API_KEY=<...> FALKORDB_URI=redis://localhost:6379 uv run python main.py --transport http --host 0.0.0.0 --port 8001 --database-provider falkordb`. Serves streamable HTTP MCP at `/mcp/` (use port 8001 if 8000 is taken by the REST server).\n\n### Backend gotcha\nThe FalkorDB async driver drops the connection (\"Connection closed by server\") when Graphiti issues concurrent queries on one connection (e.g. the gather inside `Graphiti.search`). For local hybrid-search work, prefer the Neo4j backend, which handles concurrent queries reliably.\n","category":"root","tokens":1655},{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nGraphiti 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.\n\nKey features:\n\n- Bi-temporal data model with explicit tracking of event occurrence times\n- Hybrid retrieval combining semantic embeddings, keyword search (BM25), and graph traversal\n- Support for custom entity definitions via Pydantic models\n- Integration with Neo4j and FalkorDB as graph storage backends\n- Optional OpenTelemetry distributed tracing support\n\n## Development Commands\n\n### Main Development Commands (run from project root)\n\n```bash\n# Install dependencies\nuv sync --extra dev\n\n# Format code (ruff import sorting + formatting)\nmake format\n\n# Lint code (ruff + pyright type checking)\nmake lint\n\n# Run tests\nmake test\n\n# Run all checks (format, lint, test)\nmake check\n```\n\n### Server Development (run from server/ directory)\n\n```bash\ncd server/\n# Install server dependencies\nuv sync --extra dev\n\n# Run server in development mode\nuvicorn graph_service.main:app --reload\n\n# Format, lint, test server code\nmake format\nmake lint\nmake test\n```\n\n### MCP Server Development (run from mcp_server/ directory)\n\n```bash\ncd mcp_server/\n# Install MCP server dependencies\nuv sync\n\n# Run with Docker Compose\ndocker-compose up\n```\n\n## Code Architecture\n\n### Core Library (`graphiti_core/`)\n\n- **Main Entry Point**: `graphiti.py` - Contains the main `Graphiti` class that orchestrates all functionality\n- **Graph Storage**: `driver/` - Database drivers for Neo4j and FalkorDB\n- **LLM Integration**: `llm_client/` - Clients for OpenAI, Anthropic, Gemini, Groq\n- **Embeddings**: `embedder/` - Embedding clients for various providers\n- **Graph Elements**: `nodes.py`, `edges.py` - Core graph data structures\n- **Search**: `search/` - Hybrid search implementation with configurable strategies\n- **Prompts**: `prompts/` - LLM prompts for entity extraction, deduplication, summarization\n- **Utilities**: `utils/` - Maintenance operations, bulk processing, datetime handling\n\n### Server (`server/`)\n\n- **FastAPI Service**: `graph_service/main.py` - REST API server\n- **Routers**: `routers/` - API endpoints for ingestion and retrieval\n- **DTOs**: `dto/` - Data transfer objects for API contracts\n\n### MCP Server (`mcp_server/`)\n\n- **MCP Implementation**: `graphiti_mcp_server.py` - Model Context Protocol server for AI assistants\n- **Docker Support**: Containerized deployment with Neo4j\n\n## Testing\n\n- **Unit Tests**: `tests/` - Comprehensive test suite using pytest\n- **Integration Tests**: Tests marked with `_int` suffix require database connections\n- **Evaluation**: `tests/evals/` - End-to-end evaluation scripts\n\n## Configuration\n\n### Environment Variables\n\n- `OPENAI_API_KEY` - Required for LLM inference and embeddings\n- `USE_PARALLEL_RUNTIME` - Optional boolean for Neo4j parallel runtime (enterprise only)\n- Provider-specific keys: `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `GROQ_API_KEY`, `VOYAGE_API_KEY`\n\n### Database Setup\n\n- **Neo4j**: Version 5.26+ required, available via Neo4j Desktop\n  - Database name defaults to `neo4j` (hardcoded in Neo4jDriver)\n  - Override by passing `database` parameter to driver constructor\n- **FalkorDB**: Version 1.1.2+ as alternative backend\n  - Database name defaults to `default_db` (hardcoded in FalkorDriver)\n  - Override by passing `database` parameter to driver constructor\n\n## Development Guidelines\n\n### Code Style\n\n- Use Ruff for formatting and linting (configured in pyproject.toml)\n- Line length: 100 characters\n- Quote style: single quotes\n- Type checking with Pyright is enforced\n- Main project uses `typeCheckingMode = \"basic\"`, server uses `typeCheckingMode = \"standard\"`\n\n### Testing Requirements\n\n- Run tests with `make test` or `pytest`\n- Integration tests require database connections and are marked with `_int` suffix\n- Use `pytest-xdist` for parallel test execution\n- Run specific test files: `pytest tests/test_specific_file.py`\n- Run specific test methods: `pytest tests/test_file.py::test_method_name`\n- Run only integration tests: `pytest tests/ -k \"_int\"`\n- Run only unit tests: `pytest tests/ -k \"not _int\"`\n\n### LLM Provider Support\n\nThe 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.\n\n#### Current LLM Models (as of November 2025)\n\n**OpenAI Models:**\n- **GPT-5 Family** (Reasoning models, require temperature=0):\n  - `gpt-5-mini` - Fast reasoning model\n  - `gpt-5-nano` - Smallest reasoning model\n- **GPT-4.1 Family** (Standard models):\n  - `gpt-4.1` - Full capability model\n  - `gpt-4.1-mini` - Efficient model for most tasks\n  - `gpt-4.1-nano` - Lightweight model\n- **Legacy Models** (Still supported):\n  - `gpt-4o` - Previous generation flagship\n  - `gpt-4o-mini` - Previous generation efficient\n\n**Anthropic Models:**\n- **Claude 4.5 Family** (Latest):\n  - `claude-sonnet-4-5-latest` - Flagship model, auto-updates\n  - `claude-sonnet-4-5-20250929` - Pinned Sonnet version from September 2025\n  - `claude-haiku-4-5-latest` - Fast model, auto-updates\n- **Claude 3.7 Family**:\n  - `claude-3-7-sonnet-latest` - Auto-updates\n  - `claude-3-7-sonnet-20250219` - Pinned version from February 2025\n- **Claude 3.5 Family**:\n  - `claude-3-5-sonnet-latest` - Auto-updates\n  - `claude-3-5-sonnet-20241022` - Pinned version from October 2024\n  - `claude-3-5-haiku-latest` - Fast model\n\n**Google Gemini Models:**\n- **Gemini 2.5 Family** (Latest):\n  - `gemini-2.5-pro` - Flagship reasoning and multimodal\n  - `gemini-2.5-flash` - Fast, efficient\n- **Gemini 2.0 Family**:\n  - `gemini-2.0-flash` - Experimental fast model\n- **Gemini 1.5 Family** (Stable):\n  - `gemini-1.5-pro` - Production-stable flagship\n  - `gemini-1.5-flash` - Production-stable efficient\n\n**Note**: Model names like `gpt-5-mini`, `gpt-4.1`, and `gpt-4.1-mini` used in this codebase are valid OpenAI model identifiers. The GPT-5 family are reasoning models that require `temperature=0` (automatically handled in the code).\n\n### MCP Server Usage Guidelines\n\nWhen working with the MCP server, follow the patterns established in `mcp_server/cursor_rules.md`:\n\n- Always search for existing knowledge before adding new information\n- Use specific entity type filters (`Preference`, `Procedure`, `Requirement`)\n- Store new information immediately using `add_memory`\n- Follow discovered procedures and respect established preferences","category":"root","tokens":1668}]}