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

package/dist/domain/graph-layout.js

@@ -1,3 +1,4 @@
+import { inferExplicitVisualGraphContext } from './graph-contexts.js';
 const hierarchyGroupNodeLimit = 1000;
 const groupLabels = {
     '00-maps': 'maps',
@@ -140,8 +141,16 @@ const selectSegmentSeeds = (nodes, edges, degrees) => {
 const assignSegments = (nodes, edges, degrees) => {
     const adjacency = createAdjacency(nodes, edges);
     const seeds = selectSegmentSeeds(nodes, edges, degrees);
-    const assignments = new Map(seeds.map((seed) => [seed.id, segmentName(seed)]));
+    const assignments = new Map(nodes.flatMap((node) => {
+        const visualContext = inferExplicitVisualGraphContext(node);
+        return visualContext ? [[node.id, visualContext.title]] : [];
+    }));
     const queue = seeds.map((seed) => seed.id);
+    seeds.forEach((seed) => {
+        if (!assignments.has(seed.id)) {
+            assignments.set(seed.id, segmentName(seed));
+        }
+    });
     for (let index = 0; index < queue.length; index += 1) {
         const id = queue[index];
         const segment = assignments.get(id);
@@ -347,8 +356,9 @@ const resolveCollisionPair = (left, right, minDistance) => {
         return;
     }
     const push = (minDistance - distance) / 2;
-    const ux = dx / distance;
-    const uy = dy / distance;
+    const fallbackAngle = Math.PI * 2 * (Math.abs(hashText(`${left.id}:${right.id}`) % 1000) / 1000);
+    const ux = Math.abs(dx) + Math.abs(dy) < 0.001 ? Math.cos(fallbackAngle) : dx / distance;
+    const uy = Math.abs(dx) + Math.abs(dy) < 0.001 ? Math.sin(fallbackAngle) : dy / distance;
     left.x -= ux * push;
     left.y -= uy * push;
     right.x += ux * push;
@@ -478,19 +488,35 @@ const createStarNodes = (nodes, segments, degrees, hubId, levels) => {
                 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)
-            };
+        const levelNodesBySegment = segmentNames
+            .map((segment) => ({
+            segment,
+            nodes: levelNodes.filter((node) => (segments.get(node.id) ?? groupLabel(groupKey(node))) === segment)
+        }))
+            .filter((group) => group.nodes.length > 0);
+        const totalNodes = levelNodesBySegment.reduce((total, group) => total + group.nodes.length, 0);
+        const baseRadius = Math.max(360 + (level - 1) * 460, (levelNodes.length * 156) / (Math.PI * 2));
+        let arcCursor = -Math.PI / 2;
+        return levelNodesBySegment.flatMap((group) => {
+            const arcSize = (Math.PI * 2 * group.nodes.length) / Math.max(totalNodes, 1);
+            const arcPadding = Math.min(0.22, arcSize * 0.18);
+            const arcStart = arcCursor + arcPadding;
+            const arcEnd = arcCursor + arcSize - arcPadding;
+            const usableArc = Math.max(0.001, arcEnd - arcStart);
+            const segmentRadius = Math.max(baseRadius, (group.nodes.length * 156) / usableArc);
+            arcCursor += arcSize;
+            return group.nodes.map((node, index) => {
+                const lane = index % 3 - 1;
+                const angle = arcStart + usableArc * ((index + 0.5) / Math.max(group.nodes.length, 1)) + jitter(node.title, 0.035);
+                const radialJitter = jitter(node.id, 34);
+                return {
+                    ...node,
+                    group: groupLabel(groupKey(node)),
+                    segment: group.segment,
+                    x: Math.cos(angle) * (segmentRadius + lane * 52 + radialJitter) + jitter(node.title, 16),
+                    y: Math.sin(angle) * (segmentRadius + lane * 52 + radialJitter) + jitter(node.path, 16)
+                };
+            });
         });
     });
 };
