graphiti-core 0.13.1__tar.gz → 0.14.0__tar.gz

graphiti_core-0.14.0/.env.example

@@ -0,0 +1,20 @@
+OPENAI_API_KEY=
+
+# Neo4j database connection
+NEO4J_URI=
+NEO4J_PORT=
+NEO4J_USER=
+NEO4J_PASSWORD=
+
+# FalkorDB database connection 
+FALKORDB_URI=
+FALKORDB_PORT=
+FALKORDB_USER=
+FALKORDB_PASSWORD=
+
+DEFAULT_DATABASE=
+USE_PARALLEL_RUNTIME=
+SEMAPHORE_LIMIT=
+GITHUB_SHA=
+MAX_REFLEXION_ITERATIONS=
+ANTHROPIC_API_KEY=

graphiti_core-0.14.0/.github/dependabot.yml

@@ -0,0 +1,19 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "pip"
+    directory: "/server" # Location of server package manifests
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "pip"
+    directory: "/mcp_server" # Location of server package manifests
+    schedule:
+      interval: "weekly"

graphiti_core-0.14.0/.github/secret_scanning.yml

@@ -0,0 +1,11 @@
+# Secret scanning configuration
+# This file excludes specific files/directories from secret scanning alerts
+
+paths-ignore:
+  # PostHog public API key for anonymous telemetry
+  # This is a public key intended for client-side use and safe to commit
+  # Key: phc_UG6EcfDbuXz92neb3rMlQFDY0csxgMqRcIPWESqnSmo
+  - "graphiti_core/telemetry/telemetry.py"
+  
+  # Example/test directories that may contain dummy credentials
+  - "tests/**/fixtures/**" 

graphiti_core-0.14.0/.github/workflows/cla.yml

@@ -0,0 +1,42 @@
+name: "CLA Assistant"
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened, closed, synchronize]
+
+# explicitly configure permissions, in case your GITHUB_TOKEN workflow permissions are set to read-only in repository settings
+permissions:
+  actions: write
+  contents: write # this can be 'read' if the signatures are in remote repository
+  pull-requests: write
+  statuses: write
+
+jobs:
+  CLAAssistant:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "CLA Assistant"
+        if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
+        uses: contributor-assistant/github-action@v2.6.1
+        env:
+          # the default github token does not have branch protection override permissions
+          # the repo secrets will need to be updated when the token expires.
+          GITHUB_TOKEN: ${{ secrets.DANIEL_PAT }}
+        with:
+          path-to-signatures: "signatures/version1/cla.json"
+          path-to-document: "https://github.com/getzep/graphiti/blob/main/Zep-CLA.md" # e.g. a CLA or a DCO document
+          # branch should not be protected unless a personal PAT is used
+          branch: "main"
+          allowlist: paul-paliychuk,prasmussen15,danielchalef,dependabot[bot],ellipsis-dev
+
+          # the followings are the optional inputs - If the optional inputs are not given, then default values will be taken
+          #remote-organization-name: enter the remote organization name where the signatures should be stored (Default is storing the signatures in the same repository)
+          #remote-repository-name: enter the  remote repository name where the signatures should be stored (Default is storing the signatures in the same repository)
+          #create-file-commit-message: 'For example: Creating file for storing CLA Signatures'
+          #signed-commit-message: 'For example: $contributorName has signed the CLA in $owner/$repo#$pullRequestNo'
+          #custom-notsigned-prcomment: 'pull request comment with Introductory message to ask new contributors to sign'
+          #custom-pr-sign-comment: 'The signature to be committed in order to sign the CLA'
+          #custom-allsigned-prcomment: 'pull request comment when all contributors has signed, defaults to **CLA Assistant Lite bot** All Contributors have signed the CLA.'
+          #lock-pullrequest-aftermerge: false - if you don't want this bot to automatically lock the pull request after merging (default - true)
+          #use-dco-flag: true - If you are using DCO instead of CLA

graphiti_core-0.14.0/.github/workflows/codeql.yml

@@ -0,0 +1,100 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '43 1 * * 6'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        - language: python
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:${{matrix.language}}"

graphiti_core-0.14.0/.github/workflows/lint.yml

@@ -0,0 +1,24 @@
+name: Lint with Ruff
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  ruff:
+    environment: development
+    runs-on: depot-ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install "ruff>0.1.7"
+      - name: Run Ruff linting
+        run: ruff check --output-format=github

graphiti_core-0.14.0/.github/workflows/release-graphiti-core.yml

@@ -0,0 +1,37 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+    environment:
+      name: release
+      url: https://pypi.org/p/zep-cloud
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+      - name: Compare pyproject version with tag
+        run: |
+          TAG_VERSION=${GITHUB_REF#refs/tags/}
+          PROJECT_VERSION=$(uv run python -c "import tomllib; print('v' + tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "$TAG_VERSION" != "$PROJECT_VERSION" ]; then
+            echo "Tag version $TAG_VERSION does not match the project version $PROJECT_VERSION"
+            exit 1
+          fi
+      - name: Build project for distribution
+        run: uv build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

graphiti_core-0.14.0/.github/workflows/typecheck.yml

@@ -0,0 +1,47 @@
+name: MyPy Type Check
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  mypy:
+    runs-on: depot-ubuntu-22.04
+    environment: development
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        id: setup-python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Run MyPy for graphiti-core
+        shell: bash
+        run: |
+          set -o pipefail
+          uv run mypy ./graphiti_core --show-column-numbers --show-error-codes | sed -E '
+            s/^(.*):([0-9]+):([0-9]+): (error|warning): (.+) \[(.+)\]/::error file=\1,line=\2,endLine=\2,col=\3,title=\6::\5/;
+            s/^(.*):([0-9]+):([0-9]+): note: (.+)/::notice file=\1,line=\2,endLine=\2,col=\3,title=Note::\4/;
+          '
+      - name: Install graph-service dependencies
+        shell: bash
+        run: |
+          cd server
+          uv sync --extra dev
+      - name: Run MyPy for graph-service
+        shell: bash
+        run: |
+          cd server
+          set -o pipefail
+          uv run mypy . --show-column-numbers --show-error-codes | sed -E '
+            s/^(.*):([0-9]+):([0-9]+): (error|warning): (.+) \[(.+)\]/::error file=\1,line=\2,endLine=\2,col=\3,title=\6::\5/;
+            s/^(.*):([0-9]+):([0-9]+): note: (.+)/::notice file=\1,line=\2,endLine=\2,col=\3,title=Note::\4/;
+          '

graphiti_core-0.14.0/.github/workflows/unit_tests.yml

@@ -0,0 +1,30 @@
+name: Unit Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: depot-ubuntu-22.04
+    environment:
+      name: development
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Run non-integration tests
+        env:
+          PYTHONPATH: ${{ github.workspace }}
+        run: |
+          uv run pytest -m "not integration"

graphiti_core-0.14.0/.gitignore

@@ -0,0 +1,168 @@
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# uv
+#   It is generally recommended to include uv.lock in version control.
+#   This ensures reproducibility across different environments.
+#   https://docs.astral.sh/uv/concepts/projects/#lockfile
+# uv.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+.vscode/
+
+## Other
+# Cache files
+cache.db*
+
+# All DS_Store files
+.DS_Store

graphiti_core-0.14.0/CLAUDE.md

@@ -0,0 +1,133 @@
+# 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