Skip to content

LLM Wiki is a cross-platform desktop application that turns your documents into an organized, interlinked knowledge base — automatically. Instead of traditional RAG (retrieve-and-answer from scratch every time), the LLM incrementally builds and maintains a persistent wiki from your sources。

TypeScript

feat: add Louvain community detection to knowledge graph

nash_sua6b0ba973da7
diff --git a/package-lock.json b/package-lock.json
index 4dd48ef1..502e527d 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -21,6 +21,7 @@
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"graphology": "^0.26.0",
+ "graphology-communities-louvain": "^2.0.2",
"graphology-layout-forceatlas2": "^0.10.1",
"i18next": "^26.0.3",
"lucide-react": "^1.7.0",
@@ -4620,6 +4621,34 @@
"graphology-types": ">=0.24.0"
}
},
+ "node_modules/graphology-communities-louvain": {
+ "version": "2.0.2",
+ "resolved": "https://registry.npmjs.org/graphology-communities-louvain/-/graphology-communities-louvain-2.0.2.tgz",
+ "integrity": "sha512-zt+2hHVPYxjEquyecxWXoUoIuN/UvYzsvI7boDdMNz0rRvpESQ7+e+Ejv6wK7AThycbZXuQ6DkG8NPMCq6XwoA==",
+ "license": "MIT",
+ "dependencies": {
+ "graphology-indices": "^0.17.0",
+ "graphology-utils": "^2.4.4",
+ "mnemonist": "^0.39.0",
+ "pandemonium": "^2.4.1"
+ },
+ "peerDependencies": {
+ "graphology-types": ">=0.19.0"
+ }
+ },
+ "node_modules/graphology-indices": {
+ "version": "0.17.0",
+ "resolved": "https://registry.npmjs.org/graphology-indices/-/graphology-indices-0.17.0.tgz",
+ "integrity": "sha512-A7RXuKQvdqSWOpn7ZVQo4S33O0vCfPBnUSf7FwE0zNCasqwZVUaCXePuWo5HBpWw68KJcwObZDHpFk6HKH6MYQ==",
+ "license": "MIT",
+ "dependencies": {
+ "graphology-utils": "^2.4.2",
+ "mnemonist": "^0.39.0"
+ },
+ "peerDependencies": {
+ "graphology-types": ">=0.20.0"
+ }
+ },
"node_modules/graphology-layout-forceatlas2": {
"version": "0.10.1",
"resolved": "https://registry.npmjs.org/graphology-layout-forceatlas2/-/graphology-layout-forceatlas2-0.10.1.tgz",
@@ -6627,6 +6656,15 @@
"url": "https://github.com/sponsors/ljharb"
}
},
+ "node_modules/mnemonist": {
+ "version": "0.39.8",
+ "resolved": "https://registry.npmjs.org/mnemonist/-/mnemonist-0.39.8.tgz",
+ "integrity": "sha512-vyWo2K3fjrUw8YeeZ1zF0fy6Mu59RHokURlld8ymdUPjMlD9EC9ov1/YPqTgqRvUN9nTr3Gqfz29LYAmu0PHPQ==",
+ "license": "MIT",
+ "dependencies": {
+ "obliterator": "^2.0.1"
+ }
+ },
"node_modules/ms": {
"version": "2.1.3",
"resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
@@ -6828,6 +6866,12 @@
"node": ">= 10"
}
},
+ "node_modules/obliterator": {
+ "version": "2.0.5",
+ "resolved": "https://registry.npmjs.org/obliterator/-/obliterator-2.0.5.tgz",
+ "integrity": "sha512-42CPE9AhahZRsMNslczq0ctAEtqk8Eka26QofnqC346BZdHDySk3LWka23LI7ULIw11NmltpiLagIq8gBozxTw==",
+ "license": "MIT"
+ },
"node_modules/on-finished": {
"version": "2.4.1",
"resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz",
@@ -6919,6 +6963,15 @@
"integrity": "sha512-+Sl2UErvtsoajRDKCE5/dBz4DIvHXQQnAxtQTF04OJxY0+DyZXSo5P5Bb7XYWOh81syohlYL24hbDwxedPUJCA==",
"license": "MIT"
},
+ "node_modules/pandemonium": {
+ "version": "2.4.1",
+ "resolved": "https://registry.npmjs.org/pandemonium/-/pandemonium-2.4.1.tgz",
+ "integrity": "sha512-wRqjisUyiUfXowgm7MFH2rwJzKIr20rca5FsHXCMNm1W5YPP1hCtrZfgmQ62kP7OZ7Xt+cR858aB28lu5NX55g==",
+ "license": "MIT",
+ "dependencies": {
+ "mnemonist": "^0.39.2"
+ }
+ },
"node_modules/parent-module": {
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz",
diff --git a/package.json b/package.json
index 5a1ba503..4579f52a 100644
--- a/package.json
+++ b/package.json
@@ -23,6 +23,7 @@
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"graphology": "^0.26.0",
+ "graphology-communities-louvain": "^2.0.2",
"graphology-layout-forceatlas2": "^0.10.1",
"i18next": "^26.0.3",
"lucide-react": "^1.7.0",
diff --git a/src/components/graph/graph-view.tsx b/src/components/graph/graph-view.tsx
index d76bde8c..25098733 100644
--- a/src/components/graph/graph-view.tsx
+++ b/src/components/graph/graph-view.tsx
@@ -3,11 +3,11 @@ import Graph from "graphology"
import { SigmaContainer, useLoadGraph, useRegisterEvents, useSigma } from "@react-sigma/core"
import "@react-sigma/core/lib/style.css"
import forceAtlas2 from "graphology-layout-forceatlas2"
-import { Network, RefreshCw, ZoomIn, ZoomOut, Maximize } from "lucide-react"
+import { Network, RefreshCw, ZoomIn, ZoomOut, Maximize, Layers, Tag } from "lucide-react"
import { Button } from "@/components/ui/button"
import { useWikiStore } from "@/stores/wiki-store"
import { readFile } from "@/commands/fs"
-import { buildWikiGraph, type GraphNode, type GraphEdge } from "@/lib/wiki-graph"
+import { buildWikiGraph, type GraphNode, type GraphEdge, type CommunityInfo } from "@/lib/wiki-graph"
import { normalizePath } from "@/lib/path-utils"
const NODE_TYPE_COLORS: Record<string, string> = {
@@ -32,6 +32,23 @@ const NODE_TYPE_LABELS: Record<string, string> = {
other: "Other",
}
+const COMMUNITY_COLORS = [
+ "#60a5fa", // blue-400
+ "#4ade80", // green-400
+ "#fb923c", // orange-400
+ "#c084fc", // purple-400
+ "#f87171", // red-400
+ "#2dd4bf", // teal-400
+ "#facc15", // yellow-400
+ "#f472b6", // pink-400
+ "#a78bfa", // violet-400
+ "#38bdf8", // sky-400
+ "#34d399", // emerald-400
+ "#fbbf24", // amber-400
+]
+
+type ColorMode = "type" | "community"
+
const BASE_NODE_SIZE = 8
const MAX_NODE_SIZE = 28
@@ -68,7 +85,7 @@ function nodeSize(linkCount: number, maxLinks: number): number {
const positionCache = new Map<string, { x: number; y: number }>()
let lastLayoutDataKey = ""
-function GraphLoader({ nodes, edges }: { nodes: GraphNode[]; edges: GraphEdge[] }) {
+function GraphLoader({ nodes, edges, colorMode }: { nodes: GraphNode[]; edges: GraphEdge[]; colorMode: ColorMode }) {
const loadGraph = useLoadGraph()
useEffect(() => {
@@ -79,16 +96,19 @@ function GraphLoader({ nodes, edges }: { nodes: GraphNode[]; edges: GraphEdge[]
const maxLinks = Math.max(...nodes.map((n) => n.linkCount), 1)
for (const node of nodes) {
- // Reuse cached positions if available, otherwise random
const cached = positionCache.get(node.id)
+ const color = colorMode === "community"
+ ? COMMUNITY_COLORS[node.community % COMMUNITY_COLORS.length]
+ : nodeColor(node.type)
graph.addNode(node.id, {
x: cached?.x ?? Math.random() * 100,
y: cached?.y ?? Math.random() * 100,
size: nodeSize(node.linkCount, maxLinks),
- color: nodeColor(node.type),
+ color,
label: node.label,
nodeType: node.type,
nodePath: node.path,
+ community: node.community,
})
}
@@ -135,7 +155,7 @@ function GraphLoader({ nodes, edges }: { nodes: GraphNode[]; edges: GraphEdge[]
}
loadGraph(graph)
- }, [loadGraph, nodes, edges])
+ }, [loadGraph, nodes, edges, colorMode])
return null
}
@@ -238,9 +258,11 @@ export function GraphView() {
const [nodes, setNodes] = useState<GraphNode[]>([])
const [edges, setEdges] = useState<GraphEdge[]>([])
+ const [communities, setCommunities] = useState<CommunityInfo[]>([])
const [loading, setLoading] = useState(false)
const [error, setError] = useState<string | null>(null)
const [hoveredType, setHoveredType] = useState<string | null>(null)
+ const [colorMode, setColorMode] = useState<ColorMode>("type")
const lastLoadedVersion = useRef(-1)
const loadGraph = useCallback(async () => {
@@ -251,6 +273,7 @@ export function GraphView() {
const result = await buildWikiGraph(normalizePath(project.path))
setNodes(result.nodes)
setEdges(result.edges)
+ setCommunities(result.communities)
lastLoadedVersion.current = useWikiStore.getState().dataVersion
} catch (err) {
const message = err instanceof Error ? err.message : "Failed to build graph"
@@ -339,10 +362,29 @@ export function GraphView() {
<span className="rounded bg-muted px-1.5 py-0.5">{edges.length} links</span>
</div>
</div>
- <Button variant="ghost" size="sm" onClick={loadGraph} className="text-xs gap-1">
- <RefreshCw className="h-3.5 w-3.5" />
- Reload
- </Button>
+ <div className="flex items-center gap-1">
+ <Button
+ variant={colorMode === "type" ? "secondary" : "ghost"}
+ size="sm"
+ onClick={() => setColorMode("type")}
+ className="text-xs gap-1 h-7"
+ >
+ <Tag className="h-3 w-3" />
+ Type
+ </Button>
+ <Button
+ variant={colorMode === "community" ? "secondary" : "ghost"}
+ size="sm"
+ onClick={() => setColorMode("community")}
+ className="text-xs gap-1 h-7"
+ >
+ <Layers className="h-3 w-3" />
+ Community
+ </Button>
+ <Button variant="ghost" size="sm" onClick={loadGraph} className="text-xs gap-1 h-7">
+ <RefreshCw className="h-3.5 w-3.5" />
+ </Button>
+ </div>
</div>
{/* Graph canvas */}
@@ -391,38 +433,69 @@ export function GraphView() {
},
}}
>
- <GraphLoader nodes={nodes} edges={edges} />
+ <GraphLoader nodes={nodes} edges={edges} colorMode={colorMode} />
<EventHandler onNodeClick={handleNodeClick} />
<ZoomControls />
</SigmaContainer>
{/* Legend */}
- <div className="absolute bottom-3 left-3 rounded-lg border bg-background/90 backdrop-blur-sm px-3 py-2 text-xs shadow-sm">
- <div className="mb-1.5 font-semibold text-foreground">Node Types</div>
- <div className="flex flex-col gap-0.5">
- {Object.entries(NODE_TYPE_LABELS)
- .filter(([type]) => (typeCounts[type] ?? 0) > 0)
- .map(([type, label]) => (
- <div
- key={type}
- className="flex items-center gap-2 rounded px-1 py-0.5 transition-colors hover:bg-accent/50"
- onMouseEnter={() => setHoveredType(type)}
- onMouseLeave={() => setHoveredType(null)}
- >
- <span
- className="inline-block h-3 w-3 rounded-full shrink-0 shadow-sm"
- style={{
- backgroundColor: NODE_TYPE_COLORS[type],
- boxShadow: `0 0 4px ${hexToRgba(NODE_TYPE_COLORS[type] ?? "#94a3b8", 0.4)}`,
- }}
- />
- <span className={hoveredType === type ? "text-foreground font-medium" : "text-muted-foreground"}>
- {label}
- </span>
- <span className="text-muted-foreground/60 ml-auto">{typeCounts[type]}</span>
- </div>
- ))}
- </div>
+ <div className="absolute bottom-3 left-3 rounded-lg border bg-background/90 backdrop-blur-sm px-3 py-2 text-xs shadow-sm max-w-[260px]">
+ {colorMode === "type" ? (
+ <>
+ <div className="mb-1.5 font-semibold text-foreground">Node Types</div>
+ <div className="flex flex-col gap-0.5">
+ {Object.entries(NODE_TYPE_LABELS)
+ .filter(([type]) => (typeCounts[type] ?? 0) > 0)
+ .map(([type, label]) => (
+ <div
+ key={type}
+ className="flex items-center gap-2 rounded px-1 py-0.5 transition-colors hover:bg-accent/50"
+ onMouseEnter={() => setHoveredType(type)}
+ onMouseLeave={() => setHoveredType(null)}
+ >
+ <span
+ className="inline-block h-3 w-3 rounded-full shrink-0 shadow-sm"
+ style={{
+ backgroundColor: NODE_TYPE_COLORS[type],
+ boxShadow: `0 0 4px ${hexToRgba(NODE_TYPE_COLORS[type] ?? "#94a3b8", 0.4)}`,
+ }}
+ />
+ <span className={hoveredType === type ? "text-foreground font-medium" : "text-muted-foreground"}>
+ {label}
+ </span>
+ <span className="text-muted-foreground/60 ml-auto">{typeCounts[type]}</span>
+ </div>
+ ))}
+ </div>
+ </>
+ ) : (
+ <>
+ <div className="mb-1.5 font-semibold text-foreground">Communities</div>
+ <div className="flex flex-col gap-0.5">
+ {communities.map((c) => (
+ <div
+ key={c.id}
+ className="flex items-center gap-2 rounded px-1 py-0.5 transition-colors hover:bg-accent/50"
+ >
+ <span
+ className="inline-block h-3 w-3 rounded-full shrink-0 shadow-sm"
+ style={{
+ backgroundColor: COMMUNITY_COLORS[c.id % COMMUNITY_COLORS.length],
+ boxShadow: `0 0 4px ${hexToRgba(COMMUNITY_COLORS[c.id % COMMUNITY_COLORS.length], 0.4)}`,
+ }}
+ />
+ <span className="text-muted-foreground truncate" title={c.topNodes.join(", ")}>
+ {c.topNodes[0] ?? `Cluster ${c.id}`}
+ </span>
+ <span className="text-muted-foreground/60 ml-auto shrink-0">{c.nodeCount}</span>
+ {c.cohesion < 0.15 && c.nodeCount >= 3 && (
+ <span className="text-amber-500 shrink-0" title={`Low cohesion: ${c.cohesion.toFixed(2)}`}>!</span>
+ )}
+ </div>
+ ))}
+ </div>
+ </>
+ )}
</div>
</div>
diff --git a/src/lib/wiki-graph.ts b/src/lib/wiki-graph.ts
index b3370835..0c6cea1a 100644
--- a/src/lib/wiki-graph.ts
+++ b/src/lib/wiki-graph.ts
@@ -2,6 +2,8 @@ import { readFile, listDirectory } from "@/commands/fs"
import type { FileNode } from "@/types/wiki"
import { buildRetrievalGraph, calculateRelevance } from "./graph-relevance"
import { normalizePath } from "@/lib/path-utils"
+import Graph from "graphology"
+import louvain from "graphology-communities-louvain"
export interface GraphNode {
id: string
@@ -9,6 +11,7 @@ export interface GraphNode {
type: string
path: string
linkCount: number // inbound + outbound
+ community: number // community id from Louvain detection
}
export interface GraphEdge {
@@ -17,6 +20,98 @@ export interface GraphEdge {
weight: number // relevance score between source and target
}
+export interface CommunityInfo {
+ id: number
+ nodeCount: number
+ cohesion: number // intra-community edge density
+ topNodes: string[] // top nodes by linkCount (labels)
+}
+
+/** Run Louvain community detection and compute cohesion per community */
+function detectCommunities(
+ nodes: { id: string; label: string; linkCount: number }[],
+ edges: GraphEdge[],
+): { assignments: Map<string, number>; communities: CommunityInfo[] } {
+ if (nodes.length === 0) {
+ return { assignments: new Map(), communities: [] }
+ }
+
+ const g = new Graph()
+ for (const node of nodes) {
+ g.addNode(node.id)
+ }
+ for (const edge of edges) {
+ if (g.hasNode(edge.source) && g.hasNode(edge.target)) {
+ const key = `${edge.source}->${edge.target}`
+ if (!g.hasEdge(key) && !g.hasEdge(`${edge.target}->${edge.source}`)) {
+ g.addEdgeWithKey(key, edge.source, edge.target, { weight: edge.weight })
+ }
+ }
+ }
+
+ // Run Louvain — returns { nodeId: communityId }
+ const communityMap: Record<string, number> = louvain(g, { resolution: 1 })
+ const assignments = new Map(Object.entries(communityMap).map(([k, v]) => [k, v as number]))
+
+ // Group nodes by community
+ const groups = new Map<number, string[]>()
+ for (const [nodeId, commId] of assignments) {
+ const list = groups.get(commId) ?? []
+ list.push(nodeId)
+ groups.set(commId, list)
+ }
+
+ // Build edge lookup for cohesion calculation
+ const edgeSet = new Set<string>()
+ for (const edge of edges) {
+ edgeSet.add(`${edge.source}:::${edge.target}`)
+ edgeSet.add(`${edge.target}:::${edge.source}`)
+ }
+
+ // Build label + linkCount lookup
+ const nodeInfo = new Map(nodes.map((n) => [n.id, { label: n.label, linkCount: n.linkCount }]))
+
+ // Compute per-community info
+ const communities: CommunityInfo[] = []
+ for (const [commId, memberIds] of groups) {
+ const n = memberIds.length
+ // Cohesion = actual intra-community edges / possible edges
+ let intraEdges = 0
+ for (let i = 0; i < memberIds.length; i++) {
+ for (let j = i + 1; j < memberIds.length; j++) {
+ if (edgeSet.has(`${memberIds[i]}:::${memberIds[j]}`)) {
+ intraEdges++
+ }
+ }
+ }
+ const possibleEdges = n > 1 ? (n * (n - 1)) / 2 : 1
+ const cohesion = intraEdges / possibleEdges
+
+ // Top nodes by linkCount
+ const sorted = [...memberIds].sort(
+ (a, b) => (nodeInfo.get(b)?.linkCount ?? 0) - (nodeInfo.get(a)?.linkCount ?? 0),
+ )
+ const topNodes = sorted.slice(0, 5).map((id) => nodeInfo.get(id)?.label ?? id)
+
+ communities.push({ id: commId, nodeCount: n, cohesion, topNodes })
+ }
+
+ // Sort by nodeCount descending
+ communities.sort((a, b) => b.nodeCount - a.nodeCount)
+
+ // Re-number community IDs sequentially (0, 1, 2, ...)
+ const idRemap = new Map<number, number>()
+ communities.forEach((c, idx) => {
+ idRemap.set(c.id, idx)
+ c.id = idx
+ })
+ for (const [nodeId, oldId] of assignments) {
+ assignments.set(nodeId, idRemap.get(oldId) ?? 0)
+ }
+
+ return { assignments, communities }
+}
+
const WIKILINK_REGEX = /\[\[([^\]|]+?)(?:\|[^\]]+?)?\]\]/g
function flattenMdFiles(nodes: FileNode[]): FileNode[] {
@@ -63,19 +158,19 @@ function fileNameToId(fileName: string): string {
export async function buildWikiGraph(
projectPath: string,
-): Promise<{ nodes: GraphNode[]; edges: GraphEdge[] }> {
+): Promise<{ nodes: GraphNode[]; edges: GraphEdge[]; communities: CommunityInfo[] }> {
const wikiRoot = `${normalizePath(projectPath)}/wiki`
let tree: FileNode[]
try {
tree = await listDirectory(wikiRoot)
} catch {
- return { nodes: [], edges: [] }
+ return { nodes: [], edges: [], communities: [] }
}
const mdFiles = flattenMdFiles(tree)
if (mdFiles.length === 0) {
- return { nodes: [], edges: [] }
+ return { nodes: [], edges: [], communities: [] }
}
// Build a map of id -> node data
@@ -159,15 +254,25 @@ export async function buildWikiGraph(
return { source: e.source, target: e.target, weight }
})
+ // Build preliminary nodes for community detection
+ const prelimNodes = Array.from(nodeMap.values()).map((n) => ({
+ id: n.id,
+ label: n.label,
+ linkCount: linkCounts.get(n.id) ?? 0,
+ }))
+
+ const { assignments, communities } = detectCommunities(prelimNodes, edges)
+
const nodes: GraphNode[] = Array.from(nodeMap.values()).map((n) => ({
id: n.id,
label: n.label,
type: n.type,
path: n.path,
linkCount: linkCounts.get(n.id) ?? 0,
+ community: assignments.get(n.id) ?? 0,
}))
- return { nodes, edges }
+ return { nodes, edges, communities }
}
function resolveTarget(