yhl999
diff --git a/‎.github/workflows/ci.yml‎
Lines changed: 10 additions & 0 deletions b/‎.github/workflows/ci.yml‎
Lines changed: 10 additions & 0 deletions
diff --git a/‎.github/workflows/lint.yml‎
Lines changed: 25 additions & 0 deletions b/‎.github/workflows/lint.yml‎
Lines changed: 25 additions & 0 deletions
diff --git a/‎.github/workflows/typecheck.yml‎
Lines changed: 43 additions & 0 deletions b/‎.github/workflows/typecheck.yml‎
Lines changed: 43 additions & 0 deletions
diff --git a/‎.github/workflows/unit_tests.yml‎
Lines changed: 102 additions & 0 deletions b/‎.github/workflows/unit_tests.yml‎
Lines changed: 102 additions & 0 deletions
diff --git a/‎config/graphiti_core_allowlist.txt‎
Lines changed: 7 additions & 0 deletions b/‎config/graphiti_core_allowlist.txt‎
Lines changed: 7 additions & 0 deletions
diff --git a/‎config/public_export_allowlist.yaml‎
Lines changed: 1 addition & 0 deletions b/‎config/public_export_allowlist.yaml‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/runbooks/upstream-sync-openclaw.md‎
Lines changed: 15 additions & 0 deletions b/‎docs/runbooks/upstream-sync-openclaw.md‎
Lines changed: 15 additions & 0 deletions
diff --git a/‎graphiti_core/driver/driver.py‎
Lines changed: 101 additions & 5 deletions b/‎graphiti_core/driver/driver.py‎
Lines changed: 101 additions & 5 deletions
@@ -14,6 +14,16 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  graphiti_core_guard:
+    name: Graphiti core allowlist guard
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Enforce graphiti_core patch allowlist
+        run: bash scripts/ci/check_graphiti_core_allowlist.sh
+
   lint:
     name: Ruff lint
     runs-on: ubuntu-latest
 
@@ -0,0 +1,25 @@
+name: Lint with Ruff
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  ruff:
+    if: github.repository == 'getzep/graphiti'
+    environment: development
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install "ruff>0.1.7"
+      - name: Run Ruff linting
+        run: ruff check --output-format=github
@@ -0,0 +1,43 @@
+name: Pyright Type Check
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  pyright:
+    if: github.repository == 'getzep/graphiti'
+    runs-on: ubuntu-latest
+    environment: development
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        id: setup-python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Run Pyright for graphiti-core
+        shell: bash
+        run: |
+          uv run pyright ./graphiti_core
+      - name: Install graph-service dependencies
+        shell: bash
+        run: |
+          cd server
+          uv sync --all-extras
+      - name: Run Pyright for graph-service
+        shell: bash
+        run: |
+          cd server
+          uv run pyright .
@@ -0,0 +1,102 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  unit-tests:
+    if: github.repository == 'getzep/graphiti'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Run unit tests (no external dependencies)
+        env:
+          PYTHONPATH: ${{ github.workspace }}
+          DISABLE_NEPTUNE: 1
+          DISABLE_NEO4J: 1
+          DISABLE_FALKORDB: 1
+          DISABLE_KUZU: 1
+        run: |
+          uv run pytest tests/ -m "not integration" \
+            --ignore=tests/test_graphiti_int.py \
+            --ignore=tests/test_graphiti_mock.py \
+            --ignore=tests/test_node_int.py \
+            --ignore=tests/test_edge_int.py \
+            --ignore=tests/test_entity_exclusion_int.py \
+            --ignore=tests/driver/ \
+            --ignore=tests/llm_client/test_anthropic_client_int.py \
+            --ignore=tests/utils/maintenance/test_temporal_operations_int.py \
+            --ignore=tests/cross_encoder/test_bge_reranker_client_int.py \
+            --ignore=tests/evals/
+
+  database-integration-tests:
+    if: github.repository == 'getzep/graphiti'
+    runs-on: ubuntu-latest
+    services:
+      falkordb:
+        image: falkordb/falkordb:latest
+        ports:
+          - 6379:6379
+        options: --health-cmd "redis-cli ping" --health-interval 10s --health-timeout 5s --health-retries 5
+      neo4j:
+        image: neo4j:5.26-community
+        ports:
+          - 7687:7687
+          - 7474:7474
+        env:
+          NEO4J_AUTH: neo4j/testpass
+          NEO4J_PLUGINS: '["apoc"]'
+        options: --health-cmd "cypher-shell -u neo4j -p testpass 'RETURN 1'" --health-interval 10s --health-timeout 5s --health-retries 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+      - name: Install redis-cli for FalkorDB health check
+        run: sudo apt-get update && sudo apt-get install -y redis-tools
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Wait for FalkorDB
+        run: |
+          timeout 60 bash -c 'until redis-cli -h localhost -p 6379 ping; do sleep 1; done'
+      - name: Wait for Neo4j
+        run: |
+          timeout 60 bash -c 'until wget -O /dev/null http://localhost:7474 >/dev/null 2>&1; do sleep 1; done'
+      - name: Run database integration tests
+        env:
+          PYTHONPATH: ${{ github.workspace }}
+          NEO4J_URI: bolt://localhost:7687
+          NEO4J_USER: neo4j
+          NEO4J_PASSWORD: testpass
+          FALKORDB_HOST: localhost
+          FALKORDB_PORT: 6379
+          DISABLE_NEPTUNE: 1
+        run: |
+          uv run pytest \
+            tests/test_graphiti_mock.py \
+            tests/test_node_int.py \
+            tests/test_edge_int.py \
+            tests/cross_encoder/test_bge_reranker_client_int.py \
+            tests/driver/test_falkordb_driver.py \
+            -m "not integration"
@@ -0,0 +1,7 @@
+graphiti_core/search/search.py
+graphiti_core/search/search_config.py
+graphiti_core/search/search_config_recipes.py
+graphiti_core/search/search_utils.py
+graphiti_core/edges.py
+graphiti_core/graphiti.py
+graphiti_core/utils/maintenance/edge_operations.py
@@ -19,6 +19,7 @@ allowlist:
   - "examples/**"
   - "images/**"
   - "reports/publicization/**"
