chore: import upstream snapshot with attribution

.github/workflows/adapter_caching_tests.yml

@@ -0,0 +1,291 @@
+name: Reusable Adapter Caching Tests
+
+permissions:
+  contents: read
+  packages: read
+
+on:
+  workflow_call:
+    inputs:
+      databases:
+        required: false
+        type: string
+        default: "all"
+        description: "Which provider combos to test (comma-separated list or 'all')"
+      python-version:
+        required: false
+        type: string
+        default: '3.11.x'
+        description: "Python version to test"
+      ci-image:
+        required: false
+        type: string
+        default: ''
+        description: "Container image for CI (empty string means no container)"
+    secrets:
+      LLM_MODEL:
+        required: true
+      LLM_ENDPOINT:
+        required: true
+      LLM_API_KEY:
+        required: true
+      LLM_ARGS:
+        required: false
+      LLM_API_VERSION:
+        required: true
+      EMBEDDING_MODEL:
+        required: true
+      EMBEDDING_API_KEY:
+        required: true
+
+jobs:
+  run-ladybug-lance-sqlite-caching:
+    name: Adapter caching — Ladybug + LanceDB + Sqlite
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'ladybug/lance/sqlite') }}
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Run adapter caching test
+        env:
+          ENV: 'dev'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          GRAPH_DATABASE_PROVIDER: 'ladybug'
+          VECTOR_DB_PROVIDER: 'lancedb'
+          DB_PROVIDER: 'sqlite'
+        run: uv run python ./cognee/tests/test_adapter_object_caching.py
+
+  run-neo4j-lance-sqlite-caching:
+    name: Adapter caching — Neo4j + LanceDB + Sqlite
+    runs-on: ubuntu-22.04
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'neo4j/lance/sqlite') }}
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Setup Neo4j with GDS
+        uses: ./.github/actions/setup_neo4j
+        id: neo4j
+
+      - name: Run adapter caching test
+        env:
+          ENV: 'dev'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          GRAPH_DATABASE_PROVIDER: 'neo4j'
+          VECTOR_DB_PROVIDER: 'lancedb'
+          DB_PROVIDER: 'sqlite'
+          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+          GRAPH_DATABASE_URL: ${{ steps.neo4j.outputs.neo4j-url }}
+          GRAPH_DATABASE_USERNAME: ${{ steps.neo4j.outputs.neo4j-username }}
+          GRAPH_DATABASE_PASSWORD: ${{ steps.neo4j.outputs.neo4j-password }}
+        run: uv run python ./cognee/tests/test_adapter_object_caching.py
+
+  run-ladybug-pgvector-postgres-caching:
+    name: Adapter caching — Ladybug + PGVector + Postgres
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'ladybug/pgvector/postgres') }}
+    services:
+      postgres:
+        image: ghcr.io/topoteretes/pgvector:pg17
+        credentials:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          POSTGRES_USER: cognee
+          POSTGRES_PASSWORD: cognee
+          POSTGRES_DB: cognee_db
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+          extra-dependencies: "postgres"
+
+      - name: Run adapter caching test
+        env:
+          ENV: 'dev'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          GRAPH_DATABASE_PROVIDER: 'ladybug'
+          VECTOR_DB_PROVIDER: 'pgvector'
+          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+          DB_PROVIDER: 'postgres'
+          DB_NAME: 'cognee_db'
+          DB_HOST: ${{ inputs.ci-image != '' && 'postgres' || '127.0.0.1' }}
+          DB_PORT: 5432
+          DB_USERNAME: cognee
+          DB_PASSWORD: cognee
+        run: uv run python ./cognee/tests/test_adapter_object_caching.py
+
+  run-neo4j-pgvector-postgres-caching:
+    name: Adapter caching — Neo4j + PGVector + Postgres
+    runs-on: ubuntu-22.04
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'neo4j/pgvector/postgres') }}
+    services:
+      postgres:
+        image: ghcr.io/topoteretes/pgvector:pg17
+        credentials:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          POSTGRES_USER: cognee
+          POSTGRES_PASSWORD: cognee
+          POSTGRES_DB: cognee_db
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries=5
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+          extra-dependencies: "postgres"
+
+      - name: Setup Neo4j with GDS
+        uses: ./.github/actions/setup_neo4j
+        id: neo4j
+
+      - name: Run adapter caching test
+        env:
+          ENV: 'dev'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          GRAPH_DATABASE_PROVIDER: 'neo4j'
+          VECTOR_DB_PROVIDER: 'pgvector'
+          DB_PROVIDER: 'postgres'
+          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+          GRAPH_DATABASE_URL: ${{ steps.neo4j.outputs.neo4j-url }}
+          GRAPH_DATABASE_USERNAME: ${{ steps.neo4j.outputs.neo4j-username }}
+          GRAPH_DATABASE_PASSWORD: ${{ steps.neo4j.outputs.neo4j-password }}
+          DB_NAME: cognee_db
+          DB_HOST: 127.0.0.1
+          DB_PORT: 5432
+          DB_USERNAME: cognee
+          DB_PASSWORD: cognee
+        run: uv run python ./cognee/tests/test_adapter_object_caching.py
+
+  run-postgres-pgvector-postgres-caching:
+    name: Adapter caching — Postgres graph + PGVector + Postgres (access control)
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'postgres/pgvector/postgres') }}
+    services:
+      postgres:
+        image: ghcr.io/topoteretes/pgvector:pg17
+        credentials:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          POSTGRES_USER: cognee
+          POSTGRES_PASSWORD: cognee
+          POSTGRES_DB: cognee_db
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+          extra-dependencies: "postgres"
+
+      - name: Run adapter caching test
+        env:
+          ENV: 'dev'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          # Access control mode: every dataset gets its own physical Postgres
+          # database (named after the deterministic dataset id) that is created
+          # on add and dropped on delete — the engine-cache lifecycle across
+          # that drop/recreate boundary is what this job guards.
+          ENABLE_BACKEND_ACCESS_CONTROL: 'true'
+          DB_PROVIDER: 'postgres'
+          DB_NAME: 'cognee_db'
+          DB_HOST: ${{ inputs.ci-image != '' && 'postgres' || '127.0.0.1' }}
+          DB_PORT: 5432
+          DB_USERNAME: cognee
+          DB_PASSWORD: cognee
+          VECTOR_DB_PROVIDER: 'pgvector'
+          VECTOR_DB_NAME: 'cognee_db'
+          VECTOR_DB_HOST: ${{ inputs.ci-image != '' && 'postgres' || '127.0.0.1' }}
+          VECTOR_DB_PORT: 5432
+          VECTOR_DB_USERNAME: cognee
+          VECTOR_DB_PASSWORD: cognee
+          VECTOR_DATASET_DATABASE_HANDLER: 'pgvector'
+          GRAPH_DATABASE_PROVIDER: 'postgres'
+          GRAPH_DATABASE_NAME: 'cognee_db'
+          GRAPH_DATABASE_HOST: ${{ inputs.ci-image != '' && 'postgres' || '127.0.0.1' }}
+          GRAPH_DATABASE_PORT: 5432
+          GRAPH_DATABASE_USERNAME: cognee
+          GRAPH_DATABASE_PASSWORD: cognee
+          GRAPH_DATASET_DATABASE_HANDLER: 'postgres_graph'
+        run: uv run python ./cognee/tests/test_adapter_object_caching.py

.github/workflows/approve_dco.yaml

@@ -0,0 +1,40 @@
+name: community | DCO Check
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize, ready_for_review]
+
+jobs:
+  check-dco:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate Developer Certificate of Origin statement
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const prUser = context.payload.pull_request.user.login;
+            const prBody = context.payload.pull_request.body || '';
+            const authorAssociation = context.payload.pull_request.author_association;
+
+            // Exact text you require in the PR body
+            const requiredStatement = "I affirm that all code in every commit of this pull request conforms to the terms of the Topoteretes Developer Certificate of Origin";
+
+            // 1. Check if user is an org member via author_association
+            //    (available on the PR payload without extra API calls or permissions)
+            //    OWNER, MEMBER, and COLLABORATOR are trusted roles.
+            const trustedRoles = ['OWNER', 'MEMBER', 'COLLABORATOR', 'CONTRIBUTOR'];
+            const isTrusted = trustedRoles.includes(authorAssociation);
+
+            if (isTrusted) {
+              console.log(`${prUser} has association '${authorAssociation}'. Skipping DCO check.`);
+            } else {
+              console.log(`${prUser} has association '${authorAssociation}'. Enforcing DCO check.`);
+
+              // 2. If user is not trusted, enforce the DCO statement
+              if (!prBody.includes(requiredStatement)) {
+                core.setFailed(
+                  `DCO check failed. The PR body must include the following statement:\n\n${requiredStatement}`
+                );
+              }
+            }

.github/workflows/backend_docker_build_test.yml

@@ -0,0 +1,27 @@
+name: build test | Docker image
+
+on:
+  workflow_call:
+
+env:
+  AWS_ACCOUNT_ID_DEV: "463722570299"
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+
+  build_docker:
+    name: Build Cognee Backend Docker App Image
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out Cognee code
+        uses: actions/checkout@v6
+
+      - name: Build Cognee Docker image
+        id: cognee-docker-tag
+        run: |
+          export SHA_SHORT="$(git rev-parse --short HEAD)"
+          export CUR_DATE="$(date +%Y%m%d%H%M%S)"
+          export VERSION="dev-$CUR_DATE-$SHA_SHORT"
+          image_name="cognee" docker_login="false" version="$VERSION" account="${{ env.AWS_ACCOUNT_ID_DEV }}" app_dir="." publish="false" ./bin/dockerize
+          export DOCKER_TAG=$(cat /tmp/.DOCKER_IMAGE_VERSION)
+          echo "Successfully built cognee Docker image. Tag is: $DOCKER_TAG"

.github/workflows/basic_tests.yml

@@ -0,0 +1,139 @@
+name: Reusable Basic Tests
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        required: false
+        type: string
+        default: '3.11.x'
+      ci-image:
+        required: false
+        type: string
+        default: ''
+    secrets:
+      LLM_PROVIDER:
+        required: true
+      LLM_MODEL:
+        required: true
+      LLM_ENDPOINT:
+        required: true
+      LLM_API_KEY:
+        required: true
+      LLM_ARGS:
+        required: false
+      LLM_API_VERSION:
+        required: true
+      EMBEDDING_PROVIDER:
+        required: true
+      EMBEDDING_MODEL:
+        required: true
+      EMBEDDING_API_KEY:
+        required: true
+
+env:
+  RUNTIME__LOG_LEVEL: ERROR
+  ENV: 'dev'
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  unit-tests:
+    name: Run Unit Tests
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    env:
+      ENV: 'dev'
+      LLM_PROVIDER: openai
+      LLM_MODEL: ${{ secrets.LLM_MODEL }}
+      LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+      LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+      LLM_ARGS: ${{ secrets.LLM_ARGS }}
+      LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+
+      EMBEDDING_PROVIDER: openai
+      EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+      EMBEDDING_DIMENSIONS: 300
+      EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Run Unit Tests
+        run: uv run pytest cognee/tests/unit/ --timeout=300 --timeout-method=thread
+
+  simple-examples:
+    name: Run Simple Examples
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    env:
+      ENV: 'dev'
+      LLM_PROVIDER: openai
+      LLM_MODEL: ${{ secrets.LLM_MODEL }}
+      LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+      LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+      LLM_ARGS: ${{ secrets.LLM_ARGS }}
+      LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+
+      EMBEDDING_PROVIDER: openai
+      EMBEDDING_DIMENSIONS: 300
+      EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+      EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Run Simple Examples
+        run: uv run python ./examples/demos/simple_cognee_example.py
+
+  simple-examples-baml:
+    name: Run Simple Examples BAML
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    env:
+      ENV: 'dev'
+      STRUCTURED_OUTPUT_FRAMEWORK: "BAML"
+      BAML_LLM_PROVIDER: openai
+      BAML_LLM_MODEL: ${{ secrets.OPENAI_MODEL }}
+      BAML_LLM_ENDPOINT: ${{ secrets.OPENAI_ENDPOINT }}
+      BAML_LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+#      BAML_LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+
+      LLM_PROVIDER: openai
+      LLM_MODEL: ${{ secrets.LLM_MODEL }}
+      LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+      LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+      LLM_ARGS: ${{ secrets.LLM_ARGS }}
+      LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+
+      EMBEDDING_PROVIDER: openai
+      EMBEDDING_DIMENSIONS: 300
+      EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+      EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+          extra-dependencies: "baml"
+
+      - name: Run Simple Examples
+        run: uv run python ./examples/demos/simple_cognee_example.py

.github/workflows/clean_stale_pr.yaml

@@ -0,0 +1,32 @@
+name: clean | remove stale PRs
+
+on:
+  # Run this action periodically (daily at 0:00 UTC).
+  schedule:
+    - cron: "0 0 * * *"
+  # Optionally, also run when pull requests are labeled, unlabeled, synchronized, or reopened
+  # to update the stale timer as needed. Uncomment if desired.
+  # pull_request:
+  #   types: [labeled, unlabeled, synchronize, reopened]
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Mark and Close Stale PRs
+        uses: actions/stale@v10
+        with:
+          # Number of days of inactivity before the pull request is marked stale
+          days-before-stale: 60
+          # Number of days of inactivity after being marked stale before the pull request is closed
+          days-before-close: 7
+          # Comment to post when marking as stale
+          stale-pr-message: "This pull request has been automatically marked as stale due to inactivity. It will be closed in 7 days if no further activity occurs."
+          # Comment to post when closing a stale pull request
+          close-pr-message: "This pull request has been closed due to prolonged inactivity."
+          # Labels for stale and closed PRs
+          stale-pr-label: "stale"
+          exempt-pr-labels: "keep-open"

.github/workflows/cli_tests.yml

@@ -0,0 +1,171 @@
+name: test | cli
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        required: false
+        type: string
+        default: '3.11.x'
+      cognee_version:
+        required: false
+        type: string
+        default: "local"
+        description: "Pypi-compatible version of cognee to use. For example, 0.5.2.dev0. `local` (default) - Installing Cognee from local source"
+      ci-image:
+        required: false
+        type: string
+        default: ''
+    secrets:
+      LLM_PROVIDER:
+        required: true
+      LLM_MODEL:
+        required: true
+      LLM_ENDPOINT:
+        required: true
+      LLM_API_KEY:
+        required: true
+      LLM_ARGS:
+        required: false
+      LLM_API_VERSION:
+        required: true
+      EMBEDDING_PROVIDER:
+        required: true
+      EMBEDDING_MODEL:
+        required: true
+      EMBEDDING_API_KEY:
+        required: true
+
+env:
+  RUNTIME__LOG_LEVEL: ERROR
+  ENV: 'dev'
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  cli-unit-tests:
+    name: CLI Unit Tests
+    if: ${{ inputs.cognee_version == 'local' }}
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    env:
+      ENV: 'dev'
+      LLM_PROVIDER: openai
+      LLM_MODEL: ${{ secrets.LLM_MODEL }}
+      LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+      LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+      LLM_ARGS: ${{ secrets.LLM_ARGS }}
+      LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+      EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+      EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Run CLI Unit Tests
+        run: uv run pytest cognee/tests/cli_tests/cli_unit_tests/ -v
+
+  cli-integration-tests:
+    name: CLI Integration Tests
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    env:
+      ENV: 'dev'
+      LLM_PROVIDER: openai
+      LLM_MODEL: ${{ secrets.LLM_MODEL }}
+      LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+      LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+      LLM_ARGS: ${{ secrets.LLM_ARGS }}
+      LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+      EMBEDDING_DIMENSIONS: 300
+      EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+      EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Install Cognee
+        uses: ./.github/actions/install_cognee
+        with:
+          python-version: ${{ inputs.python-version }}
+          cognee_version: ${{ inputs.cognee_version }}
+
+      - name: Run CLI Integration Tests
+        run: uv run pytest cognee/tests/cli_tests/cli_integration_tests/ -v
+
+  cli-functionality-tests:
+    name: CLI Functionality Tests
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    env:
+      ENV: 'dev'
+      LLM_PROVIDER: openai
+      LLM_MODEL: ${{ secrets.LLM_MODEL }}
+      LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+      LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+      LLM_ARGS: ${{ secrets.LLM_ARGS }}
+      LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+      EMBEDDING_DIMENSIONS: 300
+      EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+      EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Install Cognee
+        uses: ./.github/actions/install_cognee
+        with:
+          python-version: ${{ inputs.python-version }}
+          cognee_version: ${{ inputs.cognee_version }}
+
+      - name: Test CLI Help Commands
+        run: |
+          uv run python -m cognee.cli._cognee --help
+          uv run python -m cognee.cli._cognee --version
+          uv run python -m cognee.cli._cognee add --help
+          uv run python -m cognee.cli._cognee search --help
+          uv run python -m cognee.cli._cognee cognify --help
+          uv run python -m cognee.cli._cognee delete --help
+          uv run python -m cognee.cli._cognee config --help
+
+      - name: Test CLI Config Subcommands
+        run: |
+          uv run python -m cognee.cli._cognee config get --help
+          uv run python -m cognee.cli._cognee config set --help
+          uv run python -m cognee.cli._cognee config list --help
+          uv run python -m cognee.cli._cognee config unset --help
+          uv run python -m cognee.cli._cognee config reset --help
+
+      - name: Test CLI Error Handling
+        run: |
+          # Test invalid command (should fail gracefully)
+          ! uv run python -m cognee.cli._cognee invalid_command
+
+          # Test missing required arguments (should fail gracefully)
+          ! uv run python -m cognee.cli._cognee search
+
+          # Test invalid search type (should fail gracefully)
+          ! uv run python -m cognee.cli._cognee search "test" --query-type INVALID_TYPE
+
+          # Test invalid chunker (should fail gracefully)
+          ! uv run python -m cognee.cli._cognee cognify --chunker InvalidChunker

.github/workflows/community_greetings.yml

@@ -0,0 +1,25 @@
+name: community | Greetings
+
+on:
+  issues:
+    types: [opened]
+  pull_request_target:
+    types: [opened]
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  greeting:
+    if: github.actor != 'github-actions[bot]' && github.actor != 'dependabot[bot]' && !contains(github.event.pull_request.body, 'Generated with [Claude Code]')
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/first-interaction@v3
+      with:
+        repo_token: ${{ secrets.GITHUB_TOKEN }}
+        pr_message:  'Hello @${{ github.actor }}, thank you for submitting a PR! We will respond as soon as possible.'
+        issue_message: |
+          Hello @${{ github.actor }}, thank you for your interest in our work!
+
+          If this is a bug report, please provide screenshots and **minimum viable code to reproduce your issue**, otherwise we can not help you.

.github/workflows/community_tests.yml

@@ -0,0 +1,180 @@
+name: Community Tests (No Secrets)
+
+# Runs on ALL pull requests, including forks.
+# No secrets required — only fully mocked unit tests and code quality checks.
+# This gives community contributors fast feedback on their changes.
+
+on:
+  pull_request:
+    branches: [ main, dev ]
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: community-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  RUNTIME__LOG_LEVEL: ERROR
+  ENV: 'dev'
+
+jobs:
+  code-quality:
+    name: Code Quality
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Validate uv lockfile
+        run: uv lock --check || { echo "'uv lock --check' failed. Run 'uv lock' and push your changes."; exit 1; }
+
+      - name: Run pre-commit hooks
+        uses: pre-commit/action@v3.0.1
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Ty type check
+        run: uv run ty check .
+
+  unit-tests:
+    name: Unit Tests (Mocked, No Secrets)
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11.x']
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        # postgres is needed so the SQL cache adapter tests run instead of skipping.
+        run: uv sync --extra dev --extra postgres
+
+      - name: Run mocked unit tests
+        run: |
+          uv run pytest \
+            cognee/tests/unit/processing/ \
+            cognee/tests/unit/entity_extraction/ \
+            cognee/tests/unit/modules/graph/ \
+            cognee/tests/unit/modules/chunking/ \
+            cognee/tests/unit/modules/data/ \
+            cognee/tests/unit/modules/retrieval/ \
+            --ignore=cognee/tests/unit/modules/retrieval/graph_completion_retriever_cot_test.py \
+            --ignore=cognee/tests/unit/modules/retrieval/temporal_retriever_test.py \
+            --ignore=cognee/tests/unit/modules/retrieval/triplet_retriever_test.py \
+            cognee/tests/unit/modules/search/ \
+            cognee/tests/unit/modules/pipelines/ \
+            cognee/tests/unit/modules/visualization/ \
+            cognee/tests/unit/modules/ontology/ \
+            cognee/tests/unit/modules/observability/ \
+            cognee/tests/unit/modules/users/ \
+            cognee/tests/unit/modules/memify_tasks/ \
+            cognee/tests/unit/interfaces/graph/ \
+            cognee/tests/unit/infrastructure/databases/cache/ \
+            cognee/tests/unit/infrastructure/databases/vector/test_vector_db_config.py \
+            cognee/tests/unit/infrastructure/databases/relational/ \
+            cognee/tests/unit/infrastructure/databases/test_unified_store_engine.py \
+            cognee/tests/unit/infrastructure/session/ \
+            cognee/tests/unit/infrastructure/llm/ \
+            cognee/tests/unit/infrastructure/test_rate_limiting_retry.py \
+            cognee/tests/unit/tasks/storage/test_add_data_points.py \
+            cognee/tests/unit/shared/ \
+            -v --tb=short
+
+  cli-unit-tests:
+    name: CLI Unit Tests (Mocked, No Secrets)
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11.x'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run CLI unit tests
+        run: uv run pytest cognee/tests/cli_tests/cli_unit_tests/ -v --tb=short
+
+  telemetry-test:
+    name: Telemetry Test (Mocked, No Secrets)
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11.x'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run telemetry test
+        run: uv run pytest cognee/tests/test_telemetry.py -v --tb=short
+
+  notify:
+    name: Community Tests Status
+    needs: [code-quality, unit-tests, cli-unit-tests, telemetry-test]
+    runs-on: ubuntu-latest
+    if: ${{ !cancelled() }}
+    steps:
+      - name: Check Status
+        run: |
+          if [[ "${{ needs.code-quality.result }}" == "success" &&
+                "${{ needs.unit-tests.result }}" == "success" &&
+                "${{ needs.cli-unit-tests.result }}" == "success" &&
+                "${{ needs.telemetry-test.result }}" == "success" ]]; then
+            echo "All community tests passed!"
+          else
+            echo "One or more community tests failed."
+            exit 1
+          fi

.github/workflows/db_examples_tests.yml

