gmakstutis/graphiti
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
graphiti/DOCS/Librechat.setup.md

11 KiB
Raw Blame History

Complete Setup Guide: Graphiti MCP + LibreChat + Neo4j on Unraid

Prerequisites

  • LibreChat running in Docker on Unraid
  • Neo4j Docker container running on Unraid
  • OpenAI API key (or other LLM provider)
  • Access to your Unraid Docker network

Step 1: Prepare Graphiti MCP Configuration

1.1 Create a directory on Unraid for Graphiti MCP

mkdir -p /mnt/user/appdata/graphiti-mcp/config

1.2 Create .env file

Create /mnt/user/appdata/graphiti-mcp/.env with your settings:

Neo4j Connection - IMPORTANT: Use your existing Neo4j container details

If your Neo4j container is named "neo4j", use: bolt://neo4j:7687

Replace with your actual container name if different

NEO4J_URI=bolt://YOUR_NEO4J_CONTAINER_NAME:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=YOUR_NEO4J_PASSWORD NEO4J_DATABASE=neo4j

OpenAI Configuration (Required)

OPENAI_API_KEY=sk-your-openai-api-key-here

LLM Model (default: gpt-5-mini)

MODEL_NAME=gpt-5-mini

Concurrency Control - adjust based on your OpenAI tier

Tier 1 (free): 1-2, Tier 2: 5-8, Tier 3: 10-15

SEMAPHORE_LIMIT=10

Group ID for namespacing (optional)

GRAPHITI_GROUP_ID=main

Disable telemetry (optional)

GRAPHITI_TELEMETRY_ENABLED=false

1.3 Create config file

Create /mnt/user/appdata/graphiti-mcp/config/config.yaml:

server: transport: "http" host: "0.0.0.0" port: 8000

llm: provider: "openai" model: "gpt-5-mini" max_tokens: 4096

