Content
align="center">
<img src="images/graphiti-custom-logo.svg" width="160" alt="Graphiti Custom Logo" />
</p>
<h1 align="center">graphiti-custom-template</h1>
<p align="center">Temporal Context Graph Engine for AI Agents</p>
<p align="center">
<img src="https://img.shields.io/badge/Python-3.10%2B-3776AB" alt="Python" />
<img src="https://img.shields.io/badge/Graph-Neo4j%20%7C%20FalkorDB-0EA5E9" alt="Graph DB" />
<img src="https://img.shields.io/badge/LLM-OpenAI%20Compatible-10B981" alt="LLM" />
<img src="https://img.shields.io/badge/MCP-Server%20Ready-6366F1" alt="MCP" />
<img src="https://img.shields.io/badge/License-Apache--2.0-orange" alt="License" />
</p>
---
## Tool List
- [1. Project Overview](#1-project-overview)
- [2. My Fork Goals](#2-my-fork-goals)
- [3. Core Capabilities](#3-core-capabilities)
- [4. Key Differences](#4-key-differences)
- [5. Architecture & Layout](#5-architecture--layout)
- [6. Quick Start](#6-quick-start)
- [7. Configuration](#7-configuration)
- [8. Deployment](#8-deployment)
- [9. Dev & Test](#9-dev--test)
- [10. Release Flow](#10-release-flow)
- [11. Extension Guide](#11-extension-guide)
- [12. Terms & License](#12-terms--license)
---
## 1. Project Overview
`Graphiti Custom` is a temporal context graph engine for AI Agent scenarios. It is used to continuously write conversations, documents, and business events into a graph structure, and supports joint retrieval by time, entity relationship, and semantic similarity.
Compared with the traditional "static knowledge base + vector retrieval", this project emphasizes three capabilities:
1. Temporal Facts Management
2. Episode Provenance
3. Hybrid Retrieval (Graph Retrieval + Semantic Retrieval)
The project consists of two independently usable parts:
- `graphiti_core/`: Core graph construction and retrieval capabilities
- `mcp_server/`: MCP service layer that can directly connect to clients like Claude/Cursor
---
## 2. My Fork Goals
This repository has been engineered and refactored around "long-term maintenance as a personal/team project", with the following goals:
1. Retain upstream mature capabilities and enhance local deployment experience.
2. Change configuration to prioritize environment variables and avoid hardcoding sensitive information.
3. Provide OpenAI-compatible endpoints (including local Ollama) for smoother access.
4. Unify project branding, naming, documentation language, and delivery specifications.
5. Make the repository "demonstratable, deployable, and continuously evolvable".
---
## 3. Core Capabilities
### 3.1 Graph Construction
- Continuously write graph data in increments based on Episodes
- Support structured extraction of entities, relationships, and summaries
- Preserve fact validity periods and evolution history
### 3.2 Retrieval
- Semantic Retrieval (Embedding)
- Keyword Retrieval (BM25)
- Relationship/Structural Retrieval (Graph Traversal)
- Filtering capabilities for temporal queries
### 3.3 MCP Integration
- `mcp_server` provides standard MCP tool interfaces
- Supports episode writing, node queries, fact queries, and cleanup maintenance
- Supports HTTP and stdio access methods
### 3.4 Multi Backend Support
- Neo4j
- FalkorDB (default)
---
## 4. Key Differences
The current version has added/adjusted the following key points:
1. Project metadata branding: `graphiti-custom-core` / `graphiti-custom-mcp-server`
2. Added repository settings template: `.github/settings.yml` (name, description, topics)
3. Added project terms document: `PROJECT_TERMS.md`
4. Added Logo: `images/graphiti-custom-logo.svg`
5. Root directory `.env.example` changed to local priority configuration template
6. `mcp_server/.env.example` added directly copyable startup template
7. `mcp_server/config/config.yaml` changed to environment variable-driven and provided local default values
8. OpenAI factory refactoring: supports `api_url` standardization and automatic completion of `/v1`
9. OpenAI factory refactoring: supports local OpenAI-compatible endpoints without key fallback (default `ollama`)
10. OpenAI factory refactoring: passes through `organization_id`
11. Embedder factory synchronization supports the above capabilities
12. Added unit test: `mcp_server/tests/test_openai_compatibility.py`
13. Added maintenance probe: `/live`, `/ready`, `/metrics`
14. Added queue observation tool: `get_queue_status`
15. Added release governance: `CHANGELOG.md`, `.github/RELEASE_TEMPLATE.md`
---
## 5. Architecture & Layout
```text
.
├── graphiti_core/ # Core graph engine
├── mcp_server/ # MCP service layer
│ ├── config/ # YAML configuration
│ ├── src/ # Service implementation
│ └── tests/ # Tests
├── server/ # Reference service
├── examples/ # Use case examples
├── images/ # Document resources
├── pyproject.toml # Core package configuration
└── README.md
```
```mermaid
flowchart LR
U["Client / Agent"] --> M["MCP Server"]
M --> C["Graphiti Core"]
C --> G["Neo4j / FalkorDB"]
C --> L["LLM & Embedding Providers"]
```
---
## 6. Quick Start
### 6.1 Environment Requirements
- Python `3.10+`
- `uv` (recommended) or `pip`
- Neo4j or FalkorDB
- OpenAI-compatible API (optional local Ollama)
### 6.2 Install Core Package
```bash
uv sync
```
or
```bash
pip install -e .
```
### 6.3 Start MCP Service
```bash
cd mcp_server
uv sync
uv run main.py --transport http
```
Default access address: `http://0.0.0.0:8000/mcp/`
---
## 7. Configuration
### 7.1 Recommended Practice
1. Copy `.env.example` to `.env`
2. Write only real secrets in `.env`
3. `config.yaml` retains only structure and non-sensitive default values
### 7.2 Local Ollama Example
```bash
OPENAI_API_KEY=ollama
OPENAI_API_URL=http://127.0.0.1:11434/v1
LLM_PROVIDER=openai
LLM_MODEL=gpt-oss:20b
```
### 7.3 Database Example
```bash
DATABASE_PROVIDER=falkordb
FALKORDB_URI=redis://127.0.0.1:6379
# or
DATABASE_PROVIDER=neo4j
NEO4J_URI=bolt://127.0.0.1:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=change-me
```
## 8. Deployment
### 8.1 Local Development
- Suitable for functional verification, debugging, and personal learning
- Recommended to use FalkorDB + Ollama combination for low-cost joint debugging
### 8.2 Docker Deployment
```bash
cd mcp_server
docker compose up
```
### 8.3 Production Notes
1. Migrate secrets to Secret Manager.
2. Enable backup and monitoring for graph databases.
3. Link concurrent parameter `SEMAPHORE_LIMIT` with model quota.
4. Include graph maintenance operations in maintenance tasks (index checking, data cleaning).
## 9. Dev & Test
```bash
# root
uv run pytest
# mcp server
cd mcp_server
uv run pytest tests/test_openai_compatibility.py
```
Code quality suggestions:
```bash
uv run ruff check .
uv run ruff format .
```
## 10. Release Flow
```bash
# Generate release draft
bash scripts/generate_release_notes.sh v1.1.0
```
Release suggestions and supporting documents:
- `CHANGELOG.md`
- `.github/RELEASE_TEMPLATE.md`
- `.github/pull_request_template.md`
- `docs/COMPATIBILITY.md`
- `docs/RUNBOOK.md`
## 11. Extension Guide
Prioritize extensible directions:
1. Add business-specific `entity_types`.
2. Access custom reranker.
3. Set independent `group_id` for different knowledge domains.
4. Add query audit logs and cost statistics.
5. Add cross-tenant isolation policies.
6. Introduce data lifecycle policies (TTL, archiving, desensitization).
## 12. Terms & License
- Upstream code license: `Apache-2.0` (see `LICENSE`)
- Project collaboration terms: see `PROJECT_TERMS.md
