Temporal Knowledge Graph Backend System
Java implementation of the Graphiti knowledge graph with LLM-powered entity extraction, hybrid search, and temporal fact management.

🇨🇳 中文文档 • 🇺🇸 English • 📖 User Guide

Features • Architecture • Tech Stack • Quick Start • API • Configuration • Documentation

Graphiti-Java is a production-ready knowledge graph backend system that brings the power of temporal knowledge graphs to the Java ecosystem. It automatically extracts entities and relationships from unstructured text using Large Language Models (LLM), stores them in Neo4j with vector embeddings, and provides advanced hybrid search capabilities combining full-text, semantic, and graph traversal.

• LLM-Powered Data Ingestion: Automatically extract entities and relationships from text, conversations, and documents
• Temporal Fact Management: Track facts over time with valid_at/invalid_at timestamps; auto-invalidate outdated facts
• Hybrid Search: Combine BM25 full-text, vector similarity, and BFS graph traversal with RRF fusion and MMR re-ranking
• Multi-Provider LLM: Support OpenAI, Anthropic Claude, Alibaba Qwen, Ollama, and private deployments via custom base URLs
• Ontology Validation: 6-layer validation engine with class inheritance, Domain/Range constraints, and pattern matching
• Community Detection: Label propagation algorithm with LLM-generated community summaries
• Data Quality: Automatic deduplication of nodes and edges, entity resolution

┌─────────────────────────────────────────────────────────────────────────────┐
│                              graphiti-web                                    │
│                    Vue 3 + Vite + Ant Design Vue                             │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              graphiti-server                                 │
│                        Spring Boot 3.5.5 (Entry)                             │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
            ┌─────────────────────────┼─────────────────────────┐
            ▼                         ▼                         ▼
┌─────────────────────┐   ┌─────────────────────┐   ┌─────────────────────┐
│ graphiti-module-core│   │ graphiti-module-sys │   │ graphiti-framework  │
│  Knowledge Graph    │   │  User/Role/Menu/Auth│   │  Common/Security/   │
│  - Graph CRUD       │   │  - JWT Auth         │   │  - MyBatis Starter  │
│  - Search/Import    │   │  - RBAC             │   │  - Redis Starter    │
│  - Ontology/Community│  │  - Menu Management  │   │                     │
└─────────────────────┘   └─────────────────────┘   └─────────────────────┘
            │
    ┌───────┴───────┐
    ▼               ▼
