@andespindola/brainlink 0.1.0-beta.156 → 0.1.0-beta.157

package/README.md

@@ -82,14 +82,14 @@ Legacy `.jsonl.gz` packs are upgraded to `.blpk` automatically on first search/c
 - Built-in MCP stdio server for agent tool integration.
 - Local HTTP API.
 - Realtime graph UI with agent selector and colored knowledge groups.
-- Graph renderer uses a star layout centered on the primary hub while preserving real weighted `[[wiki link]]` edges for backlinks, ranking and context traversal.
+- Graph renderer uses a cauliflower-style hub layout: the primary hub stays centered, segment hubs anchor surrounding lobes, and real weighted `[[wiki link]]` edges stay preserved for backlinks, ranking and context traversal.
 - The full filtered graph stays visible during zoom/pan, rendering every visible node and edge without viewport culling or edge caps in the main view.
 - Graph exploration uses viewport-first chunk streaming (`/api/graph-stream`) with explicit node/edge budgets.
 - Render pipeline uses WebGL in a dedicated worker through `OffscreenCanvas`, keeping the main thread focused on UI controls and details panels.
 - Large graph layout API automatically uses compact payload encoding with link-coverage-aware edge selection to reduce initial client load without hiding major relationships.
 - Large-segment layout spacing now grows logarithmically to keep initial visual density consistent between medium and very large vaults (for example, ~1k vs ~50k notes).
 - Graph coordinates are visually compacted across graph sizes so reset starts from a stable fitted scene and zoom-in progressively reveals local detail.
-- Zoomed-out graph keeps the same flat graph scene and preserves complete filtered relationships without switching to nested subgraphs.
+- Zoomed-out graph summarizes the scene as segment hub clusters, then progressively reveals individual nodes as the user zooms in.
 - Graph reset fits the full graph scene instead of starting in a separate macro overview mode.
 - Graph filtering runs in a dedicated browser worker to keep the UI thread responsive during heavy datasets.
 - Node titles are shown as the user zooms closer, while labels remain bounded to visible on-screen nodes in very large graphs.
@@ -600,11 +600,11 @@ The graph UI shows:
 
 - notes as nodes
 - all non-self `[[wiki links]]` inside `## Context Links` as weighted edges
-- default star layout centered on the primary hub, without rewriting or flattening underlying relationships
+- default cauliflower-style layout centered on the primary hub, with segment hubs anchoring surrounding lobes and without rewriting or flattening underlying relationships
 - details opened in a non-modal side panel (tags, outgoing links, backlinks, full Markdown content), so zoom and pan remain available while inspecting data
 - neutral graph nodes with segment/group metadata
 - agent selector (id-only labels) for isolated views
-- context selector for segment-scoped star subgraphs derived from the visual graph context
+- context selector for segment-scoped cauliflower subgraphs derived from the visual graph context
 - graph filter matches title, path, tags and note content
 - graph filter keeps hub context nodes visible (`Memory Hub`/`MOC`/high-degree fallback) to preserve relationship readability
 - realtime refresh while watch mode is enabled
@@ -612,14 +612,14 @@ The graph UI shows:
 - wheel zoom (including `cmd+scroll` and `ctrl+scroll`) anchored to cursor position for faster navigation in large graphs
 - wheel/button zoom updates immediately at the cursor anchor without delayed focus-transition interpolation
 - Bloom-like scene navigation: reset fits the current graph scene, wheel zoom stays anchored to the cursor, and worker-driven WebGL rendering keeps pan/zoom interaction responsive
-- zoom-out floor for large and massive graphs to keep the scene reachable without switching into a separate macro graph mode
+- zoom-out cluster mode that shows segment hub clusters first, then reveals local nodes as zoom increases
 - keyboard shortcuts: `+` zoom in, `-` zoom out, `0` reset fit
 - click on a node opens its details panel; double-click on empty canvas zooms in at cursor position
 - floating graph totals (notes, links, tags) below the Brainlink title
 - graph rendering safeguards (batched GPU draw calls, lower redraw rate, zoom-aware interaction)
 - adaptive CPU safeguards for large graphs: idle frame pacing, throttled background physics updates and cached viewport dimensions to reduce redraw/layout overhead while preserving interaction responsiveness
 - worker-first WebGL rendering with Canvas fallback when `OffscreenCanvas` or worker rendering is unavailable
