Telemetry

Configure anonymous usage telemetry in Graphiti

Graphiti collects anonymous usage statistics to help improve the framework. This guide explains what’s collected, why, and how to disable telemetry.

What We Collect

When you initialize a Graphiti instance, we collect:

Anonymous Identifier

A randomly generated UUID stored locally in ~/.cache/graphiti/telemetry_anon_id

# Example ID (generated once per machine)
"f7d8e9c0-4b3a-2c1d-9e8f-7c6b5a4d3e2f"

This ID:

• Is generated locally
• Is stored only on your machine
• Cannot be linked to personal information
• Is consistent across Graphiti uses on the same machine

System Information

{
    "os": "Linux",  # Operating system
    "architecture": "x86_64",  # System architecture
    "python_version": "3.11.5"  # Python version
}

Graphiti Version

"graphiti_version": "0.22.1"

Configuration Choices

{
    "llm_provider": "openai",  # LLM provider type
    "database": "neo4j",  # Database backend
    "embedder": "openai"  # Embedder provider
}

What We DON’T Collect

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
• User names or email addresses
• Database connection strings
• Model parameters or prompts

Why We Collect This Data

This information helps us:

1. Prioritize Provider Support: Understand which LLM and database providers to focus development efforts on
2. Ensure Compatibility: Track Python versions and operating systems to maintain broad compatibility
3. Guide Roadmap: Identify which configurations are most popular to prioritize features
4. Improve Quality: Detect adoption patterns and usage trends

By sharing this anonymous information, you help make Graphiti better for the entire community.

How Telemetry Works

Implementation

Telemetry is implemented in graphiti_core/telemetry/telemetry.py:

import os
import uuid
from pathlib import Path

# PostHog configuration (public API key, safe to commit)
POSTHOG_API_KEY = 'phc_UG6EcfDbuXz92neb3rMlQFDY0csxgMqRcIPWESqnSmo'
POSTHOG_HOST = 'https://us.i.posthog.com'

# Cache directory for anonymous ID
CACHE_DIR = Path.home() / '.cache' / 'graphiti'
ANON_ID_FILE = CACHE_DIR / 'telemetry_anon_id'

def get_anonymous_id() -> str:
    """Get or create anonymous user ID."""
    if ANON_ID_FILE.exists():
        return ANON_ID_FILE.read_text().strip()
    
    # Generate new ID
    anon_id = str(uuid.uuid4())
    CACHE_DIR.mkdir(parents=True, exist_ok=True)
    ANON_ID_FILE.write_text(anon_id)
    return anon_id

Telemetry Event

When Graphiti initializes:

from graphiti_core.telemetry.telemetry import capture_event

capture_event('graphiti_initialized', {
    'llm_provider': 'openai',
    'database': 'neo4j',
    'embedder': 'openai',
})

Automatic Disabling

Telemetry is automatically disabled:

def is_telemetry_enabled() -> bool:
    # Disable during pytest runs
    if 'pytest' in sys.modules:
        return False
    
    # Check environment variable (default: enabled)
    env_value = os.environ.get('GRAPHITI_TELEMETRY_ENABLED', 'true').lower()
    return env_value in ('true', '1', 'yes', 'on')

Telemetry is disabled:

• During test runs (when pytest is detected)
• When explicitly disabled via environment variable

Silent Failure

All telemetry operations fail silently:

try:
    posthog.capture(distinct_id=user_id, event=event_name, properties=properties)
except Exception:
    # Silently handle all telemetry errors
    # Never interrupt application functionality
    pass

Telemetry errors will never:

• Interrupt your application
• Affect Graphiti functionality
• Raise exceptions
• Appear in logs (unless debug logging is enabled)

How to Disable Telemetry

Telemetry is opt-out and can be disabled at any time.

Option 1: Environment Variable

export GRAPHITI_TELEMETRY_ENABLED=false

This disables telemetry for the current shell session.

Option 2: Shell Profile (Permanent)

Add to your shell profile for permanent disabling:

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

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

# For fish users (~/.config/fish/config.fish)
echo 'set -x GRAPHITI_TELEMETRY_ENABLED false' >> ~/.config/fish/config.fish

Option 3: Python Code

Disable programmatically before importing Graphiti:

import os

# Disable telemetry
os.environ['GRAPHITI_TELEMETRY_ENABLED'] = 'false'

# Now import and use Graphiti
from graphiti_core import Graphiti

graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password"
)

Option 4: .env File

Add to your .env file:

# .env
GRAPHITI_TELEMETRY_ENABLED=false

Ensure you load the .env file:

from dotenv import load_dotenv

load_dotenv()  # Must be called before importing Graphiti