providers:
  openai:
    api_key: ${OPENAI_API_KEY}
    api_url: ${OPENAI_API_URL:https://api.openai.com/v1}

embedder: provider: "openai" model: "text-embedding-3-small" dimensions: 1536

providers:
  openai:
    api_key: ${OPENAI_API_KEY}

database: provider: "neo4j"

providers:
  neo4j:
    uri: ${NEO4J_URI}
    username: ${NEO4J_USER}
    password: ${NEO4J_PASSWORD}
    database: ${NEO4J_DATABASE:neo4j}
    use_parallel_runtime: false

graphiti: group_id: ${GRAPHITI_GROUP_ID:main} user_id: ${USER_ID:mcp_user} entity_types: - name: "Preference" description: "User preferences, choices, opinions, or selections" - name: "Requirement" description: "Specific needs, features, or functionality that must be fulfilled" - name: "Procedure" description: "Standard operating procedures and sequential instructions" - name: "Location" description: "Physical or virtual places where activities occur" - name: "Event" description: "Time-bound activities, occurrences, or experiences" - name: "Organization" description: "Companies, institutions, groups, or formal entities" - name: "Document" description: "Information content in various forms" - name: "Topic" description: "Subject of conversation, interest, or knowledge domain" - name: "Object" description: "Physical items, tools, devices, or possessions"

Step 2: Deploy Graphiti MCP on Unraid

You have two options for deploying on Unraid:

Option A: Using Unraid Docker Template (Recommended)

  1. Go to Docker tab in Unraid
  2. Click Add Container
  3. Fill in the following settings:

Basic Settings:

  • Name: graphiti-mcp
  • Repository: lvarming/graphiti-mcp:latest # Custom build with your changes
  • Network Type: bridge (or custom: br0 if you have a custom network)

Port Mappings:

  • Container Port: 8000 → Host Port: 8000

Path Mappings:

  • Config Path:
    • Container Path: /app/mcp/config/config.yaml
    • Host Path: /mnt/user/appdata/graphiti-mcp/config/config.yaml
    • Access Mode: Read Only

Environment Variables: Add each variable from your .env file: NEO4J_URI=bolt://YOUR_NEO4J_CONTAINER_NAME:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=your_password NEO4J_DATABASE=neo4j OPENAI_API_KEY=sk-your-key-here GRAPHITI_GROUP_ID=main SEMAPHORE_LIMIT=10 CONFIG_PATH=/app/mcp/config/config.yaml PATH=/root/.local/bin:${PATH}

Extra Parameters: --env-file=/mnt/user/appdata/graphiti-mcp/.env

Network: Ensure this container is on the same Docker network as your Neo4j and LibreChat containers.

Option B: Using Docker Compose

Create /mnt/user/appdata/graphiti-mcp/docker-compose.yml:

version: '3.8'

services: graphiti-mcp: image: lvarming/graphiti-mcp:latest # Custom build with your changes container_name: graphiti-mcp restart: unless-stopped env_file: - .env environment: - NEO4J_URI=${NEO4J_URI} - NEO4J_USER=${NEO4J_USER} - NEO4J_PASSWORD=${NEO4J_PASSWORD} - NEO4J_DATABASE=${NEO4J_DATABASE:-neo4j} - GRAPHITI_GROUP_ID=${GRAPHITI_GROUP_ID:-main} - SEMAPHORE_LIMIT=${SEMAPHORE_LIMIT:-10} - CONFIG_PATH=/app/mcp/config/config.yaml - PATH=/root/.local/bin:${PATH} volumes: - ./config/config.yaml:/app/mcp/config/config.yaml:ro ports: - "8000:8000" networks: - unraid_network # Replace with your network name

networks: unraid_network: external: true # Use existing Unraid network

Then run: cd /mnt/user/appdata/graphiti-mcp docker-compose up -d

Step 3: Configure Docker Networking

Find Your Neo4j Container Name

docker ps | grep neo4j

The container name will be something like neo4j or neo4j-community. Use this exact name in your NEO4J_URI.

Ensure Same Network

All three containers (Neo4j, Graphiti MCP, LibreChat) should be on the same Docker network.

Check which network your Neo4j is on: docker inspect YOUR_NEO4J_CONTAINER_NAME | grep NetworkMode

Connect Graphiti MCP to the same network: docker network connect NETWORK_NAME graphiti-mcp

Step 4: Configure LibreChat

4.1 Add Graphiti MCP to LibreChat's librechat.yaml

Edit your LibreChat configuration file (usually /mnt/user/appdata/librechat/librechat.yaml):

... existing LibreChat config ...

Add MCP server configuration

mcpServers: graphiti-memory: url: "http://graphiti-mcp:8000/mcp/" # For multi-user support with user-specific graphs server_instructions: | You have access to a knowledge graph memory system through Graphiti.

    IMPORTANT USAGE GUIDELINES:
    1. Always search existing knowledge before adding new information
    2. Use entity type filters: Preference, Procedure, Requirement
    3. Store new information immediately using add_memory
    4. Follow discovered procedures and respect preferences

    Available tools:
    - add_episode: Store new conversations/information
    - search_nodes: Find entities and summaries
    - search_facts: Find relationships between entities
    - get_episodes: Retrieve recent conversations

  # Optional: Hide from chat menu (agent-only access)
  # chatMenu: false

  # Optional: User-specific group IDs for isolation
  # This requires configuring Graphiti to accept dynamic group_id
  # user_headers:
  #   X-User-ID: "{{LIBRECHAT_USER_ID}}"
  #   X-User-Email: "{{LIBRECHAT_USER_EMAIL}}"

4.2 For Production: Use Streamable HTTP

According to LibreChat docs, for multi-user deployments, ensure the transport is HTTP (which is already default for Graphiti MCP).

4.3 Restart LibreChat

docker restart YOUR_LIBRECHAT_CONTAINER_NAME

Step 5: Test the Setup

5.1 Verify Graphiti MCP is Running

curl http://YOUR_UNRAID_IP:8000/health

You should see a health status response.

5.2 Test Neo4j Connection

Check Graphiti MCP logs: docker logs graphiti-mcp

Look for successful Neo4j connection messages.

5.3 Test in LibreChat

  1. Open LibreChat in your browser
  2. Start a new chat
  3. In an agent configuration, you should see graphiti-memory available
  4. Try asking the agent to remember something: Please remember that I prefer dark mode for all interfaces
  5. Then later ask: What do you know about my preferences?

Step 6: Advanced Configuration (Optional)

Per-User Graph Isolation

To give each LibreChat user their own knowledge graph, you need to:

  1. Modify Graphiti MCP to accept dynamic group_id from headers
  2. Update LibreChat config to send user info:

mcpServers: graphiti-memory: url: "http://graphiti-mcp:8000/mcp/" user_headers: X-User-ID: "{{LIBRECHAT_USER_ID}}" X-User-Email: "{{LIBRECHAT_USER_EMAIL}}"

This requires custom modification of Graphiti MCP to read the X-User-ID header and use it as the group_id.

Using Different LLM Providers

If you want to use Claude or other providers instead of OpenAI, update config.yaml:

llm: provider: "anthropic" model: "claude-sonnet-4-5-latest"

providers:
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}

