npm - @andespindola/brainlink - Versions diffs - 0.1.0-beta.152 → 0.1.0-beta.153 - Mend

@andespindola/brainlink 0.1.0-beta.152 → 0.1.0-beta.153

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md +3 -0
package/dist/application/frontend/client-css.js +8 -4
package/dist/application/frontend/client-html.js +3 -0
package/dist/application/frontend/client-js.js +103 -7
package/dist/application/get-graph-contexts.js +19 -0
package/dist/application/get-graph-layout.js +37 -17
package/dist/application/get-graph-stream-chunk.js +4 -1
package/dist/application/get-graph-view.js +4 -1
package/dist/application/server/routes.js +16 -3
package/docs/ARCHITECTURE.md +2 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -601,6 +601,7 @@ The graph UI shows:
 - 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
 - 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` is enabled
@@ -632,6 +633,7 @@ The server always refuses non-loopback hosts. Brainlink HTTP only runs on localh
 Routes:
 - `GET /api/agents`
+- `GET /api/graph-contexts`
 - `GET /api/graph`
 - `GET /api/graph-layout`
 - `GET /api/graph-view?x=<x>&y=<y>&w=<width>&h=<height>&scale=<scale>`
@@ -650,6 +652,7 @@ Read routes accept `agent=<agent-id>`:
 ```txt
 /api/graph-layout?agent=coding-agent
+/api/graph-layout?agent=coding-agent&context=Architecture
 /api/search?q=typescript&agent=coding-agent&mode=hybrid
 /api/context?q=module-boundaries&agent=coding-agent&mode=semantic
 ```

package/dist/application/frontend/client-css.js CHANGED Viewed

@@ -113,7 +113,8 @@ select {
   min-width: 220px;
 }
-.agent-filter {
+.agent-filter,
+.context-filter {
   width: min(220px, 28vw);
 }
@@ -125,7 +126,8 @@ select {
 }
 .search input,
-.agent-filter select {
+.agent-filter select,
+.context-filter select {
   width: 100%;
   height: 40px;
   border: 1px solid var(--line);
@@ -137,7 +139,8 @@ select {
 }
 .search input:focus,
-.agent-filter select:focus {
+.agent-filter select:focus,
+.context-filter select:focus {
   border-color: var(--accent);
 }
@@ -405,7 +408,8 @@ li small {
     order: 3;
   }
-  .agent-filter {
+  .agent-filter,
+  .context-filter {
     width: 100%;
   }

package/dist/application/frontend/client-html.js CHANGED Viewed

@@ -35,6 +35,9 @@ export const createClientHtml = () => `<!doctype html>
             <label class="agent-filter">
               <select id="agent"></select>
             </label>
+            <label class="context-filter">
+              <select id="context"></select>
+            </label>
             <div class="toolbar" aria-label="Graph controls">
               <button id="zoomIn" type="button" title="Zoom in">+</button>
               <button id="zoomOut" type="button" title="Zoom out">-</button>

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