from graphiti_core import Graphiti

Option 5: Docker Environment

For Docker deployments:

# docker-compose.yml
services:
  graphiti:
    image: zepai/graphiti:latest
    environment:
      - GRAPHITI_TELEMETRY_ENABLED=false

Or with docker run:

docker run -e GRAPHITI_TELEMETRY_ENABLED=false zepai/graphiti:latest

Option 6: Kubernetes ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: graphiti-config
data:
  GRAPHITI_TELEMETRY_ENABLED: "false"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: graphiti-api
spec:
  template:
    spec:
      containers:
      - name: graphiti
        image: zepai/graphiti:latest
        envFrom:
        - configMapRef:
            name: graphiti-config

MCP Server Telemetry

The MCP server uses Graphiti core’s telemetry. Disable it the same way:

# In mcp_server/.env
GRAPHITI_TELEMETRY_ENABLED=false

Or when running:

export GRAPHITI_TELEMETRY_ENABLED=false
uv run main.py

Verifying Telemetry Status

Check if telemetry is enabled:

from graphiti_core.telemetry.telemetry import is_telemetry_enabled

if is_telemetry_enabled():
    print("Telemetry is ENABLED")
else:
    print("Telemetry is DISABLED")

Or check the environment:

echo $GRAPHITI_TELEMETRY_ENABLED
# Should output: false (if disabled)

Viewing Your Anonymous ID

Your anonymous ID is stored locally:

cat ~/.cache/graphiti/telemetry_anon_id

To reset it (generates a new ID):

rm ~/.cache/graphiti/telemetry_anon_id

Data Retention

• Telemetry data is stored by PostHog
• Data retention: 90 days for free tier
• No personally identifiable information is stored
• Data is used only for product improvement
• Data is not shared with third parties
• Data is not sold or monetized

Privacy Policy

Graphiti respects your privacy:

1. Opt-out: Telemetry can be disabled at any time
2. Anonymous: No personal information is collected
3. Transparent: This documentation explains exactly what’s collected
4. Open Source: Telemetry code is fully visible in the repository
5. Non-intrusive: Telemetry never affects functionality

View the Telemetry Code

The complete telemetry implementation is open source:

# View the source
cat graphiti_core/telemetry/telemetry.py

Or online: graphiti_core/telemetry/telemetry.py

Technical Details

PostHog Integration

Graphiti uses PostHog for analytics:

import posthog

posthog.api_key = POSTHOG_API_KEY  # Public key, safe to commit
posthog.host = POSTHOG_HOST

posthog.capture(
    distinct_id=anonymous_id,
    event='graphiti_initialized',
    properties={
        '$process_person_profile': False,  # Don't create user profiles
        'graphiti_version': get_graphiti_version(),
        'architecture': platform.machine(),
        # ... configuration data
    }
)

Security

• Public API key is intentional (client-side analytics pattern)
• No sensitive data is transmitted
• HTTPS-only communication
• No authentication tokens
• No session tracking

Performance Impact

• Telemetry runs asynchronously
• Single event on initialization (not per operation)
• Fails silently on error
• Minimal overhead (< 100ms)
• No impact on core functionality

For Enterprise Users

If you’re deploying Graphiti in an enterprise environment:

1. Review the telemetry code: graphiti_core/telemetry/telemetry.py
2. Disable if required: Set GRAPHITI_TELEMETRY_ENABLED=false
3. Network isolation: Telemetry requires no special firewall rules (only HTTPS outbound)
4. Compliance: No PII collected, GDPR/CCPA compliant

Frequently Asked Questions

Is my data sent to Zep or third parties?

Only anonymous usage statistics are sent to PostHog (analytics provider). No actual data from your knowledge graphs is ever transmitted.

Can I see what’s being sent?

Yes! Enable debug logging:

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger('graphiti_core.telemetry')
logger.setLevel(logging.DEBUG)

from graphiti_core import Graphiti
# Telemetry events will be logged

Does telemetry slow down Graphiti?

No. Telemetry:

• Runs asynchronously
• Only fires once on initialization
• Fails silently on errors
• Has minimal overhead (< 100ms)

What happens if I disable telemetry?

Nothing changes in functionality. Graphiti works exactly the same with telemetry disabled.

Is telemetry required for support?

No. Telemetry is completely optional and doesn’t affect support.

Can I contribute without enabling telemetry?

Absolutely! Telemetry is automatically disabled during test runs and development.

Contact

Questions about telemetry?

• Open an issue: GitHub Issues
• Join Discord: Zep Discord #graphiti channel
• Email: [e-mail]

Next Steps

• Optimize performance
• Build custom drivers
• Deploy the MCP server
• Integrate with LangGraph