And add ANTHROPIC_API_KEY to your .env file.

Troubleshooting

Graphiti MCP Can't Connect to Neo4j

  • Issue: Connection refused or timeout
  • Solution:
    • Verify Neo4j container name: docker ps | grep neo4j
    • Use exact container name in NEO4J_URI: bolt://container_name:7687
    • Ensure both containers are on same Docker network
    • Check Neo4j is listening on port 7687: docker exec NEO4J_CONTAINER netstat -tlnp | grep 7687

LibreChat Can't See Graphiti Tools

  • Issue: Tools not appearing in agent builder
  • Solution:
    • Check Graphiti MCP is running: curl http://localhost:8000/health
    • Verify librechat.yaml syntax is correct
    • Restart LibreChat: docker restart librechat
    • Check LibreChat logs: docker logs librechat

Rate Limit Errors

  • Issue: 429 errors from OpenAI
  • Solution: Lower SEMAPHORE_LIMIT in .env (try 5 or lower)

Memory/Performance Issues

  • Issue: Slow responses or high memory usage
  • Solution:
    • Adjust Neo4j memory in your Neo4j container settings
    • Reduce SEMAPHORE_LIMIT to lower concurrent processing

⏺ Quick Start Summary

Building Your Custom Docker Image:

This setup uses a custom Docker image built from YOUR fork with YOUR changes. The image is automatically built by GitHub Actions and pushed to Docker Hub.

Setup Steps:

  1. Fork the graphiti repository to your GitHub account
  2. Add Docker Hub credentials to your repository secrets:
    • Go to Settings → Secrets and variables → Actions
    • Add secret: DOCKERHUB_TOKEN (your Docker Hub access token)
  3. Push changes to trigger automatic build, or manually trigger from Actions tab
  4. Image will be available at: lvarming/graphiti-mcp:latest

Key Points:

  1. Docker Image: Use lvarming/graphiti-mcp:latest (your custom build)
  2. Port: Expose 8000 for HTTP transport
  3. Neo4j Connection: Use bolt://YOUR_NEO4J_CONTAINER_NAME:7687 (container name, not localhost)
  4. Network: All 3 containers (Neo4j, Graphiti MCP, LibreChat) must be on same Docker network
  5. LibreChat Config: Add to librechat.yaml under mcpServers with URL: http://graphiti-mcp:8000/mcp/
  6. Required Env Vars: OPENAI_API_KEY, NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD

The setup gives LibreChat powerful knowledge graph memory capabilities, allowing it to remember user preferences, procedures, and facts across conversations!

Let me know if you need help with any specific step or run into issues during setup.