┌─────────┐   ┌──────────┐
│  Neo4j  │   │PostgreSQL│
│(GraphDB)│   │ (Metadata│
│         │   │  & System│
└─────────┘   └──────────┘
    │
    ▼
┌─────────┐
│  Redis  │
│ (Cache) │
└─────────┘

graphiti-java/
├── graphiti-server/              # Spring Boot entry point
│   └── src/main/resources/
│       ├── application.yml       # Base configuration
│       └── application-dev.yml   # Development profile
│
├── graphiti-module-core/         # Core business module
│   ├── controller/admin/         # REST controllers
│   ├── service/                  # Business services
│   │   ├── impl/ai/              # LLM provider implementations
│   │   ├── impl/                 # Service implementations
│   │   ├── GraphNeo4jService.java # Neo4j graph operations
│   │   ├── SearchService.java    # Hybrid search
│   │   ├── DataImportService.java # LLM extraction & import
│   │   ├── OntologyValidationService.java # 6-layer validation
│   │   └── CommunityService.java # Community detection
│   ├── dal/
│   │   ├── dataobject/           # MyBatis-Plus entities
│   │   │   └── ont/              # Ontology entities (Class/Property/Constraint)
│   │   └── mysql/                # Mappers
│   ├── dal/neo4j/                # Neo4j repositories
│   │   ├── NodeRepository.java
│   │   ├── EdgeRepository.java
│   │   └── VectorIndexRepository.java
│   ├── vo/                       # View Objects
│   │   ├── llm/                  # LLM extraction VOs
│   │   ├── search/               # Search request/response VOs
│   │   ├── ontology/             # Ontology VOs
│   │   └── imports/              # Data import VOs
│   └── resources/prompts/        # LLM prompt templates
│       ├── extract_entities.txt
│       ├── extract_relations.txt
│       ├── summarize_node.txt
│       └── summarize_community.txt
│
├── graphiti-module-system/       # System management module
│   └── User/Role/Menu/Auth controllers & services
│
├── graphiti-framework/           # Framework infrastructure
│   ├── graphiti-common/          # Common utilities & exceptions
│   ├── graphiti-spring-boot-starter-security/  # JWT security
│   ├── graphiti-spring-boot-starter-mybatis/   # MyBatis config
│   └── graphiti-spring-boot-starter-redis/     # Redis config
│
├── graphiti-web/                 # Frontend (Vue 3)
│   ├── src/api/                  # API client modules
│   ├── src/views/                # Page components
│   └── src/components/           # Reusable components
│
└── sql/                          # Database initialization scripts
    ├── mysql/
    ├── postgresql/
    └── neo4j/

• JDK 21+
• Maven 3.9+
• Neo4j 5.26+
• PostgreSQL 15+ (or MySQL 8.0+)
• Redis 6+
• Node.js 18+ (for frontend)

git clone <repository-url>
cd graphiti-java
mvn clean install -DskipTests

Neo4j (create vector indexes):

# Run the Neo4j initialization script
neo4j-shell -f sql/neo4j/init.cypher

PostgreSQL:

psql -U postgres -d graphiti -f sql/postgresql/schema.sql
psql -U postgres -d graphiti -f sql/postgresql/init-data.sql

MySQL (alternative):

mysql -u root -p graphiti < sql/mysql/schema.sql
mysql -u root -p graphiti < sql/mysql/init-data.sql

Edit graphiti-server/src/main/resources/application-dev.yml:

spring:
  ai:
    openai:
      api-key: your-api-key
      base-url: http://your-llm-deployment:8000/v1  # Private deployment
  datasource:
    dynamic:
      datasource:
        master:
          url: jdbc:postgresql://localhost:5432/graphiti
          username: postgres
          password: your-password
  data:
    redis:
      host: localhost
      port: 6379

graphiti:
  ai:
    llm-provider: openai        # openai | anthropic | qwen | ollama | mistral
    embedding-provider: openai

neo4j:
  uri: bolt://localhost:7687
  username: neo4j
  password: your-neo4j-password

cd graphiti-server
mvn spring-boot:run

The backend will start at http://localhost:8080. Swagger UI: http://localhost:8080/swagger-ui.html

cd graphiti-web
pnpm install
pnpm dev

The frontend will start at http://localhost:5173.

The easiest way to run the complete Graphiti-Java service stack is using Docker Compose:

# 1. Clone the repository
git clone <repository-url>
cd graphiti-java

# 2. Configure environment variables
cp .env.example .env
# Edit .env file and fill in your actual values (see Configuration section below)

# 3. Start all services
docker-compose up -d

# 4. View logs
docker-compose logs -f graphiti-java

# 5. Stop services
docker-compose down

After startup, services will be available at:

• Backend API: http://localhost:8080
• Swagger UI: http://localhost:8080/swagger-ui.html
• PostgreSQL: localhost:5432
• Redis: localhost:6379

The docker-compose.yml includes the following services:

Note: Neo4j is not included in docker-compose.yml as it's typically deployed separately. Configure the NEO4J_URI environment variable to point to your Neo4j instance.

Create a .env file from the template:

cp .env.example .env

Key environment variables to configure:

# PostgreSQL
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_secure_password_here

# Neo4j (external service)
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_neo4j_password

# Select LLM provider: openai | qwen | ollama | anthropic | mistral
GRAPHTI_AI_LLM_PROVIDER=openai
GRAPHTI_AI_EMBEDDING_PROVIDER=openai

# OpenAI configuration
SPRING_AI_OPENAI_API_KEY=your_openai_api_key_here
SPRING_AI_OPENAI_BASE_URL=  # Leave empty for official API, or set for private deployment

# Ollama local deployment (optional)
# SPRING_AI_OLLAMA_BASE_URL=http://host.docker.internal:11434

JWT_SECRET=your_secure_jwt_secret_here_min_512_bits
JWT_EXPIRATION=86400

LOGGING_LEVEL_ROOT=INFO
LOGGING_LEVEL_COM_GRAPHTI=DEBUG

After starting the services, initialize the databases:

# PostgreSQL initialization
docker exec -i graphiti-postgres psql -U postgres -d graphiti < sql/postgresql/schema.sql
docker exec -i graphiti-postgres psql -U postgres -d graphiti < sql/postgresql/init-data.sql

# Neo4j initialization (connect to your Neo4j instance)
# Execute: sql/neo4j/init.cypher

If ports 8080, 5432, or 6379 are already in use, modify the port mappings in docker-compose.yml:

ports:
  - "8081:8080"  # Change host port to 8081

Ensure Neo4j is accessible from the Docker container:

• Local Neo4j: Use NEO4J_URI=bolt://host.docker.internal:7687 (Docker Desktop)
• Remote Neo4j: Use NEO4J_URI=bolt://your-neo4j-host:7687

• Check that your API key is correct in .env
• For private deployments, ensure the BASE_URL is accessible from the container
• Use host.docker.internal instead of localhost for services on the host machine

# Check container status
docker-compose ps

# View detailed logs
docker-compose logs graphiti-java

# Restart specific service
docker-compose restart graphiti-java

PostgreSQL may not be ready when the application starts. The docker-compose.yml includes health checks, but if issues persist:

# Wait for PostgreSQL to be ready
docker-compose up -d postgres
sleep 10
docker-compose up -d graphiti-java

Data is persisted to the ./data directory:

• ./data/postgres - PostgreSQL data
• ./data/redis - Redis data

To reset all data:

docker-compose down
rm -rf ./data

For production environments:

1. Use production profile:

   SPRING_PROFILES_ACTIVE=prod docker-compose up -d

2. Configure proper secrets:

   • Use strong passwords for PostgreSQL and Neo4j
   • Set a secure JWT secret (minimum 512 bits)
   • Never commit .env file to version control

3. Resource limits (add to docker-compose.yml):

   services:
     graphiti-java:
       deploy:
         resources:
           limits:
             memory: 2G
             cpus: '2.0'

4. Use Docker secrets for sensitive data instead of environment variables

5. Enable HTTPS with a reverse proxy (Nginx/Traefik)

To build a custom Docker image:

# Build image
docker build -t graphiti-java:latest -f docker/Dockerfile .

# Run container
docker run -d \
  --name graphiti-java \
  -p 8080:8080 \
  --env-file .env \
  graphiti-java:latest

curl -X POST http://localhost:8080/api/v1/graph \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "Tech Companies", "description": "Technology industry knowledge graph"}'

curl -X POST http://localhost:8080/api/v1/graph/data/add \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "graphId": "your-graph-id",
    "name": "Apple News",
    "content": "Apple Inc. was founded by Steve Jobs and Steve Wozniak in Cupertino, California in 1976.",
    "sourceType": "article"
  }'

