graphiti-core 0.20.3__tar.gz → 0.21.0__tar.gz

{graphiti_core-0.20.3 → graphiti_core-0.21.0}/.github/workflows/claude-code-review.yml

@@ -29,6 +29,8 @@ jobs:
 
             Please review this pull request.
 
+            IMPORTANT: Your role is to critically review code. You must not provide POSITIVE feedback on code, this only adds noise to the review process.
+
             Note: The PR branch is already checked out in the current working directory.
 
             Focus on:
@@ -48,3 +50,4 @@ jobs:
 
           claude_args: |
             --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*), Bash(gh pr diff:*), Bash(gh pr view:*)"
+            --model claude-sonnet-4-5-20250929

graphiti_core-0.21.0/.github/workflows/daily_issue_maintenance.yml

@@ -0,0 +1,123 @@
+name: Daily Issue Maintenance
+on:
+  schedule:
+    - cron: "0 0 * * *" # Every day at midnight
+  workflow_dispatch: # Manual trigger option
+
+jobs:
+  find-legacy-duplicates:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch'
+    permissions:
+      contents: read
+      issues: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            REPO: ${{ github.repository }}
+
+            Find potential duplicate issues in the repository:
+
+            1. Use `gh issue list --state open --limit 1000 --json number,title,body,createdAt` to get all open issues
+            2. For each issue, search for potential duplicates using `gh search issues` with keywords from the title and body
+            3. Compare issues to identify true duplicates using these criteria:
+               - Same bug or error being reported
+               - Same feature request (even if worded differently)
+               - Same question being asked
+               - Issues describing the same root problem
+
+            For each duplicate found:
+            - Add a comment linking to the original issue
+            - Apply the "duplicate" label using `gh issue edit`
+            - Be polite and explain why it's a duplicate
+
+            Focus on finding true duplicates, not just similar issues.
+
+          claude_args: |
+            --allowedTools "Bash(gh issue:*),Bash(gh search:*)"
+            --model claude-sonnet-4-5-20250929
+
+  check-stale-issues:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'schedule'
+    permissions:
+      contents: read
+      issues: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            REPO: ${{ github.repository }}
+
+            Review stale issues and request confirmation:
+
+            1. Use `gh issue list --state open --limit 1000 --json number,title,updatedAt,comments` to get all open issues
+            2. Identify issues that are:
+               - Older than 60 days (based on updatedAt)
+               - Have no comments with "stale-check" label
+               - Are not labeled as "enhancement" or "documentation"
+            3. For each stale issue:
+               - Add a polite comment asking the issue originator if this is still relevant
+               - Apply a "stale-check" label to track that we've asked
+               - Use format: "@{author} Is this still an issue? Please confirm within 14 days or this issue will be closed."
+
+            Use:
+            - `gh issue view` to check issue details and labels
+            - `gh issue comment` to add comments
+            - `gh issue edit` to add the "stale-check" label
+
+          claude_args: |
+            --allowedTools "Bash(gh issue:*)"
+            --model claude-sonnet-4-5-20250929
+
+  close-unconfirmed-issues:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'schedule'
+    needs: check-stale-issues
+    permissions:
+      contents: read
+      issues: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            REPO: ${{ github.repository }}
+
+            Close unconfirmed stale issues:
+
+            1. Use `gh issue list --state open --label "stale-check" --limit 1000 --json number,title,comments,updatedAt` to get issues with stale-check label
+            2. For each issue, check if:
+               - The "stale-check" comment was added 14+ days ago
+               - There has been no response from the issue author or activity since the comment
+            3. For issues meeting the criteria:
+               - Add a polite closing comment
+               - Close the issue using `gh issue close`
+               - Use format: "Closing due to inactivity. Feel free to reopen if this is still relevant."
+
+            Use:
+            - `gh issue view` to check issue comments and activity
+            - `gh issue comment` to add closing comment
+            - `gh issue close` to close the issue
+
+          claude_args: |
+            --allowedTools "Bash(gh issue:*)"
+            --model claude-sonnet-4-5-20250929

graphiti_core-0.21.0/.github/workflows/issue-triage.yml