+  - "reports/upstream-sync/**"
 
   # Build/release/config metadata
   - "config/**"
 
@@ -103,6 +103,21 @@ Why strict:
 - PR lane preserves review, rollback, and conflict visibility,
 - Sync button bypasses branch-level review discipline.
 
+## Graphiti Core Patch-Stack Guardrail
+
+Policy file: `config/graphiti_core_allowlist.txt`
+
+CI check: `scripts/ci/check_graphiti_core_allowlist.sh` (wired into `.github/workflows/ci.yml`)
+
+Rule:
+- Any PR touching `graphiti_core/**` must be limited to the allowlisted files.
+- Non-allowlisted `graphiti_core/**` changes fail CI by default.
+
+Operational intent:
+- keep `graphiti_core` local drift explicit and small,
+- preserve fast upstream syncs,
+- move behavior to runtime layer when feasible.
+
 ## Rollback / Recovery
 
 ### A) Bad sync PR before merge
 
@@ -14,19 +14,36 @@
 limitations under the License.
 """
 
+from __future__ import annotations
+
 import copy
 import logging
 import os
 from abc import ABC, abstractmethod
-from collections.abc import Coroutine
+from collections.abc import AsyncIterator, Coroutine
+from contextlib import asynccontextmanager
 from enum import Enum
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from dotenv import load_dotenv
 
 from graphiti_core.driver.graph_operations.graph_operations import GraphOperationsInterface
+from graphiti_core.driver.query_executor import QueryExecutor, Transaction
 from graphiti_core.driver.search_interface.search_interface import SearchInterface
 
+if TYPE_CHECKING:
+    from graphiti_core.driver.operations.community_edge_ops import CommunityEdgeOperations
+    from graphiti_core.driver.operations.community_node_ops import CommunityNodeOperations
+    from graphiti_core.driver.operations.entity_edge_ops import EntityEdgeOperations
+    from graphiti_core.driver.operations.entity_node_ops import EntityNodeOperations
+    from graphiti_core.driver.operations.episode_node_ops import EpisodeNodeOperations
+    from graphiti_core.driver.operations.episodic_edge_ops import EpisodicEdgeOperations
+    from graphiti_core.driver.operations.graph_ops import GraphMaintenanceOperations
+    from graphiti_core.driver.operations.has_episode_edge_ops import HasEpisodeEdgeOperations
+    from graphiti_core.driver.operations.next_episode_edge_ops import NextEpisodeEdgeOperations
+    from graphiti_core.driver.operations.saga_node_ops import SagaNodeOperations
+    from graphiti_core.driver.operations.search_ops import SearchOperations
+
 logger = logging.getLogger(__name__)
 
 DEFAULT_SIZE = 10
@@ -70,13 +87,14 @@ async def execute_write(self, func, *args, **kwargs):
         raise NotImplementedError()
 
 
-class GraphDriver(ABC):
+class GraphDriver(QueryExecutor, ABC):
     provider: GraphProvider
     fulltext_syntax: str = (
         ''  # Neo4j (default) syntax does not require a prefix for fulltext queries
     )
     _database: str
     default_group_id: str = ''
+    # Legacy interfaces (kept for backwards compatibility during Phase 1)
     search_interface: SearchInterface | None = None
     graph_operations_interface: GraphOperationsInterface | None = None
 
@@ -96,7 +114,7 @@ def close(self):
     def delete_all_indexes(self) -> Coroutine:
         raise NotImplementedError()
 
-    def with_database(self, database: str) -> 'GraphDriver':
+    def with_database(self, database: str) -> GraphDriver:
         """
         Returns a shallow copy of this driver with a different default database.
         Reuses the same connection (e.g. FalkorDB, Neo4j).
