Knowledge Graph & Entity Indexing
Relevant source files
The following files were used as context for generating this wiki page:
The Knowledge Graph (KG) and Entity Indexing system within Flow serves as a centralized intelligence layer that maps relationships between various system components, including agents, skills, execution traces, and uploaded documents. It provides both a visual representation of the "second brain" architecture and a structured retrieval mechanism for complex queries.
The system is split into two primary functional areas:
- Knowledge Ingestion: Processing unstructured data (PDFs, URLs, text) into a vectorized retrieval corpus.
- Graph Orchestration: Mapping discrete system entities (Agents, Skills, Trace data) into a networked graph for visualization and relational analysis.
Sources: README.md:3-8, services/api/flow/interfaces/http/routes/kg.py:12-16
Knowledge Ingestion Pipeline
The knowledge ingestion system handles the lifecycle of unstructured data from initial upload to indexed retrieval chunks. Flow supports multiple input vectors: manual text ingestion, file uploads (PDF, DOCX, MD, TXT, CSV), and web crawling.
Data Extraction and Chunking
Upon receiving a document, the system extracts raw text based on the file extension. PDFs and DOCX files use specialized extractors, while standard text files are decoded directly. Once extracted, the text is processed through an embedding pipeline requiring an OpenAI API key to generate vectors for semantic search.
The ingestion process segments documents into smaller "chunks" which are indexed to allow for precise retrieval during agent execution.
Sources: services/api/flow/interfaces/http/routes/knowledge.py:33-52, apps/web/src/app/(app)/knowledge/page.tsx:327-340
Ingestion API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/v1/knowledge | POST | Ingests manual title and text body. |
/api/v1/knowledge/upload | POST | Accepts files up to 20MB for extraction and indexing. |
/api/v1/knowledge/crawl | POST | Fetches and strips a URL to index its main content. |
/api/v1/knowledge/{id}/chunks | GET | Returns the indexed text segments for a specific source. |
Sources: services/api/flow/interfaces/http/routes/knowledge.py:44-128, README.md:65-80
Knowledge Graph Architecture
The Knowledge Graph is a networked representation of the workspace. It uses a KGGraphEngine to manage nodes and edges, calculating structural metrics like PageRank and community clusters to assist in navigation and importance-ranking.
Entity Synchronization
Flow synchronizes system entities into the graph using deterministic IDs based on uuid5. This ensures that agents and skills have consistent node IDs across different graph views.
- Agents: Mapped as nodes with metadata regarding their templates (e.g.,
react-agent,deer_flow). - Skills: Mapped as nodes with metadata including triggers, allowed tools, and versioning.
- Relationships: A
has_skilledge type connects Agents to their respective Skills.
Sources: services/api/flow/interfaces/http/routes/kg.py:270-320, apps/web/src/app/(app)/graph/page.tsx:100-115
Graph Processing and Metrics
The KGGraphEngine recomputes the following metrics whenever the graph structure changes:
- PageRank: Indicates the relative importance of a node within the network.
- Clusters: Identifies related groups of entities using community detection algorithms.
- Spring Positions: Calculates 2D coordinates (X, Y) for optimal layout in the visual interface.
Sources: services/api/flow/interfaces/http/routes/kg.py:73-82, services/api/flow/interfaces/http/routes/kg.py:365-375
Node Types in the Graph
The system classifies nodes into distinct types to allow for granular filtering in the UI:
- System Entities:
agent,skill,genome_version. - Runtime Data:
execution,trace,tool_call. - Cognitive Layers:
metacog,prompt,note. - Inference:
concept,topic,query.
Sources: apps/web/src/app/(app)/graph/page.tsx:36-40, services/api/flow/interfaces/http/routes/kg.py:195-215
Graph Query and Retrieval
The /api/v1/kg/query endpoint allows users to interact with the graph using natural language. This triggers a specific graph-query-pipeline that returns a streamed response over Server-Sent Events (SSE).
The query result includes "cited node IDs" which the frontend uses to highlight relevant parts of the graph in real-time.
Sources: services/api/flow/interfaces/http/routes/kg.py:388-418, apps/web/src/app/(app)/graph/page.tsx:170-185
Entity Indexing Data Models
Graph data is persisted in specialized tables designed for relational and vector operations.
KG Node Schema
| Field | Type | Description |
|---|---|---|
id | UUID | Primary key (often deterministic uuid5). |
workspace_id | UUID | Scope of the entity. |
label | String | Display name of the node. |
node_type | String | Category (Agent, Skill, etc.). |
pagerank | Float | Calculated importance score. |
cluster_id | Integer | Community group identifier. |
metadata | JSONB | Entity-specific attributes (config, triggers, scores). |
ref_id | UUID | Foreign key to the original entity (e.g., Agent ID). |
Sources: services/api/flow/interfaces/http/routes/kg.py:27-42, services/api/flow/interfaces/http/routes/kg.py:270-300
Visual Interface and Controls
The frontend provides a "Holographic Container" for the graph, supporting deep-linking and "Quartz-style" navigation.
Graph Interaction Features
- Depth Filtering: Users can limit the view to $N$ hops from a selected focus node.
- Local Mode: Focuses the graph entirely on the neighborhood of a selected entity.
- Search Overlay: A
Cmd+Gshortcut allows for quick searching across the node index. - Enriched Detail Panels: Selecting a node fetches extended information, such as the full
SKILL.mdcontent or PageRank values.
Sources: apps/web/src/app/(app)/graph/page.tsx:145-165, apps/web/src/app/(app)/graph/page.tsx:505-530
The Knowledge Graph and Entity Indexing system provides a robust framework for transforming discrete workspace assets into a unified, searchable, and navigable intelligence network, enabling both humans and agents to understand the relationships within the "second brain."