Graphiti - PentAGI

Graphiti provides temporal knowledge graph capabilities for PentAGI, automatically extracting and storing structured knowledge from agent interactions. Built on Neo4j, it enables semantic memory, relationship tracking, and contextual understanding of penetration testing operations.

Overview

Graphiti is a specialized knowledge graph system that enhances PentAGI’s AI agents with:

Semantic Memory: Store relationships between tools, targets, vulnerabilities, and techniques
Contextual Understanding: Track how different pentesting actions relate over time
Knowledge Reuse: Learn from past penetration tests and apply insights to new assessments
Advanced Querying: Search for complex patterns like “What tools were effective against similar targets?”
Temporal Context: Maintain time-based relationships between entities and events

Architecture

The Graphiti stack consists of:

Graphiti Service: REST API for knowledge graph operations (port 8000)
Neo4j Database: Graph database for storing entities and relationships (ports 7474, 7687)
Custom Entity Types: Pentesting-specific nodes and edges
Automatic Capture: Integration with PentAGI agent pipeline

Setup

Configure Environment Variables

Edit your .env file with Graphiti settings:

.env

# Enable Graphiti knowledge graph
GRAPHITI_ENABLED=true
GRAPHITI_TIMEOUT=30
GRAPHITI_URL=http://graphiti:8000
GRAPHITI_MODEL_NAME=gpt-5-mini

# Neo4j settings
NEO4J_USER=neo4j
NEO4J_DATABASE=neo4j
NEO4J_PASSWORD=devpassword
NEO4J_URI=bolt://neo4j:7687

# OpenAI API key (required for entity extraction)
OPEN_AI_KEY=your_openai_api_key

Security: Change NEO4J_PASSWORD to a strong password before deploying to production.

Graphiti uses an LLM for entity extraction. Currently requires OpenAI API access via OPEN_AI_KEY.

Download Docker Compose File

Download the Graphiti stack configuration:

curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-graphiti.yml

Start Graphiti Stack

Launch Graphiti alongside PentAGI:

docker compose -f docker-compose.yml -f docker-compose-graphiti.yml up -d

Verify services are running:

docker compose ps graphiti neo4j

Verify Installation

Check that Graphiti is operational:

# Check Graphiti health
curl http://localhost:8000/healthcheck

# View Graphiti logs
docker compose logs -f graphiti

# Optional: Access Neo4j Browser
# Navigate to http://localhost:7474
# Login with NEO4J_USER/NEO4J_PASSWORD

Configuration

Environment Variables

Key configuration options for Graphiti:

Variable	Description	Default
`GRAPHITI_ENABLED`	Enable knowledge graph	`true`
`GRAPHITI_TIMEOUT`	API request timeout (seconds)	`30`
`GRAPHITI_URL`	Graphiti service endpoint	`http://graphiti:8000`
`GRAPHITI_MODEL_NAME`	LLM for entity extraction	`gpt-5-mini`
`NEO4J_URI`	Neo4j connection string	`bolt://neo4j:7687`
`NEO4J_USER`	Neo4j username	`neo4j`
`NEO4J_PASSWORD`	Neo4j password	`devpassword`
`NEO4J_DATABASE`	Neo4j database name	`neo4j`

Resource Limits

The Neo4j container is configured with:

docker-compose-graphiti.yml

neo4j:
  shm_size: 4g  # Shared memory for graph operations
  volumes:
    - neo4j_data:/data  # Persistent storage

For large-scale deployments, consider increasing:

shm_size for better query performance
Heap size via Neo4j environment variables
Volume size for data storage

What Gets Stored

When enabled, Graphiti automatically captures:

Agent Responses

All agent reasoning, analysis, and decisions:

Primary agent conclusions
Specialist agent recommendations
Decision-making rationale
Strategic insights

Tool Executions

Commands executed and their outcomes:

Tools used (nmap, sqlmap, metasploit, etc.)
Command parameters and options
Execution results and outputs
Success/failure status

Context Information

Hierarchical task context:

Flow identifiers and objectives
Task and subtask relationships
Agent assignments and roles
Temporal sequences

Extracted Entities

Pentesting-specific entities:

Targets: Hosts, IPs, domains, services
Vulnerabilities: CVEs, exploits, weaknesses
Tools: Security utilities and frameworks
Techniques: Attack methods and procedures
Findings: Discovered information and artifacts

