@andespindola/brainlink 0.1.0-beta.87 → 0.1.0-beta.89

package/README.md

@@ -84,7 +84,7 @@ Legacy `.jsonl.gz` packs are upgraded to `.blpk` automatically on first search/c
 - Graph renderer optimized for large datasets with viewport-driven node culling and edge lookup by visible nodes.
 - Canvas graph rendering uses the same batched node and edge pipeline for every graph size, reducing per-frame draw calls while keeping selected and hovered items highlighted.
 - WebGL acceleration is used when available for dense node and edge drawing, with Canvas 2D preserved as the interaction and fallback layer.
-- Graph zoom-out renders hierarchical ecosystem subgraphs only above 1000 notes: distant groups stay as small sand-like points and expand near the user's focus into smaller graph meshes before individual notes are rendered.
+- Graph zoom-out renders hierarchical ecosystem subgraphs only above 1000 notes: the memory hub stays centered, 1000-note groups stay as compact sand-like points, and focused groups gradually expand into smaller graph meshes before individual notes are rendered.
 - 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 macro mass and zoom-in progressively expands toward local detail.
@@ -602,7 +602,7 @@ The graph UI shows:
 - WebGL node and edge acceleration when supported, falling back to Canvas 2D without changing graph behavior
 - compact macro-to-micro density progression so reset keeps the graph mass oriented and zoom-in separates local neighborhoods progressively
 - graph camera treats hub-centered navigation as structural only when the hub is dominant; diffuse stress graphs reset and zoom around the full graph mass
-- graph LOD progression: graphs up to 1000 notes render directly; larger graphs use connected sand-like ecosystem points of up to 1000 notes, zoom-in spreads only focused clusters into 250-note and 60-note subgraphs with aggregated real links, then progressively raises the focused node budget so local areas keep nearby notes and links visible
+- graph LOD progression: graphs up to 1000 notes render directly; larger graphs use a compact memory-hub-centered mesh of connected 1000-note points, zoom-in spreads only focused clusters into 250-note and 60-note subgraphs with aggregated real links, keeps parent points during expansion to avoid visual jumps, then progressively raises the focused node budget so local areas keep nearby notes and links visible
 
 The server indexes before starting by default. Use `--no-index` to skip that step:
 

package/dist/application/frontend/client-js.js

@@ -25,6 +25,7 @@ const ecosystemGroupSize = 1000
 const ecosystemActivationNodeThreshold = 1000
 const ecosystemGroupSizes = [1000, 250, 60]
 const ecosystemClusterEdgeLimit = 520
+const ecosystemHubEdgeLimit = 120
 const ecosystemClusterScaleThreshold = 0.32
 const ecosystemSubgraphScaleThreshold = 0.18
 const ecosystemMicroScaleThreshold = 0.08
@@ -37,9 +38,9 @@ const meshEdgeMaxBudget = 1400
 const layeredCoreScaleThreshold = 0.55
 const dragNeighborhoodMaxAffected = 180
 const dragSettleRounds = 3