@@ -0,0 +1,165 @@
+name: Reusable DB Examples Tests
+
+on:
+  workflow_call:
+    inputs:
+      databases:
+        required: false
+        type: string
+        default: "all"
+        description: "Which databases to run (comma-separated or 'all')"
+      python-version:
+        required: false
+        type: string
+        default: "3.11.x"
+      ci-image:
+        required: false
+        type: string
+        default: ''
+    secrets:
+      LLM_MODEL:
+        required: true
+      LLM_ENDPOINT:
+        required: true
+      LLM_API_KEY:
+        required: true
+      LLM_ARGS:
+        required: false
+      LLM_API_VERSION:
+        required: true
+      EMBEDDING_MODEL:
+        required: true
+      EMBEDDING_API_KEY:
+        required: true
+
+      POSTGRES_PASSWORD:
+        required: false
+      NEO4J_API_URL:
+        required: false
+      NEO4J_API_KEY:
+        required: false
+
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  run-db-example-neo4j:
+    name: "Neo4j DB Example Test"
+    runs-on: ubuntu-22.04
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'neo4j') }}
+    steps:
+      - name: Check out
+        uses: actions/checkout@master
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Setup Neo4j with GDS
+        uses: ./.github/actions/setup_neo4j
+        id: neo4j
+
+      - name: Run Neo4j Example
+        env:
+          ENV: 'dev'
+          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          GRAPH_DATABASE_PROVIDER: "neo4j"
+          GRAPH_DATABASE_URL: ${{ steps.neo4j.outputs.neo4j-url }}
+          GRAPH_DATABASE_USERNAME: ${{ steps.neo4j.outputs.neo4j-username }}
+          GRAPH_DATABASE_PASSWORD: ${{ steps.neo4j.outputs.neo4j-password }}
+        run: |
+          uv run python examples/database_examples/neo4j_example.py
+
+  run-db-example-ladybug:
+    name: "Ladybug DB Example Test"
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'ladybug') || contains(inputs.databases, 'kuzu') }}
+
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Dependencies already installed
+        run: echo "Dependencies already installed in setup"
+
+      - name: Run Ladybug Example
+        env:
+          ENV: 'dev'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          GRAPH_DATABASE_PROVIDER: "ladybug"
+        run: |
+          uv run python examples/database_examples/ladybug_example.py
+
+  run-db-example-pgvector:
+    name: "PostgreSQL PGVector DB Example Test"
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'postgres') }}
+    services:
+      postgres:
+        image: ghcr.io/topoteretes/pgvector:pg17
+        credentials:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          POSTGRES_USER: cognee
+          POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}
+          POSTGRES_DB: cognee_db
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+            fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+          extra-dependencies: "postgres"
+
+      - name: Run PGVector Example
+        env:
+          ENV: 'dev'
+          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          DB_HOST: ${{ inputs.ci-image != '' && 'postgres' || '127.0.0.1' }}
+        run: |
+          uv run python examples/database_examples/pgvector_example.py

.github/workflows/dev_canary_release.yml

@@ -0,0 +1,123 @@
+name: Dev Canary Release
+
+on:
+  schedule:
+    # Every Monday at 06:00 UTC
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+  workflow_call:
+
+concurrency:
+  group: dev-canary-release
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  # ── Gate: run core test suites before publishing ────────────────────
+  test-gate:
+    name: Canary Test Gate
+    uses: ./.github/workflows/basic_tests.yml
+    with:
+      ci-image: ""
+    secrets: inherit
+
+  # ── Compute canary version ──────────────────────────────────────────
+  prepare:
+    name: Prepare Canary Version
+    runs-on: ubuntu-latest
+    needs: test-gate
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      canary_version: ${{ steps.version.outputs.canary_version }}
+    steps:
+      - name: Check out dev
+        uses: actions/checkout@v6
+        with:
+          ref: dev
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install Python
+        run: uv python install
+
+      - name: Compute canary version
+        id: version
+        run: |
+          BASE_VERSION="$(uv version --short)"
+          # Strip any existing .devN suffix to get the base
+          CLEAN_VERSION="${BASE_VERSION%%\.dev*}"
+          # PEP 440 dev release: 0.5.4.dev20260309
+          CANARY_VERSION="${CLEAN_VERSION}.dev$(date -u +%Y%m%d)"
+          echo "version=${CLEAN_VERSION}" >> "$GITHUB_OUTPUT"
+          echo "canary_version=${CANARY_VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Canary version: ${CANARY_VERSION}"
+
+  # ── Publish to PyPI ─────────────────────────────────────────────────
+  release-pypi:
+    name: Publish Dev Canary to PyPI
+    needs: prepare
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out dev
+        uses: actions/checkout@v6
+        with:
+          ref: dev
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install Python
+        run: uv python install
+
+      - name: Set canary version in pyproject.toml
+        run: uv version "${{ needs.prepare.outputs.canary_version }}"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: uv publish
+
+  # ── Publish Docker image ────────────────────────────────────────────
+  release-docker:
+    name: Publish Dev Canary Docker Image
+    needs: prepare
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out dev
+        uses: actions/checkout@v6
+        with:
+          ref: dev
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            cognee/cognee:dev-canary
+            cognee/cognee:${{ needs.prepare.outputs.canary_version }}
+          labels: |
+            version=${{ needs.prepare.outputs.canary_version }}
+            flavour=dev-canary
+          cache-from: type=registry,ref=cognee/cognee:buildcache
+          cache-to: type=registry,ref=cognee/cognee:buildcache,mode=max

.github/workflows/dev_previous_day_commits.yml

@@ -0,0 +1,351 @@
+name: automation | Draft Docs PRs For Previous Day Dev PRs
+
+on:
+  workflow_dispatch:
+    inputs:
+      lookback_days:
+        description: Number of UTC calendar days to look back when scanning merged PRs
+        required: false
+        default: "1"
+      anchor_date:
+        description: Optional UTC date to scan, in YYYY-MM-DD format
+        required: false
+        default: ""
+  schedule:
+    - cron: "59 23 * * *"
+
+permissions:
+  contents: read
+  pull-requests: read
+
+env:
+  lookback_days: ${{ github.event.inputs.lookback_days || vars.lookback_days || '1' }}
+
+jobs:
+  prepare-merged-branches:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 10
+    outputs:
+      start_date: ${{ steps.prepare.outputs.start_date }}
+      end_date: ${{ steps.prepare.outputs.end_date }}
+      has_merges: ${{ steps.prepare.outputs.has_merges }}
+      merge_summary: ${{ steps.prepare.outputs.merge_summary }}
+      matrix: ${{ steps.prepare.outputs.matrix }}
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Fetch latest dev branch
+        run: git fetch origin dev:refs/remotes/origin/dev --no-tags
+
+      - name: Prepare merged PRs
+        id: prepare
+        shell: bash
+        env:
+          INPUT_ANCHOR_DATE: ${{ github.event.inputs.anchor_date || '' }}
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+
+          args=(
+            --branch origin/dev
+            --lookback-days "${lookback_days}"
+          )
+
+          anchor_date="${INPUT_ANCHOR_DATE}"
+          if [ "${{ github.event_name }}" = "schedule" ]; then
+            anchor_date="$(date -u -d 'yesterday' +%F)"
+          fi
+
+          if [ -n "${anchor_date}" ]; then
+            echo "Using anchor date ${anchor_date}"
+            args+=(--anchor-date "${anchor_date}")
+          fi
+
+          python3 tools/prepare_merged_branches.py "${args[@]}"
+
+  create-docs-prs:
+    needs:
+      - prepare-merged-branches
+    if: ${{ needs.prepare-merged-branches.outputs.has_merges == 'true' }}
+    runs-on: ubuntu-22.04
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include: ${{ fromJSON(needs.prepare-merged-branches.outputs.matrix) }}
+
+    steps:
+      - name: Check out core repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install workflow dependencies
+        run: uv sync --locked
+
+      - name: Fetch latest dev branch
+        run: git fetch origin dev:refs/remotes/origin/dev --no-tags
+
+      - name: Prepare branch note paths
+        id: branch_paths
+        run: |
+          OUTPUT_DIR="branch-dev-notes/${{ matrix.safe_branch }}-${{ matrix.short_sha }}"
+          mkdir -p "${OUTPUT_DIR}"
+          echo "output_dir=${OUTPUT_DIR}" >> "${GITHUB_OUTPUT}"
+          echo "notes_json=${OUTPUT_DIR}/branch_notes.json" >> "${GITHUB_OUTPUT}"
+          echo "notes_markdown=${OUTPUT_DIR}/branch_notes.md" >> "${GITHUB_OUTPUT}"
+          echo "assessment_json=${OUTPUT_DIR}/docs_assessment.json" >> "${GITHUB_OUTPUT}"
+          echo "assessment_markdown=${OUTPUT_DIR}/docs_assessment.md" >> "${GITHUB_OUTPUT}"
+          echo "docs_edit_scope_json=${OUTPUT_DIR}/docs_edit_scope.json" >> "${GITHUB_OUTPUT}"
+          echo "docs_edit_scope_markdown=${OUTPUT_DIR}/docs_edit_scope.md" >> "${GITHUB_OUTPUT}"
+          echo "docs_scope_plan=${OUTPUT_DIR}/docs_scope_plan.md" >> "${GITHUB_OUTPUT}"
+
+      - name: Generate branch notes
+        env:
+          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY || secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_MODEL: ${{ vars.LLM_MODEL || secrets.LLM_MODEL || 'openai/gpt-4o-mini' }}
+          NOTES_JSON: ${{ steps.branch_paths.outputs.notes_json }}
+          NOTES_MARKDOWN: ${{ steps.branch_paths.outputs.notes_markdown }}
+          PR_NUMBER: ${{ matrix.pr_number }}
+          PR_TITLE: ${{ matrix.pr_title }}
+          PR_BODY_B64: ${{ matrix.pr_body_b64 }}
+          PR_URL: ${{ matrix.pr_url }}
+        run: |
+          uv run python tools/generate_branch_notes.py \
+            --branch-name "${{ matrix.branch_name }}" \
+            --merge-sha "${{ matrix.merge_sha }}" \
+            --first-parent "${{ matrix.first_parent }}" \
+            --second-parent "${{ matrix.second_parent }}" \
+            --pr-number "${PR_NUMBER}" \
+            --pr-title "${PR_TITLE}" \
+            --pr-body-base64 "${PR_BODY_B64}" \
+            --pr-url "${PR_URL}" \
+            --json-output "${NOTES_JSON}" \
+            --markdown-output "${NOTES_MARKDOWN}"
+
+      - name: Assess documentation impact for branch
+        id: assessment
+        env:
+          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY || secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_MODEL: ${{ vars.LLM_MODEL || secrets.LLM_MODEL || 'openai/gpt-4o-mini' }}
+          NOTES_JSON: ${{ steps.branch_paths.outputs.notes_json }}
+          NOTES_MARKDOWN: ${{ steps.branch_paths.outputs.notes_markdown }}
+          ASSESSMENT_JSON: ${{ steps.branch_paths.outputs.assessment_json }}
+          ASSESSMENT_MARKDOWN: ${{ steps.branch_paths.outputs.assessment_markdown }}
+        run: |
+          uv run python tools/assess_branch_notes.py \
+            --notes-json "${NOTES_JSON}" \
+            --notes-markdown "${NOTES_MARKDOWN}" \
+            --json-output "${ASSESSMENT_JSON}" \
+            --markdown-output "${ASSESSMENT_MARKDOWN}"
+
+          python3 tools/write_docs_assessment_outputs.py \
+            --assessment-json "${ASSESSMENT_JSON}" \
+            --branch-slug "${{ matrix.safe_branch }}" \
+            --short-sha "${{ matrix.short_sha }}" \
+            --pr-number "${{ matrix.pr_number }}"
+
+      - name: Check out docs repository
+        if: ${{ steps.assessment.outputs.needs_update == 'true' }}
+        uses: actions/checkout@v6
+        with:
+          repository: topoteretes/cognee-docs
+          token: ${{ secrets.REPO_DISPATCH_PAT_TOKEN }}
+          ref: main
+          path: docs-repo
+
+      - name: Prepare docs branch
+        if: ${{ steps.assessment.outputs.needs_update == 'true' }}
+        working-directory: docs-repo
+        run: |
+          git fetch origin "${{ steps.assessment.outputs.docs_branch }}" || true
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          if git show-ref --verify --quiet "refs/remotes/origin/${{ steps.assessment.outputs.docs_branch }}"; then
+            git checkout -B "${{ steps.assessment.outputs.docs_branch }}" "origin/${{ steps.assessment.outputs.docs_branch }}"
+          else
+            git checkout -B "${{ steps.assessment.outputs.docs_branch }}"
+          fi
+
+      - name: Prepare docs edit scope
+        if: ${{ steps.assessment.outputs.needs_update == 'true' }}
+        id: docs_scope
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          python3 tools/prepare_docs_edit_scope.py \
+            --repo "${{ github.repository }}" \
+            --pr-number "${{ matrix.pr_number }}" \
+            --docs-root docs-repo \
+            --notes-json "${{ steps.branch_paths.outputs.notes_json }}" \
+            --assessment-json "${{ steps.branch_paths.outputs.assessment_json }}" \
+            --scope-json-output "${{ steps.branch_paths.outputs.docs_edit_scope_json }}" \
+            --scope-markdown-output "${{ steps.branch_paths.outputs.docs_edit_scope_markdown }}"
+
+      - name: Plan docs changes with Claude
+        if: ${{ steps.assessment.outputs.needs_update == 'true' }}
+        id: claude_scope
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          prompt: |
+            Read and follow `.github/prompts/docs_scope_plan.md`.
+
+            - Branch: `${{ matrix.branch_name }}`
+            - PR: `#${{ matrix.pr_number }} ${{ matrix.pr_title }}`
+            - Merge SHA: `${{ matrix.merge_sha }}`
+            - Short SHA: `${{ matrix.short_sha }}`
+            - First parent: `${{ matrix.first_parent }}`
+            - Second parent: `${{ matrix.second_parent }}`
+            - Scope plan output: `./${{ steps.branch_paths.outputs.docs_scope_plan }}`
+
+            - **Prepared documentation edit scope** (`./${{ steps.branch_paths.outputs.docs_edit_scope_markdown }}`): Curated source files, docs candidates, assessment summary, and out-of-scope files.
+            - **Prepared documentation edit scope JSON** (`./${{ steps.branch_paths.outputs.docs_edit_scope_json }}`): Machine-readable copy of the prepared scope.
+          claude_args: "--allowed-tools Read,Write,Glob,Grep --max-turns 35"
+
+      - name: Validate docs scope plan
+        if: ${{ steps.assessment.outputs.needs_update == 'true' }}
+        run: |
+          test -s "${{ steps.branch_paths.outputs.docs_scope_plan }}"
+          if [ -n "$(git -C docs-repo status --short)" ]; then
+            echo "The docs planning step modified docs-repo, but planning must not edit documentation." >&2
+            git -C docs-repo status --short >&2
+            exit 1
+          fi
+
+      - name: Read docs scope plan outputs
+        if: ${{ steps.assessment.outputs.needs_update == 'true' }}
+        id: scope_plan
+        run: |
+          python3 tools/write_docs_scope_plan_outputs.py \
+            --scope-plan "${{ steps.branch_paths.outputs.docs_scope_plan }}"
+
+      - name: Generate docs changes with Claude
+        if: ${{ steps.assessment.outputs.needs_update == 'true' && steps.scope_plan.outputs.docs_needed == 'true' }}
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          prompt: |
+            Read and follow `.github/prompts/docs_edit.md`.
+
+            - Branch: `${{ matrix.branch_name }}`
+            - PR: `#${{ matrix.pr_number }} ${{ matrix.pr_title }}`
+            - Merge SHA: `${{ matrix.merge_sha }}`
+            - Short SHA: `${{ matrix.short_sha }}`
+            - First parent: `${{ matrix.first_parent }}`
+            - Second parent: `${{ matrix.second_parent }}`
+
+            ## Required inputs
+
+            Read these first:
+
+            - **Documentation scope plan** (`./${{ steps.branch_paths.outputs.docs_scope_plan }}`)
+            - **Branch notes** (`./${{ steps.branch_paths.outputs.notes_markdown }}`)
+            - **Documentation assessment** (`./${{ steps.branch_paths.outputs.assessment_markdown }}`)
+          claude_args: "--allowed-tools Read,Edit,Write,Glob,Grep,Bash --max-turns 50"
+
+      - name: Prepare docs PR content
+        if: ${{ steps.assessment.outputs.needs_update == 'true' && steps.scope_plan.outputs.docs_needed == 'true' }}
+        id: pr_content
+        env:
+          NOTES_JSON: ${{ steps.branch_paths.outputs.notes_json }}
+          ASSESSMENT_JSON: ${{ steps.branch_paths.outputs.assessment_json }}
+          BRANCH_NAME: ${{ matrix.branch_name }}
+          SHORT_SHA: ${{ matrix.short_sha }}
+          DEFAULT_PR_TITLE: ${{ steps.assessment.outputs.pr_title }}
+        run: |
+          python3 tools/prepare_docs_pr_content.py \
+            --notes-json "${NOTES_JSON}" \
+            --assessment-json "${ASSESSMENT_JSON}" \
+            --branch-name "${BRANCH_NAME}" \
+            --short-sha "${SHORT_SHA}" \
+            --default-pr-title "${DEFAULT_PR_TITLE}" \
+            --docs-root docs-repo
+
+      - name: Create docs draft commit
+        if: ${{ steps.assessment.outputs.needs_update == 'true' && steps.scope_plan.outputs.docs_needed == 'true' }}
+        id: commit_docs
+        working-directory: docs-repo
+        run: |
+          git add -A
+
+          if git diff --cached --quiet; then
+            echo "changes_made=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          git commit -m "${{ steps.pr_content.outputs.pr_title }}"
+          echo "changes_made=true" >> "$GITHUB_OUTPUT"
+
+      - name: Push docs draft branch
+        if: ${{ steps.assessment.outputs.needs_update == 'true' && steps.scope_plan.outputs.docs_needed == 'true' && steps.commit_docs.outputs.changes_made == 'true' }}
+        working-directory: docs-repo
+        run: git push --force-with-lease origin "${{ steps.assessment.outputs.docs_branch }}"
+
+      - name: Create or update docs pull request
+        if: ${{ steps.assessment.outputs.needs_update == 'true' && steps.scope_plan.outputs.docs_needed == 'true' }}
+        id: manage_pr
+        env:
+          GH_TOKEN: ${{ secrets.REPO_DISPATCH_PAT_TOKEN }}
+          HEAD_BRANCH: ${{ steps.assessment.outputs.docs_branch }}
+          PR_TITLE: ${{ steps.pr_content.outputs.pr_title }}
+          PR_BODY: ${{ steps.pr_content.outputs.pr_body }}
+          CHANGES_MADE: ${{ steps.commit_docs.outputs.changes_made }}
+        run: |
+          python3 tools/manage_docs_pr.py \
+            --target-repo topoteretes/cognee-docs \
+            --head-branch "${HEAD_BRANCH}" \
+            --pr-title "${PR_TITLE}" \
+            --pr-body "${PR_BODY}" \
+            --changes-made "${CHANGES_MADE}"
+
+      - name: Summarize docs PR result
+        if: ${{ steps.assessment.outputs.needs_update == 'true' && steps.scope_plan.outputs.docs_needed == 'true' }}
+        env:
+          CHANGED_FILES: ${{ steps.pr_content.outputs.changed_files }}
+        run: |
+          {
+            echo "## PR docs review: #${{ matrix.pr_number }} ${{ matrix.pr_title }}"
+            echo
+            echo "- Branch: \`${{ matrix.branch_name }}\`"
+            echo "- Merge commit: \`${{ matrix.merge_sha }}\`"
+            echo "- Needs documentation update: \`${{ steps.assessment.outputs.needs_update }}\`"
+            if [ "${{ steps.assessment.outputs.needs_update }}" = "true" ]; then
+              echo "- Docs branch: \`${{ steps.assessment.outputs.docs_branch }}\`"
+              if [ -n "${CHANGED_FILES}" ]; then
+                echo "- Updated docs files:"
+                printf '%s\n' "${CHANGED_FILES}" | while IFS= read -r changed_file; do
+                  [ -n "${changed_file}" ] || continue
+                  echo "  - \`${changed_file}\`"
+                done
+              else
+                echo "- Updated docs files: none"
+              fi
+              if [ -n "${{ steps.manage_pr.outputs.pr_url }}" ]; then
+                echo "- Pull request: ${{ steps.manage_pr.outputs.pr_url }}"
+              else
+                echo "- Pull request: not created"
+              fi
+            fi
+            echo
+            echo "### Documentation assessment"
+            echo
+            cat "${{ steps.branch_paths.outputs.assessment_markdown }}"
+          } >> "${GITHUB_STEP_SUMMARY}"

.github/workflows/disable_independent_workflows.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+
+# Navigate to the workflows directory
+cd "$(dirname "$0")"
+
+# List of workflows that should only be triggered via test-suites.yml
+WORKFLOWS=(
+  "test_weaviate.yml"
+  "test_kuzu.yml"
+  "test_multimetric_qa_eval_run.yaml"
+  "test_graphrag_vs_rag_notebook.yml"
+  "test_llms.yml"
+  "test_multimedia_example.yaml"
+  "test_deduplication.yml"
+  "test_eval_framework.yml"
+  "test_descriptive_graph_metrics.yml"
+  "test_llama_index_cognee_integration_notebook.yml"
+  "test_cognee_llama_index_notebook.yml"
+  "test_cognee_multimedia_notebook.yml"
+  "test_cognee_server_start.yml"
+  "test_telemetry.yml"
+  "test_neo4j.yml"
+  "test_pgvector.yml"
+  "test_ollama.yml"
+  "test_notebook.yml"
+  "test_simple_example.yml"
+  "test_code_graph_example.yml"
+)
+
+for workflow in "${WORKFLOWS[@]}"; do
+  if [ -f "$workflow" ]; then
+    echo "Processing $workflow..."
+
+    # Create a backup
+    cp "$workflow" "${workflow}.bak"
+
+    # Check if the file begins with a workflow_call trigger
+    if grep -q "workflow_call:" "$workflow"; then
+      echo "$workflow already has workflow_call trigger, skipping..."
+      continue
+    fi
+
+    # Get the content after the 'on:' section
+    on_line=$(grep -n "^on:" "$workflow" | cut -d ':' -f1)
+
+    if [ -z "$on_line" ]; then
+      echo "Warning: No 'on:' section found in $workflow, skipping..."
+      continue
+    fi
+
+    # Create a new file with the modified content
+    {
+      # Copy the part before 'on:'
+      head -n $((on_line-1)) "$workflow"
+
+      # Add the new on: section that only includes workflow_call
+      echo "on:"
+      echo "  workflow_call:"
+      echo "    secrets:"
+      echo "      inherit: true"
+
+      # Find where to continue after the original 'on:' section
+      next_section=$(awk "NR > $on_line && /^[a-z]/ {print NR; exit}" "$workflow")
+
+      if [ -z "$next_section" ]; then
+        next_section=$(wc -l < "$workflow")
+        next_section=$((next_section+1))
+      fi
+
+      # Copy the rest of the file starting from the next section
+      tail -n +$next_section "$workflow"
+    } > "${workflow}.new"
+
+    # Replace the original with the new version
+    mv "${workflow}.new" "$workflow"
+
+    echo "Modified $workflow to only run when called from test-suites.yml"
+  else
+    echo "Warning: $workflow not found, skipping..."
+  fi
+done
+
+echo "Finished modifying workflows!"

.github/workflows/distributed_test.yml

@@ -0,0 +1,81 @@
+name: Distributed Cognee test with modal
+permissions:
+  contents: read
+  packages: read
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        required: false
+        type: string
+        default: '3.13.x'
+      ci-image:
+        required: false
+        type: string
+        default: ''
+    secrets:
+      LLM_MODEL:
+        required: true
+      LLM_ENDPOINT:
+        required: true
+      LLM_API_KEY:
+        required: true
+      LLM_ARGS:
+        required: false
+      LLM_API_VERSION:
+        required: true
+      EMBEDDING_MODEL:
+        required: true
+      EMBEDDING_API_KEY:
+        required: true
+      OPENAI_API_KEY:
+        required: true
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  run-server-start-test:
+    name: Distributed Cognee test (Modal)
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.13.x'
+          extra-dependencies: "distributed postgres"
+
+      - name: Run Distributed Cognee (Modal)
+        env:
+          ENV: 'dev'
+          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          MODAL_TOKEN_ID: ${{ secrets.MODAL_TOKEN_ID }}
+          MODAL_TOKEN_SECRET: ${{ secrets.MODAL_TOKEN_SECRET }}
+          MODAL_SECRET_NAME: ${{ secrets.MODAL_SECRET_NAME }}
+          GRAPH_DATABASE_PROVIDER: "neo4j"
+          GRAPH_DATABASE_URL: ${{ secrets.AZURE_NEO4j_URL }}
+          GRAPH_DATABASE_USERNAME: ${{ secrets.AZURE_NEO4J_USERNAME }}
+          GRAPH_DATABASE_PASSWORD: ${{ secrets.AZURE_NEO4J_PW }}
+          DB_PROVIDER: "postgres"
+          DB_NAME: ${{ secrets.AZURE_POSTGRES_DB_NAME }}
+          DB_HOST: ${{ secrets.AZURE_POSTGRES_HOST }}
+          DB_PORT: ${{ secrets.AZURE_POSTGRES_PORT }}
+          DB_USERNAME: ${{ secrets.AZURE_POSTGRES_USERNAME }}
+          DB_PASSWORD: ${{ secrets.AZURE_POSTGRES_PW }}
+          VECTOR_DB_PROVIDER: "pgvector"
+          COGNEE_DISTRIBUTED: "true"
+        run: uv run modal run ./distributed/entrypoint.py