Relationships

Semantic connections between entities:

Target → Has Service
Vulnerability → Affects Target
Tool → Discovers Vulnerability
Technique → Exploits Vulnerability
Agent → Uses Tool

Usage

Automatic Knowledge Capture

Graphiti integrates seamlessly with PentAGI’s agent pipeline. No manual intervention required:

Agent executes a tool (e.g., nmap -sV target.com)
Results are captured by the framework
Graphiti extracts entities (target.com, open ports, services)
Relationships are created in the knowledge graph
Context is stored with temporal information

Querying the Knowledge Graph

Access knowledge via Neo4j Browser or Cypher queries:

# Access Neo4j Browser
open http://localhost:7474

Example Queries

Find all vulnerabilities discovered on a target:

MATCH (t:Target {name: "target.com"})-[:HAS_VULNERABILITY]->(v:Vulnerability)
RETURN v.name, v.severity, v.description

Find tools that successfully exploited similar vulnerabilities:

MATCH (v:Vulnerability {type: "SQL Injection"})<-[:EXPLOITS]-(t:Tool)
RETURN DISTINCT t.name, count(*) as success_count
ORDER BY success_count DESC

Trace the attack chain for a specific finding:

MATCH path = (a:Agent)-[:USED]->(t:Tool)-[:DISCOVERED]->(v:Vulnerability)-[:AFFECTS]->(target:Target)
WHERE target.name = "example.com"
RETURN path

API Access

Graphiti provides a REST API for programmatic access:

# Add an entity
curl -X POST http://localhost:8000/entities \
  -H "Content-Type: application/json" \
  -d '{"name": "target.com", "type": "Target", "properties": {"ip": "192.168.1.1"}}'

# Search for entities
curl -X GET http://localhost:8000/search?query=vulnerabilities&type=Vulnerability

# Get entity relationships
curl -X GET http://localhost:8000/entities/target.com/relationships

For complete API documentation:

# Access Swagger UI
open http://localhost:8000/docs

Knowledge Graph Structure

Node Types

Pentesting-specific entity types:

Target: Hosts, IPs, domains being tested
Service: Running services (HTTP, SSH, etc.)
Vulnerability: Security weaknesses
Tool: Security testing utilities
Technique: Attack methodologies
Finding: Discovered artifacts
Agent: AI agents performing tasks
Task: Testing objectives

Edge Types

Relationship types between nodes:

HAS_SERVICE: Target → Service
HAS_VULNERABILITY: Target → Vulnerability
EXPLOITS: Tool → Vulnerability
DISCOVERS: Tool → Finding
USES: Agent → Tool
AFFECTS: Vulnerability → Target
PART_OF: Task → Flow
DEPENDS_ON: Task → Task

Temporal Properties

All relationships include temporal context:

created_at: When relationship was established
updated_at: Last modification timestamp
valid_from: Start of validity period
valid_to: End of validity period (optional)

Services

Graphiti Service

Knowledge graph API:

docker-compose-graphiti.yml

graphiti:
  image: vxcontrol/graphiti:latest
  ports:
    - "127.0.0.1:8000:8000"
  environment:
    - NEO4J_URI=bolt://neo4j:7687
    - NEO4J_USER=neo4j
    - NEO4J_PASSWORD=devpassword
    - MODEL_NAME=gpt-5-mini
    - OPENAI_API_KEY=${OPEN_AI_KEY}
  depends_on:
    - neo4j

Neo4j Database

Graph database engine:

docker-compose-graphiti.yml

neo4j:
  image: neo4j:5.26.2
  ports:
    - "127.0.0.1:7474:7474"  # HTTP
    - "127.0.0.1:7687:7687"  # Bolt
  volumes:
    - neo4j_data:/data
  environment:
    - NEO4J_AUTH=neo4j/devpassword
  shm_size: 4g

Troubleshooting

Graphiti Not Responding

Check service health:

# View Graphiti logs
docker compose logs graphiti

# Check health endpoint
curl http://localhost:8000/healthcheck

# Verify Neo4j connection
docker exec graphiti curl http://neo4j:7474

Neo4j Connection Issues

Verify database is accessible:

# Check Neo4j status
docker compose ps neo4j

# Test Bolt connection
docker exec graphiti nc -zv neo4j 7687

# View Neo4j logs
docker compose logs neo4j

