@andespindola/brainlink 0.1.0-beta.149 → 0.1.0-beta.150

package/README.md

@@ -82,7 +82,8 @@ 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 keeps the full filtered graph visible during zoom/pan, rendering every visible node and edge without viewport culling or edge caps in the main view.
+- Graph renderer uses a star layout centered on the primary hub while preserving real weighted `[[wiki link]]` edges 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.
@@ -589,6 +590,7 @@ The graph UI shows:
 
 - notes as nodes
 - representative `[[wiki links]]` as weighted edges
+- star layout centered on the primary hub, 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

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

@@ -1,10 +1,10 @@
 import { createHash } from 'node:crypto';
 import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { createCauliflowerGraphLayout } from '../domain/graph-layout.js';
+import { createStarGraphLayout } from '../domain/graph-layout.js';
 import { indexStoragePath } from '../infrastructure/file-index.js';
 import { getGraphSummary } from './get-graph-summary.js';
-const graphLayoutVersion = 2;
+const graphLayoutVersion = 3;
 const graphLayoutCache = new Map();
 const graphLayoutStoragePath = (vaultPath, agentId) => join(vaultPath, '.brainlink', `graph-layout-${agentId?.replace(/[^a-zA-Z0-9_-]/g, '_') ?? 'all'}.json`);
 const readPersistedLayout = async (vaultPath, databaseSignature, agentId) => {
@@ -61,7 +61,7 @@ export const getGraphLayout = async (vaultPath, agentId) => {
     }
     const graph = await getGraphSummary(vaultPath, agentId);
     const signature = createGraphSignature(graph);
-    const rawLayout = createCauliflowerGraphLayout(graph);
+    const rawLayout = createStarGraphLayout(graph);
     const layout = {
         ...rawLayout,
         nodes: rawLayout.nodes.map((node) => ({ ...node, content: '' }))

package/dist/domain/graph-layout.js

@@ -88,6 +88,10 @@ const selectPrimaryHubId = (nodes, degrees) => {
     });
     return ranked[0]?.id ?? null;
 };
