deepsemantics-core 0.444
A temporal graph building library
Requires Python: <4,>=3.10

<p align="center">
  <a href="https://deepsemantics.io/">
    <img src="https://github.com/user-attachments/assets/119c5682-9654-4257-8922-56b7cb8ffd73" width="150" alt="DeepSemantics Logo">
  </a>
</p>

<h1 align="center">
DeepSemantics
</h1>
<h2 align="center"> Build Real-Time Knowledge Graphs for AI Agents</h2>
<div align="center">

[![Lint](https://github.com/gabelogan195/deepsemantics/actions/workflows/lint.yml/badge.svg?style=flat)](https://github.com/gabelogan195/deepsemantics/actions/workflows/lint.yml)
[![Unit Tests](https://github.com/gabelogan195/deepsemantics/actions/workflows/unit_tests.yml/badge.svg)](https://github.com/gabelogan195/deepsemantics/actions/workflows/unit_tests.yml)
[![MyPy Check](https://github.com/gabelogan195/deepsemantics/actions/workflows/typecheck.yml/badge.svg)](https://github.com/gabelogan195/deepsemantics/actions/workflows/typecheck.yml)

![GitHub Repo stars](https://img.shields.io/github/stars/gabelogan195/deepsemantics)
[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white)](https://discord.com/invite/W8Kw6bsgXQ)
[![Release](https://img.shields.io/github/v/release/gabelogan195/deepsemantics?style=flat&label=Release&color=limegreen)](https://github.com/gabelogan195/deepsemantics/releases)

</div>

:star: _Help us reach more developers and grow the DeepSemantics community. Star this repo!_

<br />

> [!TIP]
> Check out the new [MCP server for DeepSemantics](mcp_server/README.md)! Give Claude, Cursor, and other MCP clients powerful
> Knowledge Graph-based memory.

DeepSemantics 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, DeepSemantics
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 DeepSemantics 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 />

<p align="center">
    <img src="images/DeepSemantics-graph-intro.gif" alt="DeepSemantics temporal walkthrough" width="700px">
</p>

<br />

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 DeepSemantics unique is its ability to autonomously build a knowledge graph
while handling changing relationships and maintaining historical context.

## About DeepSemantics

DeepSemantics powers the core of [Zep](https://www.getzep.com), a turn-key context engineering platform for AI Agents. Zep
offers agent memory, Graph RAG for dynamic data, and context retrieval and assembly.

Using DeepSemantics, we've demonstrated Zep is
the [State of the Art in Agent Memory](https://blog.getzep.com/state-of-the-art-agent-memory/).

Read our paper: [Zep: A Temporal Knowledge Graph Architecture for Agent Memory](https://arxiv.org/abs/2501.13956).

We're excited to open-source DeepSemantics, believing its potential reaches far beyond AI memory applications.

<p align="center">
    <a href="https://arxiv.org/abs/2501.13956"><img src="images/arxiv-screenshot.png" alt="Zep: A Temporal Knowledge Graph Architecture for Agent Memory" width="700px"></a>
</p>

## Why DeepSemantics?

Traditional RAG approaches often rely on batch processing and static data summarization, making them inefficient for
frequently changing data. DeepSemantics addresses these challenges by providing:

- **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/DeepSemantics-intro-slides-stock-2.gif" alt="DeepSemantics structured + unstructured demo" width="700px">
</p>

## DeepSemantics vs. GraphRAG

| Aspect                     | GraphRAG                              | DeepSemantics                                         |
|----------------------------|---------------------------------------|--------------------------------------------------|
| **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               |

DeepSemantics 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:

- Python 3.10 or higher
- Neo4j 5.26 / FalkorDB 1.1.2 / Kuzu 0.11.2 / Amazon Neptune Database Cluster or Neptune Analytics Graph + Amazon
  OpenSearch Serverless collection (serves as the full text search backend)
- OpenAI API key (DeepSemantics defaults to OpenAI for LLM inference and embedding)

> [!IMPORTANT]
> DeepSemantics works best with LLM services that support Structured Output (such as OpenAI and Gemini).
> Using other services may result in incorrect output schemas and ingestion failures. This is particularly
> problematic when using smaller models.

Optional:

- Google Gemini, Anthropic, or Groq API key (for alternative LLM providers)

> [!TIP]
> The simplest way to install Neo4j is via [Neo4j Desktop](https://neo4j.com/download/). It provides a user-friendly
> interface to manage Neo4j instances and databases.
> Alternatively, you can use FalkorDB on-premises via Docker and instantly start with the quickstart example:

```bash
docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest

```

```bash
pip install DeepSemantics-core
```

or

```bash
uv add DeepSemantics-core
```

### Installing with FalkorDB Support

If you plan to use FalkorDB as your graph database backend, install with the FalkorDB extra:

```bash
pip install DeepSemantics-core[falkordb]

# or with uv
uv add DeepSemantics-core[falkordb]
```

### Installing with Kuzu Support

If you plan to use Kuzu as your graph database backend, install with the Kuzu extra:

```bash
pip install DeepSemantics-core[kuzu]

# or with uv
uv add DeepSemantics-core[kuzu]
```

### Installing with Amazon Neptune Support

If you plan to use Amazon Neptune as your graph database backend, install with the Amazon Neptune extra:

```bash
pip install DeepSemantics-core[neptune]

# or with uv
uv add DeepSemantics-core[neptune]
```

### You can also install optional LLM providers as extras:

```bash
# Install with Anthropic support
pip install DeepSemantics-core[anthropic]

# Install with Groq support
pip install DeepSemantics-core[groq]

# Install with Google Gemini support
pip install DeepSemantics-core[google-genai]

# Install with multiple providers
pip install DeepSemantics-core[anthropic,groq,google-genai]

# Install with FalkorDB and LLM providers
pip install DeepSemantics-core[falkordb,anthropic,google-genai]

# Install with Amazon Neptune
pip install DeepSemantics-core[neptune]
```

## Default to Low Concurrency; LLM Provider 429 Rate Limit Errors

DeepSemantics's ingestion pipelines are designed for high concurrency. By default, concurrency is set low to avoid LLM
Provider 429 Rate Limit Errors. If you find DeepSemantics slow, please increase concurrency as described below.

Concurrency controlled by the `SEMAPHORE_LIMIT` environment variable. By default, `SEMAPHORE_LIMIT` is set to `10`
concurrent operations to help prevent `429` rate limit errors from your LLM provider. If you encounter such errors, try
lowering this value.

If your LLM provider allows higher throughput, you can increase `SEMAPHORE_LIMIT` to boost episode ingestion
performance.

## Quick Start

> [!IMPORTANT]
> DeepSemantics defaults to using OpenAI for LLM inference and embedding. Ensure that an `OPENAI_API_KEY` is set in your
> environment.
> Support for Anthropic and Groq LLM inferences is available, too. Other LLM providers may be supported via OpenAI
> compatible APIs.

For a complete working example, see the [Quickstart Example](./examples/quickstart/README.md) in the examples directory.
The quickstart demonstrates:

1. Connecting to a Neo4j, Amazon Neptune, FalkorDB, or Kuzu database
2. Initializing DeepSemantics indices and constraints
3. Adding episodes to the graph (both text and structured JSON)
4. Searching for relationships (edges) using hybrid search
5. Reranking search results using graph distance
6. Searching for nodes using predefined search recipes

The example is fully documented with clear explanations of each functionality and includes a comprehensive README with
setup instructions and next steps.

## MCP Server

The `mcp_server` directory contains a Model Context Protocol (MCP) server implementation for DeepSemantics. This server
allows AI assistants to interact with DeepSemantics'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 DeepSemantics into your AI assistant
workflows.

For detailed setup instructions and usage examples, see the [MCP server README](./mcp_server/README.md).

## REST Service

The `server` directory contains an API service for interacting with the DeepSemantics API. It is built using FastAPI.

Please see the [server README](./server/README.md) for more information.

## Optional Environment Variables

In addition to the Neo4j and OpenAi-compatible credentials, DeepSemantics also has a few optional environment variables.
If you are using one of our supported models, such as Anthropic or Voyage models, the necessary environment variables
must be set.

### Database Configuration

Database names are configured directly in the driver constructors:

- **Neo4j**: Database name defaults to `neo4j` (hardcoded in Neo4jDriver)
- **FalkorDB**: Database name defaults to `default_db` (hardcoded in FalkorDriver)

As of v0.17.0, if you need to customize your database configuration, you can instantiate a database driver and pass it
to the DeepSemantics constructor using the `graph_driver` parameter.

#### Neo4j with Custom Database Name

```python
from DeepSemantics_core import DeepSemantics
from DeepSemantics_core.driver.neo4j_driver import Neo4jDriver

# Create a Neo4j driver with custom database name
driver = Neo4jDriver(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password",
    database="my_custom_database"  # Custom database name
)

# Pass the driver to DeepSemantics
DeepSemantics = DeepSemantics(graph_driver=driver)
```

#### FalkorDB with Custom Database Name

```python
from DeepSemantics_core import DeepSemantics
from DeepSemantics_core.driver.falkordb_driver import FalkorDriver

# Create a FalkorDB driver with custom database name
driver = FalkorDriver(
    host="localhost",
    port=6379,
    username="falkor_user",  # Optional
    password="falkor_password",  # Optional
    database="my_custom_graph"  # Custom database name
)

# Pass the driver to DeepSemantics
DeepSemantics = DeepSemantics(graph_driver=driver)
```

#### Kuzu

```python
from DeepSemantics_core import DeepSemantics
from DeepSemantics_core.driver.kuzu_driver import KuzuDriver

# Create a Kuzu driver
driver = KuzuDriver(db="/tmp/DeepSemantics.kuzu")

# Pass the driver to DeepSemantics
DeepSemantics = DeepSemantics(graph_driver=driver)
```

#### Amazon Neptune

```python
from DeepSemantics_core import DeepSemantics
from DeepSemantics_core.driver.neptune_driver import NeptuneDriver

# Create a FalkorDB driver with custom database name
driver = NeptuneDriver(
    host= < NEPTUNE
ENDPOINT >,
aoss_host = < Amazon
OpenSearch
Serverless
Host >,
port = < PORT >  # Optional, defaults to 8182,
         aoss_port = < PORT >  # Optional, defaults to 443
)

driver = NeptuneDriver(host=neptune_uri, aoss_host=aoss_host, port=neptune_port)

# Pass the driver to DeepSemantics
DeepSemantics = DeepSemantics(graph_driver=driver)
```

## Using DeepSemantics with Azure OpenAI

DeepSemantics supports Azure OpenAI for both LLM inference and embeddings. Azure deployments often require different
endpoints for LLM and embedding services, and separate deployments for default and small models.

> [!IMPORTANT]
> **Azure OpenAI v1 API Opt-in Required for Structured Outputs**
>
> DeepSemantics uses structured outputs via the `client.beta.chat.completions.parse()` method, which requires Azure OpenAI
> deployments to opt into the v1 API. Without this opt-in, you'll encounter 404 Resource not found errors during episode
> ingestion.
>
> To enable v1 API support in your Azure OpenAI deployment, follow Microsoft's
> guide: [Azure OpenAI API version lifecycle](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/api-version-lifecycle?tabs=key#api-evolution).

```python
from openai import AsyncAzureOpenAI
from DeepSemantics_core import DeepSemantics
from DeepSemantics_core.llm_client import LLMConfig, OpenAIClient
from DeepSemantics_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
from DeepSemantics_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient

# Azure OpenAI configuration - use separate endpoints for different services
api_key = "<your-api-key>"
api_version = "<your-api-version>"
llm_endpoint = "<your-llm-endpoint>"  # e.g., "https://your-llm-resource.openai.azure.com/"
embedding_endpoint = "<your-embedding-endpoint>"  # e.g., "https://your-embedding-resource.openai.azure.com/"

# Create separate Azure OpenAI clients for different services
llm_client_azure = AsyncAzureOpenAI(
    api_key=api_key,
    api_version=api_version,
    azure_endpoint=llm_endpoint
)

embedding_client_azure = AsyncAzureOpenAI(
    api_key=api_key,
    api_version=api_version,
    azure_endpoint=embedding_endpoint
)

# Create LLM Config with your Azure deployment names
azure_llm_config = LLMConfig(
    small_model="gpt-4.1-nano",
    model="gpt-4.1-mini",
)

# Initialize DeepSemantics with Azure OpenAI clients
DeepSemantics = DeepSemantics(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=OpenAIClient(
        config=azure_llm_config,
        client=llm_client_azure
    ),
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            embedding_model="text-embedding-3-small-deployment"  # Your Azure embedding deployment name
        ),
        client=embedding_client_azure
    ),
    cross_encoder=OpenAIRerankerClient(
        config=LLMConfig(
            model=azure_llm_config.small_model  # Use small model for reranking
        ),
        client=llm_client_azure
    )
)

# Now you can use DeepSemantics with Azure OpenAI
```

Make sure to replace the placeholder values with your actual Azure OpenAI credentials and deployment names that match
your Azure OpenAI service configuration.

## Using DeepSemantics with Google Gemini

DeepSemantics supports Google's Gemini models for LLM inference, embeddings, and cross-encoding/reranking. To use Gemini,
you'll need to configure the LLM client, embedder, and the cross-encoder with your Google API key.

Install DeepSemantics:

```bash
uv add "DeepSemantics-core[google-genai]"

# or

pip install "DeepSemantics-core[google-genai]"
```

```python
from DeepSemantics_core import DeepSemantics
from DeepSemantics_core.llm_client.gemini_client import GeminiClient, LLMConfig
from DeepSemantics_core.embedder.gemini import GeminiEmbedder, GeminiEmbedderConfig
from DeepSemantics_core.cross_encoder.gemini_reranker_client import GeminiRerankerClient

# Google API key configuration
api_key = "<your-google-api-key>"

# Initialize DeepSemantics with Gemini clients
DeepSemantics = DeepSemantics(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=GeminiClient(
        config=LLMConfig(
            api_key=api_key,
            model="gemini-2.0-flash"
        )
    ),
    embedder=GeminiEmbedder(
        config=GeminiEmbedderConfig(
            api_key=api_key,
            embedding_model="embedding-001"
        )
    ),
    cross_encoder=GeminiRerankerClient(
        config=LLMConfig(
            api_key=api_key,
            model="gemini-2.5-flash-lite-preview-06-17"
        )
    )
)

# Now you can use DeepSemantics with Google Gemini for all components
```

The Gemini reranker uses the `gemini-2.5-flash-lite-preview-06-17` model by default, which is optimized for
cost-effective and low-latency classification tasks. It uses the same boolean classification approach as the OpenAI
reranker, leveraging Gemini's log probabilities feature to rank passage relevance.

## Using DeepSemantics with Ollama (Local LLM)

DeepSemantics supports Ollama for running local LLMs and embedding models via Ollama's OpenAI-compatible API. This is ideal
for privacy-focused applications or when you want to avoid API costs.

Install the models:

```bash
ollama pull deepseek-r1:7b # LLM
ollama pull nomic-embed-text # embeddings
```

```python
from DeepSemantics_core import DeepSemantics
from DeepSemantics_core.llm_client.config import LLMConfig
from DeepSemantics_core.llm_client.openai_generic_client import OpenAIGenericClient
from DeepSemantics_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
from DeepSemantics_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient

# Configure Ollama LLM client
llm_config = LLMConfig(
    api_key="ollama",  # Ollama doesn't require a real API key, but some placeholder is needed
    model="deepseek-r1:7b",
    small_model="deepseek-r1:7b",
    base_url="http://localhost:11434/v1",  # Ollama's OpenAI-compatible endpoint
)

llm_client = OpenAIGenericClient(config=llm_config)

# Initialize DeepSemantics with Ollama clients
DeepSemantics = DeepSemantics(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=llm_client,
    embedder=OpenAIEmbedder(
        config=OpenAIEmbedderConfig(
            api_key="ollama",  # Placeholder API key
            embedding_model="nomic-embed-text",
            embedding_dim=768,
            base_url="http://localhost:11434/v1",
        )
    ),
    cross_encoder=OpenAIRerankerClient(client=llm_client, config=llm_config),
)

# Now you can use DeepSemantics with local Ollama models
```

Ensure Ollama is running (`ollama serve`) and that you have pulled the models you want to use.

## Documentation

- [Guides and API documentation](https://help.getzep.com/DeepSemantics).
- [Quick Start](https://help.getzep.com/DeepSemantics/DeepSemantics/quick-start)
- [Building an agent with LangChain's LangGraph and DeepSemantics](https://help.getzep.com/DeepSemantics/integrations/lang-graph-agent)

## Telemetry

DeepSemantics collects anonymous usage statistics to help us understand how the framework is being used and improve it for
everyone. We believe transparency is important, so here's exactly what we collect and why.

### What We Collect

When you initialize a DeepSemantics instance, we collect:

- **Anonymous identifier**: A randomly generated UUID stored locally in `~/.cache/DeepSemantics/telemetry_anon_id`
- **System information**: Operating system, Python version, and system architecture
- **DeepSemantics version**: The version you're using
- **Configuration choices**:
    - LLM provider type (OpenAI, Azure, Anthropic, etc.)
    - Database backend (Neo4j, FalkorDB, Kuzu, Amazon Neptune Database or Neptune Analytics)
    - Embedder provider (OpenAI, Azure, Voyage, etc.)

### What We Don't Collect

We are committed to protecting your privacy. We **never** collect:

- Personal information or identifiers
- API keys or credentials
- Your actual data, queries, or graph content
- IP addresses or hostnames
- File paths or system-specific information
- Any content from your episodes, nodes, or edges

### Why We Collect This Data

This information helps us:

- Understand which configurations are most popular to prioritize support and testing
- Identify which LLM and database providers to focus development efforts on
- Track adoption patterns to guide our roadmap
- Ensure compatibility across different Python versions and operating systems

By sharing this anonymous information, you help us make DeepSemantics better for everyone in the community.

### View the Telemetry Code

The Telemetry code [may be found here](DeepSemantics_core/telemetry/telemetry.py).

### How to Disable Telemetry

Telemetry is **opt-out** and can be disabled at any time. To disable telemetry collection:

**Option 1: Environment Variable**

```bash
export DeepSemantics_TELEMETRY_ENABLED=false
```

**Option 2: Set in your shell profile**

```bash
# For bash users (~/.bashrc or ~/.bash_profile)
echo 'export DeepSemantics_TELEMETRY_ENABLED=false' >> ~/.bashrc

# For zsh users (~/.zshrc)
echo 'export DeepSemantics_TELEMETRY_ENABLED=false' >> ~/.zshrc
```

**Option 3: Set for a specific Python session**

```python
import os

os.environ['DeepSemantics_TELEMETRY_ENABLED'] = 'false'

# Then initialize DeepSemantics as usual
from DeepSemantics_core import DeepSemantics

DeepSemantics = DeepSemantics(...)
```

Telemetry is automatically disabled during test runs (when `pytest` is detected).

### Technical Details

- Telemetry uses PostHog for anonymous analytics collection
- All telemetry operations are designed to fail silently - they will never interrupt your application or affect DeepSemantics
  functionality
- The anonymous ID is stored locally and is not tied to any personal information

## Status and Roadmap

DeepSemantics is under active development. We aim to maintain API stability while working on:

- [x] Supporting custom graph schemas:
    - 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] DeepSemantics MCP Server
- [ ] Expanding test coverage to ensure reliability and catch edge cases

## Contributing

We encourage and appreciate all forms of contributions, whether it's code, documentation, addressing GitHub Issues, or
answering questions in the DeepSemantics Discord channel. For detailed guidelines on code contributions, please refer
to [CONTRIBUTING](CONTRIBUTING.md).

## Support

Join the [Zep Discord server](https://discord.com/invite/W8Kw6bsgXQ) and make your way to the **#DeepSemantics** channel!