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

package/README.md

@@ -82,9 +82,9 @@ 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 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.
+- Graph renderer uses a cauliflower-style hub layout: the primary hub stays centered, segment hubs anchor surrounding lobes, and visual edges are simplified to root hub -> segment hubs -> local context nodes.
+- Real weighted `[[wiki link]]` edges stay preserved in the indexed graph APIs for backlinks, ranking and context traversal; the browser layout uses a separate visual edge layer for readability.
+- Graph exploration uses stable chunk streaming (`/api/graph-stream`) with explicit node/edge budgets, returning the full mode-level scene while it fits the budget.
 - 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).
@@ -599,8 +599,8 @@ When native GUI is used, the GUI window automatically closes when the `blink ser
 The graph UI shows:
 
 - notes as nodes
-- all non-self `[[wiki links]]` inside `## Context Links` as weighted edges
-- default cauliflower-style layout centered on the primary hub, with segment hubs anchoring surrounding lobes and without rewriting or flattening underlying relationships
+- all non-self `[[wiki links]]` inside `## Context Links` as weighted indexed edges
+- default cauliflower-style visual layout centered on the primary hub, with segment hubs anchoring surrounding lobes and visual edges simplified to root hub -> segment hubs -> local context nodes
 - 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
@@ -619,7 +619,7 @@ The graph UI shows:
 - 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 one semantic graph model across zoom levels, uses segment clusters at high zoom-out, and shows node titles as zoom approaches readable scale
+- large graph view keeps one indexed graph model across zoom levels, uses a stable visual hierarchy for rendering, 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

@@ -5,7 +5,7 @@ import { addVisualContextEdges } from '../domain/graph-contexts.js';
 import { createCauliflowerGraphLayout } from '../domain/graph-layout.js';
 import { indexStoragePath } from '../infrastructure/file-index.js';
 import { getGraphSummary } from './get-graph-summary.js';