@@ -4,6 +4,7 @@ const byId = (id) => document.getElementById(id)
 const elements = {
   search: byId('search'),
   agent: byId('agent'),
+  context: byId('context'),
   nodeCount: byId('nodeCount'),
   edgeCount: byId('edgeCount'),
   tagCount: byId('tagCount'),
@@ -49,6 +50,7 @@ const state = {
   rendererMode: 'worker',
   renderWorker: null,
   agentId: '',
+  contextId: '',
   graphSignature: '',
   graphMode: 'near',
   chunk: {
@@ -77,6 +79,7 @@ const zoomRange = {
 }
 const selectedAgentStorageKey = 'brainlink:selected-agent'
+const selectedContextStorageKey = 'brainlink:selected-context'
 const escapeHtml = (value) => String(value)
   .replaceAll('&', '&amp;')
@@ -104,6 +107,25 @@ const writeStoredAgent = (agentId) => {
   } catch {}
 }
+const readStoredContext = () => {
+  try {
+    const value = window.localStorage.getItem(selectedContextStorageKey)?.trim() ?? ''
+    return value.length > 0 ? value : ''
+  } catch {
+    return ''
+  }
+}
+const writeStoredContext = (contextId) => {
+  try {
+    if (!contextId) {
+      window.localStorage.removeItem(selectedContextStorageKey)
+      return
+    }
+    window.localStorage.setItem(selectedContextStorageKey, contextId)
+  } catch {}
+}
 const syncAgentInUrl = (agentId) => {
   try {
     const url = new URL(window.location.href)
@@ -116,6 +138,18 @@ const syncAgentInUrl = (agentId) => {
   } catch {}
 }
+const syncContextInUrl = (contextId) => {
+  try {
+    const url = new URL(window.location.href)
+    if (contextId && contextId.trim().length > 0) {
+      url.searchParams.set('context', contextId)
+    } else {
+      url.searchParams.delete('context')
+    }
+    window.history.replaceState({}, '', url.toString())
+  } catch {}
+}
 const initialAgentFromUrl = (() => {
   try {
     const raw = new URL(window.location.href).searchParams.get('agent')
@@ -126,7 +160,28 @@ const initialAgentFromUrl = (() => {
   }
 })()
-const agentQuery = (separator = '?') => state.agentId ? separator + 'agent=' + encodeURIComponent(state.agentId) : ''
+const initialContextFromUrl = (() => {
+  try {
+    const raw = new URL(window.location.href).searchParams.get('context')
+    const value = raw?.trim() ?? ''
+    return value.length > 0 ? value : ''
+  } catch {
+    return ''
+  }
+})()
+const scopeQuery = (separator = '?') => {
+  const params = new URLSearchParams()
+  if (state.agentId) {
+    params.set('agent', state.agentId)
+  }
+  if (state.contextId) {
+    params.set('context', state.contextId)
+  }
+  const query = params.toString()
+  return query ? separator + query : ''
+}
 const parseColor = (hex) => {
   const normalized = String(hex || '#ffffff').replace('#', '')
@@ -375,7 +430,7 @@ const loadNodeDetails = async (nodeId) => {
     return
   }
-  const response = await fetch('/api/graph-node?id=' + encodeURIComponent(nodeId) + agentQuery('&'))
+  const response = await fetch('/api/graph-node?id=' + encodeURIComponent(nodeId) + scopeQuery('&'))
   if (!response.ok) {
     throw new Error('Failed to load graph node details')
   }
@@ -479,6 +534,9 @@ const fetchChunk = async ({ fit } = { fit: false }) => {
   if (state.agentId) {
     params.set('agent', state.agentId)
   }
+  if (state.contextId) {
+    params.set('context', state.contextId)
+  }
   const response = await fetch('/api/graph-stream?' + params.toString(), { signal: controller.signal })
   if (!response.ok) {
@@ -751,7 +809,7 @@ const setupControls = () => {
       return
     }
-    fetch('/api/graph-filter?q=' + encodeURIComponent(query) + '&limit=1800' + agentQuery('&'))
+    fetch('/api/graph-filter?q=' + encodeURIComponent(query) + '&limit=1800' + scopeQuery('&'))
       .then((response) => response.json())
       .then((payload) => {
         if (token !== state.searchToken) {
@@ -795,12 +853,50 @@ const loadAgents = async () => {
     state.agentId = elements.agent.value || ''
     writeStoredAgent(state.agentId)
     syncAgentInUrl(state.agentId)
-    scheduleChunkFetch({ fit: true })
+    loadContexts().then(() => scheduleChunkFetch({ fit: true })).catch((error) => console.error(error))
   })
   syncAgentInUrl(state.agentId)
 }
+const loadContexts = async () => {
+  const response = await fetch('/api/graph-contexts' + (state.agentId ? '?agent=' + encodeURIComponent(state.agentId) : ''))
+  if (!response.ok) {
+    throw new Error('Failed to load graph contexts')
+  }
+  const payload = await response.json()
+  const contexts = Array.isArray(payload?.contexts) ? payload.contexts : []
+  const options = [
+    '<option value="">All contexts</option>',
+    ...contexts.map((context) => {
+      const id = String(context?.id || '')
+      const title = String(context?.title || id || 'Untitled')
+      const count = Number.isFinite(context?.nodeCount) ? context.nodeCount : 0
+      return '<option value="' + escapeHtml(id) + '">' + escapeHtml(title) + ' (' + count + ')</option>'
+    })
+  ]
+  elements.context.innerHTML = options.join('')
+  const preferredContext = initialContextFromUrl || readStoredContext()
+  const hasPreferred = preferredContext && contexts.some((context) => context?.id === preferredContext)
+  state.contextId = hasPreferred ? preferredContext : ''
+  elements.context.value = state.contextId
+  writeStoredContext(state.contextId)
+  syncContextInUrl(state.contextId)
+}
+const setupContextControl = () => {
+  elements.context.addEventListener('change', () => {
+    state.contextId = elements.context.value || ''
+    state.selectedNodeId = null
+    writeStoredContext(state.contextId)
+    syncContextInUrl(state.contextId)
+    scheduleChunkFetch({ fit: true })
+  })
+}
 const setupRenderWorker = () => {
   const hasWorker = typeof Worker !== 'undefined'
   const canTransfer = typeof canvas.transferControlToOffscreen === 'function'
@@ -892,6 +988,7 @@ const bootstrap = async () => {
   setupRenderWorker()
   setupInput()
   setupControls()
+  setupContextControl()
   wireNodeLinkClicks()
   window.addEventListener('resize', () => {
@@ -900,12 +997,11 @@ const bootstrap = async () => {
   })
   await loadAgents()
+  await loadContexts()
   updateTotals()
   updateTagCount()
-  if (state.rendererMode === 'fallback') {
-    scheduleChunkFetch({ fit: true })
-  }
+  scheduleChunkFetch({ fit: true })
 }
 bootstrap().catch((error) => {

package/dist/application/get-graph-contexts.js ADDED Viewed

@@ -0,0 +1,19 @@
+import { getGraphLayout } from './get-graph-layout.js';
+export const getGraphContexts = async (vaultPath, agentId) => {
+    const { layout } = await getGraphLayout(vaultPath, { agentId });
+    const nodeIdsByContext = layout.nodes.reduce((contexts, node) => {
+        const title = node.segment || node.group || 'root';
+        const nodeIds = contexts.get(title) ?? new Set();
+        nodeIds.add(node.id);
+        contexts.set(title, nodeIds);
+        return contexts;
+    }, new Map());
+    return Array.from(nodeIdsByContext.entries())
+        .map(([title, nodeIds]) => ({
+        id: title,
+        title,
+        nodeCount: nodeIds.size,
+        edgeCount: layout.edges.filter((edge) => nodeIds.has(edge.source) && Boolean(edge.target && nodeIds.has(edge.target))).length
+    }))
+        .sort((left, right) => right.nodeCount - left.nodeCount || left.title.localeCompare(right.title));
+};

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

@@ -4,20 +4,25 @@ import { dirname, join } from 'node:path';
 import { createStarGraphLayout } from '../domain/graph-layout.js';
 import { indexStoragePath } from '../infrastructure/file-index.js';
 import { getGraphSummary } from './get-graph-summary.js';
-const graphLayoutVersion = 3;
+const graphLayoutVersion = 4;
 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) => {
+const safeCacheSegment = (value, fallback) => value?.replace(/[^a-zA-Z0-9_-]/g, '_') || fallback;
+const graphLayoutStoragePath = (vaultPath, options) => {
+    const agent = safeCacheSegment(options.agentId, 'all');
+    const context = safeCacheSegment(options.context, 'all-contexts');
+    return join(vaultPath, '.brainlink', `graph-layout-${agent}-${context}.json`);
+};
+const readPersistedLayout = async (vaultPath, databaseSignature, options) => {
     try {
-        const parsed = JSON.parse(await readFile(graphLayoutStoragePath(vaultPath, agentId), 'utf8'));
+        const parsed = JSON.parse(await readFile(graphLayoutStoragePath(vaultPath, options), 'utf8'));
         return parsed.databaseSignature === databaseSignature && parsed.layoutVersion === graphLayoutVersion ? parsed : null;
     }
     catch {
         return null;
     }
 };
-const writePersistedLayout = async (vaultPath, agentId, cached) => {
-    const target = graphLayoutStoragePath(vaultPath, agentId);
+const writePersistedLayout = async (vaultPath, options, cached) => {
+    const target = graphLayoutStoragePath(vaultPath, options);
     const temp = `${target}.tmp`;
     await mkdir(dirname(target), { recursive: true, mode: 0o700 });
     await writeFile(temp, `${JSON.stringify(cached)}\n`, { encoding: 'utf8', mode: 0o600 });
@@ -41,9 +46,27 @@ const createGraphSignature = (graph) => {
         .update(`${graph.nodes.length}:${nodesSignature}|${graph.edges.length}:${edgesSignature}`)
         .digest('hex');
 };
-export const getGraphLayout = async (vaultPath, agentId) => {
+const createLayout = (graph) => {
+    const rawLayout = createStarGraphLayout(graph);
+    return {
+        ...rawLayout,
+        nodes: rawLayout.nodes.map((node) => ({ ...node, content: '' }))
+    };
+};
+const filterGraphByContext = (graph, context) => {
+    const baseLayout = createStarGraphLayout(graph);
+    const selectedNodeIds = new Set(baseLayout.nodes
+        .filter((node) => node.segment === context)
+        .map((node) => node.id));
+    return {
+        nodes: graph.nodes.filter((node) => selectedNodeIds.has(node.id)),
+        edges: graph.edges.filter((edge) => selectedNodeIds.has(edge.source) && Boolean(edge.target && selectedNodeIds.has(edge.target)))
+    };
+};
+export const getGraphLayout = async (vaultPath, optionsOrAgentId) => {
+    const options = typeof optionsOrAgentId === 'string' ? { agentId: optionsOrAgentId } : optionsOrAgentId ?? {};
     const databaseSignature = await readDatabaseSignature(vaultPath);
-    const cacheKey = `${vaultPath}:${agentId ?? ''}`;
+    const cacheKey = `${vaultPath}:${options.agentId ?? ''}:${options.context ?? ''}`;
     const cached = graphLayoutCache.get(cacheKey);
     if (cached?.databaseSignature === databaseSignature && cached.layoutVersion === graphLayoutVersion) {
         return {
@@ -51,7 +74,7 @@ export const getGraphLayout = async (vaultPath, agentId) => {
             layout: cached.layout
         };
     }
-    const persisted = await readPersistedLayout(vaultPath, databaseSignature, agentId);
+    const persisted = await readPersistedLayout(vaultPath, databaseSignature, options);
     if (persisted) {
         graphLayoutCache.set(cacheKey, persisted);
         return {
@@ -59,16 +82,13 @@ export const getGraphLayout = async (vaultPath, agentId) => {
             layout: persisted.layout
         };
     }
-    const graph = await getGraphSummary(vaultPath, agentId);
-    const signature = createGraphSignature(graph);
-    const rawLayout = createStarGraphLayout(graph);
-    const layout = {
-        ...rawLayout,
-        nodes: rawLayout.nodes.map((node) => ({ ...node, content: '' }))
-    };
+    const graph = await getGraphSummary(vaultPath, options.agentId);
+    const scopedGraph = options.context ? filterGraphByContext(graph, options.context) : graph;
+    const signature = createGraphSignature(scopedGraph);
+    const layout = createLayout(scopedGraph);
     const nextCache = { layoutVersion: graphLayoutVersion, databaseSignature, signature, layout };
     graphLayoutCache.set(cacheKey, nextCache);
-    await writePersistedLayout(vaultPath, agentId, nextCache);
+    await writePersistedLayout(vaultPath, options, nextCache);
     return {
         signature,
         layout

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

@@ -244,7 +244,10 @@ const normalizeBudget = (value, fallback, min, max) => {
 export const getGraphStreamChunk = async (vaultPath, input) => {
     const nodeBudget = normalizeBudget(input.nodeBudget, 1800, 80, 12_000);
     const edgeBudget = normalizeBudget(input.edgeBudget, 5000, 120, 60_000);
-    const { signature, layout } = await getGraphLayout(vaultPath, input.agentId);
+    const { signature, layout } = await getGraphLayout(vaultPath, {
+        agentId: input.agentId,
+        context: input.context
+    });
     const groups = layout.groups ?? [];
     const cache = getOrCreateLayoutCache(signature, layout.nodes, layout.edges, groups);
     if (layout.nodes.length === 0) {

package/dist/application/get-graph-view.js CHANGED Viewed

@@ -180,7 +180,10 @@ const arrangeChildGraphNodes = (nodes, group, degrees) => {
 };
 const limitEdges = (edges) => edges.slice(0, edgeLimit);
 export const getGraphView = async (vaultPath, input) => {
-    const { signature, layout } = await getGraphLayout(vaultPath, input.agentId);
+    const { signature, layout } = await getGraphLayout(vaultPath, {
+        agentId: input.agentId,
+        context: input.context
+    });
     const groups = layout.groups ?? [];
     const degrees = degreeMap(layout.edges);
     const groupById = new Map(groups.map((group) => [group.id, group]));

package/dist/application/server/routes.js CHANGED Viewed

@@ -1,6 +1,7 @@
 import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../analyze-vault.js';
 import { buildContextPackage } from '../build-context.js';
 import { getGraph } from '../get-graph.js';
+import { getGraphContexts } from '../get-graph-contexts.js';
 import { getGraphNode } from '../get-graph-node.js';
 import { getGraphLayout } from '../get-graph-layout.js';
 import { getGraphView } from '../get-graph-view.js';
@@ -55,6 +56,10 @@ const sameEntityTag = (candidate, signature) => {
     return decodeEntityTag(candidate) === signature;
 };
 const readAgentQuery = (url) => url.searchParams.get('agent') ?? undefined;
+const readContextQuery = (url) => {
+    const value = url.searchParams.get('context')?.trim() ?? '';
+    return value.length > 0 ? value : undefined;
+};
 const parseNumber = (value, fallback) => {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : fallback;
@@ -218,7 +223,10 @@ export const route = async (request, url, vaultPath) => {
         return createResponse(createJsonResponse(await getGraph(vaultPath, readAgentQuery(url))), 200, contentTypes['.json']);
     }
     if (isReadMethod(request) && url.pathname === '/api/graph-layout') {
-        const { signature, layout } = await getGraphLayout(vaultPath, readAgentQuery(url));
+        const { signature, layout } = await getGraphLayout(vaultPath, {
+            agentId: readAgentQuery(url),
+            context: readContextQuery(url)
+        });
         const requestEtags = request.headers['if-none-match'];
         const notModified = sameEntityTag(requestEtags, signature);
         const etag = encodeEntityTag(signature);
@@ -253,7 +261,8 @@ export const route = async (request, url, vaultPath) => {
             width: parseNumber(url.searchParams.get('w'), 2000),
             height: parseNumber(url.searchParams.get('h'), 2000),
             scale: parseNumber(url.searchParams.get('scale'), 1),
-            agentId: readAgentQuery(url)
+            agentId: readAgentQuery(url),
+            context: readContextQuery(url)
         })), 200, contentTypes['.json']);
     }
     if (isReadMethod(request) && url.pathname === '/api/graph-stream') {
@@ -272,7 +281,8 @@ export const route = async (request, url, vaultPath) => {
             scale,
             nodeBudget,
             edgeBudget,
-            agentId: readAgentQuery(url)
+            agentId: readAgentQuery(url),
+            context: readContextQuery(url)
         })), 200, contentTypes['.json']);
     }
     if (isReadMethod(request) && url.pathname === '/api/graph-node') {
@@ -298,6 +308,9 @@ export const route = async (request, url, vaultPath) => {
     if (isReadMethod(request) && url.pathname === '/api/agents') {
         return createResponse(createJsonResponse({ agents: await listAgents(vaultPath) }), 200, contentTypes['.json']);
     }
+    if (isReadMethod(request) && url.pathname === '/api/graph-contexts') {
+        return createResponse(createJsonResponse({ contexts: await getGraphContexts(vaultPath, readAgentQuery(url)) }), 200, contentTypes['.json']);
+    }
     if (isReadMethod(request) && url.pathname === '/api/search') {
         const query = url.searchParams.get('q') ?? '';
         const limit = parsePositiveInteger(url.searchParams.get('limit'), 10);

package/docs/ARCHITECTURE.md CHANGED Viewed

@@ -154,8 +154,10 @@ server command
   -> optional index rebuild
   -> HTTP server
   -> /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
   -> browser renders graph canvas
 ```

package/package.json CHANGED Viewed

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