-const wheelZoomExponent = 0.0018
-const wheelZoomExponentCap = 0.09
-const wheelZoomModifierBoost = 1.22
+const wheelZoomExponent = 0.0009
+const wheelZoomExponentCap = 0.035
+const wheelZoomModifierBoost = 1.08
 const state = {
   graph: { nodes: [], edges: [] },
   nodes: [],
@@ -74,6 +75,8 @@ const state = {
   visibleEdgeByNode: new Map(),
   ecosystemClusters: [],
   ecosystemClustersBySize: new Map(),
+  ecosystemNodeClusterBySize: new Map(),
+  ecosystemHubCluster: null,
   macroCenter: { x: 0, y: 0 },
   macroRepresentative: null,
   primaryHub: null,
@@ -570,11 +573,6 @@ const recomputeVisibility = () => {
   state.visibleEdges = limitedEdges
   state.visibleNodeSpatial = createSpatialIndex(nodes)
   state.visibleEdgeByNode = createVisibleEdgeLookup(limitedEdges)
-  const ecosystemGraph = nodes.length > ecosystemActivationNodeThreshold
-    ? buildEcosystemGraph(nodes)
-    : { clusters: [], clustersBySize: new Map() }
-  state.ecosystemClusters = ecosystemGraph.clusters
-  state.ecosystemClustersBySize = ecosystemGraph.clustersBySize
   const primaryHub = rankedHubNodes()[0] ?? null
   state.primaryHub = primaryHub
   state.hubNeighborDistance = nearestHubNeighborDistance(primaryHub, nodes)
@@ -586,6 +584,13 @@ const recomputeVisibility = () => {
       y: macroHub ? macroHub.y : (bounds.minY + bounds.maxY) / 2
     }
     : { x: 0, y: 0 }
+  const ecosystemGraph = nodes.length > ecosystemActivationNodeThreshold
+    ? buildEcosystemGraph(nodes, state.macroCenter, primaryHub)
+    : { clusters: [], clustersBySize: new Map(), nodeClusterBySize: new Map(), hubCluster: null }
+  state.ecosystemClusters = ecosystemGraph.clusters
+  state.ecosystemClustersBySize = ecosystemGraph.clustersBySize
+  state.ecosystemNodeClusterBySize = ecosystemGraph.nodeClusterBySize
+  state.ecosystemHubCluster = ecosystemGraph.hubCluster
   state.macroRepresentative = resolveMacroRepresentative(nodes)
   markRenderDirty()
 }
@@ -730,18 +735,32 @@ const selectEcosystemRepresentative = nodes => {
   return representative
 }
 
-const buildEcosystemCluster = (nodes, index) => {
+const ecosystemLayoutSpacingForSize = size => {
+  if (size >= 1000) return 360
+  if (size >= 250) return 92
+  return 28
+}
+
+const ecosystemCompactPoint = (index, total, center, spacing) => {
+  if (total <= 1) {
+    return { x: center.x, y: center.y }
+  }
+  const angle = index * 2.399963229728653
+  const radius = spacing * Math.sqrt(index + 1)
+  return {
+    x: center.x + Math.cos(angle) * radius,
+    y: center.y + Math.sin(angle) * radius
+  }
+}
+
+const buildEcosystemCluster = (nodes, index, point) => {
   const count = Math.max(nodes.length, 1)
-  const sum = nodes.reduce((accumulator, node) => ({
-    x: accumulator.x + node.x,
-    y: accumulator.y + node.y
-  }), { x: 0, y: 0 })
   const representative = selectEcosystemRepresentative(nodes)
 
   return {
     id: 'ecosystem-' + index,
-    x: sum.x / count,
-    y: sum.y / count,
+    x: point.x,
+    y: point.y,
     count,
     nodeIds: nodes.map(node => node.id),
     representative,
@@ -749,15 +768,42 @@ const buildEcosystemCluster = (nodes, index) => {
   }
 }
 
-const buildEcosystemLevel = (sortedNodes, size, parentLookup) => {
+const buildEcosystemHubCluster = (hub, center) => hub
+  ? {
+      id: 'ecosystem-hub',
+      x: center.x,
+      y: center.y,
+      count: 1,
+      size: 1,
+      nodeIds: [hub.id],
+      representative: hub,
+      label: hub.title || 'Memory Hub',
+      parentId: null,
+      parentX: null,
+      parentY: null,
+      isHub: true
+    }
+  : null
+
+const buildEcosystemLevel = (sortedNodes, size, parentLookup, center) => {
   const clusters = []
   const clusterByNodeId = new Map()
+  const parentChildIndex = new Map()
 
   for (let offset = 0; offset < sortedNodes.length; offset += size) {
     const clusterNodes = sortedNodes.slice(offset, offset + size)
     const parentCluster = parentLookup?.get(clusterNodes[0]?.id)
+    const siblingIndex = parentCluster
+      ? (parentChildIndex.get(parentCluster.id) ?? 0)
+      : clusters.length
+    if (parentCluster) {
+      parentChildIndex.set(parentCluster.id, siblingIndex + 1)
+    }
+    const point = parentCluster
+      ? ecosystemCompactPoint(siblingIndex, Math.ceil((parentCluster.count || size) / size), parentCluster, ecosystemLayoutSpacingForSize(size))
+      : ecosystemCompactPoint(clusters.length, Math.ceil(sortedNodes.length / size), center, ecosystemLayoutSpacingForSize(size))
     const cluster = {
-      ...buildEcosystemCluster(clusterNodes, clusters.length),
+      ...buildEcosystemCluster(clusterNodes, clusters.length, point),
       id: 'ecosystem-' + size + '-' + clusters.length,
       size,
       parentId: parentCluster?.id ?? null,
@@ -773,25 +819,32 @@ const buildEcosystemLevel = (sortedNodes, size, parentLookup) => {
   return { clusters, clusterByNodeId }
 }
 
-const buildEcosystemGraph = (nodes) => {
+const buildEcosystemGraph = (nodes, center, hub) => {
   if (nodes.length === 0) {
-    return { clusters: [], clustersBySize: new Map() }
+    return { clusters: [], clustersBySize: new Map(), nodeClusterBySize: new Map(), hubCluster: null }
   }
 
-  const sortedNodes = [...nodes].sort(compareNodesForEcosystem)
+  const hubCluster = buildEcosystemHubCluster(hub, center)
+  const sortedNodes = nodes
+    .filter(node => node.id !== hub?.id)
+    .sort(compareNodesForEcosystem)
   const clustersBySize = new Map()
+  const nodeClusterBySize = new Map()
   let parentLookup = null
 
   for (let index = 0; index < ecosystemGroupSizes.length; index += 1) {
     const size = ecosystemGroupSizes[index]
-    const level = buildEcosystemLevel(sortedNodes, size, parentLookup)
+    const level = buildEcosystemLevel(sortedNodes, size, parentLookup, center)
     clustersBySize.set(size, level.clusters)
+    nodeClusterBySize.set(size, level.clusterByNodeId)
     parentLookup = level.clusterByNodeId
   }
 
   return {
     clusters: clustersBySize.get(ecosystemGroupSize) ?? [],
-    clustersBySize
+    clustersBySize,
+    nodeClusterBySize,
+    hubCluster
   }
 }
 
@@ -832,21 +885,24 @@ const smoothStep = value => {
 const zoomProgress = (scale, start, end) =>
   smoothStep((scale - start) / Math.max(end - start, 0.0001))
 
-const ecosystemPlanForScale = scale => {
-  if (scale <= ecosystemMicroScaleThreshold) {
-    return { baseSize: 1000, childSize: null, spread: 0 }
-  }
-  if (scale <= ecosystemSubgraphScaleThreshold) {
-    return {
-      baseSize: 1000,
-      childSize: 250,
-      spread: zoomProgress(scale, ecosystemMicroScaleThreshold, ecosystemSubgraphScaleThreshold)
-    }
-  }
+const shouldReplaceParentCluster = spread => spread >= 0.96
+
+const expandFocusedClusters = (parentClusters, childSize, spread, viewport) => {
+  const focusPoint = ecosystemFocusPoint()
+  const expandedParentIds = new Set(nearestEcosystemParentIds(
+    parentClusters,
+    focusPoint,
+    ecosystemFocusedParentLimit
+  ))
+  const childClusters = state.ecosystemClustersBySize.get(childSize) ?? []
+  const visibleChildClusters = childClusters
+    .filter(cluster => expandedParentIds.has(cluster.parentId))
+    .map(cluster => spreadChildClusterFromParent(cluster, spread))
+    .filter(cluster => isClusterInViewport(cluster, viewport))
+
   return {
-    baseSize: 250,
-    childSize: 60,
-    spread: zoomProgress(scale, ecosystemSubgraphScaleThreshold, ecosystemClusterScaleThreshold)
+    expandedParentIds,
+    childClusters: visibleChildClusters
   }
 }
 
@@ -863,50 +919,93 @@ const spreadChildClusterFromParent = (cluster, spread) => {
 }
 
 const selectHierarchicalEcosystemClusters = viewport => {
-  const plan = ecosystemPlanForScale(state.transform.scale)
-  const baseClusters = state.ecosystemClustersBySize.get(plan.baseSize) ?? state.ecosystemClusters
+  const baseClusters = state.ecosystemClustersBySize.get(ecosystemGroupSize) ?? state.ecosystemClusters
   const visibleBaseClusters = filterEcosystemClustersByViewport(baseClusters, viewport)
+  const hubClusters = state.ecosystemHubCluster ? [state.ecosystemHubCluster] : []
 
-  if (!plan.childSize) {
-    return visibleBaseClusters
+  if (state.transform.scale <= ecosystemMicroScaleThreshold) {
+    return [...hubClusters, ...visibleBaseClusters]
   }
 
-  const focusPoint = ecosystemFocusPoint()
-  const expandedParentIds = new Set(nearestEcosystemParentIds(
+  const midExpansion = expandFocusedClusters(
     visibleBaseClusters,
-    focusPoint,
-    ecosystemFocusedParentLimit
-  ))
-  const childClusters = state.ecosystemClustersBySize.get(plan.childSize) ?? []
-  const visibleChildClusters = childClusters.filter(cluster =>
-    expandedParentIds.has(cluster.parentId) &&
-    isClusterInViewport(cluster, viewport)
-  ).map(cluster => spreadChildClusterFromParent(cluster, plan.spread))
+    250,
+    state.transform.scale <= ecosystemSubgraphScaleThreshold
+      ? zoomProgress(state.transform.scale, ecosystemMicroScaleThreshold, ecosystemSubgraphScaleThreshold)
+      : 1,
+    viewport
+  )
+  if (midExpansion.childClusters.length === 0) {
+    return [...hubClusters, ...visibleBaseClusters]
+  }
 
-  if (visibleChildClusters.length === 0) {
-    return visibleBaseClusters
+  const midSpread = state.transform.scale <= ecosystemSubgraphScaleThreshold
+    ? zoomProgress(state.transform.scale, ecosystemMicroScaleThreshold, ecosystemSubgraphScaleThreshold)
+    : 1
+  const remainingBaseClusters = shouldReplaceParentCluster(midSpread)
+    ? visibleBaseClusters.filter(cluster => !midExpansion.expandedParentIds.has(cluster.id))
+    : visibleBaseClusters
+  if (state.transform.scale <= ecosystemSubgraphScaleThreshold) {
+    return [
+      ...hubClusters,
+      ...remainingBaseClusters,
+      ...midExpansion.childClusters
+    ]
   }
 
+  const microExpansion = expandFocusedClusters(
+    midExpansion.childClusters,
+    60,
+    zoomProgress(state.transform.scale, ecosystemSubgraphScaleThreshold, ecosystemClusterScaleThreshold),
+    viewport
+  )
+  if (microExpansion.childClusters.length === 0) {
+    return [
+      ...hubClusters,
+      ...remainingBaseClusters,
+      ...midExpansion.childClusters
+    ]
+  }
+
+  const microSpread = zoomProgress(state.transform.scale, ecosystemSubgraphScaleThreshold, ecosystemClusterScaleThreshold)
+  const visibleMidClusters = shouldReplaceParentCluster(microSpread)
+    ? midExpansion.childClusters.filter(cluster => !microExpansion.expandedParentIds.has(cluster.id))
+    : midExpansion.childClusters
   return [
-    ...visibleBaseClusters.filter(cluster => !expandedParentIds.has(cluster.id)),
-    ...visibleChildClusters
+    ...hubClusters,
+    ...remainingBaseClusters,
+    ...visibleMidClusters,
+    ...microExpansion.childClusters
   ]
 }
 
 const ecosystemEdgesForClusters = clusters => {
-  const clusterByNodeId = new Map()
-  for (let clusterIndex = 0; clusterIndex < clusters.length; clusterIndex += 1) {
-    const cluster = clusters[clusterIndex]
-    for (let nodeIndex = 0; nodeIndex < cluster.nodeIds.length; nodeIndex += 1) {
-      clusterByNodeId.set(cluster.nodeIds[nodeIndex], cluster)
+  const clusterById = new Map(clusters.map(cluster => [cluster.id, cluster]))
+  const clusterIds = new Set(clusterById.keys())
+  const levelBySize = new Map()
+  for (let index = 0; index < clusters.length; index += 1) {
+    const cluster = clusters[index]
+    if (!cluster.size || cluster.isHub) continue
+    levelBySize.set(cluster.size, state.ecosystemNodeClusterBySize.get(cluster.size) ?? new Map())
+  }
+  const resolveClusterForNode = nodeId => {
+    if (state.ecosystemHubCluster?.nodeIds.includes(nodeId) && clusterIds.has(state.ecosystemHubCluster.id)) {
+      return state.ecosystemHubCluster
+    }
+    for (const [size, lookup] of levelBySize) {
+      const cluster = lookup.get(nodeId)
+      if (cluster && clusterIds.has(cluster.id)) {
+        return clusterById.get(cluster.id) ?? cluster
+      }
     }
+    return null
   }
 
   const edgeByClusterPair = new Map()
   for (let index = 0; index < state.visibleEdges.length; index += 1) {
     const edge = state.visibleEdges[index]
-    const sourceCluster = clusterByNodeId.get(edge.source)
-    const targetCluster = clusterByNodeId.get(edge.target)
+    const sourceCluster = resolveClusterForNode(edge.source)
+    const targetCluster = resolveClusterForNode(edge.target)
     if (!sourceCluster || !targetCluster || sourceCluster.id === targetCluster.id) {
       continue
     }
@@ -929,9 +1028,34 @@ const ecosystemEdgesForClusters = clusters => {
     })
   }
 
-  return Array.from(edgeByClusterPair.values())
+  const edges = Array.from(edgeByClusterPair.values())
     .sort((left, right) => right.weight - left.weight)
     .slice(0, ecosystemClusterEdgeLimit)
+  const hubCluster = state.ecosystemHubCluster && clusterIds.has(state.ecosystemHubCluster.id)
+    ? state.ecosystemHubCluster
+    : null
+  if (!hubCluster) {
+    return edges
+  }
+
+  const existingHubTargets = new Set(edges.flatMap(edge =>
+    edge.sourceCluster.id === hubCluster.id
+      ? [edge.targetCluster.id]
+      : edge.targetCluster.id === hubCluster.id
+        ? [edge.sourceCluster.id]
+        : []
+  ))
+  const syntheticHubEdges = clusters
+    .filter(cluster => cluster.id !== hubCluster.id && !existingHubTargets.has(cluster.id))
+    .slice(0, ecosystemHubEdgeLimit)
+    .map(cluster => ({
+      id: hubCluster.id + ':' + cluster.id,
+      sourceCluster: hubCluster,
+      targetCluster: cluster,
+      weight: 1,
+      inferred: true
+    }))
+  return edges.concat(syntheticHubEdges)
 }
 
 const edgeBudgetForCurrentFrame = () => {
@@ -2372,6 +2496,9 @@ const clusterRadiusPx = cluster => {
   if (cluster.id === 'macro-galaxy') {
     return 10
   }
+  if (cluster.isHub) {
+    return 5.2
+  }
   if (String(cluster.id).startsWith('ecosystem-')) {
     const base = cluster.size >= 1000 ? 2.4 : cluster.size >= 250 ? 2.1 : 1.8
     return Math.max(1.8, Math.min(4.2, base + Math.log10(cluster.count + 1) * 0.28))
@@ -2807,10 +2934,11 @@ const render = now => {
     state.renderClusters.forEach(cluster => {
       const isMacro = cluster.id === 'macro-galaxy'
       const isEcosystem = String(cluster.id).startsWith('ecosystem-')
+      const isHub = Boolean(cluster.isHub)
       const radiusPx = clusterRadiusPx(cluster)
       const radius = radiusPx / safeScale
-      const haloRadius = (radiusPx + (isMacro ? 8 : isEcosystem ? 1.1 : 4)) / safeScale
-      if (!isEcosystem || state.transform.scale >= ecosystemSubgraphScaleThreshold) {
+      const haloRadius = (radiusPx + (isMacro ? 8 : isHub ? 4 : isEcosystem ? 1.1 : 4)) / safeScale
+      if (isHub || !isEcosystem || state.transform.scale >= ecosystemSubgraphScaleThreshold) {
         ctx.beginPath()
         ctx.arc(cluster.x, cluster.y, haloRadius, 0, Math.PI * 2)
         ctx.fillStyle = isMacro ? 'rgba(243, 247, 251, 0.28)' : graphTheme.nodeHalo
@@ -2820,7 +2948,7 @@ const render = now => {
       ctx.arc(cluster.x, cluster.y, radius, 0, Math.PI * 2)
       ctx.fillStyle = isMacro ? '#f3f7fb' : graphTheme.node
       ctx.fill()
-      ctx.lineWidth = (isEcosystem ? 0.7 : 1.4) / safeScale
+      ctx.lineWidth = (isEcosystem && !isHub ? 0.7 : 1.4) / safeScale
       ctx.strokeStyle = isMacro ? '#ffffff' : graphTheme.nodeStroke
       ctx.stroke()
       if (isMacro && cluster.representative?.title) {
@@ -3035,11 +3163,11 @@ const bindEvents = () => {
   })
   elements.zoomIn.addEventListener('click', () => {
     const rect = canvas.getBoundingClientRect()
-    zoomAtPoint(Math.max(rect.width, 320) / 2, Math.max(rect.height, 320) / 2, 1.14, 'button')
+    zoomAtPoint(Math.max(rect.width, 320) / 2, Math.max(rect.height, 320) / 2, 1.055, 'button')
   })
   elements.zoomOut.addEventListener('click', () => {
     const rect = canvas.getBoundingClientRect()
-    zoomAtPoint(Math.max(rect.width, 320) / 2, Math.max(rect.height, 320) / 2, 0.88, 'button')
+    zoomAtPoint(Math.max(rect.width, 320) / 2, Math.max(rect.height, 320) / 2, 0.948, 'button')
   })
   if (elements.fit) {
     elements.fit.addEventListener('click', () => {
@@ -3070,7 +3198,7 @@ const bindEvents = () => {
     const rect = canvas.getBoundingClientRect()
     const cursorX = event.clientX - rect.left
     const cursorY = event.clientY - rect.top
-    zoomAtPoint(cursorX, cursorY, 1.12)
+    zoomAtPoint(cursorX, cursorY, 1.055)
   })
   canvas.addEventListener('pointerdown', event => {
     const point = worldPoint(event)
@@ -3144,14 +3272,14 @@ const bindEvents = () => {
     if (event.key === '+' || event.key === '=') {
       event.preventDefault()
       const rect = canvas.getBoundingClientRect()
-      zoomAtPoint(Math.max(rect.width, 320) / 2, Math.max(rect.height, 320) / 2, 1.12)
+      zoomAtPoint(Math.max(rect.width, 320) / 2, Math.max(rect.height, 320) / 2, 1.05)
       return
     }
 
     if (event.key === '-' || event.key === '_') {
       event.preventDefault()
       const rect = canvas.getBoundingClientRect()
-      zoomAtPoint(Math.max(rect.width, 320) / 2, Math.max(rect.height, 320) / 2, 0.89)
+      zoomAtPoint(Math.max(rect.width, 320) / 2, Math.max(rect.height, 320) / 2, 0.952)
       return
     }
 

package/package.json

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