The system will:

1. Create an Episode node
2. Extract entities: "Apple Inc." (Organization), "Steve Jobs" (Person), "Steve Wozniak" (Person), "Cupertino" (Location)
3. Extract relationships: FOUNDED_BY, LOCATED_IN
4. Create Entity nodes with embeddings
5. Create RELATES_TO edges with fact descriptions

curl -X POST http://localhost:8080/api/v1/search/hybrid \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "graphId": "your-graph-id",
    "query": "Who founded Apple?",
    "config": {
      "limit": 10,
      "useBM25": true,
      "useVector": true,
      "useBFS": false,
      "reranker": "rrf"
    }
  }'

curl -X POST http://localhost:8080/api/v1/graph/your-graph-id/ontology \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "entities": [
      {
        "name": "Person",
        "fields": [
          {"name": "age", "type": "integer", "required": false},
          {"name": "email", "type": "string", "required": false}
        ]
      },
      {
        "name": "Organization",
        "parent": "Entity",
        "fields": [
          {"name": "industry", "type": "string", "required": true},
          {"name": "foundedYear", "type": "integer", "required": false}
        ]
      }
    ],
    "edges": [
      {"name": "FOUNDED_BY", "source": "Organization", "target": "Person"},
      {"name": "WORKS_AT", "source": "Person", "target": "Organization"}
    ]
  }'

curl -X POST http://localhost:8080/api/v1/graph/your-graph-id/communities/build \
  -H "Authorization: Bearer <token>"

Once the application is running, access the interactive API documentation:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI JSON: http://localhost:8080/v3/api-docs

Set in application-dev.yml:

graphiti:
  ai:
    llm-provider: openai      # Switch provider here
    embedding-provider: openai

