mdvdb graph

Show graph data (nodes, edges, automatic communities, Topics, and edge types) for visualization. The graph can be generated at document level (one node per file) or chunk level (one node per chunk within each file), then scoped by a folder or analyzed through a named Shard.

Usage

mdvdb graph [OPTIONS]

Arguments

This command takes no arguments.

Options

--level <LEVEL>

Controls the granularity of the graph nodes.

At document level, edges come from body links and whole-value frontmatter Relations. At chunk level, edges come from embedding similarity (the top 5 most similar cross-file chunks for each chunk).

--path <PREFIX>

Restricts the graph to files whose paths start with the given prefix. Only nodes matching the prefix are included, and only edges between matching nodes are returned.

# Graph only for files under docs/
mdvdb graph --path docs/

# Graph only for API documentation
mdvdb graph --path docs/api/

--shard <ID>

Uses the named Shard as an independent analysis corpus. Only indexed documents below the Shard folder participate in automatic clustering, and only that Shard’s local Topic definitions are used. Collection, parent-Shard, and sibling Topics do not leak into the response.

--path may be used together with --shard to project a descendant folder without changing the Shard-wide cluster and Topic identities:

mdvdb graph --shard research
mdvdb graph --shard research --path work/research/drafts

A descendant path narrows the visible graph, an ancestor path clamps to the Shard, and a disjoint path returns an empty graph. In every case, returned edges form a strict induced graph: both endpoints are visible.

Shard automatic clusters are computed lazily from existing stored document embeddings and cached outside the index. Graph reads never initialize an embedding provider. When local Topic centroids need to be created after a definition change, topology and automatic clusters remain available and the optional analysis.topics status reports needs_ingest.

--compact

--compact requires --json and emits a minified, versioned app wire format. Repeated edge paragraphs move into one response-level contexts array; each edge uses context_index instead of repeating context_text. The alias --intern-contexts has identical behavior.

mdvdb graph --json --compact
mdvdb graph --shard research --json --compact
mdvdb graph --level chunk --json --compact

Consumers must check format and version before interpreting the response. Compact version 1 uses format: "mdvdb.graph.compact". Chunk similarity edges have no context, so their context_index is absent and contexts is normally empty.

Global Options

These options apply to all commands. See Commands Index for details.

Human-Readable Output

When run without --json, graph displays a summary of the graph data:

Document Level

  ● Graph Data

  Level:     Document
  Nodes:     42
  Edges:     87
  Clusters:  5

    • Cluster 0 — api-reference, endpoints, authentication (12 docs)
    • Cluster 1 — setup, installation, configuration (8 docs)
    • Cluster 2 — architecture, design, patterns (10 docs)
    • Cluster 3 — guides, tutorials, howto (7 docs)
    • Cluster 4 — changelog, releases, versions (5 docs)

Chunk Level

  ● Graph Data

  Level:     Chunk
  Chunks:    156
  Edges:     780
  Weights:   0.7234 — 0.9812

  Sample labels:
    • Introduction > Getting Started
    • API > Authentication > OAuth2
    • Architecture > Data Flow
    • Setup > Prerequisites
    • Deployment > Docker

Output Elements

Examples

# Show document-level graph summary
mdvdb graph

# Show chunk-level graph summary
mdvdb graph --level chunk

# Show document-level graph as JSON
mdvdb graph --json

# Show chunk-level graph as JSON
mdvdb graph --level chunk --json

# Restrict graph to a path prefix
mdvdb graph --path docs/api/

# Chunk-level graph for a specific directory as JSON
mdvdb graph --level chunk --path src/ --json

# Analyze a Shard, then project one descendant folder
mdvdb graph --shard research --path work/research/drafts --json

# Minified app wire format with interned edge contexts
mdvdb graph --shard research --json --compact

# Graph with debug logging
mdvdb graph -vv

JSON Output

GraphData (--json)

The JSON output is a GraphData object containing nodes, edges, and clusters arrays.

Document Level