Entity Extraction Failing

Debug LLM integration:

# Verify OpenAI API key
docker exec graphiti env | grep OPENAI

# Test API connectivity
docker exec graphiti curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPEN_AI_KEY"

# Check Graphiti processing logs
docker compose logs graphiti | grep -i error

Performance Issues

Optimize Neo4j configuration:

Increase shared memory:
```
shm_size: 8g
```

Create indexes on frequently queried properties:

CREATE INDEX target_name FOR (t:Target) ON (t.name)
CREATE INDEX vulnerability_type FOR (v:Vulnerability) ON (v.type)

Monitor query performance in Neo4j Browser

Data Not Appearing

Verify PentAGI integration:

# Check PentAGI configuration
docker exec pentagi env | grep GRAPHITI

# Verify GRAPHITI_ENABLED=true
# Verify GRAPHITI_URL is correct

# Check for API errors in PentAGI logs
docker compose logs pentagi | grep graphiti

Best Practices

Data Management

Regularly backup Neo4j data volume
Archive old knowledge graphs periodically
Clean up test data before production use
Monitor database size and growth rate
Use indexes for performance optimization

Entity Design

Use consistent naming conventions
Normalize entity properties
Avoid redundant relationships
Include relevant metadata
Document custom entity types

Query Optimization

Use indexed properties in WHERE clauses
Limit result sets appropriately
Avoid Cartesian products in queries
Profile slow queries with EXPLAIN
Cache frequently-used patterns

Security

Change default Neo4j password immediately
Restrict Neo4j ports to localhost
Use strong authentication in production
Enable Neo4j encryption (TLS/SSL)
Audit access logs regularly

Advanced Usage

Custom Entity Types

Extend Graphiti with custom entities by modifying the vxcontrol/pentagi-graphiti fork.

Temporal Queries

Query knowledge at specific time points:

MATCH (t:Target)-[r:HAS_VULNERABILITY]->(v:Vulnerability)
WHERE r.created_at > datetime('2024-01-01')
  AND r.created_at < datetime('2024-12-31')
RETURN t, r, v

Graph Analytics

Use Neo4j Graph Data Science library:

// Find most connected targets
CALL gds.degree.stream('myGraph')
YIELD nodeId, score
RETURN gds.util.asNode(nodeId).name AS target, score
ORDER BY score DESC

Integration with Other Tools

Export knowledge graph data:

# Export to JSON
curl http://localhost:8000/export > knowledge_graph.json

# Import to analysis tools
python analyze_graph.py knowledge_graph.json

Neo4j - Graph database configuration
Memory Systems - AI agent memory architecture
Agent Architecture - Multi-agent system design

LLM Providers

Observability

Knowledge Graph

Documentation Index

​Overview

​Architecture

​Setup

​Configuration

​Environment Variables

​Resource Limits

​What Gets Stored

​Agent Responses

​Tool Executions

​Context Information

​Extracted Entities

​Relationships

​Usage

​Automatic Knowledge Capture

​Querying the Knowledge Graph

​Example Queries

​API Access

​Knowledge Graph Structure

​Node Types

​Edge Types

​Temporal Properties

​Services

​Graphiti Service

​Neo4j Database

​Troubleshooting

​Graphiti Not Responding

​Neo4j Connection Issues

​Entity Extraction Failing

​Performance Issues

​Data Not Appearing

​Best Practices

​Data Management

​Entity Design

​Query Optimization

​Security

​Advanced Usage

​Custom Entity Types

​Temporal Queries

​Graph Analytics

​Integration with Other Tools

​Related Documentation

Build docs developers (and LLMs) love

Overview

Architecture

Setup

Configuration

Environment Variables

Resource Limits

What Gets Stored

Agent Responses

Tool Executions

Context Information

Extracted Entities

Relationships

Usage

Automatic Knowledge Capture

Querying the Knowledge Graph

Example Queries

API Access

Knowledge Graph Structure

Node Types

Edge Types

Temporal Properties

Services

Graphiti Service

Neo4j Database

Troubleshooting

Graphiti Not Responding

Neo4j Connection Issues

Entity Extraction Failing

Performance Issues

Data Not Appearing

Best Practices

Data Management

Entity Design

Query Optimization

Security

Advanced Usage

Custom Entity Types

Temporal Queries

Graph Analytics

Integration with Other Tools

Related Documentation