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

> Understand CROSS_* edges in Codebase-Memory-MCP for visualizing cross-repository dependencies. Link nodes across repositories and see dependencies clearly.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: deep-dive
- Published: 2026-07-28

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/lib/types.ts), the `LinkedProject` interface declares:

```typescript
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```typescript
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/components/GraphScene.tsx), the rendering logic applies distinct visual styling to emphasize these boundary-crossing relationships:

```tsx
{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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/types.ts), preserving the separation between intra-repository edges (`edges`) and inter-repository edges (`cross_edges`).

3. **Visibility Filtering**: The [`GraphTab.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```typescript
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:

```tsx
<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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/lib/types.ts) stores these edges separately from intra-repository edges in the `cross_edges` array.
- Visibility filtering in [`GraphTab.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/GraphTab.tsx) ensures cross edges only render when both source and target nodes are present in the current view.
- [`GraphScene.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/GraphScene.tsx) renders these connections with enhanced opacity (0.85) to distinguish inter-repository dependencies from internal code relationships.
- The backend [`layout3d.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/layout3d.c) output and consumed by [`GraphScene.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/GraphScene.tsx) treats the primary repository as the source context and linked projects as target contexts for dependency visualization.