{
  "nodes": [
    {
      "id": "docs/architecture.md",
      "path": "docs/architecture.md",
      "label": null,
      "chunk_index": null,
      "cluster_id": 2,
      "custom_cluster_id": null
    },
    {
      "id": "docs/api/endpoints.md",
      "path": "docs/api/endpoints.md",
      "label": null,
      "chunk_index": null,
      "cluster_id": 0,
      "custom_cluster_id": null
    }
  ],
  "edges": [
    {
      "source": "docs/architecture.md",
      "target": "docs/api/endpoints.md",
      "weight": null,
      "relationship_type": "api-reference",
      "strength": 0.82,
      "context_text": "See the API endpoints documentation for details.",
      "edge_cluster_id": 1,
      "field": null
    }
  ],
  "clusters": [
    {
      "id": 0,
      "label": "api-reference, endpoints, authentication",
      "keywords": ["api", "endpoints", "authentication", "rest", "http"],
      "member_count": 12
    },
    {
      "id": 2,
      "label": "architecture, design, patterns",
      "keywords": ["architecture", "design", "patterns", "system", "components"],
      "member_count": 10
    }
  ],
  "level": "document",
  "analysis": {
    "context": "shard",
    "shard_id": "research",
    "shard_path": "work/research",
    "clusters": "ready",
    "topics": "ready"
  },
  "edge_clusters": [
    {
      "id": 0,
      "label": "api-documentation",
      "keywords": ["api", "documentation", "reference"],
      "member_count": 8
    },
    {
      "id": 1,
      "label": "setup-prerequisites",
      "keywords": ["setup", "install", "configure"],
      "member_count": 5
    }
  ]
}

Chunk Level

{
  "nodes": [
    {
      "id": "docs/architecture.md#0",
      "path": "docs/architecture.md",
      "label": "Introduction",
      "chunk_index": 0,
      "cluster_id": 2,
      "custom_cluster_id": null,
      "size": 1234.0
    },
    {
      "id": "docs/architecture.md#1",
      "path": "docs/architecture.md",
      "label": "Architecture > Data Flow",
      "chunk_index": 1,
      "cluster_id": 2,
      "custom_cluster_id": null,
      "size": 890.0
    }
  ],
  "edges": [
    {
      "source": "docs/architecture.md#1",
      "target": "docs/api/endpoints.md#0",
      "weight": 0.8723,
      "field": null
    }
  ],
  "clusters": [
    {
      "id": 0,
      "label": "api-reference, endpoints",
      "keywords": ["api", "endpoints", "authentication"],
      "member_count": 12
    }
  ],
  "level": "chunk"
}

GraphData Fields

GraphAnalysisInfo

Cluster, Topic, and edge-type summaries are pruned to entries represented by the visible graph and recounted from unique visible documents (or visible edges for edge types). Chunk nodes inherit their parent document’s assignments, so legend counts remain document counts.

GraphNode Fields

GraphEdge Fields

GraphCluster Fields

CompactGraphData (--json --compact)

{
  "format": "mdvdb.graph.compact",
  "version": 1,
  "nodes": [
    {
      "id": "docs/architecture.md",
      "path": "docs/architecture.md",
      "label": null,
      "chunk_index": null,
      "cluster_id": 2,
      "custom_cluster_id": null
    },
    {
      "id": "docs/api/endpoints.md",
      "path": "docs/api/endpoints.md",
      "label": null,
      "chunk_index": null,
      "cluster_id": 0,
      "custom_cluster_id": null
    }
  ],
  "edges": [
    {
      "source": "docs/architecture.md",
      "target": "docs/api/endpoints.md",
      "weight": null,
      "context_index": 0,
      "field": null
    }
  ],
  "contexts": ["See the API endpoints documentation for details."],
  "clusters": [],
  "level": "document"
}

Compact responses retain nodes, clusters, optional custom_clusters, optional edge_clusters, and optional Shard analysis. Only the edge context representation changes: context_text becomes a zero-based context_index into contexts.

Document vs Chunk Level

Notes

• The graph command opens the index in read-only mode. It never modifies the index.
• Run mdvdb ingest to populate nodes (indexed files/chunks), edges (links and similarities), and clusters.
• At document level, edges come from body links and frontmatter Relations. At chunk level, edges are computed from embedding similarity (top 5 most similar chunks per chunk, excluding intra-file pairs).
• The edge_clusters field is only populated at document level and only when edge clustering has been performed during ingestion (MDVDB_EDGE_EMBEDDINGS=true).
• For chunk-level graphs, the size field on nodes represents the character count of the chunk content, useful for sizing nodes in visualization.
• Cluster IDs at chunk level are inherited from the parent document’s cluster assignment.
• The --path filter applies to both nodes and edges — only edges between matching nodes are included.
• This command is designed to produce JSON output for piping into visualization tools. The human-readable output is a summary; use --json for the full graph data.

Related Commands

• mdvdb edges — Show semantic edges with relationship types and context
• mdvdb links — Show outgoing and incoming links for a specific file
• mdvdb orphans — Find files with no links at all
• mdvdb clusters — Show document clusters with keyword labels
• mdvdb search — Search with --boost-links or --expand for graph-aware results

See Also

• Link Graph — How mdvdb extracts links, builds semantic edges, and computes graph data
• Clustering — How document and edge clustering works
• JSON Output Reference — Complete JSON schema reference for all commands
• Configuration — Graph and edge config vars (MDVDB_EDGE_EMBEDDINGS, MDVDB_EDGE_BOOST_WEIGHT, MDVDB_CLUSTERING_ENABLED)