@@ -110,7 +128,7 @@ def with_database(self, database: str) -> 'GraphDriver':
     async def build_indices_and_constraints(self, delete_existing: bool = False):
         raise NotImplementedError()
 
-    def clone(self, database: str) -> 'GraphDriver':
+    def clone(self, database: str) -> GraphDriver:
         """Clone the driver with a different database or graph name."""
         return self
 
@@ -122,3 +140,81 @@ def build_fulltext_query(
         Only implemented by providers that need custom fulltext query building.
         """
         raise NotImplementedError(f'build_fulltext_query not implemented for {self.provider}')
+
+    # --- New operations interfaces ---
+
+    @asynccontextmanager
+    async def transaction(self) -> AsyncIterator[Transaction]:
+        """Return a transaction context manager.
+
+        Usage::
+
+            async with driver.transaction() as tx:
+                await ops.save(driver, node, tx=tx)
+
+        Drivers with real transaction support (e.g., Neo4j) commit on clean exit
+        and roll back on exception. Drivers without native transactions return a
+        thin wrapper where queries execute immediately.
+
+        The base implementation provides a no-op wrapper using the session. Drivers
+        should override this to provide real transaction semantics where supported.
+        """
+        session = self.session()
+        try:
+            yield _SessionTransaction(session)
+        finally:
+            await session.close()
+
+    @property
+    def entity_node_ops(self) -> EntityNodeOperations | None:
+        return None
+
+    @property
+    def episode_node_ops(self) -> EpisodeNodeOperations | None:
+        return None
+
+    @property
+    def community_node_ops(self) -> CommunityNodeOperations | None:
+        return None
+
+    @property
+    def saga_node_ops(self) -> SagaNodeOperations | None:
+        return None
+
+    @property
+    def entity_edge_ops(self) -> EntityEdgeOperations | None:
+        return None
+
+    @property
+    def episodic_edge_ops(self) -> EpisodicEdgeOperations | None:
+        return None
+
+    @property
+    def community_edge_ops(self) -> CommunityEdgeOperations | None:
+        return None
+
+    @property
+    def has_episode_edge_ops(self) -> HasEpisodeEdgeOperations | None:
+        return None
+
+    @property
+    def next_episode_edge_ops(self) -> NextEpisodeEdgeOperations | None:
+        return None
+
+    @property
+    def search_ops(self) -> SearchOperations | None:
+        return None
+
+    @property
+    def graph_ops(self) -> GraphMaintenanceOperations | None:
+        return None
+
+
+class _SessionTransaction(Transaction):
+    """Fallback transaction that wraps a session — queries execute immediately."""
+
+    def __init__(self, session: GraphDriverSession):
+        self._session = session
+
+    async def run(self, query: str, **kwargs: Any) -> Any:
+        return await self._session.run(query, **kwargs)