Workspace Graph

Visual knowledge graph of workspace content, memories, decisions, milestones, and artifacts with semantic relationship edges.

Overview

The Workspace Graph is an interactive D3.js force-directed visualization that renders all entities in a document workspace as a connected node graph. Each item in the workspace -- documents, memories, decisions, milestones, and artifacts -- appears as a node. Relationships between items are drawn as directed edges with labeled connection types.

The graph is built from two layers of edges:

  • Explicit edges -- relationship links that were explicitly recorded between items (e.g., a decision that supersedes another, or an artifact that implements a milestone). These appear as solid colored lines with directional arrow markers.
  • Similarity edges -- automatically computed semantic similarity links between nodes based on their embedding vectors. These appear as faint dashed lines and require an embeddings endpoint to be configured for the project.
  • Provenance edges -- dotted lines tracing which chat session or message produced a given item.

The layout uses a force simulation. Nodes are initially positioned using server-computed PCA coordinates derived from embedding space, then a D3 force simulation refines the positions with cluster gravity, charge repulsion, link forces, and collision avoidance.

Note: Similarity edges require an embeddings model to be provisioned for the project. Without embeddings, only explicit and provenance edges are rendered.

Accessing the Graph

The Workspace Graph is accessible from the Document Workspace view. Open any chat that has a document workspace enabled and navigate to the workspace tab. The graph renders automatically when the workspace contains at least one node.

When the workspace is empty, a placeholder state is shown in place of the graph. Add documents, create memories, or record decisions to populate the graph.

The graph can be refreshed at any time by calling the JavaScript API:

JavaScript
WorkspaceGraph.refresh();

The graph data is fetched from:

Endpoint
GET /chat/api/workspaces/{workspaceId}/graph

Node Types

Five node types are rendered in the graph. Each type has a distinct shape and color to make identification fast at a glance.

Type Shape Description
document Rounded rectangle An uploaded file in the workspace. Node size scales with chunk count -- documents with more text content appear larger. The popover shows the chunk count and a preview excerpt.
memory Circle A saved memory associated with the workspace. Memories are facts, preferences, or instructions that the model has recorded. The popover shows the memory category and source type (model or user).
decision Diamond (rotated square) An architectural or design decision captured in the workspace. Decisions record the chosen outcome, the reasoning, and any alternatives that were considered. The diamond shape visually signals a decision point.
milestone Hexagon A project milestone or goal tracked in the workspace. Milestones represent significant progress markers or deliverables.
artifact Wide rectangle A generated artifact -- typically a code file, report, or other produced output. Node size scales with file byte size. The popover shows the formatted file size.

Node radius is computed from two components: a base content size (scaled from chunk count or byte size) and a degree boost that makes highly connected nodes appear larger (up to 20 px additional radius from connections). Total radius is clamped between 20 and 65 pixels.

Edge / Relationship Types

Explicit edges between nodes carry a typed relationship. The relationship is displayed as a label near the midpoint of the edge on hover.

Relationship Color Meaning
supports Green The source node provides evidence or reasoning in favor of the target.
supersedes Orange The source node replaces or overrides the target (e.g., a newer decision superseding an older one).
blocks Red The source node prevents or blocks progress on the target.
implements Blue The source node is a concrete implementation of the target (e.g., an artifact implementing a milestone).
contradicts Red (dashed) The source node is in conflict with the target. Rendered with a dashed stroke to visually distinguish it from blocks.
refines Teal The source node extends or clarifies the target without replacing it.
similar Dark gray (faint) The nodes have high semantic similarity. This relationship appears on explicit similarity edges; automatic similarity edges use a separate faint dotted style.

Edge Visual Styles

Edge Class Style Arrow
Explicit relationship Solid, 1.5 px, relationship-colored (except contradicts which is dashed) Colored arrowhead matching the edge
Similarity (auto) Faint dotted, 0.75 px, dark gray, 35% opacity None
Provenance Dotted, 1 px, gray Gray arrowhead

When multiple edges exist between the same pair of nodes, each edge is rendered as a curved arc with increasing curvature and alternating sweep direction so the edges do not overlap.

Filtering and Search

Type Filter Chips

The filter bar displays a chip button for each node type (Document, Memory, Decision, Milestone, Artifact). Each chip shows a colored dot matching the node color. Clicking a chip toggles that type on or off. When a type is disabled, its nodes are hidden and the force simulation reheats so remaining nodes redistribute.

All types are enabled by default. Disabling a type also hides any edges that connect exclusively to hidden nodes.

Text Search

The search input filters nodes by name and preview text. Matching nodes remain fully opaque; non-matching nodes fade to 10% opacity. Matching nodes briefly scale up (1.3x) and back as a pulse animation to draw attention. Search is debounced at 200 ms to avoid thrashing the layout on every keystroke.

Cluster Select

The cluster dropdown isolates a single semantic cluster. When a cluster is selected, only nodes belonging to that cluster are shown at full opacity. Nodes from other clusters fade out and their edges are hidden.

Filter Interaction

All three filters (type chips, search, cluster) apply simultaneously. A node must pass all active filters to appear at full opacity with interactive pointer events enabled.

Tooltips and Popovers

Hover Tooltip

Hovering over a node displays a lightweight tooltip positioned near the cursor. The tooltip contains:

  • Node type label in the node's color (e.g., "DOCUMENT", "DECISION").
  • Node name in medium weight.
  • A preview excerpt of the content (up to 100 characters).
  • Creation date.

The tooltip is automatically repositioned to stay within the canvas bounds when it would otherwise overflow the right or bottom edge.

Hovering over an edge highlights it (thicker stroke, full opacity) and shows the relationship label near the midpoint of the edge.

Click Popover

Clicking a node opens a detail popover in the center of the canvas. The popover provides:

  • A colored type badge and a close button.
  • The full node name.
  • Type-specific metadata: category, source type, creation date, chunk count (documents), or file size (artifacts).
  • A preview of the node's content.
  • A connections list showing all adjacent nodes with their relationship type and a colored type dot.

Clicking a connection item in the popover navigates directly to the connected node's popover. Clicking outside the popover or on another node closes it.

Color Coding

Node colors and edge colors follow a consistent scheme across the graph, filter chips, type dots, and popovers.

Item Color Hex
Document node Blue #4a9eff
Memory node Green #6bcf7f
Decision node Orange #f0a050
Milestone node Purple #b07ce8
Artifact node Teal #5cc6c6
supports edge Green #6bcf7f
supersedes edge Orange #f0a050
blocks edge Red #e05050
implements edge Blue #4a9eff
contradicts edge Red (dashed) #e05050
refines edge Teal #5cc6c6
similar edge Dark gray #444

All nodes are rendered at 85% fill opacity to allow edges behind overlapping nodes to remain faintly visible.

Diagnostics

When the graph contains nodes but no edges are present, the graph displays a diagnostic banner above the canvas with an actionable explanation. Three conditions are detected:

Condition Message
No embeddings endpoint configured Prompts the user to provision an embeddings model (e.g., nomic-embed-text, bge-large, text-embedding-3-small) for the project.
Embeddings endpoint exists but no embeddings generated Prompts the user to re-upload documents or add new content to trigger embedding generation.
Embeddings exist but no pairs meet the similarity threshold Suggests adding more content or lowering the similarity threshold.

The diagnostic banner is removed automatically the next time the graph is refreshed and edges are present.

Related Pages