.github/workflows/docker_compose.yml

@@ -0,0 +1,108 @@
+name: test | docker compose
+
+on:
+  workflow_call:
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  docker-compose-test:
+    runs-on: ubuntu-22.04
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@master
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Build Docker images
+      env:
+        ENV: dev
+      run: |
+        docker compose -f docker-compose.yml build
+
+    - name: Create container .env
+      # docker-compose.yml bind-mounts ./.env into the container; CI has no
+      # checked-in .env, so provide the runtime credentials the server needs.
+      # Secrets flow through the env block so the script body never renders
+      # secret material (GitHub's log masking then only has exact values to hide).
+      env:
+        LLM_MODEL: ${{ secrets.LLM_MODEL }}
+        LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+        LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+        LLM_ARGS: ${{ secrets.LLM_ARGS }}
+        LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+        EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+        EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+      run: |
+        printenv | grep -E '^(LLM_|EMBEDDING_)' > .env
+        echo "EMBEDDING_DIMENSIONS=300" >> .env
+        echo "COGNEE_SKIP_CONNECTION_TEST=true" >> .env
+
+    - name: Run Docker Compose
+      env:
+        ENV: dev
+      run: |
+        docker compose -f docker-compose.yml up -d
+
+    - name: Wait for server health
+      run: |
+        for attempt in $(seq 1 60); do
+          if curl -sf http://localhost:8000/health >/dev/null; then
+            echo "server healthy after ~$((attempt * 3))s"
+            exit 0
+          fi
+          if [ "$(docker inspect -f '{{.State.Running}}' cognee 2>/dev/null)" != "true" ]; then
+            echo "cognee container is not running"
+            docker compose -f docker-compose.yml logs cognee | tail -60
+            exit 1
+          fi
+          sleep 3
+        done
+        echo "server did not become healthy in time"
+        docker compose -f docker-compose.yml logs cognee | tail -60
+        exit 1
+
+    - name: Verify remember and recall round-trip
+      run: |
+        TOKEN=$(curl -sf -X POST http://localhost:8000/api/v1/auth/login \
+          -d "username=default_user@example.com&password=default_password" | jq -r .access_token)
+        [ -n "$TOKEN" ] && [ "$TOKEN" != "null" ] || { echo "login failed"; exit 1; }
+
+        FACT="The glassblower Odene Marsk crafted the twin cobalt lanterns of the Vellinge lighthouse in 1931."
+        echo "$FACT" > fact.txt
+        REMEMBERED=$(curl -sf -X POST http://localhost:8000/api/v1/remember \
+          -H "Authorization: Bearer $TOKEN" \
+          -F "datasetName=compose_smoke" \
+          -F "data=@fact.txt;type=text/plain")
+        echo "$REMEMBERED" | jq -e '.dataset_id != null' >/dev/null \
+          || { echo "remember returned no dataset_id"; echo "$REMEMBERED"; exit 1; }
+        echo "remember: ingested into $(echo "$REMEMBERED" | jq -r .dataset_id)"
+
+        # Deterministic check: CHUNKS recall returns the raw stored text, no
+        # LLM involved — the full stored fact must come back verbatim.
+        CHUNKS=$(curl -sf -X POST http://localhost:8000/api/v1/recall \
+          -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+          -d '{"query":"cobalt lanterns lighthouse","searchType":"CHUNKS","datasets":["compose_smoke"]}')
+        echo "$CHUNKS" | grep -qF "$FACT" || { echo "CHUNKS recall missing stored fact"; echo "$CHUNKS"; exit 1; }
+        echo "recall (CHUNKS): stored fact retrieved verbatim"
+
+        # End-to-end answer check: the graph-grounded completion must name the entity.
+        ANSWER=$(curl -sf -X POST http://localhost:8000/api/v1/recall \
+          -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+          -d '{"query":"Who crafted the twin cobalt lanterns of the Vellinge lighthouse, and in which year?","searchType":"GRAPH_COMPLETION","datasets":["compose_smoke"]}')
+        echo "recall (GRAPH_COMPLETION): $ANSWER"
+        echo "$ANSWER" | grep -qi "Marsk" || { echo "graph completion did not mention the remembered entity"; exit 1; }
+
+    - name: Show server logs on failure
+      if: failure()
+      # Filter key-shaped lines: GitHub masks exact secret values, but partial
+      # or transformed echoes (e.g. provider auth errors) would slip through.
+      run: docker compose -f docker-compose.yml logs cognee | grep -viE "api[-_]?key|authorization|bearer" | tail -100
+
+    - name: Shut down Docker Compose
+      if: always()
+      run: |
+        docker compose -f docker-compose.yml down

.github/workflows/dockerhub-mcp.yml

@@ -0,0 +1,65 @@
+name: build | Build and Push Cognee MCP Docker Image to dockerhub
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  docker-build-and-push:
+    runs-on:
+      group: Default
+      labels:
+        - docker_build_runner
+
+    steps:
+      - name: Check and free disk space before build
+        run: |
+          echo "=== Before cleanup ==="
+          df -h
+          echo "Removing unused preinstalled SDKs to free space..."
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc || true
+          docker system prune -af || true
+          echo "=== After cleanup ==="
+          df -h
+
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          buildkitd-flags: --root /tmp/buildkit
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: cognee/cognee-mcp
+          tags: |
+            type=ref,event=branch
+            type=sha,prefix={{branch}}-
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          file: cognee-mcp/Dockerfile
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=registry,ref=cognee/cognee-mcp:buildcache
+          cache-to: type=registry,ref=cognee/cognee-mcp:buildcache,mode=max
+
+
+      - name: Image digest
+        run: echo ${{ steps.build.outputs.digest }}

.github/workflows/dockerhub.yml

@@ -0,0 +1,48 @@
+name: build | Build and Push Docker Image to dockerhub
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  docker-build-and-push:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: cognee/cognee
+          tags: |
+            type=ref,event=branch
+            type=sha,prefix={{branch}}-
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=registry,ref=cognee/cognee:buildcache
+          cache-to: type=registry,ref=cognee/cognee:buildcache,mode=max
+
+      - name: Image digest
+        run: echo ${{ steps.build.outputs.digest }}

.github/workflows/examples_tests.yml

@@ -0,0 +1,384 @@
+name: Reusable Examples Tests
+
+permissions:
+  contents: read
+  packages: read
+
+on:
+  workflow_call:
+    inputs:
+      ci-image:
+        required: false
+        type: string
+        default: ''
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  test-multimedia-example:
+    name: Run Multimedia Example
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+
+      - name: Run Multimedia Example
+        env:
+          ENV: 'dev'
+          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: uv run python ./examples/demos/multimedia_processing/multimedia_audio_image_processing_example.py
+
+  test-eval-example:
+    name: Run Eval Example
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: "deepeval"
+
+      - name: Run Evaluation Framework Example
+        env:
+          ENV: 'dev'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./cognee/eval_framework/run_eval.py
+
+  test-descriptive-metrics:
+    name: Run Descriptive Metrics Example
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+
+      - name: Setup Neo4j with GDS
+        uses: ./.github/actions/setup_neo4j
+        id: neo4j
+
+      - name: Run Descriptive Graph Metrics Example
+        env:
+          ENV: 'dev'
+          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          GRAPH_DATABASE_PROVIDER: "neo4j"
+          GRAPH_DATABASE_URL: ${{ steps.neo4j.outputs.neo4j-url }}
+          GRAPH_DATABASE_USERNAME: ${{ steps.neo4j.outputs.neo4j-username }}
+          GRAPH_DATABASE_PASSWORD: ${{ steps.neo4j.outputs.neo4j-password }}
+        run: uv run python ./cognee/tests/tasks/descriptive_metrics/neo4j_metrics_test.py
+
+  test-temporal-example:
+    name: Run Temporal Tests
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+
+      - name: Run Temporal Example
+        env:
+          ENV: 'dev'
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./examples/demos/temporal_awareness_example/temporal_awareness_example.py
+
+  test-ontology-example:
+    name: Run Ontology Tests
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+
+      - name: Run Ontology Demo Example
+        env:
+          ENV: 'dev'
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./examples/demos/ontology_reference_vocabulary/ontology_as_reference_vocabulary_example.py
+
+  test-feedback-score-shifting-example:
+    name: Run Feedback Score Shifting Example
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+
+      - name: Run Feedback Score Shifting Example
+        env:
+          ENV: 'dev'
+          CACHING: 'true'
+          CACHE_BACKEND: 'fs'
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./examples/demos/feedback_score_shifting_example.py
+
+  test-agentic-reasoning:
+    name: Run Agentic Reasoning Tests
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+
+      - name: Run Agentic Reasoning Example
+        env:
+          ENV: 'dev'
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./examples/custom_pipelines/agentic_reasoning_procurement_example.py
+
+  test-memify:
+    name: Run Memify Example
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+
+      - name: Run Memify Tests
+        env:
+          ENV: 'dev'
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./examples/custom_pipelines/memify_coding_agent_rule_extraction_example.py
+
+  test-custom-pipeline:
+    name: Run Custom Pipeline Example
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+
+      - name: Run Custom Pipeline Example
+        env:
+          ENV: 'dev'
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./examples/custom_pipelines/custom_cognify_pipeline_example.py
+
+  test-permissions-example:
+    name: Run Permissions Example
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+
+      - name: Run Permissions Example
+        env:
+          ENV: 'dev'
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./examples/configurations/permissions_example/user_permissions_and_access_control_example.py
+
+  test-s3-permissions-example: # Make sure permission and multi-user mode work with S3 file system
+    name: Run Permissions Example
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    defaults:
+      run:
+        shell: bash
+    services:
+      postgres: # Using postgres to avoid storing and using SQLite from S3
+        image: ghcr.io/topoteretes/pgvector:pg17
+        credentials:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          POSTGRES_USER: cognee
+          POSTGRES_PASSWORD: cognee
+          POSTGRES_DB: cognee_db
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: "postgres aws"
+
+      - name: Run S3 Permissions Example
+        env:
+          ENV: 'dev'
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          STORAGE_BACKEND: 's3'
+          AWS_REGION: eu-west-1
+          AWS_ENDPOINT_URL: https://s3-eu-west-1.amazonaws.com
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_S3_DEV_USER_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_S3_DEV_USER_SECRET_KEY }}
+          STORAGE_BUCKET_NAME: github-runner-cognee-tests
+          DATA_ROOT_DIRECTORY: "s3://github-runner-cognee-tests/cognee/data"
+          SYSTEM_ROOT_DIRECTORY: "s3://github-runner-cognee-tests/cognee/system"
+          DB_PROVIDER: 'postgres'
+          DB_NAME: 'cognee_db'
+          DB_HOST: ${{ inputs.ci-image != '' && 'postgres' || '127.0.0.1' }}
+          DB_PORT: 5432
+          DB_USERNAME: cognee
+          DB_PASSWORD: cognee
+        run: uv run python ./examples/configurations/permissions_example/user_permissions_and_access_control_example.py
+
+  # Docling test - NO container (runs on macOS, container only works on Linux)
+  test_docling_add:
+    name: Run Add with Docling Test
+    runs-on: macos-15
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: 'docling'
+
+      - name: Run Docling Test
+        env:
+          ENV: 'dev'
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: |
+          uv sync --extra docling
+          uv run python ./cognee/tests/test_add_docling_document.py

.github/workflows/graph_db_tests.yml

@@ -0,0 +1,225 @@
+name: Reusable Graph DB Tests
+
+permissions:
+  contents: read
+  packages: read
+
+on:
+  workflow_call:
+    inputs:
+      databases:
+        required: false
+        type: string
+        default: "all"
+        description: "Which vector databases to test (comma-separated list or 'all')"
+      python-version:
+        required: false
+        type: string
+        default: "3.11.x"
+        description: "Python version to use for testing"
+      ci-image:
+        required: false
+        type: string
+        default: ''
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  run-kuzu-tests:
+    name: Kuzu Tests
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'kuzu') }}
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Dependencies already installed
+        run: echo "Dependencies already installed in setup"
+
+      - name: Run Kuzu Tests
+        env:
+          ENV: 'dev'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./cognee/tests/test_kuzu.py
+
+      - name: Run Weighted Edges Tests with Kuzu
+        env:
+          ENV: 'dev'
+          GRAPH_DATABASE_PROVIDER: "kuzu"
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run pytest cognee/tests/unit/interfaces/graph/test_weighted_edges.py -v
+
+  run-postgres-tests:
+    name: Postgres Graph Tests
+    runs-on: ubuntu-22.04
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'postgres') }}
+    services:
+      postgres:
+        image: ghcr.io/topoteretes/pgvector:pg17
+        credentials:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          POSTGRES_USER: cognee
+          POSTGRES_PASSWORD: cognee
+          POSTGRES_DB: cognee_db
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+          extra-dependencies: postgres
+
+      - name: Run Postgres Adapter Unit Tests
+        env:
+          DB_PROVIDER: postgres
+          DB_HOST: localhost
+          DB_PORT: 5432
+          DB_USERNAME: cognee
+          DB_PASSWORD: cognee
+          DB_NAME: cognee_db
+        run: uv run pytest cognee/tests/e2e/postgres/test_postgres_adapter.py -v
+
+      - name: Run Postgres Graph E2E Test
+        env:
+          ENV: 'dev'
+          GRAPH_DATABASE_PROVIDER: "postgres"
+          GRAPH_DATABASE_URL: "postgresql+asyncpg://cognee:cognee@localhost:5432/cognee_db"
+          DB_PROVIDER: postgres
+          DB_HOST: localhost
+          DB_PORT: 5432
+          DB_USERNAME: cognee
+          DB_PASSWORD: cognee
+          DB_NAME: cognee_db
+          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./cognee/tests/e2e/postgres/test_graphdb_postgres.py
+
+#      - name: Run Postgres Hybrid Adapter Tests
+#        env:
+#          ENV: 'dev'
+#          DB_PROVIDER: postgres
+#          DB_HOST: localhost
+#          DB_PORT: 5432
+#          DB_USERNAME: cognee
+#          DB_PASSWORD: cognee
+#          DB_NAME: cognee_db
+#          EMBEDDING_DIMENSIONS: 300
+#          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+#          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+#        run: uv run pytest cognee/tests/e2e/postgres/test_postgres_hybrid_adapter.py -v
+#
+#      - name: Run Postgres Hybrid E2E Test
+#        env:
+#          ENV: 'dev'
+#          USE_UNIFIED_PROVIDER: "pghybrid"
+#          DB_PROVIDER: postgres
+#          DB_HOST: localhost
+#          DB_PORT: 5432
+#          DB_USERNAME: cognee
+#          DB_PASSWORD: cognee
+#          DB_NAME: cognee_db
+#          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+#          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+#          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+#          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+#          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+#          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+#          EMBEDDING_DIMENSIONS: 300
+#          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+#          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+#        run: uv run python ./cognee/tests/e2e/postgres/test_pghybrid.py
+
+  run-neo4j-tests:
+    name: Neo4j Tests
+    runs-on: ubuntu-22.04
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'neo4j') }}
+    steps:
+      - name: Check out
+        uses: actions/checkout@master
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Setup Neo4j with GDS
+        uses: ./.github/actions/setup_neo4j
+        id: neo4j
+
+      - name: Run default Neo4j
+        env:
+          ENV: 'dev'
+          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          GRAPH_DATABASE_PROVIDER: "neo4j"
+          GRAPH_DATABASE_URL: ${{ steps.neo4j.outputs.neo4j-url }}
+          GRAPH_DATABASE_USERNAME: ${{ steps.neo4j.outputs.neo4j-username }}
+          GRAPH_DATABASE_PASSWORD: ${{ steps.neo4j.outputs.neo4j-password }}
+        run: uv run python ./cognee/tests/test_neo4j.py
+
+      - name: Run Weighted Edges Tests with Neo4j
+        env:
+          ENV: 'dev'
+          GRAPH_DATABASE_PROVIDER: "neo4j"
+          GRAPH_DATABASE_URL: ${{ secrets.NEO4J_API_URL }}
+          GRAPH_DATABASE_PASSWORD: ${{ secrets.NEO4J_API_KEY }}
+          GRAPH_DATABASE_USERNAME: "neo4j"
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run pytest cognee/tests/unit/interfaces/graph/test_weighted_edges.py -v

.github/workflows/integration_tests.yml

@@ -0,0 +1,192 @@
+name: Reusable Integration Tests
+
+permissions:
+  contents: read
+  packages: read
+
+on:
+  workflow_call:
+    inputs:
+      ci-image:
+        required: false
+        type: string
+        default: ''
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  integration-retrieval:
+    name: Integration - Retrieval (${{ matrix.split-group }}/4)
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        split-group: [1, 2, 3, 4]
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    env:
+      ENV: 'dev'
+      LLM_PROVIDER: openai
+      LLM_MODEL: ${{ secrets.LLM_MODEL }}
+      LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+      LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+      LLM_ARGS: ${{ secrets.LLM_ARGS }}
+      LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+      EMBEDDING_DIMENSIONS: 300
+      EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+      EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: "scraping fastembed"
+
+      - name: Run Retrieval Tests
+        run: uv run pytest cognee/tests/integration/retrieval/ --splits 4 --group ${{ matrix.split-group }}
+
+  integration-documents-tasks:
+    name: Integration - Documents & Tasks (${{ matrix.split-group }}/2)
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        split-group: [1, 2]
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    env:
+      ENV: 'dev'
+      LLM_PROVIDER: openai
+      LLM_MODEL: ${{ secrets.LLM_MODEL }}
+      LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+      LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+      LLM_ARGS: ${{ secrets.LLM_ARGS }}
+      LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+      EMBEDDING_DIMENSIONS: 300
+      EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+      EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: "scraping"
+
+      - name: Run Document & Task Tests
+        run: uv run pytest cognee/tests/integration/documents/ cognee/tests/integration/tasks/ --splits 2 --group ${{ matrix.split-group }}
+
+  integration-infra:
+    name: Integration - Infrastructure (${{ matrix.split-group }}/3)
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        split-group: [1, 2, 3]
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    env:
+      ENV: 'dev'
+      LLM_PROVIDER: openai
+      LLM_MODEL: ${{ secrets.LLM_MODEL }}
+      LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+      LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+      LLM_ARGS: ${{ secrets.LLM_ARGS }}
+      LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+      EMBEDDING_DIMENSIONS: 300
+      EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+      EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          # fastembed so the embedding tokenizer delegation tests can import
+          # FastembedEmbeddingEngine.
+          extra-dependencies: "scraping fastembed"
+
+      - name: Run Infrastructure Tests
+        run: uv run pytest cognee/tests/integration/infrastructure/ --splits 3 --group ${{ matrix.split-group }}
+
+  integration-web:
+    name: Integration - Web
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    env:
+      ENV: 'dev'
+      LLM_PROVIDER: openai
+      LLM_MODEL: ${{ secrets.LLM_MODEL }}
+      LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+      LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+      LLM_ARGS: ${{ secrets.LLM_ARGS }}
+      LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+      EMBEDDING_DIMENSIONS: 300
+      EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+      EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: "scraping"
+
+      - name: Run Web Integration Tests
+        run: uv run pytest cognee/tests/integration/web_url_crawler/
+
+  integration-other:
+    name: Integration - Deletion & Misc
+    runs-on: ubuntu-22.04
+    services:
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 5
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    env:
+      ENV: 'dev'
+      LLM_PROVIDER: openai
+      LLM_MODEL: ${{ secrets.LLM_MODEL }}
+      LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+      LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+      LLM_ARGS: ${{ secrets.LLM_ARGS }}
+      LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+      EMBEDDING_DIMENSIONS: 300
+      EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+      EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+      CACHE_HOST: redis
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: "scraping redis"
+
+      - name: Run Deletion & Misc Tests
+        run: uv run pytest cognee/tests/integration/test_delete_edge_cases.py cognee/tests/integration/shared/

.github/workflows/label-core-team.yml

@@ -0,0 +1,74 @@
+name: Label PRs from core team
+
+on:
+  pull_request_target:
+    types: [opened, reopened, synchronize, ready_for_review, edited]
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  label-core-team:
+    if: ${{ !github.event.pull_request.draft }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out base repository
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ github.repository }}
+          ref: ${{ github.event.pull_request.base.ref }}
+
+      - name: Determine if PR author is a core team member
+        id: check_core
+        shell: bash
+        run: |
+          AUTHOR="${{ github.event.pull_request.user.login }}"
+          LIST_FILE=".github/core-team.txt"
+
+          if [ ! -f "$LIST_FILE" ]; then
+            echo "core=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Normalize author to lowercase and strip leading '@'
+          AUTHOR_NORM="$(echo "$AUTHOR" | tr '[:upper:]' '[:lower:]' | sed 's/^@//')"
+
+          # Compare against normalized list values (ignore comments/blank lines)
+          if awk -v author="$AUTHOR_NORM" '
+            BEGIN { found=0 }
+            {
+              line=$0
+              sub(/^[ \t]+|[ \t]+$/, "", line)
+              if (line ~ /^#/ || line == "") next
+              sub(/^@/, "", line)
+              line=tolower(line)
+              if (line == author) { found=1; exit }
+            }
+            END { exit(found ? 0 : 1) }
+          ' "$LIST_FILE"; then
+            echo "core=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "core=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Add core-team label
+        if: steps.check_core.outputs.core == 'true'
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const label = 'core-team';
+            const { owner, repo } = context.repo;
+            const prNumber = context.payload.pull_request.number;
+            try {
+              await github.rest.issues.addLabels({
+                owner,
+                repo,
+                issue_number: prNumber,
+                labels: [label],
+              });
+              core.info(`Label '${label}' added to PR #${prNumber}`);
+            } catch (error) {
+              core.warning(`Failed to add label: ${error.message}`);
+            }

.github/workflows/load_tests.yml

@@ -0,0 +1,73 @@
+name: Load tests
+
+permissions:
+  contents: read
+  packages: read
+
+on:
+  workflow_dispatch:
+  workflow_call:
+    inputs:
+      ci-image:
+        required: false
+        type: string
+        default: ''
+    secrets:
+      LLM_MODEL:
+        required: true
+      LLM_ENDPOINT:
+        required: true
+      LLM_API_KEY:
+        required: true
+      LLM_ARGS:
+        required: false
+      LLM_API_VERSION:
+        required: true
+      EMBEDDING_MODEL:
+        required: true
+      EMBEDDING_API_KEY:
+        required: true
+      OPENAI_API_KEY:
+        required: true
+      AWS_ACCESS_KEY_ID:
+        required: true
+      AWS_SECRET_ACCESS_KEY:
+        required: true
+
+jobs:
+  test-load:
+    name: Test Load
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    timeout-minutes: 60
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: "aws"
+
+      - name: Verify File Descriptor Limit
+        run: ulimit -n
+
+      - name: Run Load Test
+        env:
+          ENV: 'dev'
+          ENABLE_BACKEND_ACCESS_CONTROL: True
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          STORAGE_BACKEND: s3
+          AWS_REGION: eu-west-1
+          AWS_ENDPOINT_URL: https://s3-eu-west-1.amazonaws.com
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_S3_DEV_USER_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_S3_DEV_USER_SECRET_KEY }}
+        run: uv run python ./cognee/tests/test_load.py

