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

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

@@ -1,23 +1,29 @@
 import { createHash } from 'node:crypto';
 import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { addVisualContextEdges } from '../domain/graph-contexts.js';
 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 = 5;
 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 +47,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 +75,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 +83,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 = addVisualContextEdges(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

@@ -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

@@ -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/search-graph-node-ids.js

@@ -1,6 +1,7 @@
 import { stat } from 'node:fs/promises';
 import { ensureVault } from '../infrastructure/file-system-vault.js';
 import { indexStoragePath, openFileIndex } from '../infrastructure/file-index.js';
+import { getGraphLayout } from './get-graph-layout.js';
 const graphSearchCacheTtlMs = 20_000;
 const graphSearchCacheMaxEntries = 120;
 const graphSearchCache = new Map();
@@ -13,11 +14,12 @@ const readIndexSignature = async (vaultPath) => {
         return '0:0';
     }
 };
-const cacheKey = (vaultPath, query, limit, agentId) => JSON.stringify({
+const cacheKey = (vaultPath, query, limit, agentId, context) => JSON.stringify({
     vaultPath,
     query: query.trim().toLowerCase(),
     limit,
-    agentId: agentId?.trim().toLowerCase() ?? '*'
+    agentId: agentId?.trim().toLowerCase() ?? '*',
+    context: context?.trim().toLowerCase() ?? '*'
 });
 const readCached = (key, indexSignature) => {
     const entry = graphSearchCache.get(key);
@@ -39,17 +41,24 @@ const writeCached = (key, entry) => {
     const overflow = graphSearchCache.size - graphSearchCacheMaxEntries;
     Array.from(graphSearchCache.keys()).slice(0, overflow).forEach((cacheKey) => graphSearchCache.delete(cacheKey));
 };
-export const searchGraphNodeIds = async (vaultPath, query, limit, agentId) => {
+export const searchGraphNodeIds = async (vaultPath, query, limit, agentId, context) => {
     const absoluteVaultPath = await ensureVault(vaultPath);
     const indexSignature = await readIndexSignature(absoluteVaultPath);
-    const key = cacheKey(absoluteVaultPath, query, limit, agentId);
+    const key = cacheKey(absoluteVaultPath, query, limit, agentId, context);
     const cached = readCached(key, indexSignature);
     if (cached) {
         return cached;
     }
+    const contextNodeIds = context
+        ? new Set((await getGraphLayout(absoluteVaultPath, { agentId, context })).layout.nodes.map((node) => node.id))
+        : new Set();
     const index = openFileIndex(absoluteVaultPath);
     try {
-        const nodeIds = await index.searchGraphNodeIds(query, limit, agentId);
+        const searchLimit = context ? Math.max(limit, 5000) : limit;
+        const foundNodeIds = await index.searchGraphNodeIds(query, searchLimit, agentId);
+        const nodeIds = context
+            ? foundNodeIds.filter((nodeId) => contextNodeIds.has(nodeId)).slice(0, limit)
+            : foundNodeIds;
         writeCached(key, {
             createdAt: Date.now(),
             indexSignature,

package/dist/application/server/routes.js

@@ -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') {
@@ -292,12 +302,15 @@ export const route = async (request, url, vaultPath) => {
         if (!query) {
             return createResponse(createJsonResponse({ query, nodeIds: [] }), 200, contentTypes['.json']);
         }
-        const nodeIds = await searchGraphNodeIds(vaultPath, query, limit, readAgentQuery(url));
+        const nodeIds = await searchGraphNodeIds(vaultPath, query, limit, readAgentQuery(url), readContextQuery(url));
         return createResponse(createJsonResponse({ query, nodeIds }), 200, contentTypes['.json']);
     }
     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/dist/cli/commands/write-commands.js

@@ -9,6 +9,7 @@ import { resolveDuplicateNotes, scanDuplicateNotes } from '../../application/ded
 import { importLegacySqliteDatabase } from '../../application/import-legacy-sqlite.js';
 import { indexVault, indexVaultWithOptions } from '../../application/index-vault.js';
 import { migrateContextLinks } from '../../application/migrate-context-links.js';
+import { canonicalizeContextLinks } from '../../application/canonical-context-links.js';
 import { migrateVaultContent, planVaultMigration, previewVaultMigration, shouldMigrateDefaultVault } from '../../application/migrate-vault.js';
 import { createOfflinePackBackup } from '../../application/offline-pack-backup.js';
 import { startServer } from '../../application/start-server.js';
@@ -16,7 +17,7 @@ import { startVaultWatcher } from '../../application/watch-vault.js';
 import { doctorVault, getStats, validateVault } from '../../application/analyze-vault.js';
 import { defaultBrainlinkConfig, sanitizeSearchMode } from '../../infrastructure/config.js';
 import { loadBrainlinkConfig } from '../../infrastructure/config.js';
-import { assertVaultAllowed, ensureVault } from '../../infrastructure/file-system-vault.js';
+import { assertVaultAllowed, ensureVault, isBucketVaultPath } from '../../infrastructure/file-system-vault.js';
 import { getBootstrapPolicy, getBootstrapSessionStatus, touchBootstrapSession } from '../../infrastructure/session-state.js';
 import { addVolatileMemory, clearVolatileMemory } from '../../infrastructure/volatile-memory.js';
 import { installAgentIntegration } from './agent-commands.js';
@@ -731,6 +732,37 @@ export const registerWriteCommands = (program) => {
             return `${mode} ${result.scanned} notes: changed=${result.changed}, skipped=${result.skipped}, limit=${result.limit}.${indexMessage}`;
         });
     });
+    program
+        .command('canonicalize-context-links')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--dry-run', 'preview canonical context links without writing files')
+        .option('--no-create-hubs', 'do not create missing context hub notes')
+        .option('--no-index', 'skip reindexing after canonicalization')
+        .option('--json', 'print machine-readable JSON')
+        .description('ensure notes have canonical Context Links to their inferred context hubs')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const result = await canonicalizeContextLinks(resolved.vault, {
+            dryRun: options.dryRun === true,
+            agentId: resolved.agent,
+            createMissingHubs: options.createHubs !== false
+        });
+        const shouldIndex = options.index !== false && !result.dryRun && result.changed > 0;
+        const index = shouldIndex ? await indexVault(resolved.vault, { full: true }) : undefined;
+        print(options.json, {
+            vault: resolved.vault,
+            agent: resolved.agent ?? 'shared',
+            ...result,
+            ...(index ? { index } : {})
+        }, () => {
+            const mode = result.dryRun ? 'Previewed' : 'Canonicalized';
+            const indexMessage = index
+                ? ` Fully reindexed ${index.documentCount} documents, ${index.chunkCount} chunks and ${index.linkCount} context links.`
+                : '';
+            return `${mode} ${result.scanned} notes: changed=${result.changed}, createdHubs=${result.createdHubs}, skipped=${result.skipped}.${indexMessage}`;
+        });
+    });
     program
         .command('db-import')
         .option('-v, --vault <vault>', 'vault directory')
@@ -793,6 +825,7 @@ export const registerWriteCommands = (program) => {
         .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'agent memory namespace')
         .option('--allow-sensitive', 'allow writing content that looks like a secret')
+        .option('--no-auto-context-links', 'skip canonical Context Links for this note')
         .option('--no-auto-index', 'skip reindexing after add')
         .option('--json', 'print machine-readable JSON')
         .description('add a markdown note to the vault')
@@ -800,7 +833,8 @@ export const registerWriteCommands = (program) => {
         const resolved = await resolveOptions(options);
         const content = resolveAddContent(options);
         const added = await addNoteWithMetadata(resolved.vault, title, content, resolved.agent, {
-            allowSensitive: Boolean(options.allowSensitive)
+            allowSensitive: Boolean(options.allowSensitive),
+            autoContextLinks: options.autoContextLinks !== false && resolved.config.autoCanonicalContextLinks
         });
         const shouldAutoIndex = options.autoIndex !== false && resolved.config.autoIndexOnWrite;
         const index = shouldAutoIndex ? await indexVault(resolved.vault) : undefined;
@@ -824,7 +858,9 @@ export const registerWriteCommands = (program) => {
             writeConnectivity: {
                 autoLinked: added.autoLinked,
                 linkTarget: added.linkTarget,
-                guaranteedEdge: false
+                context: added.context,
+                hubCreated: added.hubCreated,
+                guaranteedEdge: added.autoLinked
             },
             possibleDuplicates,
             ...(index ? { index } : {})
@@ -832,7 +868,8 @@ export const registerWriteCommands = (program) => {
             const duplicateMessage = possibleDuplicates.length > 0
                 ? `\nPotential duplicates: ${possibleDuplicates.length}. Use "blink dedupe --json" or "blink dedupe-resolve".`
                 : '';
-            return `Created note at ${added.path}${duplicateMessage}`;
+            const linkMessage = added.autoLinked ? ` Linked to [[${added.linkTarget}]].` : '';
+            return `Created note at ${added.path}.${linkMessage}${duplicateMessage}`;
         });
     });
     program
@@ -1037,26 +1074,28 @@ export const registerWriteCommands = (program) => {
         .option('-p, --port <port>', 'server port', '4321')
         .option('--no-index', 'skip indexing before starting the server')
         .option('--no-open', 'do not open the graph UI automatically')
-        .option('-w, --watch', 'watch markdown files and reindex on changes')
+        .option('-w, --watch', 'watch markdown files and reindex on changes', true)
+        .option('--no-watch', 'disable markdown file watching')
         .option('--json', 'print machine-readable JSON')
         .description('start a local web UI for the knowledge graph')
         .action(async (options) => {
         const resolved = await resolveOptions(options);
+        const shouldWatch = options.watch !== false && !isBucketVaultPath(resolved.vault);
         const server = await startServer({
             vaultPath: resolved.vault,
             host: options.host ?? resolved.config.host,
             port: parsePositiveInteger(options.port ?? String(resolved.config.port), resolved.config.port),
             shouldIndex: options.index,
-            shouldWatch: Boolean(options.watch)
+            shouldWatch
         });
         const openResult = options.open !== false ? openUrlInUi(server.url, process.pid) : { opened: false, mode: 'none' };
         print(options.json, {
             url: server.url,
-            watch: Boolean(options.watch),
+            watch: shouldWatch,
             readonly: true,
             openedUi: openResult.opened,
             openMode: openResult.mode
-        }, () => `Brainlink graph server running at ${server.url}${openResult.opened
+        }, () => `Brainlink graph server running at ${server.url} (${shouldWatch ? 'watching for changes' : 'watch disabled'})${openResult.opened
             ? openResult.mode === 'native-gui'
                 ? ' (opened in native desktop GUI)'
                 : openResult.mode === 'app-window'

package/dist/domain/graph-contexts.js

@@ -0,0 +1,159 @@
+const normalize = (value) => value.trim().toLowerCase();
+const includesAny = (value, patterns) => patterns.some((pattern) => pattern.test(value));
+const contextId = (title) => title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+const context = (title) => ({
+    id: contextId(title),
+    title
+});
+const byTitle = (left, right) => left.title.localeCompare(right.title);
+const edgeKey = (source, target) => source < target ? `${source}|${target}` : `${target}|${source}`;
+const nodeSearchText = (node) => normalize([node.title, node.path, ...node.tags].join(' '));
+export const inferExplicitVisualGraphContext = (node) => {
+    const text = nodeSearchText(node);
+    const path = normalize(node.path);
+    if (includesAny(text, [/\bgithub repositories hub\b/]))
+        return context('GitHub Repositories');
+    if (includesAny(text, [/\bgithub organizations hub\b/]))
+        return context('GitHub Organizations');
+    if (includesAny(text, [/\bmachine configuration hub\b/]))
+        return context('Machine Configuration');
+    if (includesAny(text, [/\buser preferences hub\b/]))
+        return context('User Preferences');
+    if (includesAny(text, [/\bneovim lazyvim hub\b/]))
+        return context('Neovim LazyVim');
+    if (includesAny(text, [/\bgit workflow hub\b/]))
+        return context('Git Workflow');
+    if (includesAny(text, [/\bagent memory hub\b/]))
+        return context('Agent Memory');
+    if (path.startsWith('github-repos/'))
+        return context('GitHub Repositories');
+    if (path.startsWith('github-org-repos/'))
+        return context('GitHub Organizations');
+    if (path.startsWith('machine-config/'))
+        return context('Machine Configuration');
+    if (includesAny(text, [/\bbrainlink\b/]))
+        return context('Brainlink');
+    if (includesAny(text, [/\banonspace\b/]))
+        return context('AnonSpace');
+    if (includesAny(text, [/\bsubstructa\b/]))
+        return context('Substructa');
+    if (includesAny(text, [/\bnebula\b/]))
+        return context('Nebula');
+    if (includesAny(text, [/\bsnippets?\b/, /\bupgrader\b/, /\bversion-map\b/]))
+        return context('Snippets');
+    if (includesAny(text, [/\binkdrop\b/]))
+        return context('Inkdrop');
+    if (includesAny(text, [
+        /\bpreference\b/,
+        /\bpreferencia\b/,
+        /\bpreferencias\b/,
+        /\bplaybook\b/,
+        /\bdirective\b/,
+        /\bengineering-style\b/,
+        /\bglobal-engineering\b/,
+        /\bcoding-identity\b/,
+        /\bagents\.md\b/
+    ])) {
+        return context('User Preferences');
+    }
+    if (includesAny(text, [/\blazyvim\b/, /\bneovim\b/, /\bnvim\b/, /\bmason\b/, /\bwrapper\b/]))
+        return context('Neovim LazyVim');
+    if (includesAny(text, [/\bgit-flow\b/, /\borigin-sync\b/, /\bgit-identidade\b/, /\bcommit\b/, /\bpush\b/]))
+        return context('Git Workflow');
+    if (includesAny(text, [/\bdocker\b/, /\bkubernetes\b/, /\bdeploy\b/, /\bredeploy\b/]))
+        return context('Operations');
+    if (path.startsWith('agents/'))
+        return context('Agent Memory');
+    return null;
+};
+export const inferVisualGraphContext = (node) => {
+    const explicit = inferExplicitVisualGraphContext(node);
+    if (explicit) {
+        return explicit;
+    }
+    const [root] = node.path.split('/').filter(Boolean);
+    return context(root ? root.replace(/[-_]+/g, ' ') : 'Root');
+};
+export const groupNodesByVisualContext = (nodes) => {
+    const groups = new Map();
+    nodes.forEach((node) => {
+        const visualContext = inferVisualGraphContext(node);
+        const bucket = groups.get(visualContext.title);
+        if (bucket) {
+            bucket.push(node);
+            return;
+        }
+        groups.set(visualContext.title, [node]);
+    });
+    return new Map(Array.from(groups.entries(), ([title, groupedNodes]) => [title, [...groupedNodes].sort(byTitle)]));
+};
+const countDegrees = (edges) => edges.reduce((degrees, edge) => {
+    degrees.set(edge.source, (degrees.get(edge.source) ?? 0) + edge.weight);
+    if (edge.target) {
+        degrees.set(edge.target, (degrees.get(edge.target) ?? 0) + edge.weight);
+    }
+    return degrees;
+}, new Map());
+const selectVisualHub = (contextTitle, nodes, degrees) => {
+    const normalizedContext = normalize(contextTitle).replace(/\s+/g, ' ');
+    const ranked = [...nodes].sort((left, right) => {
+        const leftTitle = normalize(left.title);
+        const rightTitle = normalize(right.title);
+        const leftHubScore = leftTitle === normalizedContext || leftTitle === `${normalizedContext} hub`
+            ? 4
+            : leftTitle.includes(normalizedContext) && /\bhub\b/.test(leftTitle)
+                ? 3
+                : /\b(memory hub|knowledge root|moc|map|hub)\b/.test(leftTitle)
+                    ? 2
+                    : 0;
+        const rightHubScore = rightTitle === normalizedContext || rightTitle === `${normalizedContext} hub`
+            ? 4
+            : rightTitle.includes(normalizedContext) && /\bhub\b/.test(rightTitle)
+                ? 3
+                : /\b(memory hub|knowledge root|moc|map|hub)\b/.test(rightTitle)
+                    ? 2
+                    : 0;
+        const hubDelta = rightHubScore - leftHubScore;
+        if (hubDelta !== 0)
+            return hubDelta;
+        const degreeDelta = (degrees.get(right.id) ?? 0) - (degrees.get(left.id) ?? 0);
+        return degreeDelta === 0 ? left.title.localeCompare(right.title) : degreeDelta;
+    });
+    return ranked[0] ?? null;
+};
+export const addVisualContextEdges = (graph) => {
+    const existingPairs = new Set(graph.edges
+        .filter((edge) => Boolean(edge.target))
+        .map((edge) => edgeKey(edge.source, edge.target)));
+    const degrees = countDegrees(graph.edges);
+    const derivedEdges = [];
+    for (const [contextTitle, nodes] of groupNodesByVisualContext(graph.nodes).entries()) {
+        if (nodes.length <= 1) {
+            continue;
+        }
+        const hub = selectVisualHub(contextTitle, nodes, degrees);
+        if (!hub) {
+            continue;
+        }
+        nodes
+            .filter((node) => node.id !== hub.id)
+            .forEach((node) => {
+            const key = edgeKey(hub.id, node.id);
+            if (existingPairs.has(key)) {
+                return;
+            }
+            existingPairs.add(key);
+            derivedEdges.push({
+                source: hub.id,
+                target: node.id,
+                targetTitle: node.title,
+                weight: 0.5,
+                priority: 'low'
+            });
+        });
+    }
+    return {
+        nodes: graph.nodes,
+        edges: [...graph.edges, ...derivedEdges]
+    };
+};

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);

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.',