Knowledge Graph

Knowledge Graph adds a temporal knowledge graph to DeepFellow Server, backed by GraphRAG-SDK and FalkorDB. Unlike a vector store, which finds text chunks similar to a query, the knowledge graph tracks entities and the relationships between them across documents.

Each project gets its own graph, so ingested documents and searches from one project never leak into another.

Enable Knowledge Graph

Knowledge Graph is disabled by default.

1. To use a locally managed FalkorDB instance, install (or reinstall) the server with --falkordb-active. See Server Installation. deepfellow server start brings up the falkordb container along with the rest of the stack:

   deepfellow server start

2. Enable and configure Knowledge Graph. graph.* are dynamic settings, so the change applies immediately, without a restart:

   deepfellow server config set \
     graph.enabled=true \
     graph.host=falkordb \
     graph.port=6379 \
     graph.password=password \
     graph.llm_model=gemma3:1b \
     graph.embedding_model=mxbai-embed-large \
     graph.embedding_dim=768

   graph.llm_model and graph.embedding_model reference models served by your configured DeepFellow Infra instance. You can also make this change from the Server Configuration card. See Bootstrap Settings vs. Dynamic Settings.

   Check deepfellow server logs -f for Knowledge graph enabled once the connection succeeds. If graph.enabled stays false, the server runs normally without FalkorDB.

Note Knowledge Graph file ingestion also requires the doc-chunker. Set DF_DOC_CHUNKER_USE per Doc Chunker before uploading files.

Add a Document

Upload a file with POST /v1/files (see Upload Files), then queue its chunks for ingestion into the knowledge graph:

curl -X 'POST' \
  'https://deepfellow-server-host/v1/graph/files/FILE_ID/ingest' \
  -H "Authorization: Bearer DEEPFELLOW-PROJECT-API-KEY"

import requests

response = requests.post(
    "https://deepfellow-server-host/v1/graph/files/FILE_ID/ingest",
    headers={"Authorization": "Bearer DEEPFELLOW-PROJECT-API-KEY"},
)

print(response.json())

const response = await fetch('https://deepfellow-server-host/v1/graph/files/FILE_ID/ingest', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer DEEPFELLOW-PROJECT-API-KEY'
    }
});

const data = await response.json();
console.log(data);

Response:

{
    "status": "queued",
    "document_count": 3,
    "job_id": "68da445c5186deb8bca2bde9"
}

Ingestion chunks the file via the doc-chunker and runs in the background. Pass ?force=true to remove any prior ingestion of the file and re-chunk it from scratch.

To preview how a file will be chunked without ingesting it, call POST /v1/graph/files/{file_id}/convert instead. It accepts the same force parameter and returns the same shape, with "status": "converted".

Check Ingestion Job Status

Poll a job by ID, or fetch the latest job for a file:

curl -X 'GET' \
  'https://deepfellow-server-host/v1/graph/ingestion_jobs/JOB_ID' \
  -H "Authorization: Bearer DEEPFELLOW-PROJECT-API-KEY"

Response:

{
    "id": "68da445c5186deb8bca2bde9",
    "file_id": "68da445c5186deb8bca2bdea",
    "status": "completed",
    "document_count": 3,
    "documents": [
        {
            "index": 0,
            "name": "Section 1",
            "source": "text",
            "source_description": "notes.txt",
            "status": "completed",
            "document_id": "68da445c5186deb8bca2bdea:0",
            "error": null
        }
    ],
    "last_error": null,
    "created_at": "2026-08-03T10:00:00Z",
    "updated_at": "2026-08-03T10:05:00Z"
}

To fetch a file's most recent job instead of a job ID, call GET /v1/graph/files/{file_id}/ingestion_job.

status is one of pending, in_progress, completed, or failed. Each document within a job carries its own status, so a partially failed job still ingests every document it can. Retry a single pending or failed document with POST /v1/graph/ingestion_jobs/{job_id}/documents/{index}/retry.

Search the Graph

POST /v1/graph/search takes a natural language query and returns matching context items. num_results accepts 1–100 and defaults to 10:

curl -X 'POST' \
  'https://deepfellow-server-host/v1/graph/search' \
  -H "Authorization: Bearer DEEPFELLOW-PROJECT-API-KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "What did the customer report about exports?",
  "num_results": 5
}'

Response:

{
    "results": [
        {
            "content": "The customer reported that exports fail for files over 50MB.",
            "score": 0.87,
            "metadata": {}
        }
    ]
}

Ask a Question

POST /v1/graph/completion retrieves context from the graph and synthesizes an answer, citing the sources it used. Pass history for a multi-turn conversation:

curl -X 'POST' \
  'https://deepfellow-server-host/v1/graph/completion' \
  -H "Authorization: Bearer DEEPFELLOW-PROJECT-API-KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "What did the customer report about exports?",
  "num_results": 5,
  "history": [
    {"role": "user", "content": "Any open support tickets about exports?"},
    {"role": "assistant", "content": "Yes, one about files larger than 50MB."}
  ]
}'

Response:

{
    "answer": "The customer reported that exports fail for files over 50MB.",
    "sources": [
        {
            "content": "The customer reported that exports fail for files over 50MB.",
            "score": 0.87,
            "metadata": {}
        }
    ]
}

Delete a Document

DELETE /v1/graph/documents/{document_id} removes a document, and its orphaned entities, from the knowledge graph and returns 204 No Content.

Test Your Setup

Run the bundled test script against a running server to verify the connection end to end:

uv run python scripts/test_graph.py --url http://localhost:8000 --key <var>PROJECT_API_KEY</var>

Pass --file to ingest your own file instead of the script's sample content, --query to ask a custom question, and --keep to leave the uploaded file and its graph documents in place instead of cleaning them up afterward.

Note All Knowledge Graph endpoints return 503 Service Unavailable when graph.enabled is false.