.github/workflows/mirror-images.yml

@@ -0,0 +1,54 @@
+name: Mirror external images to GHCR
+
+# Copies the pinned third-party images CI depends on (pgvector) into GHCR, so the
+# PR / test hot path never pulls from Docker Hub — which is rate-limited and flaky
+# from GitHub Actions (intermittent `registry-1.docker.io ... timeout` on service
+# container setup). The test workflows reference ghcr.io/<owner>/pgvector:pg17.
+#
+# Runs weekly for freshness and on-demand. IMPORTANT: run this once (Actions ->
+# "Mirror external images to GHCR" -> Run workflow) BEFORE the GHCR references go
+# live, so the image exists. Ensure the resulting GHCR package is accessible to
+# this repo (public, or repo-linked) so service pulls with GITHUB_TOKEN succeed.
+
+on:
+  schedule:
+    - cron: "0 6 * * 1"   # Mondays 06:00 UTC
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  mirror:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        image:
+          - pgvector/pgvector:pg17
+    steps:
+      - name: Log in to Docker Hub (authenticated source pulls)
+        uses: docker/login-action@v3
+        continue-on-error: true   # best-effort: fall back to anonymous if unset
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Mirror ${{ matrix.image }} -> GHCR
+        run: |
+          set -euo pipefail
+          SRC="${{ matrix.image }}"
+          DST="ghcr.io/${{ github.repository_owner }}/${SRC##*/}"
+          echo "Mirroring $SRC -> $DST"
+          docker pull "$SRC"
+          docker tag  "$SRC" "$DST"
+          docker push "$DST"
+          echo "Done: $DST"

.github/workflows/nightly_tests.yml

@@ -0,0 +1,246 @@
+name: Nightly Tests
+permissions:
+  contents: read
+  packages: write
+
+on:
+  schedule:
+    - cron: '0 3 * * *'
+  workflow_dispatch:
+  # Note: Run Nightly CI on change to any of the following files.
+  pull_request:
+    paths:
+      - '.github/workflows/nightly_tests.yml'
+      - '.github/workflows/performance_report.yml'
+
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  RUNTIME__LOG_LEVEL: ERROR
+  ENV: 'dev'
+
+jobs:
+  ollama-tests:
+    name: Ollama Tests
+    uses: ./.github/workflows/test_ollama.yml
+    secrets: inherit
+
+  llamacpp-tests:
+    name: Llama-cpp Tests
+    uses: ./.github/workflows/test_llamacpp.yml
+    secrets: inherit
+
+  # ══ Performance: each caller runs BOTH file_based and postgres backends ════
+  perf-small-llm:
+    name: Performance — 50 Small Documents (real LLM)
+    uses: ./.github/workflows/performance_report.yml
+    with:
+      mode: llm
+      label: 50_small_documents
+      runs: '3'
+      num_memories: '50'
+      memories_key: nightly_ci_artifacts/performance_test_artifacts/memories.json
+    secrets: inherit
+
+  perf-small-mock:
+    name: Performance — 50 Small Documents (mock LLM)
+    uses: ./.github/workflows/performance_report.yml
+    with:
+      mode: mock_llm
+      label: 50_small_documents
+      runs: '3'
+      num_memories: '50'
+      memories_key: nightly_ci_artifacts/performance_test_artifacts/memories.json
+      mock_memories_key: nightly_ci_artifacts/performance_test_artifacts/mock_memories.json
+    secrets: inherit
+
+  perf-wap-llm:
+    name: Performance — War and Peace (real LLM)
+    uses: ./.github/workflows/performance_report.yml
+    with:
+      mode: llm
+      label: war_and_peace
+      runs: '3'
+      memories_key: nightly_ci_artifacts/performance_test_artifacts/war_and_peace.json
+    secrets: inherit
+
+  perf-wap-mock:
+    name: Performance — War and Peace (mock LLM)
+    uses: ./.github/workflows/performance_report.yml
+    with:
+      mode: mock_llm
+      label: war_and_peace
+      runs: '3'
+      memories_key: nightly_ci_artifacts/performance_test_artifacts/war_and_peace.json
+      mock_memories_key: nightly_ci_artifacts/performance_test_artifacts/mock_war_and_peace.json
+    secrets: inherit
+
+  notify:
+    name: Test Completion Status
+    needs: [
+      ollama-tests,
+      llamacpp-tests,
+      perf-small-llm,
+      perf-small-mock,
+      perf-wap-llm,
+      perf-wap-mock,
+    ]
+    runs-on: ubuntu-latest
+    if: ${{ !cancelled() }}
+    steps:
+      - name: Determine status
+        id: status
+        run: |
+          if [[ "${{ needs.ollama-tests.result }}" == "success" &&
+                "${{ needs.llamacpp-tests.result }}" == "success" &&
+                "${{ needs.perf-small-llm.result }}" == "success" &&
+                "${{ needs.perf-small-mock.result }}" == "success" &&
+                "${{ needs.perf-wap-llm.result }}" == "success" &&
+                "${{ needs.perf-wap-mock.result }}" == "success" ]]; then
+            echo "passed=true" >> "$GITHUB_OUTPUT"
+            echo "emoji=✅" >> "$GITHUB_OUTPUT"
+            echo "summary=All nightly test suites completed successfully!" >> "$GITHUB_OUTPUT"
+          else
+            echo "passed=false" >> "$GITHUB_OUTPUT"
+            echo "emoji=❌" >> "$GITHUB_OUTPUT"
+            echo "summary=One or more nightly test suites failed." >> "$GITHUB_OUTPUT"
+          fi
+          echo "ran_at=$(date -u '+%Y-%m-%d %H:%M UTC')" >> "$GITHUB_OUTPUT"
+
+      - name: Presign performance report links
+        id: presign
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_S3_DEV_USER_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_S3_DEV_USER_SECRET_KEY }}
+          AWS_DEFAULT_REGION: eu-west-1
+          BUCKET: github-runner-cognee-tests
+          # "<slack-output-name> <s3-key>" per line. The key already encodes the
+          # backend (file_based/ or postgres/), so presigning is fully generic.
+          REPORT_KEYS: |
+            url_file_small_llm ${{ needs.perf-small-llm.outputs.file_based_html_key }}
+            url_file_small_mock ${{ needs.perf-small-mock.outputs.file_based_html_key }}
+            url_file_wap_llm ${{ needs.perf-wap-llm.outputs.file_based_html_key }}
+            url_file_wap_mock ${{ needs.perf-wap-mock.outputs.file_based_html_key }}
+            url_pg_small_llm ${{ needs.perf-small-llm.outputs.postgres_html_key }}
+            url_pg_small_mock ${{ needs.perf-small-mock.outputs.postgres_html_key }}
+            url_pg_wap_llm ${{ needs.perf-wap-llm.outputs.postgres_html_key }}
+            url_pg_wap_mock ${{ needs.perf-wap-mock.outputs.postgres_html_key }}
+        run: |
+          set -euo pipefail
+          # 7 days = 604800s is the maximum lifetime for an IAM-user presigned URL.
+          # Skip empty keys (a failed perf job produces no report).
+          while read -r name key; do
+            [ -n "${key:-}" ] || continue
+            echo "$name=$(aws s3 presign "s3://$BUCKET/$key" --expires-in 604800)" >> "$GITHUB_OUTPUT"
+          done <<< "$REPORT_KEYS"
+
+      - name: Post status to Slack
+        uses: slackapi/slack-github-action@v2.1.0
+        with:
+          method: chat.postMessage
+          token: ${{ secrets.SLACK_NIGHTLY_BOT_TOKEN }}
+          payload: |
+            channel: ${{ secrets.SLACK_NIGHTLY_CHANNEL_ID }}
+            text: "${{ steps.status.outputs.emoji }} Nightly Tests (${{ steps.status.outputs.ran_at }}): ${{ steps.status.outputs.summary }}"
+            blocks:
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: |
+                    ${{ steps.status.outputs.emoji }} *Nightly Tests* — ${{ steps.status.outputs.summary }}
+                    *Ran at:* `${{ steps.status.outputs.ran_at }}`
+                    *Ollama:* `${{ needs.ollama-tests.result }}`  •  *Llama-cpp:* `${{ needs.llamacpp-tests.result }}`
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: |
+                    *📊 File Based — 50 Small Documents — Real LLM* (`${{ needs.perf-small-llm.result }}`)  •  runs `${{ fromJSON(needs.perf-small-llm.outputs.file_based_metrics || '{}').success }}`
+                    add      p50 `${{ fromJSON(needs.perf-small-llm.outputs.file_based_metrics || '{}').add.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-llm.outputs.file_based_metrics || '{}').add.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-llm.outputs.file_based_metrics || '{}').add.p99 }}s`
+                    cognify  p50 `${{ fromJSON(needs.perf-small-llm.outputs.file_based_metrics || '{}').cognify.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-llm.outputs.file_based_metrics || '{}').cognify.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-llm.outputs.file_based_metrics || '{}').cognify.p99 }}s`
+                    search     p50 `${{ fromJSON(needs.perf-small-llm.outputs.file_based_metrics || '{}').search.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-llm.outputs.file_based_metrics || '{}').search.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-llm.outputs.file_based_metrics || '{}').search.p99 }}s`
+                    total      p50 `${{ fromJSON(needs.perf-small-llm.outputs.file_based_metrics || '{}').total.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-llm.outputs.file_based_metrics || '{}').total.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-llm.outputs.file_based_metrics || '{}').total.p99 }}s`
+                    <${{ steps.presign.outputs.url_file_small_llm }}|HTML report>
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: |
+                    *📊 File Based — 50 Small Documents — Mock LLM* (`${{ needs.perf-small-mock.result }}`)  •  runs `${{ fromJSON(needs.perf-small-mock.outputs.file_based_metrics || '{}').success }}`
+                    add      p50 `${{ fromJSON(needs.perf-small-mock.outputs.file_based_metrics || '{}').add.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-mock.outputs.file_based_metrics || '{}').add.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-mock.outputs.file_based_metrics || '{}').add.p99 }}s`
+                    cognify  p50 `${{ fromJSON(needs.perf-small-mock.outputs.file_based_metrics || '{}').cognify.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-mock.outputs.file_based_metrics || '{}').cognify.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-mock.outputs.file_based_metrics || '{}').cognify.p99 }}s`
+                    search     p50 `${{ fromJSON(needs.perf-small-mock.outputs.file_based_metrics || '{}').search.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-mock.outputs.file_based_metrics || '{}').search.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-mock.outputs.file_based_metrics || '{}').search.p99 }}s`
+                    total      p50 `${{ fromJSON(needs.perf-small-mock.outputs.file_based_metrics || '{}').total.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-mock.outputs.file_based_metrics || '{}').total.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-mock.outputs.file_based_metrics || '{}').total.p99 }}s`
+                    <${{ steps.presign.outputs.url_file_small_mock }}|HTML report>
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: |
+                    *📚 File Based — War and Peace — Real LLM* (`${{ needs.perf-wap-llm.result }}`)  •  runs `${{ fromJSON(needs.perf-wap-llm.outputs.file_based_metrics || '{}').success }}`
+                    add      p50 `${{ fromJSON(needs.perf-wap-llm.outputs.file_based_metrics || '{}').add.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-llm.outputs.file_based_metrics || '{}').add.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-llm.outputs.file_based_metrics || '{}').add.p99 }}s`
+                    cognify  p50 `${{ fromJSON(needs.perf-wap-llm.outputs.file_based_metrics || '{}').cognify.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-llm.outputs.file_based_metrics || '{}').cognify.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-llm.outputs.file_based_metrics || '{}').cognify.p99 }}s`
+                    search     p50 `${{ fromJSON(needs.perf-wap-llm.outputs.file_based_metrics || '{}').search.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-llm.outputs.file_based_metrics || '{}').search.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-llm.outputs.file_based_metrics || '{}').search.p99 }}s`
+                    total      p50 `${{ fromJSON(needs.perf-wap-llm.outputs.file_based_metrics || '{}').total.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-llm.outputs.file_based_metrics || '{}').total.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-llm.outputs.file_based_metrics || '{}').total.p99 }}s`
+                    <${{ steps.presign.outputs.url_file_wap_llm }}|HTML report>
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: |
+                    *📚 File Based — War and Peace — Mock LLM* (`${{ needs.perf-wap-mock.result }}`)  •  runs `${{ fromJSON(needs.perf-wap-mock.outputs.file_based_metrics || '{}').success }}`
+                    add      p50 `${{ fromJSON(needs.perf-wap-mock.outputs.file_based_metrics || '{}').add.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-mock.outputs.file_based_metrics || '{}').add.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-mock.outputs.file_based_metrics || '{}').add.p99 }}s`
+                    cognify  p50 `${{ fromJSON(needs.perf-wap-mock.outputs.file_based_metrics || '{}').cognify.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-mock.outputs.file_based_metrics || '{}').cognify.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-mock.outputs.file_based_metrics || '{}').cognify.p99 }}s`
+                    search     p50 `${{ fromJSON(needs.perf-wap-mock.outputs.file_based_metrics || '{}').search.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-mock.outputs.file_based_metrics || '{}').search.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-mock.outputs.file_based_metrics || '{}').search.p99 }}s`
+                    total      p50 `${{ fromJSON(needs.perf-wap-mock.outputs.file_based_metrics || '{}').total.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-mock.outputs.file_based_metrics || '{}').total.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-mock.outputs.file_based_metrics || '{}').total.p99 }}s`
+                    <${{ steps.presign.outputs.url_file_wap_mock }}|HTML report>
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: |
+                    *📊 Full Postgres — 50 Small Documents — Real LLM* (`${{ needs.perf-small-llm.result }}`)  •  runs `${{ fromJSON(needs.perf-small-llm.outputs.postgres_metrics || '{}').success }}`
+                    add      p50 `${{ fromJSON(needs.perf-small-llm.outputs.postgres_metrics || '{}').add.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-llm.outputs.postgres_metrics || '{}').add.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-llm.outputs.postgres_metrics || '{}').add.p99 }}s`
+                    cognify  p50 `${{ fromJSON(needs.perf-small-llm.outputs.postgres_metrics || '{}').cognify.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-llm.outputs.postgres_metrics || '{}').cognify.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-llm.outputs.postgres_metrics || '{}').cognify.p99 }}s`
+                    search     p50 `${{ fromJSON(needs.perf-small-llm.outputs.postgres_metrics || '{}').search.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-llm.outputs.postgres_metrics || '{}').search.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-llm.outputs.postgres_metrics || '{}').search.p99 }}s`
+                    total      p50 `${{ fromJSON(needs.perf-small-llm.outputs.postgres_metrics || '{}').total.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-llm.outputs.postgres_metrics || '{}').total.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-llm.outputs.postgres_metrics || '{}').total.p99 }}s`
+                    <${{ steps.presign.outputs.url_pg_small_llm }}|HTML report>
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: |
+                    *📊 Full Postgres — 50 Small Documents — Mock LLM* (`${{ needs.perf-small-mock.result }}`)  •  runs `${{ fromJSON(needs.perf-small-mock.outputs.postgres_metrics || '{}').success }}`
+                    add      p50 `${{ fromJSON(needs.perf-small-mock.outputs.postgres_metrics || '{}').add.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-mock.outputs.postgres_metrics || '{}').add.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-mock.outputs.postgres_metrics || '{}').add.p99 }}s`
+                    cognify  p50 `${{ fromJSON(needs.perf-small-mock.outputs.postgres_metrics || '{}').cognify.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-mock.outputs.postgres_metrics || '{}').cognify.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-mock.outputs.postgres_metrics || '{}').cognify.p99 }}s`
+                    search     p50 `${{ fromJSON(needs.perf-small-mock.outputs.postgres_metrics || '{}').search.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-mock.outputs.postgres_metrics || '{}').search.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-mock.outputs.postgres_metrics || '{}').search.p99 }}s`
+                    total      p50 `${{ fromJSON(needs.perf-small-mock.outputs.postgres_metrics || '{}').total.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-small-mock.outputs.postgres_metrics || '{}').total.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-small-mock.outputs.postgres_metrics || '{}').total.p99 }}s`
+                    <${{ steps.presign.outputs.url_pg_small_mock }}|HTML report>
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: |
+                    *📚 Full Postgres — War and Peace — Real LLM* (`${{ needs.perf-wap-llm.result }}`)  •  runs `${{ fromJSON(needs.perf-wap-llm.outputs.postgres_metrics || '{}').success }}`
+                    add      p50 `${{ fromJSON(needs.perf-wap-llm.outputs.postgres_metrics || '{}').add.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-llm.outputs.postgres_metrics || '{}').add.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-llm.outputs.postgres_metrics || '{}').add.p99 }}s`
+                    cognify  p50 `${{ fromJSON(needs.perf-wap-llm.outputs.postgres_metrics || '{}').cognify.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-llm.outputs.postgres_metrics || '{}').cognify.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-llm.outputs.postgres_metrics || '{}').cognify.p99 }}s`
+                    search     p50 `${{ fromJSON(needs.perf-wap-llm.outputs.postgres_metrics || '{}').search.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-llm.outputs.postgres_metrics || '{}').search.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-llm.outputs.postgres_metrics || '{}').search.p99 }}s`
+                    total      p50 `${{ fromJSON(needs.perf-wap-llm.outputs.postgres_metrics || '{}').total.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-llm.outputs.postgres_metrics || '{}').total.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-llm.outputs.postgres_metrics || '{}').total.p99 }}s`
+                    <${{ steps.presign.outputs.url_pg_wap_llm }}|HTML report>
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: |
+                    *📚 Full Postgres — War and Peace — Mock LLM* (`${{ needs.perf-wap-mock.result }}`)  •  runs `${{ fromJSON(needs.perf-wap-mock.outputs.postgres_metrics || '{}').success }}`
+                    add      p50 `${{ fromJSON(needs.perf-wap-mock.outputs.postgres_metrics || '{}').add.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-mock.outputs.postgres_metrics || '{}').add.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-mock.outputs.postgres_metrics || '{}').add.p99 }}s`
+                    cognify  p50 `${{ fromJSON(needs.perf-wap-mock.outputs.postgres_metrics || '{}').cognify.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-mock.outputs.postgres_metrics || '{}').cognify.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-mock.outputs.postgres_metrics || '{}').cognify.p99 }}s`
+                    search     p50 `${{ fromJSON(needs.perf-wap-mock.outputs.postgres_metrics || '{}').search.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-mock.outputs.postgres_metrics || '{}').search.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-mock.outputs.postgres_metrics || '{}').search.p99 }}s`
+                    total      p50 `${{ fromJSON(needs.perf-wap-mock.outputs.postgres_metrics || '{}').total.p50 }}s`  •  p90 `${{ fromJSON(needs.perf-wap-mock.outputs.postgres_metrics || '{}').total.p90 }}s`  •  p99 `${{ fromJSON(needs.perf-wap-mock.outputs.postgres_metrics || '{}').total.p99 }}s`
+                    <${{ steps.presign.outputs.url_pg_wap_mock }}|HTML report>
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: |
+                    <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|View run>
+
+      - name: Fail if any suite failed
+        if: ${{ steps.status.outputs.passed != 'true' }}
+        run: |
+          echo "One or more nightly test suites failed."
+          exit 1

.github/workflows/notebooks_tests.yml

@@ -0,0 +1,28 @@
+name: Reusable Notebook Tests
+
+on:
+  workflow_call:
+    inputs:
+      ci-image:
+        required: false
+        type: string
+        default: ''
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+#  run-main-notebook:
+#    name: Main Notebook Test
+#    uses: ./.github/workflows/reusable_notebook.yml
+#    with:
+#      notebook-location: notebooks/cognee_demo.ipynb
+#    secrets: inherit
+
+  run-cognee-multimedia:
+    name: Cognee Multimedia Notebook
+    uses: ./.github/workflows/reusable_notebook.yml
+    with:
+      notebook-location: notebooks/cognee_multimedia_demo.ipynb
+      ci-image: ${{ inputs.ci-image }}
+    secrets: inherit

.github/workflows/performance_report.yml