@@ -499,7 +525,7 @@ export const createStarGraphLayout = (graph) => {
     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 nodes = relaxCollisions(createStarNodes(graph.nodes, segments, degrees, hubId, levels), 156, 22);
     const centeredNodes = centerLayoutByNode(nodes, hubId);
     const groups = createGraphLayoutHierarchy(centeredNodes, graph.edges, degrees);
     return {

package/dist/infrastructure/config.js

@@ -10,6 +10,7 @@ export const defaultBrainlinkConfig = {
     allowedVaults: [],
     defaultAgent: undefined,
     autoIndexOnWrite: true,
+    autoCanonicalContextLinks: true,
     defaultSearchLimit: 10,
     defaultContextTokens: 2000,
     embeddingProvider: 'local',
@@ -159,6 +160,9 @@ const sanitizeConfig = (value) => ({
         ? sanitizeAgentId(value.defaultAgent)
         : defaultBrainlinkConfig.defaultAgent,
     autoIndexOnWrite: typeof value.autoIndexOnWrite === 'boolean' ? value.autoIndexOnWrite : defaultBrainlinkConfig.autoIndexOnWrite,
+    autoCanonicalContextLinks: typeof value.autoCanonicalContextLinks === 'boolean'
+        ? value.autoCanonicalContextLinks
+        : defaultBrainlinkConfig.autoCanonicalContextLinks,
     defaultSearchLimit: typeof value.defaultSearchLimit === 'number' && value.defaultSearchLimit > 0
         ? value.defaultSearchLimit
         : defaultBrainlinkConfig.defaultSearchLimit,

package/dist/mcp/server.js

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, contextInputSchema, contextTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools.js';
+import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, canonicalizeContextLinksInputSchema, canonicalizeContextLinksTool, contextInputSchema, contextTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools.js';
 import { getRuntimeVersion } from './runtime.js';
 export const createBrainlinkMcpServer = () => {
     const server = new McpServer({
@@ -68,6 +68,11 @@ export const createBrainlinkMcpServer = () => {
         description: 'Read a local markdown/text file and ingest it as a Brainlink note. Reindex defaults to true.',
         inputSchema: addFileInputSchema
     }, addFileTool);
+    server.registerTool('brainlink_canonicalize_context_links', {
+        title: 'Canonicalize Brainlink Context Links',
+        description: 'Ensure notes have canonical Context Links to inferred context hubs. Supports dry-run and can create missing hub notes.',
+        inputSchema: canonicalizeContextLinksInputSchema
+    }, canonicalizeContextLinksTool);
     server.registerTool('brainlink_index', {
         title: 'Index Brainlink Vault',
         description: 'Rebuild the local Brainlink index from Markdown notes. Pass full=true to force a complete source rebuild.',
@@ -93,6 +98,11 @@ export const createBrainlinkMcpServer = () => {
         description: 'Read indexed graph nodes and wiki-link edges. Edges include weight and priority fields so agents can rank importance and priority.',
         inputSchema: graphInputSchema
     }, graphTool);
+    server.registerTool('brainlink_graph_contexts', {
+        title: 'List Brainlink Graph Contexts',
+        description: 'List visual graph contexts used by the Brainlink server to separate memory domains such as preferences, repositories and machine configuration.',
+        inputSchema: graphContextsInputSchema
+    }, graphContextsTool);
     server.registerTool('brainlink_broken_links', {
         title: 'List Brainlink Broken Links',
         description: 'List unresolved indexed wiki links.',

package/dist/mcp/tools.js

@@ -4,8 +4,10 @@ import { z } from 'zod';
 import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../application/analyze-vault.js';
 import { addNoteWithMetadata } from '../application/add-note.js';
 import { buildContextPackage } from '../application/build-context.js';
+import { canonicalizeContextLinks } from '../application/canonical-context-links.js';
 import { resolveDuplicateNotes, scanDuplicateNotes } from '../application/dedupe-notes.js';
 import { getGraph } from '../application/get-graph.js';
+import { getGraphContexts } from '../application/get-graph-contexts.js';
 import { indexVault } from '../application/index-vault.js';
 import { searchKnowledge } from '../application/search-knowledge.js';
 import { resolveAgentRuntimeDefaults, sanitizeSearchMode } from '../infrastructure/config.js';
@@ -237,7 +239,11 @@ export const addNoteInputSchema = {
         .describe('Durable Markdown memory. Include explicit [[wiki links]] and #tags when the memory should be connected. Put priority markers near important links, for example priority: high, #important or #critical.'),
     ...agentInput,
     allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.'),
-    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after writing note.')
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after writing note.'),
+    autoContextLinks: z
+        .boolean()
+        .optional()
+        .describe('Automatically add canonical Context Links to the inferred visual context hub. Defaults to Brainlink config.')
 };
 export const volatileAddInputSchema = {
     ...vaultInput,
@@ -261,6 +267,13 @@ export const addFileInputSchema = {
     autoIndex: z.boolean().optional().default(true).describe('Reindex vault after ingesting file.'),
     allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.')
 };
+export const canonicalizeContextLinksInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    dryRun: z.boolean().optional().default(false).describe('Preview canonical context-link writes without changing Markdown.'),
+    createHubs: z.boolean().optional().default(true).describe('Create missing context hub notes when needed.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex after canonicalization when files changed.')
+};
 export const indexInputSchema = {
     ...vaultInput,
     full: z
@@ -277,6 +290,10 @@ export const graphInputSchema = {
     ...vaultInput,
     ...agentInput
 };
+export const graphContextsInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
 export const brokenLinksInputSchema = {
     ...vaultInput,
     ...agentInput
@@ -401,7 +418,8 @@ export const addNoteTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const shouldIndex = isTruthy(input.autoIndex);
     const added = await addNoteWithMetadata(context.vault, input.title, input.content, context.agent, {
-        allowSensitive: input.allowSensitive
+        allowSensitive: input.allowSensitive,
+        autoContextLinks: input.autoContextLinks ?? context.config.autoCanonicalContextLinks
     });
     const index = shouldIndex ? await indexVault(context.vault) : undefined;
     const focusPath = added.path.includes('agents/') ? added.path.slice(added.path.indexOf('agents/')).replaceAll('\\', '/') : undefined;
@@ -420,7 +438,9 @@ export const addNoteTool = async (input) => {
         writeConnectivity: {
             autoLinked: added.autoLinked,
             linkTarget: added.linkTarget,
-            guaranteedEdge: false
+            context: added.context,
+            hubCreated: added.hubCreated,
+            guaranteedEdge: added.autoLinked
         },
         possibleDuplicates,
         ...(index ? { index } : {})
@@ -455,7 +475,8 @@ export const addFileTool = async (input) => {
     }
     const shouldIndex = isTruthy(input.autoIndex);
     const added = await addNoteWithMetadata(context.vault, title, content, context.agent, {
-        allowSensitive: input.allowSensitive
+        allowSensitive: input.allowSensitive,
+        autoContextLinks: context.config.autoCanonicalContextLinks
     });
     const index = shouldIndex ? await indexVault(context.vault) : undefined;
     return jsonResult({
@@ -467,11 +488,30 @@ export const addFileTool = async (input) => {
         writeConnectivity: {
             autoLinked: added.autoLinked,
             linkTarget: added.linkTarget,
-            guaranteedEdge: false
+            context: added.context,
+            hubCreated: added.hubCreated,
+            guaranteedEdge: added.autoLinked
         },
         ...(index ? { index } : {})
     });
 };
+export const canonicalizeContextLinksTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await canonicalizeContextLinks(context.vault, {
+        agentId: context.agent,
+        dryRun: input.dryRun === true,
+        createMissingHubs: input.createHubs !== false
+    });
+    const index = input.autoIndex !== false && !result.dryRun && result.changed > 0
+        ? await indexVault(context.vault, { full: true })
+        : undefined;
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...result,
+        ...(index ? { index } : {})
+    });
+};
 export const indexTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const result = await indexVault(context.vault, {
@@ -520,6 +560,25 @@ export const graphTool = async (input) => {
         ...graph
     });
 };
+export const graphContextsTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_graph_contexts');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_graph_contexts');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const contexts = await getGraphContexts(context.vault, context.agent);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        contexts
+    });
+};
 export const brokenLinksTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const readiness = await ensureBootstrapReady(context, input, 'brainlink_broken_links');

package/docs/AGENT_USAGE.md

@@ -56,6 +56,7 @@ You can tune search-pack compression with `searchPack.rowChunkSize`, `searchPack
 Guardrails for benchmark acceptance are configured with `searchPack.guardrailMinSavingsPercent` and `searchPack.guardrailMaxLatencyRegressionPercent`.
 
 `autoIndexOnWrite` (default: `true`) controls whether `add` and MCP write tools index right after writing.
+`autoCanonicalContextLinks` (default: `true`) controls whether CLI/MCP write tools add canonical `## Context Links` to inferred context hubs.
 
 ## Agent Namespaces
 
@@ -627,12 +628,14 @@ Use `--no-index` when you need to inspect the current index without rebuilding i
 blink server --vault ./vault --no-index
 ```
 
-Use `--watch` to keep the graph updated after Markdown edits:
+The server watches Markdown files by default and keeps the graph updated after edits:
 
 ```bash
-blink server --vault ./vault --watch
+blink server --vault ./vault
 ```
 
+Use `--no-watch` when you need to run the graph server without realtime reindexing.
+
 ### Watch A Vault
 
 ```bash
@@ -672,6 +675,7 @@ Available MCP tools:
 - `brainlink_resolve_duplicate`
 - `brainlink_add_note`
 - `brainlink_add_file`
+- `brainlink_canonicalize_context_links`
 - `brainlink_volatile_add`
 - `brainlink_volatile_clear`
 - `brainlink_index`
@@ -679,6 +683,7 @@ Available MCP tools:
 - `brainlink_validate`
 - `brainlink_sync`
 - `brainlink_graph`
+- `brainlink_graph_contexts`
 - `brainlink_broken_links`
 - `brainlink_orphans`
 

package/package.json

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