-- large graph view keeps a single-level graph model across zoom levels, renders the full filtered scene instead of viewport-sampled subsets, and shows node titles as zoom approaches readable scale
+- large graph view keeps one semantic graph model across zoom levels, uses segment clusters at high zoom-out, and shows node titles as zoom approaches readable scale
 
 The server indexes before starting by default. Use `--no-index` to skip that step:
 

package/dist/application/get-graph-layout.js

@@ -2,10 +2,10 @@ import { createHash } from 'node:crypto';
 import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { addVisualContextEdges } from '../domain/graph-contexts.js';
-import { createStarGraphLayout } from '../domain/graph-layout.js';
+import { createCauliflowerGraphLayout } from '../domain/graph-layout.js';
 import { indexStoragePath } from '../infrastructure/file-index.js';
 import { getGraphSummary } from './get-graph-summary.js';
-const graphLayoutVersion = 6;
+const graphLayoutVersion = 7;
 const graphLayoutCache = new Map();
 const safeCacheSegment = (value, fallback) => value?.replace(/[^a-zA-Z0-9_-]/g, '_') || fallback;
 const graphLayoutStoragePath = (vaultPath, options) => {
@@ -48,14 +48,14 @@ const createGraphSignature = (graph) => {
         .digest('hex');
 };
 const createLayout = (graph) => {
-    const rawLayout = createStarGraphLayout(graph);
+    const rawLayout = createCauliflowerGraphLayout(graph);
     return {
         ...rawLayout,
         nodes: rawLayout.nodes.map((node) => ({ ...node, content: '' }))
     };
 };
 const filterGraphByContext = (graph, context) => {
-    const baseLayout = createStarGraphLayout(graph);
+    const baseLayout = createCauliflowerGraphLayout(graph);
     const selectedNodeIds = new Set(baseLayout.nodes
         .filter((node) => node.segment === context)
         .map((node) => node.id));

package/dist/application/get-graph-stream-chunk.js

@@ -145,8 +145,8 @@ const selectMidNodes = (nodes, cache, input) => {
         relevance.get(node.id) ?? 0
     ]);
 };
-const selectFarClusters = (groups, input, nodeBudget) => {
-    const roots = groups.filter((group) => group.parentId === null);
+const selectFarClusters = (nodes, input, nodeBudget) => {
+    const roots = createSegmentClusters(nodes);
     const padding = Math.max(input.width, input.height) * 0.12;
     const candidates = roots.filter((group) => inViewport(group, input, padding));
     const relevance = new Map();
@@ -166,10 +166,42 @@ const selectFarClusters = (groups, input, nodeBudget) => {
         relevance.get(group.id) ?? 0
     ]);
 };