@@ -0,0 +1,298 @@
+name: performance report
+
+# Reusable workflow: runs the percentile performance report once for a given
+# dataset + mode, uploads the JSON + HTML artifacts to S3, and exposes the
+# headline metrics + HTML object key as outputs for the caller (the Slack bot in
+# nightly_tests.yml).
+#
+# Both backends run on every call, as two separate jobs:
+#   - file_based : cognee defaults (SQLite + Kuzu + LanceDB), no services.
+#   - postgres   : full Postgres (relational + PGVector + Postgres graph) via a
+#                  `services: postgres` container (mirrors e2e_tests.yml).
+# Each job exposes its own metrics + html_key outputs (file_based_* / postgres_*).
+on:
+  workflow_call:
+    inputs:
+      mode:
+        description: "Run mode: 'mock_llm' (no API calls) or 'llm' (real LLM)."
+        required: true
+        type: string
+      label:
+        description: "Dataset label, used in the S3 output path and display name."
+        required: true
+        type: string
+      runs:
+        description: "Number of sequential benchmark runs."
+        required: false
+        type: string
+        default: '10'
+      num_memories:
+        description: "If set, forwarded as --num-memories (limit input documents)."
+        required: false
+        type: string
+        default: ''
+      memories_key:
+        description: "S3 object key (under the bucket) downloaded and used as --memories."
+        required: true
+        type: string
+      mock_memories_key:
+        description: "If set, S3 object key downloaded and used as --mock-memories."
+        required: false
+        type: string
+        default: ''
+    outputs:
+      file_based_metrics:
+        description: "File-based run: success + add/cognify/search/total p50/p90/p99."
+        value: ${{ jobs.file_based.outputs.metrics }}
+      file_based_html_key:
+        description: "File-based run: S3 object key of the HTML report."
+        value: ${{ jobs.file_based.outputs.html_key }}
+      postgres_metrics:
+        description: "Postgres run: success + add/cognify/search/total p50/p90/p99."
+        value: ${{ jobs.postgres.outputs.metrics }}
+      postgres_html_key:
+        description: "Postgres run: S3 object key of the HTML report."
+        value: ${{ jobs.postgres.outputs.html_key }}
+
+env:
+  ENV: 'dev'
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+  RUNTIME__LOG_LEVEL: ERROR
+  BUCKET: github-runner-cognee-tests
+
+jobs:
+  # ── File-based backend: SQLite + Kuzu + LanceDB (cognee defaults) ────────────
+  file_based:
+    name: file_based — ${{ inputs.label }} (${{ inputs.mode }})
+    runs-on: ubuntu-22.04
+    outputs:
+      metrics: ${{ steps.parse.outputs.metrics }}
+      html_key: ${{ steps.upload.outputs.html_key }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+
+      - name: Download dataset from S3
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_S3_DEV_USER_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_S3_DEV_USER_SECRET_KEY }}
+          AWS_DEFAULT_REGION: eu-west-1
+          MEMORIES_KEY: ${{ inputs.memories_key }}
+          MOCK_MEMORIES_KEY: ${{ inputs.mock_memories_key }}
+        run: |
+          set -euo pipefail
+          mkdir -p performance_datasets
+          aws s3 cp "s3://$BUCKET/$MEMORIES_KEY" performance_datasets/memories.json
+          echo "MEMORIES_FILE=$PWD/performance_datasets/memories.json" >> "$GITHUB_ENV"
+          if [ -n "$MOCK_MEMORIES_KEY" ]; then
+            aws s3 cp "s3://$BUCKET/$MOCK_MEMORIES_KEY" performance_datasets/mock_memories.json
+            echo "MOCK_MEMORIES_FILE=$PWD/performance_datasets/mock_memories.json" >> "$GITHUB_ENV"
+          fi
+
+      - name: Run performance report
+        id: run
+        env:
+          PYTHONFAULTHANDLER: 1
+          # LLM + embedding config via the standard CI secrets (see e2e_tests.yml).
+          # Only exercised for mode == 'llm'; the mock run hits no external APIs.
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: |
+          set -euo pipefail
+          TS="$(date -u '+%Y-%m-%d_%H-%M-%SZ')"
+          JSON_PATH="performance_results/file_based/${{ inputs.label }}/${{ inputs.mode }}_${TS}.json"
+          HTML_PATH="performance_results/file_based/${{ inputs.label }}/${{ inputs.mode }}_${TS}.html"
+          mkdir -p "$(dirname "$JSON_PATH")"
+          echo "JSON_PATH=$JSON_PATH" >> "$GITHUB_ENV"
+          echo "HTML_PATH=$HTML_PATH" >> "$GITHUB_ENV"
+
+          ARGS=(--runs "${{ inputs.runs }}" --memories "$MEMORIES_FILE")
+          if [ -n "${MOCK_MEMORIES_FILE:-}" ]; then
+            ARGS+=(--mock-memories "$MOCK_MEMORIES_FILE")
+          fi
+          if [ "${{ inputs.mode }}" = "mock_llm" ]; then
+            ARGS+=(--mock-llm)
+          fi
+          if [ -n "${{ inputs.num_memories }}" ]; then
+            ARGS+=(--num-memories "${{ inputs.num_memories }}")
+          fi
+
+          uv run python cognee/tests/performance/statistics_percentile_report.py \
+            "${ARGS[@]}" \
+            --output "$JSON_PATH" \
+            --html "$HTML_PATH"
+
+      - name: Upload reports to S3
+        id: upload
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_S3_DEV_USER_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_S3_DEV_USER_SECRET_KEY }}
+          AWS_DEFAULT_REGION: eu-west-1
+        run: |
+          set -euo pipefail
+          aws s3 cp "$JSON_PATH" "s3://$BUCKET/$JSON_PATH" --content-type application/json
+          aws s3 cp "$HTML_PATH" "s3://$BUCKET/$HTML_PATH" --content-type text/html
+          # Presigning is done by the caller (the Slack job), NOT here: a presigned URL
+          # embeds the AWS access key id, and GitHub scrubs registered secrets from
+          # reusable-workflow outputs — which would blank the link. Pass only the
+          # (non-secret) object key across the boundary.
+          echo "html_key=$HTML_PATH" >> "$GITHUB_OUTPUT"
+
+      - name: Parse headline metrics
+        id: parse
+        run: |
+          set -euo pipefail
+          METRICS="$(jq -c '{
+            success: "\(.succeeded)/\(.num_runs)",
+            add:     {p50: .stats.add_time_s.p50,          p90: .stats.add_time_s.p90,          p99: .stats.add_time_s.p99},
+            cognify: {p50: .stats.cognify_time_s.p50,      p90: .stats.cognify_time_s.p90,      p99: .stats.cognify_time_s.p99},
+            search:  {p50: .stats.search_time.p50,         p90: .stats.search_time.p90,         p99: .stats.search_time.p99},
+            total:   {p50: .stats.total_ingest_time_s.p50, p90: .stats.total_ingest_time_s.p90, p99: .stats.total_ingest_time_s.p99}
+          }' "$JSON_PATH")"
+          echo "metrics=$METRICS" >> "$GITHUB_OUTPUT"
+
+  # ── Postgres backend: Postgres relational + PGVector + Postgres graph ────────
+  postgres:
+    name: postgres — ${{ inputs.label }} (${{ inputs.mode }})
+    runs-on: ubuntu-22.04
+    defaults:
+      run:
+        shell: bash
+    services:
+      postgres:
+        image: ghcr.io/topoteretes/pgvector:pg17
+        credentials:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          POSTGRES_USER: cognee
+          POSTGRES_PASSWORD: cognee
+          POSTGRES_DB: cognee_db
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    outputs:
+      metrics: ${{ steps.parse.outputs.metrics }}
+      html_key: ${{ steps.upload.outputs.html_key }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: "postgres"
+
+      - name: Download dataset from S3
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_S3_DEV_USER_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_S3_DEV_USER_SECRET_KEY }}
+          AWS_DEFAULT_REGION: eu-west-1
+          MEMORIES_KEY: ${{ inputs.memories_key }}
+          MOCK_MEMORIES_KEY: ${{ inputs.mock_memories_key }}
+        run: |
+          set -euo pipefail
+          mkdir -p performance_datasets
+          aws s3 cp "s3://$BUCKET/$MEMORIES_KEY" performance_datasets/memories.json
+          echo "MEMORIES_FILE=$PWD/performance_datasets/memories.json" >> "$GITHUB_ENV"
+          if [ -n "$MOCK_MEMORIES_KEY" ]; then
+            aws s3 cp "s3://$BUCKET/$MOCK_MEMORIES_KEY" performance_datasets/mock_memories.json
+            echo "MOCK_MEMORIES_FILE=$PWD/performance_datasets/mock_memories.json" >> "$GITHUB_ENV"
+          fi
+
+      - name: Run performance report
+        id: run
+        env:
+          PYTHONFAULTHANDLER: 1
+          # LLM + embedding config via the standard CI secrets (see e2e_tests.yml).
+          # Only exercised for mode == 'llm'; the mock run hits no external APIs.
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          # Full Postgres stack (creds match the postgres service above; mirrors e2e_tests.yml).
+          DB_PROVIDER: 'postgres'
+          DB_HOST: '127.0.0.1'
+          DB_PORT: '5432'
+          DB_USERNAME: cognee
+          DB_PASSWORD: cognee
+          DB_NAME: cognee_db
+          VECTOR_DB_PROVIDER: 'pgvector'
+          VECTOR_DB_HOST: '127.0.0.1'
+          VECTOR_DB_PORT: '5432'
+          VECTOR_DB_USERNAME: cognee
+          VECTOR_DB_PASSWORD: cognee
+          VECTOR_DATASET_DATABASE_HANDLER: 'pgvector'
+          GRAPH_DATABASE_PROVIDER: 'postgres'
+          GRAPH_DATABASE_HOST: '127.0.0.1'
+          GRAPH_DATABASE_PORT: '5432'
+          GRAPH_DATABASE_USERNAME: cognee
+          GRAPH_DATABASE_PASSWORD: cognee
+          GRAPH_DATABASE_NAME: cognee_db
+        run: |
+          set -euo pipefail
+          TS="$(date -u '+%Y-%m-%d_%H-%M-%SZ')"
+          JSON_PATH="performance_results/postgres/${{ inputs.label }}/${{ inputs.mode }}_${TS}.json"
+          HTML_PATH="performance_results/postgres/${{ inputs.label }}/${{ inputs.mode }}_${TS}.html"
+          mkdir -p "$(dirname "$JSON_PATH")"
+          echo "JSON_PATH=$JSON_PATH" >> "$GITHUB_ENV"
+          echo "HTML_PATH=$HTML_PATH" >> "$GITHUB_ENV"
+
+          ARGS=(--runs "${{ inputs.runs }}" --memories "$MEMORIES_FILE")
+          if [ -n "${MOCK_MEMORIES_FILE:-}" ]; then
+            ARGS+=(--mock-memories "$MOCK_MEMORIES_FILE")
+          fi
+          if [ "${{ inputs.mode }}" = "mock_llm" ]; then
+            ARGS+=(--mock-llm)
+          fi
+          if [ -n "${{ inputs.num_memories }}" ]; then
+            ARGS+=(--num-memories "${{ inputs.num_memories }}")
+          fi
+
+          uv run python cognee/tests/performance/statistics_percentile_report.py \
+            "${ARGS[@]}" \
+            --output "$JSON_PATH" \
+            --html "$HTML_PATH"
+
+      - name: Upload reports to S3
+        id: upload
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_S3_DEV_USER_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_S3_DEV_USER_SECRET_KEY }}
+          AWS_DEFAULT_REGION: eu-west-1
+        run: |
+          set -euo pipefail
+          aws s3 cp "$JSON_PATH" "s3://$BUCKET/$JSON_PATH" --content-type application/json
+          aws s3 cp "$HTML_PATH" "s3://$BUCKET/$HTML_PATH" --content-type text/html
+          # Presigning is done by the caller (the Slack job), NOT here: a presigned URL
+          # embeds the AWS access key id, and GitHub scrubs registered secrets from
+          # reusable-workflow outputs — which would blank the link. Pass only the
+          # (non-secret) object key across the boundary.
+          echo "html_key=$HTML_PATH" >> "$GITHUB_OUTPUT"
+
+      - name: Parse headline metrics
+        id: parse
+        run: |
+          set -euo pipefail
+          METRICS="$(jq -c '{
+            success: "\(.succeeded)/\(.num_runs)",
+            add:     {p50: .stats.add_time_s.p50,          p90: .stats.add_time_s.p90,          p99: .stats.add_time_s.p99},
+            cognify: {p50: .stats.cognify_time_s.p50,      p90: .stats.cognify_time_s.p90,      p99: .stats.cognify_time_s.p99},
+            search:  {p50: .stats.search_time.p50,         p90: .stats.search_time.p90,         p99: .stats.search_time.p99},
+            total:   {p50: .stats.total_ingest_time_s.p50, p90: .stats.total_ingest_time_s.p90, p99: .stats.total_ingest_time_s.p99}
+          }' "$JSON_PATH")"
+          echo "metrics=$METRICS" >> "$GITHUB_OUTPUT"

.github/workflows/pr_lint

@@ -0,0 +1,44 @@
+## Reference: https://github.com/amannn/action-semantic-pull-request
+---
+name: lint | PR
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - edited
+      - synchronize
+
+permissions:
+  contents: read
+
+jobs:
+  pr_title:
+    permissions:
+      pull-requests: write
+      statuses: write
+    name: Validate & Label PR
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # Configure which types are allowed (newline-delimited).
+          # From: https://github.com/commitizen/conventional-commit-types/blob/master/index.json
+          # listing all below
+          types: |
+            chore
+            ci
+            docs
+            feat
+            fix
+            perf
+            refactor
+            revert
+            test
+            break
+      - uses: release-drafter/release-drafter@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/pre_test.yml

@@ -0,0 +1,29 @@
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  check-uv-lock:
+    name: Lockfile and Pre-commit Hooks
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Validate uv lockfile and project metadata
+        run: uv lock --check || { echo "'uv lock --check' failed."; echo "Run 'uv lock' and push your changes."; exit 1; }
+
+      - name: Run pre-commit hooks
+        uses: pre-commit/action@v3.0.1

.github/workflows/relational_db_migration_tests.yml

@@ -0,0 +1,248 @@
+name: Relational DB Migration Tests
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        required: false
+        type: string
+        default: '3.11.x'
+      ci-image:
+        required: false
+        type: string
+        default: ''
+    secrets:
+      LLM_PROVIDER:
+        required: true
+      LLM_MODEL:
+        required: true
+      LLM_ENDPOINT:
+        required: true
+      LLM_API_KEY:
+        required: true
+      LLM_ARGS:
+        required: false
+      LLM_API_VERSION:
+        required: true
+      EMBEDDING_PROVIDER:
+        required: true
+      EMBEDDING_MODEL:
+        required: true
+      EMBEDDING_API_KEY:
+        required: true
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  run-relational-db-migration-test-networkx:
+    name: NetworkX Relational DB Migration Test
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    defaults:
+      run:
+        shell: bash
+    services:
+      postgres:
+        image: ghcr.io/topoteretes/pgvector:pg17
+        credentials:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          POSTGRES_USER: cognee
+          POSTGRES_PASSWORD: cognee
+          POSTGRES_DB: test_migration_db
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: "postgres"
+
+      - name: Install specific db dependency
+        run: echo "Dependencies already installed in setup"
+
+      - name: Run PostgreSQL Script to create test data (Chinook_PostgreSql.sql)
+        env:
+          PGPASSWORD: cognee
+          PG_HOST: ${{ inputs.ci-image != '' && 'postgres' || 'localhost' }}
+        run: |
+          # Wait until the PostgreSQL service is available
+          until pg_isready -h $PG_HOST -p 5432; do
+            echo "Waiting for postgres..."
+            sleep 2
+          done
+
+          # Execute the SQL script against the test_migration_db database
+          psql -h $PG_HOST -U cognee -d test_migration_db -f ./cognee/tests/test_data/Chinook_PostgreSql.sql
+
+      - name: Run relational db test
+        env:
+          ENV: 'dev'
+          LLM_PROVIDER: openai
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+
+          EMBEDDING_PROVIDER: openai
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          DB_HOST: ${{ inputs.ci-image != '' && 'postgres' || '127.0.0.1' }}
+        run: uv run python ./cognee/tests/test_relational_db_migration.py
+
+  run-relational-db-migration-test-kuzu:
+    name: Kuzu Relational DB Migration Test
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    defaults:
+      run:
+        shell: bash
+    services:
+      postgres:
+        image: ghcr.io/topoteretes/pgvector:pg17
+        credentials:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          POSTGRES_USER: cognee
+          POSTGRES_PASSWORD: cognee
+          POSTGRES_DB: test_migration_db
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: "postgres"
+
+      - name: Install specific db dependency
+        run: echo "Dependencies already installed in setup"
+
+      - name: Run PostgreSQL Script to create test data (Chinook_PostgreSql.sql)
+        env:
+          PGPASSWORD: cognee
+          PG_HOST: ${{ inputs.ci-image != '' && 'postgres' || 'localhost' }}
+        run: |
+          # Wait until the PostgreSQL service is available
+          until pg_isready -h $PG_HOST -p 5432; do
+            echo "Waiting for postgres..."
+            sleep 2
+          done
+
+          # Execute the SQL script against the test_migration_db database
+          psql -h $PG_HOST -U cognee -d test_migration_db -f ./cognee/tests/test_data/Chinook_PostgreSql.sql
+
+      - name: Run relational db test
+        env:
+          ENV: 'dev'
+          GRAPH_DATABASE_PROVIDER: 'kuzu'
+
+          LLM_PROVIDER: openai
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+
+          EMBEDDING_PROVIDER: openai
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          DB_HOST: ${{ inputs.ci-image != '' && 'postgres' || '127.0.0.1' }}
+        run: uv run python ./cognee/tests/test_relational_db_migration.py
+
+  run-relational-db-migration-test-neo4j:
+    name: Neo4j Relational DB Migration Test
+    runs-on: ubuntu-22.04
+    defaults:
+      run:
+        shell: bash
+    services:
+      postgres:
+        image: ghcr.io/topoteretes/pgvector:pg17
+        credentials:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          POSTGRES_USER: cognee
+          POSTGRES_PASSWORD: cognee
+          POSTGRES_DB: test_migration_db
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: "postgres"
+
+      - name: Setup Neo4j with GDS
+        uses: ./.github/actions/setup_neo4j
+        id: neo4j
+
+      - name: Install specific db dependency
+        run: echo "Dependencies already installed in setup"
+
+      - name: Run PostgreSQL Script to create test data (Chinook_PostgreSql.sql)
+        env:
+          PGPASSWORD: cognee
+        run: |
+          # Wait until the PostgreSQL service is available
+          until pg_isready -h localhost -p 5432; do
+            echo "Waiting for postgres..."
+            sleep 2
+          done
+
+          # Execute the SQL script against the test_migration_db database
+          psql -h localhost -U cognee -d test_migration_db -f ./cognee/tests/test_data/Chinook_PostgreSql.sql
+
+      - name: Run relational db test
+        env:
+          ENV: 'dev'
+          GRAPH_DATABASE_PROVIDER: "neo4j"
+          GRAPH_DATABASE_URL: ${{ steps.neo4j.outputs.neo4j-url }}
+          GRAPH_DATABASE_USERNAME: ${{ steps.neo4j.outputs.neo4j-username }}
+          GRAPH_DATABASE_PASSWORD: ${{ steps.neo4j.outputs.neo4j-password }}
+
+          LLM_PROVIDER: openai
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+
+          EMBEDDING_PROVIDER: openai
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./cognee/tests/test_relational_db_migration.py

.github/workflows/release.yml

@@ -0,0 +1,254 @@
+name: release.yml
+on:
+  workflow_dispatch:
+
+jobs:
+  release-github:
+    name: Create GitHub Release from ${{ github.ref_name }}
+    outputs:
+      tag: ${{ steps.create_tag.outputs.tag }}
+      version: ${{ steps.create_tag.outputs.version }}
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out ${{ github.ref_name }}
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.ref_name }}
+          fetch-depth: 0  # Fetch all history for comparison
+
+      - name: Fetch main branch for comparison
+        if: ${{ github.ref_name == 'dev' }}
+        run: git fetch origin main:main
+
+      - name: Fetch dev branch for comparison
+        if: ${{ github.ref_name == 'main' }}
+        run: git fetch origin dev:dev
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Create and push git tag
+        id: create_tag
+        run: |
+          VERSION="$(uv version --short)"
+          TAG="v${VERSION}"
+
+          echo "Tag to create: ${TAG}"
+
+          git config user.name "Cognee Team"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+          git tag "${TAG}"
+          git push origin "${TAG}"
+
+      - name: Generate AI-powered release notes
+        id: generate_notes
+        env:
+          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_MODEL: ${{ secrets.LLM_MODEL != '' && secrets.LLM_MODEL || 'openai/gpt-4o-mini' }}
+        run: |
+          # Set PYTHONPATH to include project root
+          export PYTHONPATH="${GITHUB_WORKSPACE}:${PYTHONPATH}"
+
+          # Generate release notes
+          # Compares current branch against the latest release tag automatically
+          uv run python tools/generate_release_notes.py \
+            --version "${{ steps.create_tag.outputs.version }}" \
+            --github-output
+
+      - name: Create GitHub Release with AI-generated notes
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.create_tag.outputs.tag }}
+          name: ${{ steps.generate_notes.outputs.RELEASE_TITLE }}
+          body: ${{ steps.generate_notes.outputs.RELEASE_NOTES }}
+          prerelease: ${{ github.ref_name == 'dev' }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_RELEASE_TOKEN }}
+
+  release-pypi-package:
+    needs: release-github
+    name: Release PyPI Package from ${{ github.ref_name }}
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out ${{ github.ref_name }}
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.ref_name }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --locked --all-extras
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish ${{ github.ref_name }} release to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: uv publish
+
+  release-docker-image:
+    needs: release-github
+    name: Release Docker Image from ${{ github.ref_name }}
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out ${{ github.ref_name }}
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.ref_name }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Build and push Dev Docker Image
+        if: ${{ github.ref_name == 'dev' }}
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: cognee/cognee:${{ needs.release-github.outputs.version }}
+          labels: |
+            version=${{ needs.release-github.outputs.version }}
+            flavour=${{ github.ref_name }}
+          cache-from: type=registry,ref=cognee/cognee:buildcache
+          cache-to: type=registry,ref=cognee/cognee:buildcache,mode=max
+
+      - name: Build and push Main Docker Image
+        if: ${{ github.ref_name == 'main' }}
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            cognee/cognee:${{ needs.release-github.outputs.version }}
+            cognee/cognee:latest
+          labels: |
+            version=${{ needs.release-github.outputs.version }}
+            flavour=${{ github.ref_name }}
+          cache-from: type=registry,ref=cognee/cognee:buildcache
+          cache-to: type=registry,ref=cognee/cognee:buildcache,mode=max
+
+      - name: Build and push Dev MCP Docker Image
+        if: ${{ github.ref_name == 'dev' }}
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: cognee-mcp/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: cognee/cognee-mcp:${{ needs.release-github.outputs.version }}
+          labels: |
+            version=${{ needs.release-github.outputs.version }}
+            flavour=${{ github.ref_name }}
+          cache-from: type=registry,ref=cognee/cognee-mcp:buildcache
+          cache-to: type=registry,ref=cognee/cognee-mcp:buildcache,mode=max
+
+      - name: Build and push Main MCP Docker Image
+        if: ${{ github.ref_name == 'main' }}
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: cognee-mcp/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            cognee/cognee-mcp:${{ needs.release-github.outputs.version }}
+            cognee/cognee-mcp:latest
+          labels: |
+            version=${{ needs.release-github.outputs.version }}
+            flavour=${{ github.ref_name }}
+          cache-from: type=registry,ref=cognee/cognee-mcp:buildcache
+          cache-to: type=registry,ref=cognee/cognee-mcp:buildcache,mode=max
+
+  trigger-docs-test-suite:
+    needs: release-pypi-package
+    if: ${{ github.ref_name == 'main' }}
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Trigger docs tests
+        run: |
+          curl -L -X POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer ${{ secrets.REPO_DISPATCH_PAT_TOKEN }}" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/topoteretes/cognee-docs/dispatches \
+            -d '{"event_type":"new-main-release","client_payload":{"caller_repo":"'"${GITHUB_REPOSITORY}"'"}}'
+
+  trigger-community-test-suite:
+    needs: release-pypi-package
+    if: ${{ github.ref_name == 'main' }}
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Trigger community tests
+        run: |
+          curl -L -X POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer ${{ secrets.REPO_DISPATCH_PAT_TOKEN }}" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/topoteretes/cognee-community/dispatches \
+            -d '{"event_type":"new-main-release","client_payload":{"caller_repo":"'"${GITHUB_REPOSITORY}"'"}}'
+
+  notify-discord:
+    needs: release-github
+    name: Send Release to Discord
+    if: ${{ github.ref_name == 'main' }}
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Send Discord notification
+        env:
+          WEBHOOK_URL: ${{ secrets.WEBHOOK_URL }}
+          TAG: ${{ needs.release-github.outputs.tag }}
+          VERSION: ${{ needs.release-github.outputs.version }}
+        run: |
+          RELEASE_URL="https://github.com/${{ github.repository }}/releases/tag/${TAG}"
+          PAYLOAD=$(jq -n \
+            --arg content "||@everyone|| **${TAG}** has been released!" \
+            --arg title "Release ${TAG}" \
+            --arg url "$RELEASE_URL" \
+            --arg description "Version ${VERSION} released from \`${{ github.ref_name }}\`. [View release notes](${RELEASE_URL})" \
+            --argjson color 2105893 \
+            '{
+              content: $content,
+              embeds: [{
+                title: $title,
+                url: $url,
+                description: $description,
+                color: $color,
+                footer: { text: "Changelog" },
+                timestamp: (now | todate)
+              }]
+            }')
+          curl -s -H "Content-Type: application/json" -d "$PAYLOAD" "$WEBHOOK_URL"

.github/workflows/release_discord_action.yml

@@ -0,0 +1,23 @@
+name: automation | Send Release to Discord
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  github-releases-to-discord:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Github Releases To Discord
+        uses: SethCohen/github-releases-to-discord@v1.19.0
+        with:
+          webhook_url: ${{ secrets.WEBHOOK_URL }}
+          color: "2105893"
+          username: "Release Changelog"
+          avatar_url: "https://cdn.discordapp.com/avatars/487431320314576937/bd64361e4ba6313d561d54e78c9e7171.png"
+          content: "||@everyone||"
+          footer_title: "Changelog"
+          footer_icon_url: "https://cdn.discordapp.com/avatars/487431320314576937/bd64361e4ba6313d561d54e78c9e7171.png"
+          footer_timestamp: true