+const selectHighestDegreeNodeId = (nodes, degrees) => [...nodes].sort((left, right) => {
+    const degreeDelta = (degrees.get(right.id) ?? 0) - (degrees.get(left.id) ?? 0);
+    return degreeDelta === 0 ? left.title.localeCompare(right.title) : degreeDelta;
+})[0]?.id ?? null;
 const centerLayoutByNode = (nodes, nodeId) => {
     if (!nodeId) {
         return nodes;
@@ -168,6 +172,18 @@ const groupNodesBySegment = (nodes, segments) => {
     return new Map(groups);
 };
 const segmentAngle = (segment, index, count) => segmentAngles[segment] ?? (Math.PI * 2 * index) / Math.max(count, 1) - Math.PI / 2;
+const compareByStarOrder = (levels, degrees, segmentIndexByName, segments) => (left, right) => {
+    const levelDelta = (levels.get(left.id) ?? 1) - (levels.get(right.id) ?? 1);
+    if (levelDelta !== 0)
+        return levelDelta;
+    const leftSegment = segments.get(left.id) ?? groupLabel(groupKey(left));
+    const rightSegment = segments.get(right.id) ?? groupLabel(groupKey(right));
+    const segmentDelta = (segmentIndexByName.get(leftSegment) ?? 0) - (segmentIndexByName.get(rightSegment) ?? 0);
+    if (segmentDelta !== 0)
+        return segmentDelta;
+    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 safeSize = Math.max(size, 1);
     return 180 + Math.log2(safeSize + 1) * 6;
@@ -414,6 +430,84 @@ const relaxCollisions = (nodes, minDistance = 132, rounds = 32) => {
     }
     return layoutNodes;
 };
+const assignStarLevels = (nodes, edges, hubId) => {
+    if (!hubId) {
+        return new Map(nodes.map((node) => [node.id, 1]));
+    }
+    const adjacency = createAdjacency(nodes, edges);
+    const levels = new Map([[hubId, 0]]);
+    const queue = [hubId];
+    for (let index = 0; index < queue.length; index += 1) {
+        const id = queue[index];
+        const nextLevel = (levels.get(id) ?? 0) + 1;
+        (adjacency.get(id) ?? []).forEach((nextId) => {
+            if (!levels.has(nextId)) {
+                levels.set(nextId, nextLevel);
+                queue.push(nextId);
+            }
+        });
+    }
+    nodes.forEach((node) => {
+        if (!levels.has(node.id)) {
+            levels.set(node.id, 2);
+        }
+    });
+    return levels;
+};
+const createStarNodes = (nodes, segments, degrees, hubId, levels) => {
+    const segmentNames = Array.from(new Set(nodes.map((node) => segments.get(node.id) ?? groupLabel(groupKey(node)))))
+        .sort((left, right) => segmentAngle(left, 0, 1) - segmentAngle(right, 0, 1) || left.localeCompare(right));
+    const segmentIndexByName = new Map(segmentNames.map((segment, index) => [segment, index]));
+    const sortedNodes = [...nodes].sort(compareByStarOrder(levels, degrees, segmentIndexByName, segments));
+    const nodesByLevel = sortedNodes.reduce((state, node) => {
+        const level = node.id === hubId ? 0 : Math.max(1, levels.get(node.id) ?? 1);
+        const levelNodes = state.get(level) ?? [];
+        levelNodes.push(node);
+        state.set(level, levelNodes);
+        return state;
+    }, new Map());
+    return Array.from(nodesByLevel.entries())
+        .sort(([left], [right]) => left - right)
+        .flatMap(([level, levelNodes]) => {
+        if (level === 0) {
+            return levelNodes.map((node) => ({
+                ...node,
+                group: groupLabel(groupKey(node)),
+                segment: segments.get(node.id) ?? groupLabel(groupKey(node)),
+                x: 0,
+                y: 0
+            }));
+        }
+        const ringRadius = Math.max(300 + (level - 1) * 360, (levelNodes.length * 112) / (Math.PI * 2));
+        return levelNodes.map((node, index) => {
+            const segment = segments.get(node.id) ?? groupLabel(groupKey(node));
+            const segmentOffset = (segmentIndexByName.get(segment) ?? 0) / Math.max(segmentNames.length, 1);
+            const angle = Math.PI * 2 * ((index / Math.max(levelNodes.length, 1) + segmentOffset * 0.18) % 1) - Math.PI / 2;
+            const radialJitter = jitter(node.id, 48);
+            return {
+                ...node,
+                group: groupLabel(groupKey(node)),
+                segment,
+                x: Math.cos(angle) * (ringRadius + radialJitter) + jitter(node.title, 18),
+                y: Math.sin(angle) * (ringRadius + radialJitter) + jitter(node.path, 18)
+            };
+        });
+    });
+};
+export const createStarGraphLayout = (graph) => {
+    const degrees = countDegrees(graph.edges);
+    const hubId = selectPrimaryHubId(graph.nodes, degrees) ?? selectHighestDegreeNodeId(graph.nodes, degrees);
+    const segments = assignSegments(graph.nodes, graph.edges, degrees);
+    const levels = assignStarLevels(graph.nodes, graph.edges, hubId);
+    const nodes = relaxCollisions(createStarNodes(graph.nodes, segments, degrees, hubId, levels), 132, 18);
+    const centeredNodes = centerLayoutByNode(nodes, hubId);
+    const groups = createGraphLayoutHierarchy(centeredNodes, graph.edges, degrees);
+    return {
+        nodes: centeredNodes,
+        edges: graph.edges,
+        ...(groups.length > 0 ? { groups } : {})
+    };
+};
 export const createCauliflowerGraphLayout = (graph) => {
     const degrees = countDegrees(graph.edges);
     const segments = assignSegments(graph.nodes, graph.edges, degrees);

package/docs/AGENT_USAGE.md

@@ -607,7 +607,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. 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 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.
 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

@@ -155,10 +155,12 @@ server command
   -> HTTP server
   -> /api/agents lists indexed namespaces
   -> /api/graph reads indexed documents and links
+  -> /api/graph-layout derives a star layout from indexed graph data
   -> 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.
 
 ## HTTP API Flow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-beta.149",
+  "version": "0.1.0-beta.150",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",
@@ -63,6 +63,7 @@
     "zod": "^4.3.6"
   },
   "overrides": {
+    "hono": "4.12.21",
     "qs": "6.15.2"
   },
   "devDependencies": {