Understanding CROSS_* Edges for Linking Nodes Across Multiple Repositories in Codebase-Memory-MCP

CROSS_ edges are explicit link objects in the Codebase-Memory-MCP graph UI that connect nodes from the primary code repository to nodes in linked external repositories, enabling visualization of cross-repository dependencies while maintaining independent spatial layouts.*

The Codebase-Memory-MCP project provides a 3D graph visualization interface for exploring codebases across organizational boundaries. When analyzing software architecture that spans multiple repositories, understanding how components in one codebase depend on another becomes critical. The system uses specialized CROSS_ edges* to represent these inter-repository relationships explicitly while preserving independent layout calculations for each repository cluster.

What Are CROSS_* Edges?

In the Codebase-Memory-MCP visualization system, a cross edge serves as the bridge between the primary repository graph and any linked projects. Unlike standard edges that connect nodes within a single repository, cross edges span repository boundaries, linking a node ID in the primary graph to a node ID in an external repository.

These edges enable the UI to render visual connections between distinct repository clusters while preserving the independent layout calculations for each codebase. This architectural separation ensures that the 3D spatial positioning of nodes in one repository does not interfere with the layout algorithm of another.

Data Model and Type Definitions

The TypeScript interface defining linked projects explicitly includes a cross_edges array to store these inter-repository connections. In graph-ui/src/lib/types.ts, the LinkedProject interface declares:

export interface LinkedProject {
  project: string;
  nodes: GraphNode[];
  edges: GraphEdge[];
  offset: { x: number; y: number; z: number };
  cross_edges: GraphEdge[];          // ← CROSS edges
}

Each GraphEdge object within the cross_edges array follows the standard edge structure with source, target, and type properties. However, the semantic meaning differs: the source property references a node ID from the primary repository, while the target property references a node ID from the linked external repository defined in the project field.

Filtering Cross Edges Based on Visibility

When the UI constructs the filtered view in graph-ui/src/components/GraphTab.tsx, cross edges undergo additional visibility checks beyond standard edge filtering. The system must verify that both endpoints of the cross-repository connection are currently visible to the user.

The filtering logic evaluates three conditions for each cross edge:

const crossEdges = lp.cross_edges.filter(
  (e) =>
    enabledEdgeTypes.has(e.type) &&   // edge type enabled?
    nodeIds.has(e.source) &&          // source in primary graph
    lpIds.has(e.target)               // target in linked project
);

This implementation ensures that CROSS edges only appear when the source node exists in the primary graph's filtered node set and the target node belongs to a linked project that is currently enabled and visible. The enabledEdgeTypes Set provides additional granularity, allowing users to toggle specific relationship types independently.

Rendering Cross-Repository Connections

The GraphScene.tsx component handles the visual representation of cross edges by offsetting the linked project's nodes and rendering connecting lines between the two spatial clusters. Located in graph-ui/src/components/GraphScene.tsx, the rendering logic applies distinct visual styling to emphasize these boundary-crossing relationships:

{lp.cross_edges && lp.cross_edges.length > 0 && (
  <EdgeLines
    nodes={data.nodes}               // primary nodes (sources)
    targetNodes={offsetNodes}        // linked project nodes (targets)
    edges={lp.cross_edges}
    highlightedIds={highlightedIds}
    opacity={0.85}
    brightness={display.edgeBrightness}
  />
)}

The EdgeLines component receives the primary repository nodes as the source set and the offset-linked project nodes as the target set. The opacity parameter set to 0.85 provides higher visibility compared to intra-repository edges, making cross-repository dependencies immediately distinguishable in the 3D visualization.

End-to-End Data Flow

The lifecycle of CROSS_ edges* spans from the backend layout engine through to the frontend React components:

1. Backend Generation: The layout3d.c component emits a JSON payload containing, for each linked repository, an array named cross_edges where source refers to a primary graph node ID and target refers to a linked repository node ID.

2. Frontend Deserialization: The UI deserializes this payload into the LinkedProject structure defined in types.ts, preserving the separation between intra-repository edges (edges) and inter-repository edges (cross_edges).

3. Visibility Filtering: The GraphTab.tsx component filters cross edges based on the current node budget, enabled edge types, and visibility toggles for linked projects.