.github/workflows/release_test.yml

@@ -0,0 +1,201 @@
+# Long-running, heavy and resource-consuming tests for release validation.
+# Runs automatically on PRs targeting main (the dev -> main promotion) and manually
+# via workflow_dispatch. Fork PRs are skipped (no access to secrets).
+name: Release Test Workflow
+
+permissions:
+  contents: read
+  packages: write
+
+on:
+  workflow_dispatch:
+    inputs:
+      cognee_version:
+        required: false
+        default: local
+        type: string
+        description: "Pypi-compatible version of cognee to use. For example, 0.5.2.dev0. `local` (default) - Installing Cognee from local source"
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: release-tests-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+
+  mcp-test:
+    name: MCP Tests
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.pull_request.head.repo.full_name == github.repository }}
+    uses: ./.github/workflows/test_mcp.yml
+    secrets: inherit
+    with:
+      cognee_version: ${{ inputs.cognee_version || 'local' }}
+
+  cli-test:
+    name: CLI Tests
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.pull_request.head.repo.full_name == github.repository }}
+    uses: ./.github/workflows/cli_tests.yml
+    secrets: inherit
+    with:
+      cognee_version: ${{ inputs.cognee_version || 'local' }}
+
+  cot-retriever-test:
+    name: COT Retriever Test
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.pull_request.head.repo.full_name == github.repository }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: |
+          if [ "${{ inputs.cognee_version }}" = "local" ] || [ -z "${{ inputs.cognee_version }}" ]; then
+            uv sync --locked --all-extras
+          else
+            uv sync --locked --all-extras
+            uv pip install cognee==${{ inputs.cognee_version }}
+          fi
+
+      - name: Run COT retriever integration test
+        env:
+          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+        run: |
+          uv run pytest cognee/tests/integration/retrieval/test_graph_completion_retriever_cot.py -v --timeout=300
+
+  # 10 parallel users against a live HTTP server with access control enabled:
+  # per-user dataset isolation, add/cognify/search verification via sentinel chunks
+  # (LLM-free CHUNKS search), delete + recreate, forget + recreate-same-name.
+  multi-user-e2e-default:
+    name: Multi-User Release E2E (default file-based DBs)
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.pull_request.head.repo.full_name == github.repository }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: |
+          if [ "${{ inputs.cognee_version }}" = "local" ] || [ -z "${{ inputs.cognee_version }}" ]; then
+            uv sync --locked --all-extras
+          else
+            uv sync --locked --all-extras
+            uv pip install cognee==${{ inputs.cognee_version }}
+          fi
+
+      - name: Run multi-user release E2E test
+        env:
+          ENV: 'dev'
+          COGNEE_SKIP_CONNECTION_TEST: 'true'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./cognee/tests/test_release_multi_user_e2e.py
+
+  multi-user-e2e-postgres:
+    name: Multi-User Release E2E (Postgres graph + PGVector + Postgres)
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.pull_request.head.repo.full_name == github.repository }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    services:
+      postgres:
+        image: ghcr.io/topoteretes/pgvector:pg17
+        credentials:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          POSTGRES_USER: cognee
+          POSTGRES_PASSWORD: cognee
+          POSTGRES_DB: cognee_db
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: |
+          if [ "${{ inputs.cognee_version }}" = "local" ] || [ -z "${{ inputs.cognee_version }}" ]; then
+            uv sync --locked --all-extras
+          else
+            uv sync --locked --all-extras
+            uv pip install cognee==${{ inputs.cognee_version }}
+          fi
+
+      - name: Run multi-user release E2E test
+        env:
+          ENV: 'dev'
+          COGNEE_SKIP_CONNECTION_TEST: 'true'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          DB_PROVIDER: 'postgres'
+          DB_NAME: 'cognee_db'
+          DB_HOST: '127.0.0.1'
+          DB_PORT: 5432
+          DB_USERNAME: cognee
+          DB_PASSWORD: cognee
+          VECTOR_DB_PROVIDER: 'pgvector'
+          VECTOR_DB_NAME: 'cognee_db'
+          VECTOR_DB_HOST: '127.0.0.1'
+          VECTOR_DB_PORT: 5432
+          VECTOR_DB_USERNAME: cognee
+          VECTOR_DB_PASSWORD: cognee
+          VECTOR_DATASET_DATABASE_HANDLER: 'pgvector'
+          GRAPH_DATABASE_PROVIDER: 'postgres'
+          GRAPH_DATABASE_NAME: 'cognee_db'
+          GRAPH_DATABASE_HOST: '127.0.0.1'
+          GRAPH_DATABASE_PORT: 5432
+          GRAPH_DATABASE_USERNAME: cognee
+          GRAPH_DATABASE_PASSWORD: cognee
+          GRAPH_DATASET_DATABASE_HANDLER: 'postgres_graph'
+        run: uv run python ./cognee/tests/test_release_multi_user_e2e.py
+
+  load-tests:
+    if: false
+    name: Load Tests
+    uses: ./.github/workflows/load_tests.yml
+    secrets: inherit
+
+  dev-canary-release:
+    name: Dev Canary Release
+    if: ${{ github.event_name == 'workflow_dispatch' }}
+    needs: load-tests
+    uses: ./.github/workflows/dev_canary_release.yml
+    secrets: inherit

.github/workflows/require-linear-issue.yml

@@ -0,0 +1,40 @@
+name: Require Linear issue
+
+# Every INTERNAL PR must reference a Linear issue (e.g. COG-123) in its title or
+# branch name — that is how Linear links a PR to a ticket. Since Linear does not
+# gate merges, enforcement is a required GitHub status check: this job fails when a
+# PR has no Linear key, and branch protection blocks the merge until it passes.
+#
+# Fork / external-contributor PRs are intentionally SKIPPED: they have no Linear
+# access, and a skipped required check counts as passing, so this never blocks the
+# community. Mark the `linear-issue-check` job as a required status check on
+# `main` and `dev` in branch protection.
+
+on:
+  pull_request:
+    # `synchronize` matters: a required check must re-run on the latest commit.
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  linear-issue-check: # this job name is what you mark "required" in branch protection
+    # Enforce for internal PRs only. Fork PRs (head repo != base repo) skip this job;
+    # a skipped required check is treated as passing, so external PRs are not blocked.
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - name: PR title or branch must reference a Linear issue
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          HEAD_REF: ${{ github.head_ref }}
+        run: |
+          # List ALL your Linear team prefixes — verify against Linear ▸ Settings ▸ Teams.
+          KEYS='COG|SDK|CLO|COM|ENG'
+          if echo "$PR_TITLE $HEAD_REF" | grep -Eiq "\b(${KEYS})-[0-9]+\b"; then
+            echo "Linear issue reference found."
+          else
+            echo "::error::PR title or branch must reference a Linear issue, e.g. COG-123."
+            exit 1
+          fi

.github/workflows/reusable_notebook.yml

@@ -0,0 +1,71 @@
+name: test-notebook
+
+on:
+  workflow_call:
+    inputs:
+      notebook-location:
+        description: "Location of Jupyter notebook to run"
+        required: true
+        type: string
+      ci-image:
+        required: false
+        type: string
+        default: ''
+    secrets:
+      #LLM_MODEL:
+      #  required: true
+      #LLM_ENDPOINT:
+      #  required: true
+      LLM_API_KEY:
+        required: true
+      LLM_ARGS:
+        required: false
+      OPENAI_API_KEY:
+        required: true
+      #LLM_API_VERSION:
+      #  required: true
+      EMBEDDING_MODEL:
+        required: true
+      EMBEDDING_API_KEY:
+        required: true
+
+env:
+  RUNTIME__LOG_LEVEL: ERROR
+
+jobs:
+
+  run_notebook_test:
+    name: test
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Check out
+        uses: actions/checkout@master
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+          extra-dependencies: "notebook"
+
+      - name: Execute Jupyter Notebook
+        env:
+          ENV: 'dev'
+          #LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          #LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} # Use OpenAI Until a multimedia model is deployed and DeepEval support for other models is added
+          #LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: |
+          uv run jupyter nbconvert \
+          --to notebook \
+          --execute ${{ inputs.notebook-location }} \
+          --output executed_notebook.ipynb \
+          --ExecutePreprocessor.timeout=1200

.github/workflows/scorecard.yml

@@ -0,0 +1,78 @@
+# This workflow uses actions that are not certified by GitHub. They are provided
+# by a third-party and are governed by separate terms of service, privacy
+# policy, and support documentation.
+
+name: Scorecard supply-chain security
+on:
+  # For Branch-Protection check. Only the default branch is supported. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
+  branch_protection_rule:
+  # To guarantee Maintained check is occasionally updated. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
+  schedule:
+    - cron: '35 8 * * 2'
+  push:
+    branches: [ "main" ]
+
+# Declare default permissions as read only.
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    # `publish_results: true` only works when run from the default branch. conditional can be removed if disabled.
+    if: github.event.repository.default_branch == github.ref_name || github.event_name == 'pull_request'
+    permissions:
+      # Needed to upload the results to code-scanning dashboard.
+      security-events: write
+      # Needed to publish results and get a badge (see publish_results below).
+      id-token: write
+      # Uncomment the permissions below if installing in a private repository.
+      # contents: read
+      # actions: read
+
+    steps:
+      - name: "Checkout code"
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: "Run analysis"
+        uses: ossf/scorecard-action@f49aabe0b5af0936a0987cfb85d86b75731b0186 # v2.4.1
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          # (Optional) "write" PAT token. Uncomment the `repo_token` line below if:
+          # - you want to enable the Branch-Protection check on a *public* repository, or
+          # - you are installing Scorecard on a *private* repository
+          # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action?tab=readme-ov-file#authentication-with-fine-grained-pat-optional.
+          # repo_token: ${{ secrets.SCORECARD_TOKEN }}
+
+          # Public repositories:
+          #   - Publish results to OpenSSF REST API for easy access by consumers
+          #   - Allows the repository to include the Scorecard badge.
+          #   - See https://github.com/ossf/scorecard-action#publishing-results.
+          # For private repositories:
+          #   - `publish_results` will always be set to `false`, regardless
+          #     of the value entered here.
+          publish_results: true
+
+          # (Optional) Uncomment file_mode if you have a .gitattributes with files marked export-ignore
+          # file_mode: git
+
+      # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
+      # format to the repository Actions tab.
+      - name: "Upload artifact"
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f  # v6.0.0
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      # Upload the results to GitHub's code scanning dashboard (optional).
+      # Commenting out will disable upload of results to your repo's Code Scanning dashboard
+      - name: "Upload to code-scanning"
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: results.sarif

.github/workflows/search_db_tests.yml

@@ -0,0 +1,244 @@
+name: Reusable Search DB Tests
+
+permissions:
+  contents: read
+  packages: read
+
+on:
+  workflow_call:
+    inputs:
+      databases:
+        required: false
+        type: string
+        default: "all"
+        description: "Which vector databases to test (comma-separated list or 'all')"
+      python-versions:
+        required: false
+        type: string
+        default: '["3.10", "3.11", "3.12", "3.13"]'
+        description: "Python versions to test (JSON array)"
+      ci-image:
+        required: false
+        type: string
+        default: ''
+        description: "Container image for CI (empty string means no container)"
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  run-kuzu-lance-sqlite-search-tests:
+    name: Search test for Kuzu/LanceDB/Sqlite (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'kuzu/lance/sqlite') }}
+    strategy:
+      matrix:
+        python-version: ${{ fromJSON(inputs.python-versions) }}
+      fail-fast: false
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Dependencies already installed
+        run: echo "Dependencies already installed in setup"
+
+      - name: Run Kuzu search Tests
+        env:
+          ENV: 'dev'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          GRAPH_DATABASE_PROVIDER: 'kuzu'
+          VECTOR_DB_PROVIDER: 'lancedb'
+          DB_PROVIDER: 'sqlite'
+        run: uv run pytest cognee/tests/test_search_db.py -v --log-level=INFO
+
+  run-neo4j-lance-sqlite-search-tests:
+    name: Search test for Neo4j/LanceDB/Sqlite (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-22.04
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'neo4j/lance/sqlite') }}
+    strategy:
+      matrix:
+        python-version: ${{ fromJSON(inputs.python-versions) }}
+      fail-fast: false
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Setup Neo4j with GDS
+        uses: ./.github/actions/setup_neo4j
+        id: neo4j
+
+      - name: Dependencies already installed
+        run: echo "Dependencies already installed in setup"
+
+      - name: Run Neo4j search Tests
+        env:
+          ENV: 'dev'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          GRAPH_DATABASE_PROVIDER: 'neo4j'
+          VECTOR_DB_PROVIDER: 'lancedb'
+          DB_PROVIDER: 'sqlite'
+          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+          GRAPH_DATABASE_URL: ${{ steps.neo4j.outputs.neo4j-url }}
+          GRAPH_DATABASE_USERNAME: ${{ steps.neo4j.outputs.neo4j-username }}
+          GRAPH_DATABASE_PASSWORD: ${{ steps.neo4j.outputs.neo4j-password }}
+        run: uv run pytest cognee/tests/test_search_db.py -v --log-level=INFO
+
+  run-kuzu-pgvector-postgres-search-tests:
+      name: Search test for Kuzu/PGVector/Postgres (Python ${{ matrix.python-version }})
+      runs-on: ubuntu-22.04
+      container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+      if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'kuzu/pgvector/postgres') }}
+      strategy:
+        matrix:
+          python-version: ${{ fromJSON(inputs.python-versions) }}
+        fail-fast: false
+      services:
+        postgres:
+          image: ghcr.io/topoteretes/pgvector:pg17
+          credentials:
+            username: ${{ github.actor }}
+            password: ${{ secrets.GITHUB_TOKEN }}
+          env:
+            POSTGRES_USER: cognee
+            POSTGRES_PASSWORD: cognee
+            POSTGRES_DB: cognee_db
+          options: >-
+            --health-cmd pg_isready
+            --health-interval 10s
+            --health-timeout 5s
+            --health-retries 5
+          ports:
+            - 5432:5432
+      steps:
+        - name: Check out
+          uses: actions/checkout@v6
+          with:
+            fetch-depth: 0
+
+        - name: Cognee Setup
+          uses: ./.github/actions/cognee_setup
+          with:
+            python-version: ${{ matrix.python-version }}
+            extra-dependencies: "postgres"
+
+        - name: Dependencies already installed
+          run: echo "Dependencies already installed in setup"
+
+        - name: Run Kuzu/PGVector/Postgres Tests
+          env:
+            ENV: dev
+            LLM_MODEL: ${{ secrets.LLM_MODEL }}
+            LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+            LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+            LLM_ARGS: ${{ secrets.LLM_ARGS }}
+            LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+            EMBEDDING_DIMENSIONS: 300
+            EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+            EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+            GRAPH_DATABASE_PROVIDER: 'kuzu'
+            VECTOR_DB_PROVIDER: 'pgvector'
+            ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+            DB_PROVIDER: 'postgres'
+            DB_NAME: 'cognee_db'
+            DB_HOST: ${{ inputs.ci-image != '' && 'postgres' || '127.0.0.1' }}
+            DB_PORT: 5432
+            DB_USERNAME: cognee
+            DB_PASSWORD: cognee
+          run: uv run pytest cognee/tests/test_search_db.py -v --log-level=INFO
+
+  run-neo4j-pgvector-postgres-search-tests:
+    name: Search test for Neo4j/PGVector/Postgres (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-22.04
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'neo4j/pgvector/postgres') }}
+    strategy:
+      matrix:
+        python-version: ${{ fromJSON(inputs.python-versions) }}
+      fail-fast: false
+    services:
+      postgres:
+        image: ghcr.io/topoteretes/pgvector:pg17
+        credentials:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          POSTGRES_USER: cognee
+          POSTGRES_PASSWORD: cognee
+          POSTGRES_DB: cognee_db
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries=5
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ matrix.python-version }}
+          extra-dependencies: "postgres"
+
+      - name: Setup Neo4j with GDS
+        uses: ./.github/actions/setup_neo4j
+        id: neo4j
+
+      - name: Dependencies already installed
+        run: echo "Dependencies already installed in setup"
+
+      - name: Run Neo4j + PGVector + Postgres search Tests
+        env:
+          ENV: dev
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          GRAPH_DATABASE_PROVIDER: 'neo4j'
+          VECTOR_DB_PROVIDER: 'pgvector'
+          DB_PROVIDER: 'postgres'
+          GRAPH_DATABASE_URL: ${{ steps.neo4j.outputs.neo4j-url }}
+          GRAPH_DATABASE_USERNAME: ${{ steps.neo4j.outputs.neo4j-username }}
+          GRAPH_DATABASE_PASSWORD: ${{ steps.neo4j.outputs.neo4j-password }}
+          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+          DB_NAME: cognee_db
+          DB_HOST: 127.0.0.1
+          DB_PORT: 5432
+          DB_USERNAME: cognee
+          DB_PASSWORD: cognee
+        run: uv run pytest cognee/tests/test_search_db.py -v --log-level=INFO

.github/workflows/slow_e2e_tests.yml

@@ -0,0 +1,93 @@
+name: Slow End-to-End Tests
+permissions:
+  contents: read
+  packages: read
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        required: false
+        type: string
+        default: '3.11.x'
+      ci-image:
+        required: false
+        type: string
+        default: ''
+    secrets:
+      LLM_MODEL:
+        required: true
+      LLM_ENDPOINT:
+        required: true
+      LLM_API_KEY:
+        required: true
+      LLM_ARGS:
+        required: false
+      LLM_API_VERSION:
+        required: true
+      EMBEDDING_MODEL:
+        required: true
+      EMBEDDING_API_KEY:
+        required: true
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  test-edge-centered-payload:
+    name: Test Cognify - Edge Centered Payload
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Dependencies already installed
+        run: echo "Dependencies already installed in setup"
+
+      - name: Run Edge Centered Payload Test
+        env:
+          ENV: 'dev'
+          TRIPLET_EMBEDDING: True
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./cognee/tests/test_edge_centered_payload.py
+
+  test-deletion-on-default-graph_with_legacy_data_1_default:
+    name: Delete default graph with legacy data test 1 in Kuzu case
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Run deletion on default graph with legacy data (Kuzu)
+        env:
+          ENV: 'dev'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          ENABLE_AUTO_MIGRATIONS: 'false'
+        run: uv run python ./cognee/tests/test_delete_default_graph_with_legacy_data_1.py

.github/workflows/sync_mintlify_docs.yml