+const createSegmentClusters = (nodes) => {
+    const nodesBySegment = new Map();
+    nodes.forEach((node) => {
+        const bucket = nodesBySegment.get(node.segment) ?? [];
+        bucket.push(node);
+        nodesBySegment.set(node.segment, bucket);
+    });
+    return Array.from(nodesBySegment.entries()).map(([segment, segmentNodes]) => {
+        const center = segmentNodes.reduce((state, node) => ({
+            x: state.x + node.x,
+            y: state.y + node.y
+        }), { x: 0, y: 0 });
+        const x = center.x / Math.max(segmentNodes.length, 1);
+        const y = center.y / Math.max(segmentNodes.length, 1);
+        const radius = segmentNodes.reduce((largest, node) => Math.max(largest, Math.hypot(node.x - x, node.y - y)), 80);
+        return {
+            id: `segment:${segment}`,
+            level: 0,
+            parentId: null,
+            title: segment,
+            segment,
+            group: segmentNodes[0]?.group ?? segment,
+            x,
+            y,
+            radius: Math.max(radius + 96, 160),
+            nodeIds: segmentNodes.map((node) => node.id),
+            childGroupIds: [],
+            internalEdges: [],
+            externalEdges: []
+        };
+    });
+};
 const collectEdgesForNodes = (allEdges, cache, nodeRows, edgeBudget, maxEdgesPerNode) => {
     const isClusterMode = nodeRows.length > 0 && nodeRows[0]?.[6] === 'cluster';
     if (isClusterMode) {
-        const clusterIds = new Set(nodeRows.map((row) => row[0].replace(/^cluster:/, '')));
+        const clusterSegments = new Set(nodeRows.map((row) => row[5]));
         const clusterEdges = new Map();
         for (let index = 0; index < allEdges.length; index += 1) {
             const edge = allEdges[index];
@@ -179,9 +211,9 @@ const collectEdgesForNodes = (allEdges, cache, nodeRows, edgeBudget, maxEdgesPer
             const targetNode = cache.nodeById.get(edge.target);
             if (!sourceNode || !targetNode)
                 continue;
-            const sourceCluster = sourceNode.group;
-            const targetCluster = targetNode.group;
-            if (!clusterIds.has(sourceCluster) || !clusterIds.has(targetCluster) || sourceCluster === targetCluster)
+            const sourceCluster = sourceNode.segment;
+            const targetCluster = targetNode.segment;
+            if (!clusterSegments.has(sourceCluster) || !clusterSegments.has(targetCluster) || sourceCluster === targetCluster)
                 continue;
             const key = sourceCluster < targetCluster ? `${sourceCluster}|${targetCluster}` : `${targetCluster}|${sourceCluster}`;
             const current = clusterEdges.get(key);
@@ -193,12 +225,12 @@ const collectEdgesForNodes = (allEdges, cache, nodeRows, edgeBudget, maxEdgesPer
             .sort((left, right) => edgeRank(right) - edgeRank(left))
             .slice(0, Math.max(1, edgeBudget))
             .map((edge) => [
-            `cluster:${cache.nodeById.get(edge.source)?.group ?? ''}`,
-            `cluster:${cache.nodeById.get(edge.target ?? '')?.group ?? ''}`,
+            `cluster:segment:${cache.nodeById.get(edge.source)?.segment ?? ''}`,
+            `cluster:segment:${cache.nodeById.get(edge.target ?? '')?.segment ?? ''}`,
             edge.weight,
             edge.priority
         ])
-            .filter((edge) => edge[0] !== edge[1] && edge[0] !== 'cluster:' && edge[1] !== 'cluster:');
+            .filter((edge) => edge[0] !== edge[1] && edge[0] !== 'cluster:segment:' && edge[1] !== 'cluster:segment:');
     }
     const nodeIds = new Set(nodeRows.map((row) => row[0]));
     const collected = new Map();
@@ -267,8 +299,8 @@ export const getGraphStreamChunk = async (vaultPath, input) => {
         : input.scale < midScaleThreshold
             ? 'mid'
             : 'near';
-    const nodes = mode === 'far' && groups.length > 0
-        ? selectFarClusters(groups, input, nodeBudget)
+    const nodes = mode === 'far'
+        ? selectFarClusters(layout.nodes, input, nodeBudget)
         : mode === 'mid'
             ? selectMidNodes(layout.nodes, cache, {
                 ...input,

package/dist/domain/graph-layout.js

@@ -193,29 +193,66 @@ const compareByStarOrder = (levels, degrees, segmentIndexByName, segments) => (l
     const degreeDelta = (degrees.get(right.id) ?? 0) - (degrees.get(left.id) ?? 0);
     return degreeDelta === 0 ? left.title.localeCompare(right.title) : degreeDelta;
 };
-const petalSpreadForSegmentSize = (size) => {
+const petalRadiusForSegmentSize = (size) => {
     const safeSize = Math.max(size, 1);
-    return 180 + Math.log2(safeSize + 1) * 6;
+    return Math.max(260, Math.sqrt(safeSize) * 96);
 };
-const createSegmentNodes = (segments, degrees, segmentCount) => ([segment, nodes], segmentIndex) => {
+const selectSegmentHub = (nodes, degrees, primaryHubId) => {
+    const primary = nodes.find((node) => node.id === primaryHubId);
+    if (primary) {
+        return primary;
+    }
+    return [...nodes].sort((left, right) => {
+        const hubDelta = hubScore(right) - hubScore(left);
+        if (hubDelta !== 0)
+            return hubDelta;
+        const degreeDelta = (degrees.get(right.id) ?? 0) - (degrees.get(left.id) ?? 0);
+        if (degreeDelta !== 0)
+            return degreeDelta;
+        return left.title.localeCompare(right.title);
+    })[0] ?? null;
+};
+const segmentCenterRadius = (segments) => {
+    if (segments.length <= 1) {
+        return 0;
+    }
+    const circumference = segments.reduce((total, [, nodes]) => total + petalRadiusForSegmentSize(nodes.length) * 2 + 180, 0);
+    return Math.max(520, circumference / (Math.PI * 2));
+};
+const createCauliflowerSegmentNodes = (segments, degrees, primaryHubId, segmentGroups) => ([segment, nodes], segmentIndex) => {
     const sortedNodes = [...nodes].sort(byDegreeThenTitle(degrees));
-    const angle = segmentAngle(segment, segmentIndex, segmentCount);
-    const baseRadius = segmentCount === 1 ? 0 : 340 + Math.min(sortedNodes.length, 22) * 10;
-    const centerX = Math.cos(angle) * baseRadius;
-    const centerY = Math.sin(angle) * (baseRadius * 0.78);
-    const petalSpread = petalSpreadForSegmentSize(sortedNodes.length);
-    return sortedNodes.map((node, index) => {
-        const localAngle = index * 2.399963 + jitter(node.title, 0.42);
-        const localRadius = Math.sqrt(index + 1) * petalSpread;
-        const hubPull = segmentCount === 1 ? 0 : Math.min(degrees.get(node.id) ?? 0, 12) * 12;
+    const segmentHub = selectSegmentHub(sortedNodes, degrees, primaryHubId);
+    const angle = segmentAngle(segment, segmentIndex, segmentGroups.length);
+    const globalRadius = segmentCenterRadius(segmentGroups);
+    const petalRadius = petalRadiusForSegmentSize(sortedNodes.length);
+    const isPrimarySegment = Boolean(segmentHub && segmentHub.id === primaryHubId);
+    const centerX = isPrimarySegment || globalRadius === 0 ? 0 : Math.cos(angle) * globalRadius;
+    const centerY = isPrimarySegment || globalRadius === 0 ? 0 : Math.sin(angle) * (globalRadius * 0.86);
+    const nonHubNodes = sortedNodes.filter((node) => node.id !== segmentHub?.id);
+    const hubNode = segmentHub
+        ? [{
+                ...segmentHub,
+                group: groupLabel(groupKey(segmentHub)),
+                segment: segments.get(segmentHub.id) ?? segment,
+                x: centerX,
+                y: centerY
+            }]
+        : [];
+    const petalNodes = nonHubNodes.map((node, index) => {
+        const localAngle = index * 2.399963 + jitter(node.title, 0.5);
+        const radialLayer = Math.sqrt(index + 1) / Math.sqrt(Math.max(nonHubNodes.length, 1));
+        const localRadius = 150 + radialLayer * petalRadius + jitter(node.id, 34);
+        const degreePull = Math.min(degrees.get(node.id) ?? 0, 16) * 8;
+        const radius = Math.max(126, localRadius - degreePull);
         return {
             ...node,
             group: groupLabel(groupKey(node)),
             segment: segments.get(node.id) ?? segment,
-            x: centerX + Math.cos(localAngle) * localRadius - Math.cos(angle) * hubPull + jitter(node.id, 24),
-            y: centerY + Math.sin(localAngle) * localRadius * 0.78 - Math.sin(angle) * hubPull + jitter(node.path, 24)
+            x: centerX + Math.cos(localAngle) * radius + jitter(node.title, 20),
+            y: centerY + Math.sin(localAngle) * radius * 0.84 + jitter(node.path, 20)
         };
     });
+    return [...hubNode, ...petalNodes];
 };
 const distanceBetween = (left, right) => Math.hypot(right.x - left.x, right.y - left.y);
 const layoutBounds = (nodes) => {
@@ -539,8 +576,8 @@ export const createCauliflowerGraphLayout = (graph) => {
     const segments = assignSegments(graph.nodes, graph.edges, degrees);
     const segmentGroups = Array.from(groupNodesBySegment(graph.nodes, segments).entries())
         .sort(([left], [right]) => left.localeCompare(right));
-    const nodes = relaxCollisions(segmentGroups.flatMap(createSegmentNodes(segments, degrees, segmentGroups.length)));
     const primaryHubId = selectPrimaryHubId(graph.nodes, degrees);
+    const nodes = relaxCollisions(segmentGroups.flatMap(createCauliflowerSegmentNodes(segments, degrees, primaryHubId, segmentGroups)), 156, 28);
     const centeredNodes = centerLayoutByNode(nodes, primaryHubId);
     const groups = createGraphLayoutHierarchy(centeredNodes, graph.edges, degrees);
     return {

package/docs/AGENT_USAGE.md

@@ -610,7 +610,7 @@ Without `--vault`, the graph UI serves `$HOME/.brainlink/vault`.
 
 The frontend includes an agent selector that shows only the agent id. Selecting an agent calls the same read APIs with `agent=<agent-id>` and renders that namespace instead of merging every agent into one graph.
 
-Graph navigation controls include zoom in, zoom out, fit visible nodes and reset-to-fit-all nodes. Mouse wheel zoom (including `cmd+scroll` and `ctrl+scroll`) is anchored to the cursor and applied immediately without delayed focus interpolation. Keyboard shortcuts are `+` (zoom in), `-` (zoom out) and `0` (reset fit). Double-click on empty canvas zooms in at cursor position. Clicking a node opens its details panel. Totals for notes, links and tags stay visible as floating metrics under the Brainlink title, and node details open in a non-modal side panel (tags, outgoing links, backlinks and Markdown content), so zoom and pan remain available during inspection. The visual layout is a star centered on the primary hub, while underlying weighted wiki-link edges are preserved for backlinks, ranking and context traversal. Vaults above 1000 notes keep the same single graph scene and render the full filtered node/edge set during navigation, without viewport-sampled subgraph switching. Node titles appear as zoom approaches readable scale, limited to on-screen nodes in very large graphs.
+Graph navigation controls include zoom in, zoom out, fit visible nodes and reset-to-fit-all nodes. Mouse wheel zoom (including `cmd+scroll` and `ctrl+scroll`) is anchored to the cursor and applied immediately without delayed focus interpolation. Keyboard shortcuts are `+` (zoom in), `-` (zoom out) and `0` (reset fit). Double-click on empty canvas zooms in at cursor position. Clicking a node opens its details panel. Totals for notes, links and tags stay visible as floating metrics under the Brainlink title, and node details open in a non-modal side panel (tags, outgoing links, backlinks and Markdown content), so zoom and pan remain available during inspection. The visual layout is a cauliflower hub layout: the primary hub stays centered, segment hubs anchor surrounding lobes, and underlying weighted wiki-link edges are preserved for backlinks, ranking and context traversal. At high zoom-out, graph streams show segment hub clusters first; zooming in progressively reveals the individual nodes inside those lobes. Node titles appear as zoom approaches readable scale, limited to on-screen nodes in very large graphs.
 During graph filtering, Brainlink keeps hub context nodes visible (`Memory Hub`/`MOC`/high-degree fallback) so filtered views still show relationship anchors.
 
 The command reindexes by default, then serves:

package/docs/ARCHITECTURE.md

@@ -156,13 +156,13 @@ server command
   -> /api/agents lists indexed namespaces
   -> /api/graph-contexts lists visual graph contexts
   -> /api/graph reads indexed documents and links
-  -> /api/graph-layout derives a star layout from indexed graph data
-  -> optional context query narrows the layout to a segment-scoped star subgraph
+  -> /api/graph-layout derives a cauliflower hub layout from indexed graph data
+  -> optional context query narrows the layout to a segment-scoped cauliflower subgraph
   -> browser renders graph canvas
 ```
 
 The graph UI is intentionally read-only. Markdown remains the write interface and index artifacts remain derived data.
-The star layout is visual only: it keeps the indexed weighted wiki-link edges unchanged so backlinks, ranking and context traversal keep their original semantics.
+The cauliflower layout is visual only: it keeps the indexed weighted wiki-link edges unchanged so backlinks, ranking and context traversal keep their original semantics. The primary hub is centered, segment hubs anchor surrounding lobes, and zoomed-out graph streams summarize those lobes as segment clusters before revealing individual nodes on zoom-in.
 
 ## HTTP API Flow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-beta.156",
+  "version": "0.1.0-beta.157",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",