-const graphLayoutVersion = 7;
+const graphLayoutVersion = 8;
 const graphLayoutCache = new Map();
 const safeCacheSegment = (value, fallback) => value?.replace(/[^a-zA-Z0-9_-]/g, '_') || fallback;
 const graphLayoutStoragePath = (vaultPath, options) => {

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

@@ -107,13 +107,15 @@ const selectTopByRelevance = (items, relevanceById, budget) => [...items]
     .slice(0, Math.max(1, budget));
 const selectNearNodes = (nodes, cache, input) => {
     const padding = Math.max(input.width, input.height) * viewportPaddingFactor;
-    const viewportNodes = nodes.filter((node) => inViewport(node, input, padding));
+    const candidateNodes = nodes.length <= input.nodeBudget
+        ? nodes
+        : nodes.filter((node) => inViewport(node, input, padding));
     const relevance = new Map();
-    for (let index = 0; index < viewportNodes.length; index += 1) {
-        const node = viewportNodes[index];
+    for (let index = 0; index < candidateNodes.length; index += 1) {
+        const node = candidateNodes[index];
         relevance.set(node.id, rankNodeRelevance(node, input, cache.degrees));
     }
-    const selected = selectTopByRelevance(viewportNodes, relevance, input.nodeBudget);
+    const selected = selectTopByRelevance(candidateNodes, relevance, input.nodeBudget);
     return selected.map((node) => [
         node.id,
         node.title,
@@ -127,13 +129,15 @@ const selectNearNodes = (nodes, cache, input) => {
 };
 const selectMidNodes = (nodes, cache, input) => {
     const padding = Math.max(input.width, input.height) * (viewportPaddingFactor + 0.08);
-    const viewportNodes = nodes.filter((node) => inViewport(node, input, padding));
+    const candidateNodes = nodes.length <= input.nodeBudget
+        ? nodes
+        : nodes.filter((node) => inViewport(node, input, padding));
     const relevance = new Map();
-    for (let index = 0; index < viewportNodes.length; index += 1) {
-        const node = viewportNodes[index];
+    for (let index = 0; index < candidateNodes.length; index += 1) {
+        const node = candidateNodes[index];
         relevance.set(node.id, rankNodeRelevance(node, input, cache.degrees) * 1.1);
     }
-    const selected = selectTopByRelevance(viewportNodes, relevance, input.nodeBudget);
+    const selected = selectTopByRelevance(candidateNodes, relevance, input.nodeBudget);
     return selected.map((node) => [
         node.id,
         node.title,
@@ -147,14 +151,12 @@ const selectMidNodes = (nodes, cache, input) => {
 };
 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();
-    for (let index = 0; index < candidates.length; index += 1) {
-        const group = candidates[index];
+    for (let index = 0; index < roots.length; index += 1) {
+        const group = roots[index];
         relevance.set(group.id, rankGroupRelevance(group, input));
     }
-    const selected = selectTopByRelevance(candidates, relevance, nodeBudget);
+    const selected = selectTopByRelevance(roots, relevance, nodeBudget);
     return selected.map((group) => [
         `cluster:${group.id}`,
         group.title,

package/dist/domain/graph-layout.js

@@ -219,13 +219,13 @@ const segmentCenterRadius = (segments) => {
     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 createCauliflowerSegmentNodes = (segments, degrees, rootHubId, segmentGroups) => ([segment, nodes], segmentIndex) => {
     const sortedNodes = [...nodes].sort(byDegreeThenTitle(degrees));
-    const segmentHub = selectSegmentHub(sortedNodes, degrees, primaryHubId);
+    const segmentHub = selectSegmentHub(sortedNodes, degrees, rootHubId);
     const angle = segmentAngle(segment, segmentIndex, segmentGroups.length);
     const globalRadius = segmentCenterRadius(segmentGroups);
     const petalRadius = petalRadiusForSegmentSize(sortedNodes.length);
-    const isPrimarySegment = Boolean(segmentHub && segmentHub.id === primaryHubId);
+    const isPrimarySegment = Boolean(segmentHub && segmentHub.id === rootHubId);
     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);
@@ -254,6 +254,41 @@ const createCauliflowerSegmentNodes = (segments, degrees, primaryHubId, segmentG
     });
     return [...hubNode, ...petalNodes];
 };
+const createVisualEdge = (source, target, weight, priority) => ({
+    source: source.id,
+    target: target.id,
+    targetTitle: target.title,
+    weight,
+    priority
+});
+const createCauliflowerVisualEdges = (segmentGroups, degrees, rootHubId) => {
+    const nodeById = new Map(segmentGroups.flatMap(([, nodes]) => nodes.map((node) => [node.id, node])));
+    const rootHub = rootHubId ? nodeById.get(rootHubId) ?? null : null;
+    const edges = new Map();
+    const addEdge = (edge) => {
+        if (!edge.target || edge.source === edge.target) {
+            return;
+        }
+        edges.set(`${edge.source}|${edge.target}`, edge);
+    };
+    segmentGroups.forEach(([, nodes]) => {
+        const segmentHub = selectSegmentHub(nodes, degrees, rootHubId);
+        const parent = segmentHub ?? rootHub;
+        if (!parent) {
+            return;
+        }
+        if (rootHub && parent.id !== rootHub.id) {
+            addEdge(createVisualEdge(rootHub, parent, 6, 'high'));
+        }
+        nodes.forEach((node) => {
+            if (node.id === parent.id || node.id === rootHub?.id) {
+                return;
+            }
+            addEdge(createVisualEdge(parent, node, 1, 'low'));
+        });
+    });
+    return Array.from(edges.values());
+};
 const distanceBetween = (left, right) => Math.hypot(right.x - left.x, right.y - left.y);
 const layoutBounds = (nodes) => {
     if (nodes.length === 0) {
@@ -576,13 +611,14 @@ 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 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);
+    const rootHubId = selectPrimaryHubId(graph.nodes, degrees) ?? selectHighestDegreeNodeId(graph.nodes, degrees);
+    const nodes = relaxCollisions(segmentGroups.flatMap(createCauliflowerSegmentNodes(segments, degrees, rootHubId, segmentGroups)), 156, 28);
+    const centeredNodes = centerLayoutByNode(nodes, rootHubId);
+    const visualEdges = createCauliflowerVisualEdges(segmentGroups, degrees, rootHubId);
+    const groups = createGraphLayoutHierarchy(centeredNodes, visualEdges, degrees);
     return {
         nodes: centeredNodes,
-        edges: graph.edges,
+        edges: visualEdges,
         ...(groups.length > 0 ? { groups } : {})
     };
 };

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 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.
+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 visual edges are simplified to root hub -> segment hubs -> local context nodes. Indexed weighted wiki-link edges remain available for backlinks, ranking and context traversal outside the render layer. 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

@@ -162,7 +162,7 @@ server command
 ```
 
 The graph UI is intentionally read-only. Markdown remains the write interface and index artifacts remain derived data.
-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.
+The cauliflower layout is a visual projection over the indexed graph. Indexed weighted wiki-link edges remain unchanged for backlinks, ranking, graph reads and context traversal. The browser layout renders a simplified hierarchy instead: primary hub -> segment hubs -> local context nodes. This avoids unstable cross-context visual edges while preserving the real relationship model outside the render layer. 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.157",
+  "version": "0.1.0-beta.158",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",