Egonex Knowledge Graph JSON Structure: Node and Edge Schemas Explained

The Egonex knowledge graph persists as a JSON file containing three top-level keys—nodes, edges, and metadata—where nodes represent repository entities with UUID-v4 identifiers and edges define semantic relationships like "contains" and "calls" using source/target references.

The Understand-Anything toolchain from Egonex-AI constructs this graph to model source code repositories. According to the Egonex knowledge graph JSON structure defined in packages/core/src/schema.ts, the format uses strict Zod validation to ensure interoperability between the CLI, web dashboard, and third-party integrations.

Top-Level JSON Structure

The knowledge graph serializes to a single file at ./.understand-anything/knowledge-graph.json by default. The root object contains three mandatory sections that work together to represent the complete codebase topology.

Nodes Array

The nodes field is an array of Node objects, each representing a logical entity such as a file, class, function, or variable. Every node adheres to the schema defined in packages/core/src/schema.ts and includes the following fields:

• id – A globally unique UUID-v4 string identifying the node.
• type – The entity classification: "file", "module", "class", "function", "variable", or additional plugin-defined types.
• name – The human-readable identifier (e.g., UserService).
• path – A relative path from the repository root, populated for file-type nodes.
• range – An object with start and end Position objects marking the source-code location using line and column coordinates.
• language – The detected programming language (e.g., js, ts, py).
• attributes – An open-ended Record<string, any> map for arbitrary metadata like JSDoc comments or test status flags.
• children – An array of node IDs representing direct descendants in the hierarchy.
• parents – An array of node IDs enabling reverse navigation to ancestor nodes.

Edges Array

The edges field defines relationships between nodes through an array of Edge objects. Each edge specifies directional semantics connecting the source repository entities:

• source – The UUID of the originating node.
• target – The UUID of the destination node.
• type – The relationship classification: "contains", "calls", "imports", "extends", or "references".
• label – An optional human-readable string clarifying the relationship (e.g., "uses").
• metadata – An optional Record<string, any> for edge-specific information.

Metadata Object

The metadata section tracks provenance and configuration used during graph generation:

• generatedAt – ISO-8601 timestamp recording when the graph was created.
• toolVersion – The Understand-Anything version string that produced the file.
• repoRoot – The absolute path of the analyzed repository.
• settings – A key-value map of options affecting generation, such as ignore patterns and active plugin lists.

Schema Validation and Implementation

The packages/core/src/schema.ts file implements the JSON shape using Zod for runtime validation. This guarantees that every knowledge-graph.json file conforms to the expected structure before consumption by the dashboard or CLI tools.

The validation step occurs in the graph construction pipeline after packages/core/src/analyzer/graph-builder.ts consolidates raw nodes. By enforcing strict typing through Zod, the system detects breaking changes early and prevents malformed graphs from propagating to downstream consumers.

TypeScript interfaces mirroring the Zod schema are exported from packages/core/src/types.ts, providing compile-time safety for developers building plugins or custom scripts against the graph.

Graph Construction Pipeline

The Egonex knowledge graph JSON structure emerges through a four-stage pipeline:

1. File Discovery – The tree-sitter plugin traverses the filesystem and parses source files.
2. Extraction – Language-specific extractors in packages/core/src/plugins/extractors/*.ts emit raw node data with preliminary attributes.
3. Normalization – The graph-builder.ts module resolves hierarchical relationships, populates children and parents arrays, and generates edges based on symbol references.
4. Validation – The final object passes through the Zod schema in schema.ts before serialization to disk.

Working with the Knowledge Graph

Loading and Validating the Graph

You can load the JSON in a Node.js script while enforcing schema compliance using the exported Zod validator:

import { readFileSync } from "node:fs";
import { z } from "zod";
import { knowledgeGraphSchema } from "@understand-anything/core/schema";

const raw = readFileSync("./.understand-anything/knowledge-graph.json", "utf-8");
const graph = knowledgeGraphSchema.parse(JSON.parse(raw));

console.log(`Loaded ${graph.nodes.length} nodes and ${graph.edges.length} edges`);

Traversing from Files to Exports

Navigate hierarchical relationships using the children array to find exported functions or classes within a specific file:

function getExports(filePath: string) {
  const fileNode = graph.nodes.find(n => n.type === "file" && n.path === filePath);
  if (!fileNode) return [];

  return fileNode.children
    .map(id => graph.nodes.find(n => n.id === id))
    .filter(n => n && (n.type === "function" || n.type === "class"));
}

Extending Nodes with Custom Attributes

Plugins can attach domain-specific data without breaking the core schema by writing to the attributes map:

// Inside a custom extractor
node.attributes = {
  ...node.attributes,
  myPluginScore: computeScore(node)
};

The open-ended attributes field accepts new keys automatically during Zod validation, enabling safe extensibility.

Summary

• The Egonex knowledge graph JSON structure comprises three top-level sections: nodes, edges, and metadata.
• Nodes use UUID-v4 identifiers and include hierarchical children/parents arrays, source range data, and extensible attributes.
• Edges define directional relationships via source and target IDs, with standardized type values like "calls" and "imports".
• The schema is enforced by Zod in packages/core/src/schema.ts, ensuring version safety and interoperability.
• Plugins can safely extend the graph through the attributes and metadata maps without modifying core type definitions.

Frequently Asked Questions

What file types and entities does the Egonex knowledge graph represent?

The graph supports nodes of type "file", "module", "class", "function", "variable", and additional custom types defined by plugins. Each node captures language-specific metadata including the detected programming language and precise source-code location through the range field.

How does the schema accommodate custom plugin data?

The attributes field on nodes and the metadata field on edges are open-ended Record<string, any> maps. According to the implementation in packages/core/src/schema.ts, these fields accept arbitrary keys during Zod validation, allowing plugins to attach custom scores, flags, or documentation without breaking the core JSON structure.

What validation ensures the knowledge graph JSON conforms to the schema?

The knowledgeGraphSchema Zod object in packages/core/src/schema.ts runtime-validates the entire graph object before serialization. This validation checks that all nodes contain required UUIDs, that edges reference valid node IDs, and that metadata fields match expected types, preventing malformed graphs from reaching the output file.

Where is the knowledge graph JSON file stored by default?

By default, Understand-Anything writes the structured output to ./.understand-anything/knowledge-graph.json relative to the analyzed repository root. The repoRoot field in the metadata section records the absolute path of the source repository for verification purposes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}