graphiti-core 0.8.1__tar.gz → 0.8.3__tar.gz

{graphiti_core-0.8.1 → graphiti_core-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: graphiti-core
-Version: 0.8.1
+Version: 0.8.3
 Summary: A temporal graph building library
 License: Apache-2.0
 Author: Paul Paliychuk
@@ -11,6 +11,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: anthropic (>=0.49.0,<0.50.0)
 Requires-Dist: diskcache (>=5.6.3,<6.0.0)
 Requires-Dist: neo4j (>=5.23.0,<6.0.0)
 Requires-Dist: numpy (>=1.0.0)
@@ -29,7 +30,7 @@ Description-Content-Type: text/markdown
 <h1 align="center">
 Graphiti
 </h1>
-<h2 align="center"> Temporal Knowledge Graphs for Agentic Applications</h2>
+<h2 align="center"> Build Real-Time Knowledge Graphs for AI Agents</h2>
 <br />
 
 [![Discord](https://dcbadge.vercel.app/api/server/W8Kw6bsgXQ?style=flat)](https://discord.com/invite/W8Kw6bsgXQ)
@@ -41,9 +42,13 @@ Graphiti
 :star: _Help us reach more developers and grow the Graphiti community. Star this repo!_
 <br />
 
-Graphiti builds dynamic, temporally aware Knowledge Graphs that represent complex, evolving relationships between
-entities over time. Graphiti ingests both unstructured and structured data, and the resulting graph may be queried using
-a fusion of time, full-text, semantic, and graph algorithm approaches, effectively serving as a powerful memory layer for AI applications.
+Graphiti is a framework for building and querying temporally-aware knowledge graphs, specifically tailored for AI agents operating in dynamic environments. Unlike traditional retrieval-augmented generation (RAG) methods, Graphiti continuously integrates user interactions, structured and unstructured enterprise data, and external information into a coherent, queryable graph. The framework supports incremental data updates, efficient retrieval, and precise historical queries without requiring complete graph recomputation, making it suitable for developing interactive, context-aware AI applications.
+
+Use Graphiti to:
+
+- Integrate and maintain dynamic user interactions and business data.
+- Facilitate state-based reasoning and task automation for agents.
+- Query complex, evolving data with semantic, keyword, and graph-based search methods.
 
 <br />
 
@@ -53,23 +58,14 @@ a fusion of time, full-text, semantic, and graph algorithm approaches, effective
 
 <br />
 
-Graphiti helps you create and query Knowledge Graphs that evolve over time. A knowledge graph is a network of
-interconnected facts, such as _“Kendra loves Adidas shoes.”_ Each fact is a “triplet” represented by two entities, or
+A knowledge graph is a network of interconnected facts, such as _“Kendra loves Adidas shoes.”_ Each fact is a “triplet” represented by two entities, or
 nodes (_”Kendra”_, _“Adidas shoes”_), and their relationship, or edge (_”loves”_). Knowledge Graphs have been explored
 extensively for information retrieval. What makes Graphiti unique is its ability to autonomously build a knowledge graph
 while handling changing relationships and maintaining historical context.
 
-With Graphiti, you can build LLM applications such as:
-
-- Assistants that learn from user interactions, fusing personal knowledge with dynamic data from business systems like
-  CRMs and billing platforms through robust conversation history management.
-- Agents that autonomously execute complex tasks, reasoning with state changes from multiple dynamic sources through persistent memory.
-
-Graphiti supports a wide range of applications in sales, customer service, health, finance, and more, enabling long-term recall and state-based reasoning for both assistants and agents.
-
 ## Graphiti and Zep Memory
 
-Graphiti powers the core of [Zep's memory layer](https://www.getzep.com) for LLM-powered Assistants and Agents.
+Graphiti powers the core of [Zep's memory layer](https://www.getzep.com) for AI Agents.
 
 Using Graphiti, we've demonstrated Zep is
 the [State of the Art in Agent Memory](https://blog.getzep.com/state-of-the-art-agent-memory/).
@@ -84,28 +80,35 @@ We're excited to open-source Graphiti, believing its potential reaches far beyon
 
 ## Why Graphiti?
 
-We were intrigued by Microsoft's GraphRAG, which expanded on RAG (Retrieval-Augmented Generation) text chunking by using a graph to better model a
-document corpus and making this representation available via semantic and graph search techniques. However, GraphRAG did
-not address our core problem: It's primarily designed for static documents and doesn't inherently handle temporal
-aspects of data.
-
-Graphiti is designed from the ground up to handle constantly changing information, hybrid semantic and graph search, and
-scale:
+Traditional RAG approaches often rely on batch processing and static data summarization, making them inefficient for frequently changing data. Graphiti addresses these challenges by providing:
 
-- **Temporal Awareness:** Tracks changes in facts and relationships over time, enabling point-in-time queries. Graph
-  edges include temporal metadata to record relationship lifecycles, creating a comprehensive context window extension.
-- **Episodic Processing:** Ingests data as discrete episodes, maintaining data provenance and allowing incremental
-  entity and relationship extraction, ideal for chat state management.
-- **Hybrid Search:** Combines semantic and BM25 full-text search, with the ability to rerank results by distance from a
-  central node e.g. "Kendra".
-- **Scalable:** Designed for processing large datasets, with parallelization of LLM calls for bulk processing while
-  preserving the chronology of events and enabling efficient knowledge retrieval.
-- **Supports Varied Sources:** Can ingest both unstructured text and structured JSON data.
+- **Real-Time Incremental Updates:** Immediate integration of new data episodes without batch recomputation.
+- **Bi-Temporal Data Model:** Explicit tracking of event occurrence and ingestion times, allowing accurate point-in-time queries.
+- **Efficient Hybrid Retrieval:** Combines semantic embeddings, keyword (BM25), and graph traversal to achieve low-latency queries without reliance on LLM summarization.
+- **Custom Entity Definitions:** Flexible ontology creation and support for developer-defined entities through straightforward Pydantic models.
+- **Scalability:** Efficiently manages large datasets with parallel processing, suitable for enterprise environments.
 
 <p align="center">
     <img src="/images/graphiti-intro-slides-stock-2.gif" alt="Graphiti structured + unstructured demo" width="700px">   
 </p>
 
+## Graphiti vs. GraphRAG
+
+| Aspect                     | GraphRAG                              | Graphiti                                         |
+| -------------------------- | ------------------------------------- | ------------------------------------------------ |
+| **Primary Use**            | Static document summarization         | Dynamic data management                          |
+| **Data Handling**          | Batch-oriented processing             | Continuous, incremental updates                  |
+| **Knowledge Structure**    | Entity clusters & community summaries | Episodic data, semantic entities, communities    |
+| **Retrieval Method**       | Sequential LLM summarization          | Hybrid semantic, keyword, and graph-based search |
+| **Adaptability**           | Low                                   | High                                             |
+| **Temporal Handling**      | Basic timestamp tracking              | Explicit bi-temporal tracking                    |
+| **Contradiction Handling** | LLM-driven summarization judgments    | Temporal edge invalidation                       |
+| **Query Latency**          | Seconds to tens of seconds            | Typically sub-second latency                     |
+| **Custom Entity Types**    | No                                    | Yes, customizable                                |
+| **Scalability**            | Moderate                              | High, optimized for large datasets               |
+
+Graphiti is specifically designed to address the challenges of dynamic and frequently updated datasets, making it particularly suitable for applications requiring real-time interaction and precise historical queries.
+
 ## Installation
 
 Requirements:
@@ -207,6 +210,22 @@ The `server` directory contains an API service for interacting with the Graphiti
 
 Please see the [server README](./server/README.md) for more information.
 
+## MCP Server
+
+The `mcp_server` directory contains a Model Context Protocol (MCP) server implementation for Graphiti. This server allows AI assistants to interact with Graphiti's knowledge graph capabilities through the MCP protocol.
+
+Key features of the MCP server include:
+
+- Episode management (add, retrieve, delete)
+- Entity management and relationship handling
+- Semantic and hybrid search capabilities
+- Group management for organizing related data
+- Graph maintenance operations
+
+The MCP server can be deployed using Docker with Neo4j, making it easy to integrate Graphiti into your AI assistant workflows.
+
+For detailed setup instructions and usage examples, see the [MCP server README](./mcp_server/README.md).
+
 ## Optional Environment Variables
 
 In addition to the Neo4j and OpenAi-compatible credentials, Graphiti also has a few optional environment variables.
@@ -280,6 +299,7 @@ Graphiti is under active development. We aim to maintain API stability while wor
   - Allow developers to provide their own defined node and edge classes when ingesting episodes
   - Enable more flexible knowledge representation tailored to specific use cases
 - [x] Enhancing retrieval capabilities with more robust and configurable options
+- [x] Graphiti MCP Server
 - [ ] Expanding test coverage to ensure reliability and catch edge cases
 
 ## Contributing

{graphiti_core-0.8.1 → graphiti_core-0.8.3}/README.md

@@ -7,7 +7,7 @@
 <h1 align="center">
 Graphiti
 </h1>
-<h2 align="center"> Temporal Knowledge Graphs for Agentic Applications</h2>
+<h2 align="center"> Build Real-Time Knowledge Graphs for AI Agents</h2>
 <br />
 
 [![Discord](https://dcbadge.vercel.app/api/server/W8Kw6bsgXQ?style=flat)](https://discord.com/invite/W8Kw6bsgXQ)
@@ -19,9 +19,13 @@ Graphiti
 :star: _Help us reach more developers and grow the Graphiti community. Star this repo!_
 <br />
 
-Graphiti builds dynamic, temporally aware Knowledge Graphs that represent complex, evolving relationships between
-entities over time. Graphiti ingests both unstructured and structured data, and the resulting graph may be queried using
-a fusion of time, full-text, semantic, and graph algorithm approaches, effectively serving as a powerful memory layer for AI applications.
+Graphiti is a framework for building and querying temporally-aware knowledge graphs, specifically tailored for AI agents operating in dynamic environments. Unlike traditional retrieval-augmented generation (RAG) methods, Graphiti continuously integrates user interactions, structured and unstructured enterprise data, and external information into a coherent, queryable graph. The framework supports incremental data updates, efficient retrieval, and precise historical queries without requiring complete graph recomputation, making it suitable for developing interactive, context-aware AI applications.
+
+Use Graphiti to:
+
+- Integrate and maintain dynamic user interactions and business data.
+- Facilitate state-based reasoning and task automation for agents.
+- Query complex, evolving data with semantic, keyword, and graph-based search methods.
 
 <br />
 
@@ -31,23 +35,14 @@ a fusion of time, full-text, semantic, and graph algorithm approaches, effective
 
 <br />
 
-Graphiti helps you create and query Knowledge Graphs that evolve over time. A knowledge graph is a network of
-interconnected facts, such as _“Kendra loves Adidas shoes.”_ Each fact is a “triplet” represented by two entities, or
+A knowledge graph is a network of interconnected facts, such as _“Kendra loves Adidas shoes.”_ Each fact is a “triplet” represented by two entities, or
 nodes (_”Kendra”_, _“Adidas shoes”_), and their relationship, or edge (_”loves”_). Knowledge Graphs have been explored
 extensively for information retrieval. What makes Graphiti unique is its ability to autonomously build a knowledge graph
 while handling changing relationships and maintaining historical context.
 
-With Graphiti, you can build LLM applications such as:
-
-- Assistants that learn from user interactions, fusing personal knowledge with dynamic data from business systems like
-  CRMs and billing platforms through robust conversation history management.
-- Agents that autonomously execute complex tasks, reasoning with state changes from multiple dynamic sources through persistent memory.
-
-Graphiti supports a wide range of applications in sales, customer service, health, finance, and more, enabling long-term recall and state-based reasoning for both assistants and agents.
-
 ## Graphiti and Zep Memory
 
-Graphiti powers the core of [Zep's memory layer](https://www.getzep.com) for LLM-powered Assistants and Agents.
+Graphiti powers the core of [Zep's memory layer](https://www.getzep.com) for AI Agents.
 
 Using Graphiti, we've demonstrated Zep is
 the [State of the Art in Agent Memory](https://blog.getzep.com/state-of-the-art-agent-memory/).
@@ -62,28 +57,35 @@ We're excited to open-source Graphiti, believing its potential reaches far beyon
 
 ## Why Graphiti?
 
-We were intrigued by Microsoft's GraphRAG, which expanded on RAG (Retrieval-Augmented Generation) text chunking by using a graph to better model a
-document corpus and making this representation available via semantic and graph search techniques. However, GraphRAG did
-not address our core problem: It's primarily designed for static documents and doesn't inherently handle temporal
-aspects of data.
-
-Graphiti is designed from the ground up to handle constantly changing information, hybrid semantic and graph search, and
-scale:
+Traditional RAG approaches often rely on batch processing and static data summarization, making them inefficient for frequently changing data. Graphiti addresses these challenges by providing:
 
-- **Temporal Awareness:** Tracks changes in facts and relationships over time, enabling point-in-time queries. Graph
-  edges include temporal metadata to record relationship lifecycles, creating a comprehensive context window extension.
-- **Episodic Processing:** Ingests data as discrete episodes, maintaining data provenance and allowing incremental
-  entity and relationship extraction, ideal for chat state management.
-- **Hybrid Search:** Combines semantic and BM25 full-text search, with the ability to rerank results by distance from a
-  central node e.g. "Kendra".
-- **Scalable:** Designed for processing large datasets, with parallelization of LLM calls for bulk processing while
-  preserving the chronology of events and enabling efficient knowledge retrieval.
-- **Supports Varied Sources:** Can ingest both unstructured text and structured JSON data.
+- **Real-Time Incremental Updates:** Immediate integration of new data episodes without batch recomputation.
+- **Bi-Temporal Data Model:** Explicit tracking of event occurrence and ingestion times, allowing accurate point-in-time queries.
+- **Efficient Hybrid Retrieval:** Combines semantic embeddings, keyword (BM25), and graph traversal to achieve low-latency queries without reliance on LLM summarization.
+- **Custom Entity Definitions:** Flexible ontology creation and support for developer-defined entities through straightforward Pydantic models.
+- **Scalability:** Efficiently manages large datasets with parallel processing, suitable for enterprise environments.
 
 <p align="center">
     <img src="/images/graphiti-intro-slides-stock-2.gif" alt="Graphiti structured + unstructured demo" width="700px">   
 </p>
 
+## Graphiti vs. GraphRAG
+
+| Aspect                     | GraphRAG                              | Graphiti                                         |
+| -------------------------- | ------------------------------------- | ------------------------------------------------ |
+| **Primary Use**            | Static document summarization         | Dynamic data management                          |
+| **Data Handling**          | Batch-oriented processing             | Continuous, incremental updates                  |
+| **Knowledge Structure**    | Entity clusters & community summaries | Episodic data, semantic entities, communities    |
+| **Retrieval Method**       | Sequential LLM summarization          | Hybrid semantic, keyword, and graph-based search |
+| **Adaptability**           | Low                                   | High                                             |
+| **Temporal Handling**      | Basic timestamp tracking              | Explicit bi-temporal tracking                    |
+| **Contradiction Handling** | LLM-driven summarization judgments    | Temporal edge invalidation                       |
+| **Query Latency**          | Seconds to tens of seconds            | Typically sub-second latency                     |
+| **Custom Entity Types**    | No                                    | Yes, customizable                                |
+| **Scalability**            | Moderate                              | High, optimized for large datasets               |
+
+Graphiti is specifically designed to address the challenges of dynamic and frequently updated datasets, making it particularly suitable for applications requiring real-time interaction and precise historical queries.
+
 ## Installation
 
 Requirements:
@@ -185,6 +187,22 @@ The `server` directory contains an API service for interacting with the Graphiti
 
 Please see the [server README](./server/README.md) for more information.
 
+## MCP Server
+
+The `mcp_server` directory contains a Model Context Protocol (MCP) server implementation for Graphiti. This server allows AI assistants to interact with Graphiti's knowledge graph capabilities through the MCP protocol.
+
+Key features of the MCP server include:
+
+- Episode management (add, retrieve, delete)
+- Entity management and relationship handling
+- Semantic and hybrid search capabilities
+- Group management for organizing related data
+- Graph maintenance operations
+
+The MCP server can be deployed using Docker with Neo4j, making it easy to integrate Graphiti into your AI assistant workflows.
+
+For detailed setup instructions and usage examples, see the [MCP server README](./mcp_server/README.md).
+
 ## Optional Environment Variables
 
 In addition to the Neo4j and OpenAi-compatible credentials, Graphiti also has a few optional environment variables.
@@ -258,6 +276,7 @@ Graphiti is under active development. We aim to maintain API stability while wor
   - Allow developers to provide their own defined node and edge classes when ingesting episodes
   - Enable more flexible knowledge representation tailored to specific use cases
 - [x] Enhancing retrieval capabilities with more robust and configurable options
+- [x] Graphiti MCP Server
 - [ ] Expanding test coverage to ensure reliability and catch edge cases
 
 ## Contributing

{graphiti_core-0.8.1 → graphiti_core-0.8.3}/graphiti_core/llm_client/anthropic_client.py

@@ -29,7 +29,7 @@ from .errors import RateLimitError
 
 logger = logging.getLogger(__name__)
 
-DEFAULT_MODEL = 'claude-3-5-sonnet-20240620'
+DEFAULT_MODEL = 'claude-3-7-sonnet-latest'
 DEFAULT_MAX_TOKENS = 8192
 
 
@@ -58,11 +58,14 @@ class AnthropicClient(LLMClient):
             {'role': 'assistant', 'content': '{'}
         ]
 
+        # Ensure max_tokens is not greater than config.max_tokens or DEFAULT_MAX_TOKENS
+        max_tokens = min(max_tokens, self.config.max_tokens, DEFAULT_MAX_TOKENS)
+
         try:
             result = await self.client.messages.create(
                 system='Only include JSON in the response. Do not include any additional text or explanation of the content.\n'
                 + system_message.content,
-                max_tokens=max_tokens or self.max_tokens,
+                max_tokens=max_tokens,
                 temperature=self.temperature,
                 messages=user_messages,  # type: ignore
                 model=self.model or DEFAULT_MODEL,

{graphiti_core-0.8.1 → graphiti_core-0.8.3}/graphiti_core/llm_client/client.py

@@ -54,7 +54,11 @@ class LLMClient(ABC):
         self.temperature = config.temperature
         self.max_tokens = config.max_tokens
         self.cache_enabled = cache
-        self.cache_dir = Cache(DEFAULT_CACHE_DIR)  # Create a cache directory
+        self.cache_dir = None
+
+        # Only create the cache directory if caching is enabled
+        if self.cache_enabled:
+            self.cache_dir = Cache(DEFAULT_CACHE_DIR)
 
     def _clean_input(self, input: str) -> str:
         """Clean input string of invalid unicode and control characters.
@@ -129,7 +133,7 @@ class LLMClient(ABC):
                 f'\n\nRespond with a JSON object in the following format:\n\n{serialized_model}'
             )
 
-        if self.cache_enabled:
+        if self.cache_enabled and self.cache_dir is not None:
             cache_key = self._get_cache_key(messages)
 
             cached_response = self.cache_dir.get(cache_key)
@@ -142,7 +146,8 @@ class LLMClient(ABC):
 
         response = await self._generate_response_with_retry(messages, response_model, max_tokens)
 
-        if self.cache_enabled:
+        if self.cache_enabled and self.cache_dir is not None:
+            cache_key = self._get_cache_key(messages)
             self.cache_dir.set(cache_key, response)
 
         return response

{graphiti_core-0.8.1 → graphiti_core-0.8.3}/graphiti_core/models/nodes/node_db_queries.py

@@ -30,10 +30,10 @@ EPISODIC_NODE_SAVE_BULK = """
 """
 
 ENTITY_NODE_SAVE = """
-        MERGE (n:Entity {uuid: $uuid})
+        MERGE (n:Entity {uuid: $entity_data.uuid})
         SET n:$($labels)
         SET n = $entity_data
-        WITH n CALL db.create.setNodeVectorProperty(n, "name_embedding", $name_embedding)
+        WITH n CALL db.create.setNodeVectorProperty(n, "name_embedding", $entity_data.name_embedding)
         RETURN n.uuid AS uuid"""
 
 ENTITY_NODE_SAVE_BULK = """

{graphiti_core-0.8.1 → graphiti_core-0.8.3}/graphiti_core/prompts/summarize_nodes.py

@@ -85,8 +85,10 @@ def summarize_context(context: dict[str, Any]) -> list[Message]:
         provided ENTITY. Summaries must be under 500 words.
         
         In addition, extract any values for the provided entity properties based on their descriptions.
-        If the value of the entity property cannot be found in the current context, set the value of the property to None.
-        Do not hallucinate entity property values if they cannot be found in the current context.
+        If the value of the entity property cannot be found in the current context, set the value of the property to the Python value None.
+        
+        Guidelines:
+        1. Do not hallucinate entity property values if they cannot be found in the current context.
         
         <ENTITY>
         {context['node_name']}

{graphiti_core-0.8.1 → graphiti_core-0.8.3}/graphiti_core/utils/maintenance/node_operations.py

@@ -364,7 +364,11 @@ async def resolve_extracted_node(
     )
 
     extracted_node.summary = node_attributes_response.get('summary', '')
-    extracted_node.attributes.update(node_attributes_response)
+    node_attributes = {
+        key: value if value != 'None' else None for key, value in node_attributes_response.items()
+    }
+
+    extracted_node.attributes.update(node_attributes)
 
     is_duplicate: bool = llm_response.get('is_duplicate', False)
     uuid: str | None = llm_response.get('uuid', None)
@@ -386,11 +390,12 @@ async def resolve_extracted_node(
             node.name = name
             node.summary = summary_response.get('summary', '')
 
-            new_attributes = existing_node.attributes
+            new_attributes = extracted_node.attributes
             existing_attributes = existing_node.attributes
             for attribute_name, attribute_value in existing_attributes.items():
                 if new_attributes.get(attribute_name) is None:
                     new_attributes[attribute_name] = attribute_value
+            node.attributes = new_attributes
 
             uuid_map[extracted_node.uuid] = existing_node.uuid
 

{graphiti_core-0.8.1 → graphiti_core-0.8.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "graphiti-core"
-version = "0.8.1"
+version = "0.8.3"
 description = "A temporal graph building library"
 authors = [
     "Paul Paliychuk <paul@getzep.com>",
@@ -21,18 +21,12 @@ openai = "^1.53.0"
 tenacity = "9.0.0"
 numpy = ">=1.0.0"
 python-dotenv = "^1.0.1"
-
-[tool.poetry.dev-dependencies]
-pytest = "^8.3.3"
-pytest-asyncio = "^0.24.0"
-pytest-xdist = "^3.6.1"
-ruff = "^0.7.1"
+anthropic = "~0.49.0"
 
 [tool.poetry.group.dev.dependencies]
-pydantic = "^2.8.2"
 mypy = "^1.11.1"
 groq = ">=0.9,<0.12"
-anthropic = ">=0.34.1,<0.36.0"
+anthropic = "~0.49.0"
 ipykernel = "^6.29.5"
 jupyterlab = "^4.2.4"
 diskcache-stubs = "^5.6.3.6.20240818"
@@ -43,6 +37,10 @@ langchain-openai = "^0.2.6"
 sentence-transformers = "^3.2.1"
 transformers = "^4.45.2"
 voyageai = "^0.2.3"
+pytest = "^8.3.3"
+pytest-asyncio = "^0.24.0"
+pytest-xdist = "^3.6.1"
+ruff = "^0.7.1"
 
 [build-system]
 requires = ["poetry-core"]