@@ -0,0 +1,169 @@
+name: automation | Sync Mintlify Docs
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  sync-mintlify-docs:
+    if: ${{ github.event_name != 'release' || github.event.release.prerelease == false }}
+    runs-on: ubuntu-22.04
+    timeout-minutes: 20
+
+    steps:
+      - name: Check out core repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      # Normalize release metadata so the sync script can run unchanged for
+      # published releases, manual dispatches, and branch-push preview runs.
+      # This step always produces a body file plus synthetic tag/url/date
+      # values when the event is not an actual GitHub release.
+      - name: Prepare release body file
+        id: release_meta
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          REF_NAME: ${{ github.ref_name }}
+          COMMIT_SHA: ${{ github.sha }}
+          RELEASE_BODY: ${{ github.event.release.body }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          RELEASE_URL: ${{ github.event.release.html_url }}
+          RELEASE_PUBLISHED_AT: ${{ github.event.release.published_at }}
+          REPOSITORY: ${{ github.repository }}
+          SERVER_URL: ${{ github.server_url }}
+        run: |
+          BODY_FILE="$(mktemp)"
+          if [ "${EVENT_NAME}" = "release" ]; then
+            TAG="${RELEASE_TAG}"
+            RELEASE_LINK="${RELEASE_URL}"
+            PUBLISHED_AT="${RELEASE_PUBLISHED_AT}"
+            DOCS_BRANCH_NAME="automation/sync-mintlify-docs-${RELEASE_TAG}"
+            printf "%s" "${RELEASE_BODY}" > "${BODY_FILE}"
+          else
+            TAG="test-sync-${REF_NAME}-${COMMIT_SHA::7}"
+            RELEASE_LINK="${SERVER_URL}/${REPOSITORY}/commit/${COMMIT_SHA}"
+            PUBLISHED_AT="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+            DOCS_BRANCH_NAME="${REF_NAME}"
+            printf "%s\n\n- Source commit: \`%s\`\n- Workflow event: \`%s\`\n- Commit URL: %s\n" \
+              "Automated docs sync test run from branch \`${REF_NAME}\`." \
+              "${COMMIT_SHA}" \
+              "${EVENT_NAME}" \
+              "${RELEASE_LINK}" > "${BODY_FILE}"
+          fi
+
+          SAFE_DOCS_BRANCH_NAME="${DOCS_BRANCH_NAME// /-}"
+
+          echo "body_file=${BODY_FILE}" >> "$GITHUB_OUTPUT"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "release_url=${RELEASE_LINK}" >> "$GITHUB_OUTPUT"
+          echo "published_at=${PUBLISHED_AT}" >> "$GITHUB_OUTPUT"
+          echo "docs_branch_name=${SAFE_DOCS_BRANCH_NAME}" >> "$GITHUB_OUTPUT"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --locked --all-extras
+
+      - name: Check out docs repository
+        uses: actions/checkout@v6
+        with:
+          repository: topoteretes/cognee-docs
+          token: ${{ secrets.REPO_DISPATCH_PAT_TOKEN }}
+          ref: main
+          path: docs-repo
+
+      - name: Sync OpenAPI and changelog
+        run: |
+          uv run python tools/sync_release_docs.py \
+            --docs-repo "${GITHUB_WORKSPACE}/docs-repo" \
+            --tag "${{ steps.release_meta.outputs.tag }}" \
+            --release-url "${{ steps.release_meta.outputs.release_url }}" \
+            --published-at "${{ steps.release_meta.outputs.published_at }}" \
+            --release-body-file "${{ steps.release_meta.outputs.body_file }}"
+
+      - name: Commit docs changes
+        id: commit_docs
+        working-directory: docs-repo
+        run: |
+          BRANCH_NAME="${{ steps.release_meta.outputs.docs_branch_name }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -B "${BRANCH_NAME}"
+          git add cognee_openapi_spec.json changelog.mdx
+          if git diff --cached --quiet; then
+            echo "changes_made=false" >> "$GITHUB_OUTPUT"
+            echo "branch_name=${BRANCH_NAME}" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          git commit -m "docs: sync ${{ steps.release_meta.outputs.tag }}"
+          echo "changes_made=true" >> "$GITHUB_OUTPUT"
+          echo "branch_name=${BRANCH_NAME}" >> "$GITHUB_OUTPUT"
+
+      - name: Push docs branch
+        if: ${{ steps.commit_docs.outputs.changes_made == 'true' }}
+        working-directory: docs-repo
+        env:
+          GH_TOKEN: ${{ secrets.REPO_DISPATCH_PAT_TOKEN }}
+        run: |
+          git push --force-with-lease origin "${{ steps.commit_docs.outputs.branch_name }}"
+
+      - name: Create or update docs pull request
+        if: ${{ steps.commit_docs.outputs.changes_made == 'true' }}
+        env:
+          GH_TOKEN: ${{ secrets.REPO_DISPATCH_PAT_TOKEN }}
+          EVENT_NAME: ${{ github.event_name }}
+          RELEASE_TAG: ${{ steps.release_meta.outputs.tag }}
+          RELEASE_URL: ${{ steps.release_meta.outputs.release_url }}
+          TARGET_REPO: topoteretes/cognee-docs
+          HEAD_BRANCH: ${{ steps.commit_docs.outputs.branch_name }}
+        run: |
+          if [ "${EVENT_NAME}" = "release" ]; then
+            PR_TITLE="docs: sync release ${RELEASE_TAG}"
+            PR_BODY=$(cat <<EOF
+          Automated sync for release \`${RELEASE_TAG}\`.
+
+          Source release: ${RELEASE_URL}
+          EOF
+            )
+          else
+            PR_TITLE="test(docs): preview sync for ${HEAD_BRANCH}"
+            PR_BODY=$(cat <<EOF
+          Automated preview sync from branch \`${HEAD_BRANCH}\`.
+
+          Source commit/revision: ${RELEASE_URL}
+          EOF
+            )
+          fi
+
+          HEAD_REF="topoteretes:${HEAD_BRANCH}"
+
+          EXISTING_PR_NUMBER="$(gh pr list \
+            --repo "${TARGET_REPO}" \
+            --head "${HEAD_REF}" \
+            --base main \
+            --state open \
+            --json number \
+            --jq '.[0].number // empty')"
+
+          if [ -n "${EXISTING_PR_NUMBER}" ]; then
+            gh pr edit "${EXISTING_PR_NUMBER}" \
+              --repo "${TARGET_REPO}" \
+              --title "${PR_TITLE}" \
+              --body "${PR_BODY}"
+          else
+            gh pr create \
+              --repo "${TARGET_REPO}" \
+              --base main \
+              --head "${HEAD_REF}" \
+              --title "${PR_TITLE}" \
+              --body "${PR_BODY}"
+          fi

.github/workflows/temporal_graph_tests.yml

@@ -0,0 +1,230 @@
+name: Temporal Graph Tests
+
+permissions:
+  contents: read
+  packages: read
+
+on:
+  workflow_call:
+    inputs:
+      databases:
+        required: false
+        type: string
+        default: "all"
+        description: "Which vector databases to test (comma-separated list or 'all')"
+      ci-image:
+        required: false
+        type: string
+        default: ''
+        description: "Optional container image for CI"
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  run_temporal_graph_kuzu_lance_sqlite:
+    name: Temporal Graph test Kuzu (lancedb + sqlite)
+    runs-on: ubuntu-22.04
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'kuzu/lance/sqlite') }}
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Dependencies already installed
+        run: echo "Dependencies already installed in setup"
+
+      - name: Run Temporal Graph with Kuzu (lancedb + sqlite)
+        env:
+          ENV: 'dev'
+          LLM_MODEL: ${{ secrets.OPENAI_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.OPENAI_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          GRAPH_DATABASE_PROVIDER: 'kuzu'
+          VECTOR_DB_PROVIDER: 'lancedb'
+          DB_PROVIDER: 'sqlite'
+        run: uv run python ./cognee/tests/test_temporal_graph.py
+
+  run_temporal_graph_neo4j_lance_sqlite:
+    name: Temporal Graph test Neo4j (lancedb + sqlite)
+    runs-on: ubuntu-22.04
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'neo4j/lance/sqlite') }}
+
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Setup Neo4j with GDS
+        uses: ./.github/actions/setup_neo4j
+        id: neo4j
+
+      - name: Dependencies already installed
+        run: echo "Dependencies already installed in setup"
+
+      - name: Run Temporal Graph with Neo4j (lancedb + sqlite)
+        env:
+          ENV: 'dev'
+          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+          LLM_MODEL: ${{ secrets.OPENAI_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.OPENAI_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          GRAPH_DATABASE_PROVIDER: 'neo4j'
+          VECTOR_DB_PROVIDER: 'lancedb'
+          DB_PROVIDER: 'sqlite'
+          GRAPH_DATABASE_URL: ${{ steps.neo4j.outputs.neo4j-url }}
+          GRAPH_DATABASE_USERNAME: ${{ steps.neo4j.outputs.neo4j-username }}
+          GRAPH_DATABASE_PASSWORD: ${{ steps.neo4j.outputs.neo4j-password }}
+        run: uv run python ./cognee/tests/test_temporal_graph.py
+
+  run_temporal_graph_kuzu_postgres_pgvector:
+      name: Temporal Graph test Kuzu (postgres + pgvector)
+      runs-on: ubuntu-22.04
+      if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'kuzu/pgvector/postgres') }}
+      container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+      services:
+        postgres:
+          image: ghcr.io/topoteretes/pgvector:pg17
+          credentials:
+            username: ${{ github.actor }}
+            password: ${{ secrets.GITHUB_TOKEN }}
+          env:
+            POSTGRES_USER: cognee
+            POSTGRES_PASSWORD: cognee
+            POSTGRES_DB: cognee_db
+          options: >-
+            --health-cmd pg_isready
+            --health-interval 10s
+            --health-timeout 5s
+            --health-retries 5
+          ports:
+            - 5432:5432
+      steps:
+        - name: Check out
+          uses: actions/checkout@v6
+          with:
+            fetch-depth: 0
+
+        - name: Cognee Setup
+          uses: ./.github/actions/cognee_setup
+          with:
+            python-version: ${{ inputs.python-version }}
+            extra-dependencies: "postgres"
+
+        - name: Dependencies already installed
+          run: echo "Dependencies already installed in setup"
+
+        - name: Run Temporal Graph with Kuzu (postgres + pgvector)
+          env:
+            ENV: dev
+            ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+            LLM_MODEL: ${{ secrets.OPENAI_MODEL }}
+            LLM_ENDPOINT: ${{ secrets.OPENAI_ENDPOINT }}
+            LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+            LLM_ARGS: ${{ secrets.LLM_ARGS }}
+            EMBEDDING_DIMENSIONS: 300
+            EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+            EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+            GRAPH_DATABASE_PROVIDER: 'kuzu'
+            VECTOR_DB_PROVIDER: 'pgvector'
+            DB_PROVIDER: 'postgres'
+            DB_NAME: 'cognee_db'
+            DB_HOST: ${{ inputs.ci-image != '' && 'postgres' || '127.0.0.1' }}
+            DB_PORT: 5432
+            DB_USERNAME: cognee
+            DB_PASSWORD: cognee
+          run: uv run python ./cognee/tests/test_temporal_graph.py
+
+  run_temporal_graph_neo4j_postgres_pgvector:
+    name: Temporal Graph test Neo4j (postgres + pgvector)
+    runs-on: ubuntu-22.04
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'neo4j/pgvector/postgres') }}
+    services:
+      neo4j:
+        image: neo4j:5.11
+        env:
+          NEO4J_AUTH: neo4j/pleaseletmein
+          NEO4J_PLUGINS: '["apoc","graph-data-science"]'
+        ports:
+          - 7474:7474
+          - 7687:7687
+        options: >-
+          --health-cmd="cypher-shell -u neo4j -p pleaseletmein 'RETURN 1'"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=5
+      postgres:
+        image: ghcr.io/topoteretes/pgvector:pg17
+        credentials:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          POSTGRES_USER: cognee
+          POSTGRES_PASSWORD: cognee
+          POSTGRES_DB: cognee_db
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries=5
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+          extra-dependencies: "postgres"
+
+      - name: Dependencies already installed
+        run: echo "Dependencies already installed in setup"
+
+      - name: Run Temporal Graph with Neo4j (postgres + pgvector)
+        env:
+          ENV: dev
+          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+          LLM_MODEL: ${{ secrets.OPENAI_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.OPENAI_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          GRAPH_DATABASE_PROVIDER: 'neo4j'
+          VECTOR_DB_PROVIDER: 'pgvector'
+          DB_PROVIDER: 'postgres'
+          GRAPH_DATABASE_URL: bolt://localhost:7687
+          GRAPH_DATABASE_USERNAME: neo4j
+          GRAPH_DATABASE_PASSWORD: pleaseletmein
+          DB_NAME: cognee_db
+          DB_HOST: 127.0.0.1
+          DB_PORT: 5432
+          DB_USERNAME: cognee
+          DB_PASSWORD: cognee
+        run: uv run python ./cognee/tests/test_temporal_graph.py

.github/workflows/test_different_operating_systems.yml

@@ -0,0 +1,220 @@
+name: Tests to run on different Operating Systems
+
+permissions:
+  contents: read
+
+on:
+  workflow_call:
+    inputs:
+      python-versions:
+        required: false
+        type: string
+        default: '["3.10.x", "3.12.x", "3.13.x"]'
+      os:
+        required: false
+        type: string
+        default: '["ubuntu-22.04", "macos-15", "windows-latest"]'
+      extra-dependencies:
+        # Space-separated package extras for the unit-test job (e.g. "postgres").
+        # Driver-dependent tests importorskip when their extra is absent.
+        required: false
+        type: string
+        default: ''
+    secrets:
+      LLM_PROVIDER:
+        required: true
+      LLM_MODEL:
+        required: true
+      LLM_ENDPOINT:
+        required: true
+      LLM_API_KEY:
+        required: true
+      LLM_ARGS:
+        required: false
+      LLM_API_VERSION:
+        required: true
+      EMBEDDING_PROVIDER:
+        required: true
+      EMBEDDING_MODEL:
+        required: true
+      EMBEDDING_API_KEY:
+        required: true
+
+env:
+  RUNTIME__LOG_LEVEL: ERROR
+  ENV: 'dev'
+
+jobs:
+  run-unit-tests:
+    name: Unit tests ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    strategy:
+      matrix:
+        python-version: ${{ fromJSON(inputs.python-versions) }}
+        os: ${{ fromJSON(inputs.os) }}
+      fail-fast: false
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ matrix.python-version }}
+          extra-dependencies: ${{ inputs.extra-dependencies }}
+
+      - name: Run unit tests
+        shell: bash
+        run: uv run pytest cognee/tests/unit/ --timeout=300 --timeout-method=thread
+        env:
+          PYTHONUTF8: 1
+          LLM_PROVIDER: openai
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+
+          EMBEDDING_PROVIDER: openai
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+
+  run-library-test:
+    name: Library test ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    strategy:
+      matrix:
+        python-version: ${{ fromJSON(inputs.python-versions) }}
+        os: ${{ fromJSON(inputs.os) }}
+      fail-fast: false
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run default basic pipeline
+        shell: bash
+        env:
+          PYTHONUTF8: 1
+          LLM_PROVIDER: openai
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+
+          EMBEDDING_PROVIDER: openai
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./cognee/tests/test_library.py
+
+  run-build-test:
+    name: Build test ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    strategy:
+      matrix:
+        python-version: ${{ fromJSON(inputs.python-versions) }}
+        os: ${{ fromJSON(inputs.os) }}
+      fail-fast: false
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Build with uv
+        shell: bash
+        run: uv build
+
+      - name: Install Package
+        if: ${{ !contains(matrix.os, 'windows-latest') }}
+        run: |
+          cd dist
+          pip install *.whl
+
+  run-soft-deletion-test:
+    name: Soft Delete test ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    strategy:
+      matrix:
+        python-version: ${{ fromJSON(inputs.python-versions) }}
+        os: ${{ fromJSON(inputs.os) }}
+      fail-fast: false
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Path setup
+        if: ${{ matrix.os == 'windows-latest' }}
+        shell: bash
+        run: |
+          PATH=$(printf '%s' "$PATH" | tr ':' $'\n' | grep -vi '/git/usr/bin' | paste -sd: -)
+          export PATH
+
+      - name: Run Soft Deletion Tests
+        env:
+          ENV: 'dev'
+          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }} # Test needs OpenAI endpoint to handle multimedia
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./cognee/tests/test_delete_default_graph.py
+
+  run-hard-deletion-test:
+    name: Custom Graph Delete test ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    strategy:
+      matrix:
+        python-version: ${{ fromJSON(inputs.python-versions) }}
+        os: ${{ fromJSON(inputs.os) }}
+      fail-fast: false
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run Custom Graph Deletion Test
+        env:
+          ENV: 'dev'
+          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }} # Test needs OpenAI endpoint to handle multimedia
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./cognee/tests/test_delete_custom_graph.py

.github/workflows/test_llamacpp.yml

@@ -0,0 +1,61 @@
+name: test | ollama
+
+on:
+  workflow_call:
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+
+  run_llama-cpp_test:
+
+    # needs ~4 Gb RAM for the GGUF model in a container which the smallest runner has
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.13.x'
+          extra-dependencies: postgres llama-cpp
+
+      - name: Install torch dependency
+        run: |
+          uv add torch
+
+      - name: Download Phi-3.5 GGUF model from S3
+        # Mirrored from huggingface.co/bartowski/Phi-3.5-mini-instruct-GGUF (MIT)
+        # into our bucket to avoid HuggingFace 429 rate limits in CI.
+        # Phi-3.5-mini reliably emits the required per-node `description`;
+        # the previous Phi-3-mini-q4 dropped it, failing extraction.
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_S3_DEV_USER_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_S3_DEV_USER_SECRET_KEY }}
+          AWS_DEFAULT_REGION: eu-west-1
+          BUCKET: github-runner-cognee-tests
+          MODEL_KEY: nightly_ci_artifacts/huggingface_models/Phi-3.5-mini-instruct-Q4_K_M.gguf
+          MODEL_SHA256: e4165e3a71af97f1b4820da61079826d8752a2088e313af0c7d346796c38eff5
+        run: |
+          set -euo pipefail
+          aws s3 cp "s3://$BUCKET/$MODEL_KEY" ./Phi-3.5-mini-instruct-Q4_K_M.gguf
+          echo "$MODEL_SHA256  ./Phi-3.5-mini-instruct-Q4_K_M.gguf" | sha256sum -c -
+
+      - name: Run example test
+        env:
+          PYTHONFAULTHANDLER: 1
+          LLM_PROVIDER: "llama_cpp"
+          LLAMA_CPP_MODEL_PATH: "./Phi-3.5-mini-instruct-Q4_K_M.gguf"
+          LLM_ENDPOINT: ""
+          LLAMA_CPP_N_CTX: 4096
+          EMBEDDING_PROVIDER: "openai"
+          LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          EMBEDDING_MODEL: "openai/text-embedding-3-large"
+          EMBEDDING_DIMENSIONS: "3072"
+          EMBEDDING_MAX_TOKENS: "8191"
+          STRUCTURED_OUTPUT_FRAMEWORK: "instructor"
+          LLM_INSTRUCTOR_MODE: ""
+        run: uv run python ./examples/demos/simple_cognee_example.py

.github/workflows/test_llms.yml

@@ -0,0 +1,220 @@
+name: LLM Test Suites
+
+permissions:
+  contents: read
+  packages: read
+
+on:
+  workflow_call:
+    inputs:
+      ci-image:
+        required: false
+        type: string
+        default: ''
+
+env:
+  RUNTIME__LOG_LEVEL: ERROR
+  ENV: 'dev'
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  test-gemini:
+    name: Run Gemini Test
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+
+      - name: Run Gemini Simple Example
+        env:
+          LLM_PROVIDER: "gemini"
+          LLM_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_MODEL: "gemini/gemini-3-flash-preview"
+          EMBEDDING_PROVIDER: "gemini"
+          EMBEDDING_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+          EMBEDDING_MODEL: "gemini/gemini-embedding-001"
+          EMBEDDING_DIMENSIONS: "768"
+          EMBEDDING_MAX_TOKENS: "8076"
+        run: uv run python ./examples/demos/simple_cognee_example.py
+
+  test-fastembed:
+    name: Run Fastembed Test
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+
+      - name: Run Fastembed Simple Example
+        env:
+          LLM_PROVIDER: "openai"
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_PROVIDER: "fastembed"
+          EMBEDDING_MODEL: "sentence-transformers/all-MiniLM-L6-v2"
+          EMBEDDING_DIMENSIONS: "384"
+          EMBEDDING_MAX_TOKENS: "256"
+        run: uv run python ./examples/demos/simple_cognee_example.py
+
+  test-openrouter:
+    name: Run OpenRouter Test
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+
+      - name: Run OpenRouter Simple Example
+        env:
+          LLM_PROVIDER: "custom"
+          LLM_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_MODEL: "openrouter/x-ai/grok-4.3"
+          LLM_ENDPOINT: "https://openrouter.ai/api/v1"
+          EMBEDDING_PROVIDER: "openai"
+          EMBEDDING_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          EMBEDDING_MODEL: "openai/text-embedding-3-large"
+          EMBEDDING_DIMENSIONS: "3072"
+          EMBEDDING_MAX_TOKENS: "8191"
+        run: uv run python ./examples/demos/simple_cognee_example.py
+
+  test-bedrock-api-key:
+    name: Run Bedrock API Key Test
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: "aws"
+
+      - name: Run Bedrock API Key Simple Example
+        env:
+          LLM_PROVIDER: "bedrock"
+          LLM_API_KEY: ${{ secrets.BEDROCK_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_MODEL: "eu.anthropic.claude-sonnet-4-5-20250929-v1:0"
+          LLM_MAX_TOKENS: "16384"
+          AWS_REGION_NAME: "eu-west-1"
+          EMBEDDING_PROVIDER: "bedrock"
+          EMBEDDING_API_KEY: ${{ secrets.BEDROCK_API_KEY }}
+          EMBEDDING_MODEL: "amazon.titan-embed-text-v2:0"
+          EMBEDDING_DIMENSIONS: "1024"
+          EMBEDDING_MAX_TOKENS: "8191"
+        run: uv run python ./examples/demos/simple_cognee_example.py
+
+  test-bedrock-aws-credentials:
+    name: Run Bedrock AWS Credentials Test
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: "aws"
+
+      - name: Run Bedrock AWS Credentials Simple Example
+        env:
+          LLM_PROVIDER: "bedrock"
+          LLM_MODEL: "eu.anthropic.claude-sonnet-4-5-20250929-v1:0"
+          LLM_MAX_TOKENS: "16384"
+          AWS_REGION_NAME: "eu-west-1"
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          EMBEDDING_PROVIDER: "bedrock"
+          EMBEDDING_API_KEY: ${{ secrets.BEDROCK_API_KEY }}
+          EMBEDDING_MODEL: "amazon.titan-embed-text-v2:0"
+          EMBEDDING_DIMENSIONS: "1024"
+          EMBEDDING_MAX_TOKENS: "8191"
+        run: uv run python ./examples/demos/simple_cognee_example.py
+
+  test-bedrock-aws-profile:
+    name: Run Bedrock AWS Profile Test
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: "aws"
+
+      - name: Configure AWS Profile
+        run: |
+          mkdir -p ~/.aws
+          cat > ~/.aws/credentials << EOF
+          [bedrock-test]
+          aws_access_key_id = ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws_secret_access_key = ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          EOF
+
+      - name: Run Bedrock AWS Profile Simple Example
+        env:
+          LLM_PROVIDER: "bedrock"
+          LLM_MODEL: "eu.anthropic.claude-sonnet-4-5-20250929-v1:0"
+          LLM_MAX_TOKENS: "16384"
+          AWS_PROFILE_NAME: "bedrock-test"
+          AWS_REGION_NAME: "eu-west-1"
+          EMBEDDING_PROVIDER: "bedrock"
+          EMBEDDING_MODEL: "amazon.titan-embed-text-v2:0"
+          EMBEDDING_DIMENSIONS: "1024"
+          EMBEDDING_MAX_TOKENS: "8191"
+        run: uv run python ./examples/demos/simple_cognee_example.py
+
+  test-claude-anthropic:
+    name: Run Anthropic Claude LLM Test
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+
+      - name: Run Claude Anthropic LLM Simple Example
+        env:
+          LLM_PROVIDER: "anthropic"
+          # Note: If model becomes outdated update docs with new model as well
+          LLM_MODEL: "anthropic/claude-sonnet-4-5-20250929"
+          LLM_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_MAX_TOKENS: "16384"
+          EMBEDDING_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          EMBEDDING_MODEL: "openai/text-embedding-3-large"
+          EMBEDDING_DIMENSIONS: "3072"
+          EMBEDDING_MAX_TOKENS: "8191"
+        run: uv run python ./examples/demos/simple_cognee_example.py

.github/workflows/test_mcp.yml

@@ -0,0 +1,64 @@
+name: test | mcp
+
+on:
+  workflow_call:
+    inputs:
+      cognee_version:
+        required: false
+        type: string
+        default: "local" # local - Installing Cognee from local source
+        description: "Pypi-compatible version of cognee to use. For example, 0.5.2.dev0. `local` (default) - Installing Cognee from local source"
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  test-mcp:
+    name: Run MCP Test
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Install UV
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          pip install uv
+
+      - name: Install dependencies
+        shell: bash
+        working-directory: cognee-mcp
+        run: uv sync
+
+      - name: Install Cognee
+        uses: ./.github/actions/install_cognee
+        with:
+          python-version: ${{ inputs.python-version }}
+          cognee_version: ${{ inputs.cognee_version }}
+
+      - name: Run MCP unit tests
+        working-directory: cognee-mcp
+        run: uv run --no-sync pytest tests/
+
+      - name: Run MCP test
+        env:
+          ENV: 'dev'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        working-directory: cognee-mcp
+        run: |
+          echo "Cognee Version:"
+          uv pip show cognee | grep Version
+          uv run --no-sync python ./src/test_client.py

.github/workflows/test_ollama.yml

@@ -0,0 +1,111 @@
+name: test | ollama
+
+on:
+  workflow_call:
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+
+  run_ollama_test:
+
+    # TODO: needs 32 Gb RAM for phi4 in a container — GitHub-hosted larger runner
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+
+      - name: Install torch dependency
+        run: |
+          uv add torch
+
+      - name: Start Ollama container
+        run: |
+          docker run -d --name ollama -p 11434:11434 ollama/ollama
+          sleep 5
+          docker exec -d ollama bash -c "ollama serve --openai"
+
+      - name: Check Ollama logs
+        run: docker logs ollama
+
+      - name: Wait for Ollama to be ready
+        run: |
+          for i in {1..30}; do
+            if curl -s http://localhost:11434/v1/models > /dev/null; then
+              echo "Ollama is ready"
+              exit 0
+            fi
+            echo "Waiting for Ollama... attempt $i"
+            sleep 2
+          done
+          echo "Ollama failed to start"
+          exit 1
+
+      - name: Pull required Ollama models
+        run: |
+          curl -X POST http://localhost:11434/api/pull -d '{"name": "phi4"}'
+          curl -X POST http://localhost:11434/api/pull -d '{"name": "qwen3-embedding:latest"}'
+
+      - name: Call ollama API
+        run: |
+          curl -X POST http://localhost:11434/v1/chat/completions \
+            -H "Content-Type: application/json" \
+            -d '{
+              "model": "phi4",
+              "stream": false,
+              "messages": [
+                { "role": "system", "content": "You are a helpful assistant." },
+                { "role": "user", "content": "Whatever I say, answer with Yes." }
+              ]
+            }'
+          curl -X POST http://127.0.0.1:11434/api/embed \
+            -H "Content-Type: application/json" \
+             -d '{
+              "model": "qwen3-embedding:latest",
+            "input": "This is a test sentence to generate an embedding."
+            }'
+
+      - name: Dump Docker logs
+        run: |
+          docker ps
+          docker logs $(docker ps --filter "ancestor=ollama/ollama" --format "{{.ID}}")
+
+      - name: Download embedding tokenizer from S3
+        # Mirrored from huggingface.co/Qwen/Qwen3-Embedding-8B (Apache-2.0) so the
+        # embedding tokenizer loads offline and never hits HuggingFace 429s in CI.
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_S3_DEV_USER_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_S3_DEV_USER_SECRET_KEY }}
+          AWS_DEFAULT_REGION: eu-west-1
+          BUCKET: github-runner-cognee-tests
+          TOKENIZER_KEY: nightly_ci_artifacts/huggingface_models/qwen3-embedding-tokenizer.tar.gz
+          TOKENIZER_SHA256: 8f5834d8791c8da03220feaccc2fe9c443e23b1092dcd99c576ef613990bbd00
+        run: |
+          set -euo pipefail
+          aws s3 cp "s3://$BUCKET/$TOKENIZER_KEY" tokenizer.tar.gz
+          echo "$TOKENIZER_SHA256  tokenizer.tar.gz" | sha256sum -c -
+          tar -xzf tokenizer.tar.gz -C "$GITHUB_WORKSPACE"
+
+      - name: Run example test
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          PYTHONFAULTHANDLER: 1
+          LLM_PROVIDER: "ollama"
+          LLM_API_KEY: "ollama"
+          LLM_ENDPOINT: "http://localhost:11434/v1/"
+          LLM_MODEL: "phi4"
+          EMBEDDING_PROVIDER: "ollama"
+          EMBEDDING_MODEL: "qwen3-embedding:latest"
+          EMBEDDING_ENDPOINT: "http://localhost:11434/api/embed"
+          EMBEDDING_DIMENSIONS: "4096"
+          # Load the tokenizer from the S3-mirrored local dir, fully offline.
+          HUGGINGFACE_TOKENIZER: "${{ github.workspace }}/qwen3-embedding-tokenizer"
+          HF_HUB_OFFLINE: "1"
+          TRANSFORMERS_OFFLINE: "1"
+        run: uv run python ./examples/demos/simple_cognee_example.py

.github/workflows/test_s3_file_storage.yml

@@ -0,0 +1,52 @@
+name: test | s3 file storage
+
+on:
+  workflow_call:
+    inputs:
+      ci-image:
+        required: false
+        type: string
+        default: ''
+
+permissions:
+  contents: read
+  packages: read
+
+env:
+  RUNTIME__LOG_LEVEL: ERROR
+  ENV: 'dev'
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  test-s3-storage:
+    name: Run S3 File Storage Test
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11.x'
+          extra-dependencies: "aws"
+
+      - name: Run S3 File Storage Test
+        env:
+          STORAGE_BACKEND: s3
+          ENABLE_BACKEND_ACCESS_CONTROL: True
+          AWS_REGION: eu-west-1
+          AWS_ENDPOINT_URL: https://s3-eu-west-1.amazonaws.com
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_S3_DEV_USER_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_S3_DEV_USER_SECRET_KEY }}
+          STORAGE_BUCKET_NAME: github-runner-cognee-tests
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./cognee/tests/test_s3_file_storage.py

.github/workflows/test_suites.yml

@@ -0,0 +1,413 @@
+name: Test Suites
+permissions:
+  contents: read
+  packages: write
+
+on:
+  push:
+    branches: [ main, dev ]
+  pull_request:
+    branches: [ main, dev ]
+    types: [opened, synchronize, reopened, labeled]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  RUNTIME__LOG_LEVEL: ERROR
+  ENV: 'dev'
+
+jobs:
+  # ── Build pre-baked CI container ──────────────────────────────────────
+  build-ci-env:
+    name: Build CI Environment
+    runs-on: ubuntu-latest
+    if: >-
+      github.event_name == 'push' || github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'pull_request' &&
+       github.event.pull_request.head.repo.full_name == github.repository)
+    outputs:
+      ci-image: ${{ steps.set-image.outputs.image }}
+    steps:
+      - name: Sparse checkout (deps only)
+        uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            pyproject.toml
+            uv.lock
+            README.md
+            Dockerfile.ci
+            .dockerignore.ci
+          sparse-checkout-cone-mode: false
+
+      - name: Compute dep hash and image tag
+        id: set-image
+        run: |
+          DEP_HASH=$(sha256sum pyproject.toml uv.lock | sha256sum | head -c 16)
+          IMAGE="ghcr.io/${{ github.repository }}/ci-env:deps-${DEP_HASH}"
+          echo "image=${IMAGE}" >> "$GITHUB_OUTPUT"
+          echo "dep_hash=${DEP_HASH}" >> "$GITHUB_OUTPUT"
+          echo "Image tag: ${IMAGE}"
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Check if image already exists
+        id: check
+        run: |
+          if docker manifest inspect "${{ steps.set-image.outputs.image }}" > /dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+            echo "Image already exists, skipping build."
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+            echo "Image not found, will build."
+          fi
+
+      - name: Set up Docker Buildx
+        if: steps.check.outputs.exists != 'true'
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push CI image
+        if: steps.check.outputs.exists != 'true'
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: Dockerfile.ci
+          push: true
+          tags: ${{ steps.set-image.outputs.image }}
+          cache-from: type=registry,ref=ghcr.io/${{ github.repository }}/ci-env:buildcache
+          cache-to: type=registry,ref=ghcr.io/${{ github.repository }}/ci-env:buildcache,mode=max
+
+  pre-test:
+    name: basic checks
+    uses: ./.github/workflows/pre_test.yml
+
+  basic-tests:
+    name: Basic Tests
+    uses: ./.github/workflows/basic_tests.yml
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  e2e-tests:
+    name: End-to-End Tests
+    uses: ./.github/workflows/e2e_tests.yml
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  cli-tests:
+    name: CLI Tests
+    uses: ./.github/workflows/cli_tests.yml
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  slow-e2e-tests:
+    name: Slow End-to-End Tests
+    uses: ./.github/workflows/slow_e2e_tests.yml
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  graph-db-tests:
+    name: Graph Database Tests
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    uses: ./.github/workflows/graph_db_tests.yml
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  vector-db-tests:
+    name: Vector DB Tests
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    uses: ./.github/workflows/vector_db_tests.yml
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  example-tests:
+    name: Example Tests
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    uses: ./.github/workflows/examples_tests.yml
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  notebook-tests:
+    name: Notebook Tests
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    uses: ./.github/workflows/notebooks_tests.yml
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  different-os-tests-basic:
+    name: OS and Python Tests Ubuntu
+    uses: ./.github/workflows/test_different_operating_systems.yml
+    with:
+      python-versions: '["3.10.x", "3.11.x", "3.12.x", "3.13.x", "3.14.x"]'
+      os: '["ubuntu-22.04"]'
+      # postgres so the SQL cache adapter tests run instead of skipping; omitted
+      # on macos/windows (extended) where psycopg2 has no prebuilt wheels.
+      extra-dependencies: 'postgres'
+    secrets: inherit
+
+  different-os-tests-extended:
+    name: OS and Python Tests Extended
+    uses: ./.github/workflows/test_different_operating_systems.yml
+    with:
+      python-versions: '["3.13.x"]'
+      os: '["macos-15", "windows-latest"]'
+    secrets: inherit
+
+  llm-tests:
+    name: LLM Test Suite
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    uses: ./.github/workflows/test_llms.yml
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  s3-file-storage-test:
+    name: S3 File Storage Test
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    uses: ./.github/workflows/test_s3_file_storage.yml
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  integration-tests:
+    name: Run Integration Tests
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    uses: ./.github/workflows/integration_tests.yml
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  mcp-test:
+    name: MCP Tests
+    uses: ./.github/workflows/test_mcp.yml
+    secrets: inherit
+
+  docker-compose-test:
+    name: Docker Compose Test
+    uses: ./.github/workflows/docker_compose.yml
+    secrets: inherit
+
+  docker-ci-test:
+    name: Docker CI test
+    uses: ./.github/workflows/backend_docker_build_test.yml
+    secrets: inherit
+
+  temporal-graph-tests:
+    name: Temporal Graph Test
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    uses: ./.github/workflows/temporal_graph_tests.yml
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  search-db-tests:
+    name: Search Test on Different DBs
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    uses: ./.github/workflows/search_db_tests.yml
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  relational-db-migration-tests:
+    name: Relational DB Migration Tests
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    uses: ./.github/workflows/relational_db_migration_tests.yml
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  # NOTE: intentionally excluded from the `notify` aggregator below — this is
+  # external infra (Modal + Azure secrets), informational only; it must not gate
+  # merges. (`continue-on-error` is not allowed on a reusable-workflow job.)
+  distributed-tests:
+    name: Distributed Cognee Test
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    uses: ./.github/workflows/distributed_test.yml
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  db-examples-tests:
+    name: DB Examples Tests
+    needs: [ build-ci-env ]
+    if: ${{ !cancelled() }}
+    uses: ./.github/workflows/db_examples_tests.yml
+    with:
+      ci-image: ${{ needs.build-ci-env.outputs.ci-image || '' }}
+    secrets: inherit
+
+  notify:
+    name: Test Completion Status
+    needs: [
+      pre-test,
+      basic-tests,
+      e2e-tests,
+      cli-tests,
+      slow-e2e-tests,
+      graph-db-tests,
+      vector-db-tests,
+      example-tests,
+      notebook-tests,
+      different-os-tests-basic,
+      different-os-tests-extended,
+      llm-tests,
+      s3-file-storage-test,
+      integration-tests,
+      mcp-test,
+      docker-compose-test,
+      docker-ci-test,
+      temporal-graph-tests,
+      search-db-tests,
+      relational-db-migration-tests,
+      db-examples-tests,
+    ]
+    runs-on: ubuntu-latest
+    if: ${{ !cancelled() }}
+    steps:
+      - name: Check Status
+        run: |
+          if [[ "${{ needs.pre-test.result }}" == "success" &&
+                "${{ needs.basic-tests.result }}" == "success" &&
+                "${{ needs.e2e-tests.result }}" == "success" &&
+                "${{ needs.cli-tests.result }}" == "success" &&
+                "${{ needs.slow-e2e-tests.result }}" == "success" &&
+                "${{ needs.graph-db-tests.result }}" == "success" &&
+                "${{ needs.vector-db-tests.result }}" == "success" &&
+                "${{ needs.example-tests.result }}" == "success" &&
+                "${{ needs.notebook-tests.result }}" == "success" &&
+                "${{ needs.different-os-tests-basic.result }}" == "success" &&
+                "${{ needs.different-os-tests-extended.result }}" == "success" &&
+                "${{ needs.llm-tests.result }}" == "success" &&
+                "${{ needs.s3-file-storage-test.result }}" == "success" &&
+                "${{ needs.integration-tests.result }}" == "success" &&
+                "${{ needs.mcp-test.result }}" == "success" &&
+                "${{ needs.docker-compose-test.result }}" == "success" &&
+                "${{ needs.docker-ci-test.result }}" == "success" &&
+                "${{ needs.temporal-graph-tests.result }}" == "success" &&
+                "${{ needs.search-db-tests.result }}" == "success" &&
+                "${{ needs.relational-db-migration-tests.result }}" == "success" &&
+                "${{ needs.db-examples-tests.result }}" == "success" ]]; then
+            echo "All test suites completed successfully!"
+          else
+            echo "One or more test suites failed."
+            exit 1
+          fi
+
+  # ── Advisory Claude Code review — pulls the private skill from cognee-ci at runtime ──
+  # The rubric + Slack map live in the private cognee-ci repo; this job carries no review
+  # logic. Runs only after the suite is green (needs: notify), core-team PRs only, advisory.
+  claude-review:
+    name: Claude Code Review
+    needs: [ notify ]
+    if: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout PR
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Core-team gate
+        id: gate
+        env:
+          AUTHOR: ${{ github.event.pull_request.user.login }}
+        run: |
+          author_lc="$(printf '%s' "$AUTHOR" | tr '[:upper:]' '[:lower:]')"
+          if grep -vE '^[[:space:]]*#' .github/core-team.txt \
+               | sed 's/^@//' | tr '[:upper:]' '[:lower:]' | grep -qxF "$author_lc"; then
+            echo "run=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "run=false" >> "$GITHUB_OUTPUT"
+            echo "PR author '$AUTHOR' not in core-team.txt — skipping."
+          fi
+
+      - name: Mint private-repo token
+        if: ${{ steps.gate.outputs.run == 'true' }}
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.CI_APP_ID }}
+          private-key: ${{ secrets.CI_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: cognee-ci
+
+      - name: Fetch private review skill + slack map
+        if: ${{ steps.gate.outputs.run == 'true' }}
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ github.repository_owner }}/cognee-ci
+          token: ${{ steps.app-token.outputs.token }}
+          path: .ci-private
+
+      - name: Stage skill into the user skills dir
+        if: ${{ steps.gate.outputs.run == 'true' }}
+        run: |
+          # Stage into the USER skills dir ($HOME/.claude), NOT the repo's .claude/.
+          # claude-code-action sanitizes the repo .claude for untrusted PR heads
+          # (it moves the working-tree .claude to .claude-pr/ and restores a clean
+          # .claude from the base branch), which wipes the staged private skill and
+          # leaves /pr-review unresolved -> 0 turns, nothing posted. $HOME/.claude is
+          # untouched by that sanitization and is loaded via settingSources: [user,...].
+          mkdir -p "$HOME/.claude/skills"
+          cp -r .ci-private/.claude/skills/pr-review "$HOME/.claude/skills/"
+
+      - name: Claude Code review
+        if: ${{ steps.gate.outputs.run == 'true' }}
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          prompt: "/pr-review"
+          claude_args: >-
+            --allowed-tools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Read,Glob,Grep"
+            --max-turns 20
+            --model claude-sonnet-4-5-20250929
+
+      - name: DM review summary to PR author on Slack
+        if: ${{ steps.gate.outputs.run == 'true' }}
+        env:
+          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          AUTHOR: ${{ github.event.pull_request.user.login }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          REPO: ${{ github.repository }}
+        run: python3 .ci-private/scripts/pr_review_slack_notify.py

.github/workflows/update-contributors.yml

@@ -0,0 +1,37 @@
+name: community | contributors leaderboard
+
+on:
+  schedule:
+    - cron: "0 0 * * 1" # Runs every Monday
+  workflow_dispatch: # Allows manual trigger
+
+jobs:
+  update-contributors:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+
+      - name: Generate Contributor List
+        run: |
+          echo "## 💫 Contributors" > CONTRIBUTORS.md
+          echo "" >> CONTRIBUTORS.md
+          echo "Thanks to our amazing contributors! 💖" >> CONTRIBUTORS.md
+          echo "" >> CONTRIBUTORS.md
+          echo '<a href="https://github.com/topoteretes/cognee/graphs/contributors">' >> CONTRIBUTORS.md
+          echo '  <img src="https://contrib.rocks/image?repo=topoteretes/cognee" />' >> CONTRIBUTORS.md
+          echo '</a>' >> CONTRIBUTORS.md
+          echo "" >> CONTRIBUTORS.md
+          echo "## 🏆 Top Contributors" >> CONTRIBUTORS.md
+          echo "" >> CONTRIBUTORS.md
+          echo "| Rank | Contributor | Contributions |" >> CONTRIBUTORS.md
+          echo "|------|------------|---------------|" >> CONTRIBUTORS.md
+          git shortlog -sne | sort -rn | head -10 | awk '{print "| "NR" | ["$2"](https://github.com/"$2") | "$1" Commits |"}' >> CONTRIBUTORS.md
+
+      - name: Commit and Push Changes
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions@users.noreply.github.com"
+          git add CONTRIBUTORS.md
+          git commit -m "Update contributors list"
+          git push

.github/workflows/vector_db_tests.yml

@@ -0,0 +1,153 @@
+name: Reusable Vector DB Tests
+
+on:
+  workflow_call:
+    inputs:
+      databases:
+        required: false
+        type: string
+        default: "all"
+        description: "Which vector databases to test (comma-separated list or 'all')"
+      ci-image:
+        required: false
+        type: string
+        default: ''
+    secrets:
+
+      POSTGRES_PASSWORD:
+        required: false
+
+env:
+  COGNEE_SKIP_CONNECTION_TEST: 'true'
+
+jobs:
+  run-postgres-tests:
+    name: PostgreSQL Tests
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'postgres') }}
+    services:
+      postgres:
+        image: ghcr.io/topoteretes/pgvector:pg17
+        credentials:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          POSTGRES_USER: cognee
+          POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}
+          POSTGRES_DB: cognee_db
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+          extra-dependencies: "postgres"
+
+      - name: Run PGVector Tests
+        env:
+          ENV: 'dev'
+          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          DB_HOST: ${{ inputs.ci-image != '' && 'postgres' || '127.0.0.1' }}
+        run: uv run python ./cognee/tests/test_pgvector.py
+
+  run-pgvector-multi-user-tests:
+    name: PGVector Multi-User Tests
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    if: ${{ inputs.databases == 'all' || contains(inputs.databases, 'postgres') }}
+    services:
+      postgres:
+        image: ghcr.io/topoteretes/pgvector:pg17
+        credentials:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        env:
+          POSTGRES_USER: cognee
+          POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}
+          POSTGRES_DB: cognee_db
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+          extra-dependencies: "postgres"
+
+      - name: Run PGVector Permissions Tests
+        env:
+          ENV: 'dev'
+          ENABLE_BACKEND_ACCESS_CONTROL: 'true'
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+          VECTOR_DB_HOST: ${{ inputs.ci-image != '' && 'postgres' || '127.0.0.1' }}
+          VECTOR_DB_PORT: 5432
+          VECTOR_DB_USERNAME: cognee
+          VECTOR_DB_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}
+          VECTOR_DATASET_DATABASE_HANDLER: pgvector
+        run: uv run python ./cognee/tests/test_permissions.py
+
+  run-lancedb-tests:
+    name: LanceDB Tests
+    runs-on: ubuntu-22.04
+    container: ${{ inputs.ci-image != '' && fromJSON(format('{{"image":"{0}","credentials":{{"username":"{1}","password":"{2}"}}}}', inputs.ci-image, github.actor, github.token)) || null }}
+    steps:
+      - name: Check out
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Run LanceDB Tests
+        env:
+          ENV: 'dev'
+          # Cap cached DB adapters
+          DATABASE_MAX_LRU_CACHE_SIZE: 1
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          LLM_ENDPOINT: ${{ secrets.LLM_ENDPOINT }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          LLM_ARGS: ${{ secrets.LLM_ARGS }}
+          LLM_API_VERSION: ${{ secrets.LLM_API_VERSION }}
+          EMBEDDING_DIMENSIONS: 300
+          EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+          EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+        run: uv run python ./cognee/tests/test_lancedb.py

.github/workflows/weighted_edges_tests.yml

@@ -0,0 +1,169 @@
+name: Weighted Edges Tests
+
+on:
+  push:
+    branches: [ main, dev, weighted_edges]
+    paths:
+      - 'cognee/modules/graph/utils/get_graph_from_model.py'
+      - 'cognee/infrastructure/engine/models/Edge.py'
+      - 'cognee/tests/unit/interfaces/graph/test_weighted_edges.py'
+      - 'examples/demos/dynamic_multiple_weighted_edges_example.py'
+      - '.github/workflows/weighted_edges_tests.yml'
+  pull_request:
+    branches: [ main, dev ]
+    paths:
+      - 'cognee/modules/graph/utils/get_graph_from_model.py'
+      - 'cognee/infrastructure/engine/models/Edge.py'
+      - 'cognee/tests/unit/interfaces/graph/test_weighted_edges.py'
+      - 'examples/demos/dynamic_multiple_weighted_edges_example.py'
+      - '.github/workflows/weighted_edges_tests.yml'
+
+env:
+  RUNTIME__LOG_LEVEL: ERROR
+  ENV: 'dev'
+
+jobs:
+  test-weighted-edges-functionality:
+    name: Test Weighted Edges Core Functionality
+    runs-on: ubuntu-22.04
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12']
+    env:
+      LLM_PROVIDER: openai
+      LLM_MODEL: gpt-5-mini
+      LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      LLM_ARGS: ${{ secrets.LLM_ARGS }}
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run Weighted Edges Unit Tests
+        run: |
+          uv run pytest cognee/tests/unit/interfaces/graph/test_weighted_edges.py -v --tb=short
+
+      - name: Run Standard Graph Tests (Regression)
+        run: |
+          uv run pytest cognee/tests/unit/interfaces/graph/get_graph_from_model_unit_test.py -v --tb=short
+
+  test-with-different-databases:
+    name: Test Weighted Edges with Different Graph Databases
+    runs-on: ubuntu-22.04
+    strategy:
+      matrix:
+        database: ['kuzu', 'neo4j']
+        include:
+          - database: kuzu
+            graph_db_provider: "kuzu"
+          - database: neo4j
+            graph_db_provider: "neo4j"
+    env:
+      LLM_PROVIDER: openai
+      LLM_MODEL: gpt-5-mini
+      LLM_ENDPOINT: https://api.openai.com/v1
+      LLM_API_KEY: ${{ secrets.OPENAI_API_KEY  }}
+      LLM_ARGS: ${{ secrets.LLM_ARGS }}
+      LLM_API_VERSION: "2024-02-01"
+      EMBEDDING_DIMENSIONS: 300
+      EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+      EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11'
+
+      - name: Setup Neo4j with GDS
+        uses: ./.github/actions/setup_neo4j
+        id: neo4j
+
+      - name: Dependencies already installed
+        run: echo "Dependencies already installed in setup"
+
+      - name: Run Weighted Edges Tests
+        env:
+          ENABLE_BACKEND_ACCESS_CONTROL: 'false'
+          GRAPH_DATABASE_PROVIDER: ${{ matrix.graph_db_provider }}
+          GRAPH_DATABASE_URL: ${{ matrix.graph_db_provider == 'neo4j' && steps.neo4j.outputs.neo4j-url || '' }}
+          GRAPH_DATABASE_USERNAME: ${{ matrix.graph_db_provider == 'neo4j' && steps.neo4j.outputs.neo4j-username || '' }}
+          GRAPH_DATABASE_PASSWORD: ${{ matrix.graph_db_provider == 'neo4j' && steps.neo4j.outputs.neo4j-password || '' }}
+        run: |
+          uv run pytest cognee/tests/unit/interfaces/graph/test_weighted_edges.py -v --tb=short
+
+  test-examples:
+    name: Test Weighted Edges Examples
+    runs-on: ubuntu-22.04
+    env:
+      LLM_PROVIDER: openai
+      LLM_MODEL: gpt-5-mini
+      LLM_ENDPOINT: https://api.openai.com/v1
+      LLM_API_KEY: ${{ secrets.OPENAI_API_KEY  }}
+      LLM_ARGS: ${{ secrets.LLM_ARGS }}
+      LLM_API_VERSION: "2024-02-01"
+      EMBEDDING_DIMENSIONS: 300
+      EMBEDDING_MODEL: ${{ secrets.EMBEDDING_MODEL }}
+      EMBEDDING_API_KEY: ${{ secrets.EMBEDDING_API_KEY }}
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11'
+
+      - name: Test Weighted Edges Example
+        run: |
+          uv run python examples/demos/dynamic_multiple_weighted_edges_example.py
+
+      - name: Verify Visualization File Created
+        run: |
+          if [ -f "examples/demos/.artifacts/dunder_mifflin_company_graph.html" ]; then
+            echo "✅ Visualization file created successfully"
+            ls -la examples/demos/.artifacts/dunder_mifflin_company_graph.html
+          else
+            echo "❌ Visualization file not found"
+            exit 1
+          fi
+
+
+
+  code-quality:
+    name: Code Quality for Weighted Edges
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Cognee Setup
+        uses: ./.github/actions/cognee_setup
+        with:
+          python-version: '3.11'
+
+      - name: Run Linting on Weighted Edges Files
+        uses: astral-sh/ruff-action@v3
+        with:
+          args: "check cognee/modules/graph/utils/get_graph_from_model.py cognee/tests/unit/interfaces/graph/test_weighted_edges.py examples/demos/dynamic_multiple_weighted_edges_example.py"
+
+      - name: Run Formatting Check on Weighted Edges Files
+        uses: astral-sh/ruff-action@v3
+        with:
+          args: "format --check cognee/modules/graph/utils/get_graph_from_model.py cognee/tests/unit/interfaces/graph/test_weighted_edges.py examples/demos/dynamic_multiple_weighted_edges_example.py"