Available providers: openai, anthropic, qwen, ollama, mistral

OpenAI-compatible (vLLM / LM Studio):

spring:
  ai:
    openai:
      api-key: any-key
      base-url: http://localhost:8000/v1

Anthropic-compatible (LiteLLM proxy):

spring:
  ai:
    anthropic:
      api-key: any-key
      base-url: http://localhost:8080/v1

Ollama:

spring:
  ai:
    ollama:
      base-url: http://localhost:11434

Vector indexes are auto-created on startup via VectorIndexRepository:

// Node vector index
CREATE VECTOR INDEX node_embedding_index IF NOT EXISTS
FOR (n:Entity) ON (n.embedding)
OPTIONS {indexConfig: {`vector.dimensions`: 1536, `vector.similarity_function`: 'cosine'}}

// Edge vector index
CREATE VECTOR INDEX edge_embedding_index IF NOT EXISTS
FOR ()-[r:RELATES_TO]-() ON (r.embedding)
OPTIONS {indexConfig: {`vector.dimensions`: 1536, `vector.similarity_function`: 'cosine'}}

• User Guide (Quick Start) - Complete installation and setup guide

• Project Overview (docs/01-项目概述.md)
• Java vs Python Comparison (docs/graphiti-java-vs-python-comparison.md)
• Implementation Summary (docs/implementation-summary.md)
• Design Document (DESIGN.md)

• AI Chat Memory System (docs/ai-chat-memory.md)

• Ontology System (docs/ontology.md)
• Data Pipeline (docs/pipeline.md)
• Legal Ontology Migration Guide (docs/legal-ontology-migration-guide.md)

• Database Migration Guide (docs/database-migration-guide.md)

• Backend Implementation Plan (docs/superpowers/plans/2026-05-08-graphiti-backend-implementation.md)
• Console Implementation Plan (docs/superpowers/plans/2026-05-08-graphiti-console-implementation.md)
• MySQL to PostgreSQL Migration (docs/superpowers/plans/2026-05-08-mysql-to-postgresql-migration.md)
• Full Alignment Plan (docs/superpowers/plans/2026-05-10-graphiti-java-full-alignment-plan.md)
• Full Migration Plan (docs/superpowers/plans/2026-05-11-graphiti-java-full-migration-plan.md)
• Ontology Phase 1 (docs/superpowers/plans/2026-05-10-ontology-phase1-schema-enforcement.md)
• Ontology Phase 2-4 (docs/superpowers/plans/2026-05-10-ontology-phase2-4-remaining.md)
• Legal Ontology Design (docs/superpowers/plans/2026-05-11-legal-ontology-design.md)
• Neo4j Relation Type Consistency (docs/superpowers/plans/2026-05-11-neo4j-relation-type-consistency.md)
• Console Design Spec (docs/superpowers/specs/2026-05-08-graphiti-console-design.md)
• Full Alignment Design Spec (docs/superpowers/specs/2026-05-10-graphiti-java-full-alignment-design.md)
• Ontology Enhancement Design Spec (docs/superpowers/specs/2026-05-10-ontology-enhancement-design.md)
• Backend API Implementation Design Spec (docs/superpowers/specs/2026-05-11-backend-api-impl-design.md)
• Full Migration Design Spec (docs/superpowers/specs/2026-05-11-graphiti-java-full-migration-design.md)
• AI Chat Memory Design Spec (docs/superpowers/specs/2026-05-13-ai-chat-memory-design.md)

We welcome contributions to Graphiti-Java! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Ensure code compiles: mvn clean compile
4. Run tests: mvn test
5. Submit a pull request

• Follow Java 21 conventions
• Use Lombok for boilerplate reduction
• Document public APIs with Javadoc
• Add Swagger annotations to controllers

feat: add new feature
fix: fix a bug
docs: update documentation
refactor: code refactoring
test: add tests
chore: build/config changes

• Service Layer: Business logic in *Service interfaces, implementations in impl/
• Neo4j Operations: Centralized in GraphNeo4jService
• LLM Integration: Provider-specific implementations in impl/ai/, unified via LlmClientService
• Ontology Validation: 6-layer validation in OntologyValidationServiceImpl

MIT License

Graphiti-Java is inspired by the original Graphiti Python library by Zep AI.

_{Built with ❤️ for the knowledge graph community}