@@ -0,0 +1,141 @@
+name: Issue Triage and Deduplication
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      issues: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code for Issue Triage
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          allowed_non_write_users: "*"
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          prompt: |
+            You're an issue triage assistant for GitHub issues. Your task is to analyze the issue and select appropriate labels from the provided list.
+
+            IMPORTANT: Don't post any comments or messages to the issue. Your only action should be to apply labels. DO NOT check for duplicates - that's handled by a separate job.
+
+            Issue Information:
+            - REPO: ${{ github.repository }}
+            - ISSUE_NUMBER: ${{ github.event.issue.number }}
+
+            TASK OVERVIEW:
+
+            1. First, fetch the list of labels available in this repository by running: `gh label list`. Run exactly this command with nothing else.
+
+            2. Next, use gh commands to get context about the issue:
+               - Use `gh issue view ${{ github.event.issue.number }}` to retrieve the current issue's details
+               - Use `gh search issues` to find similar issues that might provide context for proper categorization
+               - You have access to these Bash commands:
+                 - Bash(gh label list:*) - to get available labels
+                 - Bash(gh issue view:*) - to view issue details
+                 - Bash(gh issue edit:*) - to apply labels to the issue
+                 - Bash(gh search:*) - to search for similar issues
+
+            3. Analyze the issue content, considering:
+               - The issue title and description
+               - The type of issue (bug report, feature request, question, etc.)
+               - Technical areas mentioned
+               - Database mentions (neo4j, falkordb, neptune, etc.)
+               - LLM providers mentioned (openai, anthropic, gemini, groq, etc.)
+               - Components affected (embeddings, search, prompts, server, mcp, etc.)
+
+            4. Select appropriate labels from the available labels list:
+               - Choose labels that accurately reflect the issue's nature
+               - Be specific but comprehensive
+               - Add database-specific labels if mentioned: neo4j, falkordb, neptune
+               - Add component labels if applicable
+               - DO NOT add priority labels (P1, P2, P3)
+               - DO NOT add duplicate label - that's handled by the deduplication job
+
+            5. Apply the selected labels:
+               - Use `gh issue edit ${{ github.event.issue.number }} --add-label "label1,label2,label3"` to apply your selected labels
+               - DO NOT post any comments explaining your decision
+               - DO NOT communicate directly with users
+               - If no labels are clearly applicable, do not apply any labels
+
+            IMPORTANT GUIDELINES:
+            - Be thorough in your analysis
+            - Only select labels from the provided list
+            - DO NOT post any comments to the issue
+            - Your ONLY action should be to apply labels using gh issue edit
+            - It's okay to not add any labels if none are clearly applicable
+            - DO NOT check for duplicates
+
+          claude_args: |
+            --allowedTools "Bash(gh label list:*),Bash(gh issue view:*),Bash(gh issue edit:*),Bash(gh search:*)"
+            --model claude-sonnet-4-5-20250929
+
+  deduplicate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    needs: triage
+    permissions:
+      contents: read
+      issues: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Check for duplicate issues
+        uses: anthropics/claude-code-action@v1
+        with:
+          allowed_non_write_users: "*"
+          prompt: |
+            Analyze this new issue and check if it's a duplicate of existing issues in the repository.
+
+            Issue: #${{ github.event.issue.number }}
+            Repository: ${{ github.repository }}
+
+            Your task:
+            1. Use mcp__github__get_issue to get details of the current issue (#${{ github.event.issue.number }})
+            2. Search for similar existing OPEN issues using mcp__github__search_issues with relevant keywords from the issue title and body
+            3. Compare the new issue with existing ones to identify potential duplicates
+
+            Criteria for duplicates:
+            - Same bug or error being reported
+            - Same feature request (even if worded differently)
+            - Same question being asked
+            - Issues describing the same root problem
+
+            If you find duplicates:
+            - Add a comment on the new issue linking to the original issue(s)
+            - Apply the "duplicate" label to the new issue
+            - Be polite and explain why it's a duplicate
+            - Suggest the user follow the original issue for updates
+
+            If it's NOT a duplicate:
+            - Don't add any comments
+            - Don't modify labels
+
+            Use these tools:
+            - mcp__github__get_issue: Get issue details
+            - mcp__github__search_issues: Search for similar issues (use state:open)
+            - mcp__github__list_issues: List recent issues if needed
+            - mcp__github__create_issue_comment: Add a comment if duplicate found
+            - mcp__github__update_issue: Add "duplicate" label
+
+            Be thorough but efficient. Focus on finding true duplicates, not just similar issues.
+
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_args: |
+            --allowedTools "mcp__github__get_issue,mcp__github__search_issues,mcp__github__list_issues,mcp__github__create_issue_comment,mcp__github__update_issue,mcp__github__get_issue_comments"
+            --model claude-sonnet-4-5-20250929

graphiti_core-0.21.0/AGENTS.md

@@ -0,0 +1,21 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+Graphiti's core library lives under `graphiti_core/`, split into domain modules such as `nodes.py`, `edges.py`, `models/`, and `search/` for retrieval pipelines. Service adapters and API glue reside in `server/graph_service/`, while the MCP integration lives in `mcp_server/`. Shared assets and collateral sit in `images/` and `examples/`. Tests cover the package via `tests/`, with configuration in `conftest.py`, `pytest.ini`, and Docker compose files for optional services. Tooling manifests live at the repo root, including `pyproject.toml`, `Makefile`, and deployment compose files.
+
+## Build, Test, and Development Commands
+- `uv sync --extra dev`: install the dev environment declared in `pyproject.toml`.
+- `make format`: run `ruff` to sort imports and apply the canonical formatter.
+- `make lint`: execute `ruff` plus `pyright` type checks against `graphiti_core`.
+- `make test`: run the full `pytest` suite (`uv run pytest`).
+- `uv run pytest tests/path/test_file.py`: target a specific module or test selection.
+- `docker-compose -f docker-compose.test.yml up`: provision local graph/search dependencies for integration flows.
+
+## Coding Style & Naming Conventions
+Python code uses 4-space indentation, 100-character lines, and prefers single quotes as configured in `pyproject.toml`. Modules, files, and functions stay snake_case; Pydantic models in `graphiti_core/models` use PascalCase with explicit type hints. Keep side-effectful code inside drivers or adapters (`graphiti_core/driver`, `graphiti_core/utils`) and rely on pure helpers elsewhere. Run `make format` before committing to normalize imports and docstring formatting.
+
+## Testing Guidelines
+Author tests alongside features under `tests/`, naming files `test_<feature>.py` and functions `test_<behavior>`. Use `@pytest.mark.integration` for database-reliant scenarios so CI can gate them. Reproduce regressions with a failing test first and validate fixes via `uv run pytest -k "pattern"`. Start required backing services through `docker-compose.test.yml` when running integration suites locally.
+
+## Commit & Pull Request Guidelines
+Commits use an imperative, present-tense summary (for example, `add async cache invalidation`) optionally suffixed with the PR number as seen in history (`(#927)`). Squash fixups and keep unrelated changes isolated. Pull requests should include: a concise description, linked tracking issue, notes about schema or API impacts, and screenshots or logs when behavior changes. Confirm `make lint` and `make test` pass locally, and update docs or examples when public interfaces shift.

{graphiti_core-0.20.3 → graphiti_core-0.21.0}/Makefile

@@ -26,7 +26,7 @@ lint:
 
 # Run tests
 test:
-	$(PYTEST)
+	DISABLE_FALKORDB=1 DISABLE_KUZU=1 DISABLE_NEPTUNE=1 $(PYTEST) -m "not integration"
 
 # Run format, lint, and test
-check: format lint test
+check: format lint test

{graphiti_core-0.20.3 → graphiti_core-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphiti-core
-Version: 0.20.3
+Version: 0.21.0
 Summary: A temporal graph building library
 Project-URL: Homepage, https://help.getzep.com/graphiti/graphiti/overview
 Project-URL: Repository, https://github.com/getzep/graphiti
@@ -20,6 +20,7 @@ Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.49.0; extra == 'anthropic'
 Provides-Extra: dev
 Requires-Dist: anthropic>=0.49.0; extra == 'dev'
+Requires-Dist: boto3>=1.39.16; extra == 'dev'
 Requires-Dist: diskcache-stubs>=5.6.3.6.20240818; extra == 'dev'
 Requires-Dist: falkordb<2.0.0,>=1.1.2; extra == 'dev'
 Requires-Dist: google-genai>=1.8.0; extra == 'dev'
@@ -28,9 +29,11 @@ Requires-Dist: ipykernel>=6.29.5; extra == 'dev'
 Requires-Dist: jupyterlab>=4.2.4; extra == 'dev'
 Requires-Dist: kuzu>=0.11.2; extra == 'dev'
 Requires-Dist: langchain-anthropic>=0.2.4; extra == 'dev'
+Requires-Dist: langchain-aws>=0.2.29; extra == 'dev'
 Requires-Dist: langchain-openai>=0.2.6; extra == 'dev'
 Requires-Dist: langgraph>=0.2.15; extra == 'dev'
 Requires-Dist: langsmith>=0.1.108; extra == 'dev'
+Requires-Dist: opensearch-py>=3.0.0; extra == 'dev'
 Requires-Dist: pyright>=1.1.404; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.6.1; extra == 'dev'
@@ -47,6 +50,9 @@ Provides-Extra: groq
 Requires-Dist: groq>=0.2.0; extra == 'groq'
 Provides-Extra: kuzu
 Requires-Dist: kuzu>=0.11.2; extra == 'kuzu'
+Provides-Extra: neo4j-opensearch
+Requires-Dist: boto3>=1.39.16; extra == 'neo4j-opensearch'
+Requires-Dist: opensearch-py>=3.0.0; extra == 'neo4j-opensearch'
 Provides-Extra: neptune
 Requires-Dist: boto3>=1.39.16; extra == 'neptune'
 Requires-Dist: langchain-aws>=0.2.29; extra == 'neptune'

{graphiti_core-0.20.3 → graphiti_core-0.21.0}/docker-compose.test.yml

@@ -25,7 +25,7 @@ services:
       - PORT=8000
 
   neo4j:
-    image: neo4j:5.22.0
+    image: neo4j:5.26.2
     ports:
       - "7474:7474"
       - "${NEO4J_PORT}:${NEO4J_PORT}"

{graphiti_core-0.20.3 → graphiti_core-0.21.0}/graphiti_core/driver/driver.py

@@ -16,13 +16,25 @@ limitations under the License.
 
 import copy
 import logging
+import os
 from abc import ABC, abstractmethod
 from collections.abc import Coroutine
 from enum import Enum
 from typing import Any
 
+from dotenv import load_dotenv
+
 logger = logging.getLogger(__name__)
 
+DEFAULT_SIZE = 10
+
+load_dotenv()
+
+ENTITY_INDEX_NAME = os.environ.get('ENTITY_INDEX_NAME', 'entities')
+EPISODE_INDEX_NAME = os.environ.get('EPISODE_INDEX_NAME', 'episodes')
+COMMUNITY_INDEX_NAME = os.environ.get('COMMUNITY_INDEX_NAME', 'communities')
+ENTITY_EDGE_INDEX_NAME = os.environ.get('ENTITY_EDGE_INDEX_NAME', 'entity_edges')
+
 
 class GraphProvider(Enum):
     NEO4J = 'neo4j'
@@ -61,6 +73,7 @@ class GraphDriver(ABC):
         ''  # Neo4j (default) syntax does not require a prefix for fulltext queries
     )
     _database: str
+    aoss_client: Any  # type: ignore
 
     @abstractmethod
     def execute_query(self, cypher_query_: str, **kwargs: Any) -> Coroutine:
@@ -87,3 +100,18 @@ class GraphDriver(ABC):
         cloned._database = database
 
         return cloned
+
+    def build_fulltext_query(
+        self, query: str, group_ids: list[str] | None = None, max_query_length: int = 128
+    ) -> str:
+        """
+        Specific fulltext query builder for database providers.
+        Only implemented by providers that need custom fulltext query building.
+        """
+        raise NotImplementedError(f'build_fulltext_query not implemented for {self.provider}')
+
+    async def save_to_aoss(self, name: str, data: list[dict]) -> int:
+        return 0
+
+    async def clear_aoss_indices(self):
+        return 1

{graphiti_core-0.20.3 → graphiti_core-0.21.0}/graphiti_core/driver/falkordb_driver.py

@@ -36,6 +36,42 @@ from graphiti_core.utils.datetime_utils import convert_datetimes_to_strings
 
 logger = logging.getLogger(__name__)
 
+STOPWORDS = [
+    'a',
+    'is',
+    'the',
+    'an',
+    'and',
+    'are',
+    'as',
+    'at',
+    'be',
+    'but',
+    'by',
+    'for',
+    'if',
+    'in',
+    'into',
+    'it',
+    'no',
+    'not',
+    'of',
+    'on',
+    'or',
+    'such',
+    'that',
+    'their',
+    'then',
+    'there',
+    'these',
+    'they',
+    'this',
+    'to',
+    'was',
+    'will',
+    'with',
+]
+
 
 class FalkorDriverSession(GraphDriverSession):
     provider = GraphProvider.FALKORDB
@@ -74,6 +110,7 @@ class FalkorDriverSession(GraphDriverSession):
 
 class FalkorDriver(GraphDriver):
     provider = GraphProvider.FALKORDB
+    aoss_client: None = None
 
     def __init__(
         self,
@@ -166,3 +203,78 @@ class FalkorDriver(GraphDriver):
         cloned = FalkorDriver(falkor_db=self.client, database=database)
 
         return cloned
+
+    def sanitize(self, query: str) -> str:
+        """
+        Replace FalkorDB special characters with whitespace.
+        Based on FalkorDB tokenization rules: ,.<>{}[]"':;!@#$%^&*()-+=~
+        """
+        # FalkorDB separator characters that break text into tokens
+        separator_map = str.maketrans(
+            {
+                ',': ' ',
+                '.': ' ',
+                '<': ' ',
+                '>': ' ',
+                '{': ' ',
+                '}': ' ',
+                '[': ' ',
+                ']': ' ',
+                '"': ' ',
+                "'": ' ',
+                ':': ' ',
+                ';': ' ',
+                '!': ' ',
+                '@': ' ',
+                '#': ' ',
+                '$': ' ',
+                '%': ' ',
+                '^': ' ',
+                '&': ' ',
+                '*': ' ',
+                '(': ' ',
+                ')': ' ',
+                '-': ' ',
+                '+': ' ',
+                '=': ' ',
+                '~': ' ',
+                '?': ' ',
+            }
+        )
+        sanitized = query.translate(separator_map)
+        # Clean up multiple spaces
+        sanitized = ' '.join(sanitized.split())
+        return sanitized
+
+    def build_fulltext_query(
+        self, query: str, group_ids: list[str] | None = None, max_query_length: int = 128
+    ) -> str:
+        """
+        Build a fulltext query string for FalkorDB using RedisSearch syntax.
+        FalkorDB uses RedisSearch-like syntax where:
+        - Field queries use @ prefix: @field:value
+        - Multiple values for same field: (@field:value1|value2)
+        - Text search doesn't need @ prefix for content fields
+        - AND is implicit with space: (@group_id:value) (text)
+        - OR uses pipe within parentheses: (@group_id:value1|value2)
+        """
+        if group_ids is None or len(group_ids) == 0:
+            group_filter = ''
+        else:
+            group_values = '|'.join(group_ids)
+            group_filter = f'(@group_id:{group_values})'
+
+        sanitized_query = self.sanitize(query)
+
+        # Remove stopwords from the sanitized query
+        query_words = sanitized_query.split()
+        filtered_words = [word for word in query_words if word.lower() not in STOPWORDS]
+        sanitized_query = ' | '.join(filtered_words)
+
+        # If the query is too long return no query
+        if len(sanitized_query.split(' ')) + len(group_ids or '') >= max_query_length:
+            return ''
+
+        full_query = group_filter + ' (' + sanitized_query + ')'
+
+        return full_query

{graphiti_core-0.20.3 → graphiti_core-0.21.0}/graphiti_core/driver/kuzu_driver.py

@@ -92,6 +92,7 @@ SCHEMA_QUERIES = """
 
 class KuzuDriver(GraphDriver):
     provider: GraphProvider = GraphProvider.KUZU
+    aoss_client: None = None
 
     def __init__(
         self,

{graphiti_core-0.20.3 → graphiti_core-0.21.0}/graphiti_core/driver/neo4j_driver.py

@@ -29,7 +29,13 @@ logger = logging.getLogger(__name__)
 class Neo4jDriver(GraphDriver):
     provider = GraphProvider.NEO4J
 
-    def __init__(self, uri: str, user: str | None, password: str | None, database: str = 'neo4j'):
+    def __init__(
+        self,
+        uri: str,
+        user: str | None,
+        password: str | None,
+        database: str = 'neo4j',
+    ):
         super().__init__()
         self.client = AsyncGraphDatabase.driver(
             uri=uri,
@@ -37,6 +43,8 @@ class Neo4jDriver(GraphDriver):
         )
         self._database = database
 
+        self.aoss_client = None
+
     async def execute_query(self, cypher_query_: LiteralString, **kwargs: Any) -> EagerResult:
         # Check if database_ is provided in kwargs.
         # If not populated, set the value to retain backwards compatibility
@@ -60,7 +68,7 @@ class Neo4jDriver(GraphDriver):
     async def close(self) -> None:
         return await self.client.close()
 
-    def delete_all_indexes(self) -> Coroutine[Any, Any, EagerResult]:
+    def delete_all_indexes(self) -> Coroutine:
         return self.client.execute_query(
             'CALL db.indexes() YIELD name DROP INDEX name',
         )

{graphiti_core-0.20.3 → graphiti_core-0.21.0}/graphiti_core/driver/neptune_driver.py

@@ -257,15 +257,13 @@ class NeptuneDriver(GraphDriver):
             if name.lower() == index['index_name']:
                 to_index = []
                 for d in data:
-                    item = {'_index': name}
+                    item = {'_index': name, '_id': d['uuid']}
                     for p in index['body']['mappings']['properties']:
-                        item[p] = d[p]
+                        if p in d:
+                            item[p] = d[p]
                     to_index.append(item)
                 success, failed = helpers.bulk(self.aoss_client, to_index, stats_only=True)
-                if failed > 0:
-                    return success
-                else:
-                    return 0
+                return success
 
         return 0