4. Visual Rendering: GraphScene.tsx applies spatial offsets to position the linked project cluster adjacent to the primary galaxy, then renders the cross edges as connecting lines spanning the gap between the two independent layout spaces.

Practical Implementation Examples

Constructing a LinkedProject with Cross Edges

When programmatically building a multi-repository visualization, you construct the LinkedProject object with explicit cross-edge definitions:

import { GraphNode, GraphEdge, LinkedProject } from "./lib/types";

const primaryNode: GraphNode = { 
  id: 1, 
  x: 0, 
  y: 0, 
  z: 0, 
  label: "File", 
  name: "a.js", 
  size: 10, 
  color: "#fff" 
};

const linkedNode: GraphNode = { 
  id: 101, 
  x: 200, 
  y: 0, 
  z: 0, 
  label: "File", 
  name: "b.js", 
  size: 12, 
  color: "#fff" 
};

// Edge within the linked repo (intra-repository)
const intraEdge: GraphEdge = { source: 101, target: 102, type: "import" };

// CROSS edge: source in primary, target in linked repo
const crossEdge: GraphEdge = { source: 1, target: 101, type: "call" };

const linkedProject: LinkedProject = {
  project: "github.com/other/repo",
  nodes: [linkedNode],
  edges: [intraEdge],
  offset: { x: 300, y: 0, z: 0 },   // position beside primary galaxy
  cross_edges: [crossEdge],
};

Integrating with GraphScene

The GraphScene component consumes these data structures to render the complete multi-repository visualization:

<GraphScene
  data={primaryGraphData}
  missed={null}
  highlightedIds={highlightedIds}
  cameraTarget={cameraTarget}
  showLabels={true}
  display={displaySettings}
  onNodeClick={handleNodeClick}
>
  {/* GraphScene iterates over linked_projects and draws cross_edges */}
</GraphScene>

Internally, the component offsets the linked nodes using the offset coordinates, then invokes EdgeLines with nodes={data.nodes} (primary) and targetNodes={offsetNodes} (linked) to draw the cross-repository connections.

Summary

• CROSS_ edges* explicitly link nodes in the primary repository to nodes in external linked repositories within the Codebase-Memory-MCP visualization system.
• The LinkedProject interface in graph-ui/src/lib/types.ts stores these edges separately from intra-repository edges in the cross_edges array.
• Visibility filtering in GraphTab.tsx ensures cross edges only render when both source and target nodes are present in the current view.
• GraphScene.tsx renders these connections with enhanced opacity (0.85) to distinguish inter-repository dependencies from internal code relationships.
• The backend layout3d.c engine generates these edges, allowing the frontend to maintain independent spatial layouts for each repository while visualizing cross-boundary dependencies.

Frequently Asked Questions

How do CROSS_* edges differ from standard edges in the data model?

While both use the GraphEdge type structure with source, target, and type properties, CROSS edges reside in the cross_edges array of the LinkedProject interface rather than the standard edges array. Semantically, cross edges always connect a node from the primary repository (source) to a node in an external linked repository (target), whereas standard edges connect nodes within the same repository boundary.

What determines whether a cross edge appears in the visualization?

Three conditions control visibility according to the filtering logic in GraphTab.tsx: the edge type must exist in enabledEdgeTypes, the source node ID must be present in the primary graph's nodeIds set, and the target node ID must exist in the linked project's visible nodes (lpIds). If any condition fails, the edge is filtered from the rendered view.

Why are cross edges rendered with 0.85 opacity instead of the default value?

The opacity value of 0.85, specified in GraphScene.tsx, provides higher visual prominence than standard intra-repository edges. This deliberate styling choice makes cross-repository dependencies immediately noticeable to users examining the 3D graph, highlighting architectural boundaries and external dependencies that span multiple codebases.

Can cross edges reference relationships in both directions between repositories?

The current implementation in graph-ui/src/lib/types.ts supports unidirectional linking from the primary repository to linked projects through the cross_edges array. While the data model uses generic source and target fields that could theoretically support bidirectional relationships, the typical pattern shown in layout3d.c output and consumed by GraphScene.tsx treats the primary repository as the source context and linked projects as target contexts for dependency visualization.

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