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

package/AGENTS.md

@@ -78,10 +78,10 @@ http://127.0.0.1:4321/
 http://127.0.0.1:4321/api/graph
 ```
 
-Use watch mode while editing notes:
+The graph server watches Markdown files by default while editing notes:
 
 ```bash
-npm run dev -- server --vault ./vault --watch
+npm run dev -- server --vault ./vault
 npm run dev -- watch --vault ./vault
 npm run dev -- bench --vault ./vault
 npm run dev -- bench --vault ./vault --watch

package/README.md

@@ -265,7 +265,7 @@ blink search "jwt auth" --vault ./vault
 
 blink context "how does auth work?" --vault ./vault
 
-blink server --vault ./vault --watch
+blink server --vault ./vault
 ```
 
 Open the graph UI:
@@ -536,6 +536,7 @@ Available tools:
 - `brainlink_resolve_duplicate`: resolve duplicate pairs (`merge`, `link`, `ignore`) with connectivity-safe fallback edges.
 - `brainlink_add_note`: write durable Markdown memory and reindex.
 - `brainlink_add_file`: ingest a local file as a note and reindex.
+- `brainlink_canonicalize_context_links`: ensure existing notes link to inferred context hubs.
 - `brainlink_volatile_add`: write temporary agent-decided memory with TTL; volatile sections are included in context and never create durable graph edges.
 - `brainlink_volatile_clear`: clear temporary memory for the current vault/agent namespace.
 - `brainlink_index`: rebuild the vault index. Pass `full=true` for a complete source reindex.
@@ -543,6 +544,7 @@ Available tools:
 - `brainlink_validate`: validate broken links and orphan notes.
 - `brainlink_sync`: run index, stats, validation, broken-link and orphan checks in one call.
 - `brainlink_graph`: read indexed graph nodes and weighted links.
+- `brainlink_graph_contexts`: list the visual graph contexts used by the local server.
 - `brainlink_broken_links`: list unresolved wiki links.
 - `brainlink_orphans`: list disconnected notes.
 
@@ -577,10 +579,11 @@ blink index --vault ./vault --full
 Start the local frontend:
 
 ```bash
-blink server --host 127.0.0.1 --port 4321 --watch
+blink server --host 127.0.0.1 --port 4321
 ```
 
 By default, the server uses `$HOME/.brainlink/vault`. Pass `--vault ./vault` only when you want to inspect a custom vault.
+By default, the server watches Markdown files in local filesystem vaults and reindexes after note changes. Use `--no-watch` to disable realtime reindexing.
 By default, `blink server` tries to open the graph in a native desktop GUI window:
 - macOS: Swift + WebKit
 - Windows: PowerShell WinForms WebBrowser
@@ -604,7 +607,7 @@ The graph UI shows:
 - 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
+- realtime refresh while watch mode is enabled
 - graph controls for zoom in, zoom out, fit visible nodes and reset-to-fit-all
 - wheel zoom (including `cmd+scroll` and `ctrl+scroll`) anchored to cursor position for faster navigation in large graphs
 - wheel/button zoom updates immediately at the cursor anchor without delayed focus-transition interpolation
@@ -944,15 +947,26 @@ blink watch --vault ./vault
 
 Watches Markdown files and rebuilds the index when notes change.
 
+### `canonicalize-context-links`
+
+```bash
+blink canonicalize-context-links --vault ./vault --dry-run
+blink canonicalize-context-links --vault ./vault
+```
+
+Ensures existing notes have canonical `## Context Links` entries to inferred context hubs such as `User Preferences Hub`, `GitHub Repositories Hub` or `Brainlink Hub`. The command is idempotent, creates missing hub notes by default, and fully reindexes after writes unless `--no-index` is passed.
+
 ### `server`
 
 ```bash
-blink server --watch
-blink server --vault ./vault --watch
-blink server --vault ./vault --watch --no-open
+blink server
+blink server --vault ./vault
+blink server --vault ./vault --no-open
+blink server --vault ./vault --no-watch
 ```
 
 Starts the local read-only graph UI and HTTP API.
+Watch mode is enabled by default for Markdown changes in local filesystem vaults. Use `--no-watch` to run without the watcher.
 By default, it tries to open a native desktop GUI window for the graph URL.
 On Linux, native GUI is disabled by default; enable it with `BRAINLINK_LINUX_NATIVE_GUI=1`.
 If native GUI launch is unavailable, it falls back to dedicated app-window mode and then browser open.
@@ -993,6 +1007,7 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
   "allowedVaults": [".brainlink-vault"],
   "defaultAgent": "shared",
   "autoIndexOnWrite": true,
+  "autoCanonicalContextLinks": true,
   "defaultSearchLimit": 10,
   "defaultContextTokens": 2000,
   "embeddingProvider": "local",
@@ -1022,6 +1037,7 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
 `agentProfiles` is optional. When present, CLI and MCP resolve `mode`, `limit` and `tokens` per agent automatically, then fallback to global defaults.
 
 `autoIndexOnWrite` is optional and defaults to `true`. Set it to `false` to defer indexing after writes.
+`autoCanonicalContextLinks` is optional and defaults to `true`. When enabled, `blink add`, `brainlink_add_note` and `brainlink_add_file` add a canonical `## Context Links` entry to the inferred context hub, creating that hub when needed.
 
 Use `"embeddingProvider": "none"` when you want FTS-only indexing.
 
@@ -1100,7 +1116,7 @@ Local CLI:
 
 ```bash
 npm run dev -- --help
-npm run dev -- server --vault .brainlink-vault --watch
+npm run dev -- server --vault .brainlink-vault
 ```
 
 Package smoke test:

package/dist/application/add-note.js

@@ -2,6 +2,7 @@ import { writeMarkdownFile } from '../infrastructure/file-system-vault.js';
 import { sanitizeAgentId, sharedAgentId } from '../domain/agents.js';
 import { validateNoteInput } from '../domain/note-safety.js';
 import { ensureVault } from '../infrastructure/file-system-vault.js';
+import { addCanonicalContextLinkToContent, ensureCanonicalContextHub } from './canonical-context-links.js';
 const slugify = (title) => title
     .normalize('NFKD')
     .replace(/[\u0300-\u036f]/g, '')
@@ -28,12 +29,20 @@ export const addNoteWithMetadata = async (vaultPath, title, content, agentId = s
     const sanitizedAgentId = sanitizeAgentId(agentId);
     const filename = `agents/${sanitizedAgentId}/${slugify(title) || 'untitled'}.md`;
     await ensureVault(vaultPath);
-    const note = buildNote(title, content.trim(), sanitizedAgentId);
+    const canonical = options.autoContextLinks === false
+        ? null
+        : addCanonicalContextLinkToContent(title, content.trim());
+    const hub = canonical?.changed
+        ? await ensureCanonicalContextHub(vaultPath, canonical.context, sanitizedAgentId)
+        : null;
+    const note = buildNote(title, canonical?.content ?? content.trim(), sanitizedAgentId);
     const path = await writeMarkdownFile(vaultPath, filename, note);
     return {
         path,
-        autoLinked: false,
-        linkTarget: null
+        autoLinked: canonical?.changed ?? false,
+        linkTarget: canonical?.changed ? canonical.hubTitle : null,
+        context: canonical?.context ?? null,
+        hubCreated: hub?.created ?? false
     };
 };
 export const addNote = async (vaultPath, title, content, agentId = sharedAgentId, options = {}) => (await addNoteWithMetadata(vaultPath, title, content, agentId, options)).path;

package/dist/application/canonical-context-links.js

@@ -0,0 +1,209 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { inferVisualGraphContext } from '../domain/graph-contexts.js';
+import { sanitizeAgentId, sharedAgentId } from '../domain/agents.js';
+import { extractContextLinkWeights, parseMarkdownDocument } from '../domain/markdown.js';
+import { ensureVault, readMarkdownFileSummaries, writeMarkdownFile } from '../infrastructure/file-system-vault.js';
+const canonicalPriority = 'high';
+const slugify = (title) => title
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+export const hubTitleForContext = (contextTitle) => `${contextTitle} Hub`;
+const hubPathForContext = (contextTitle, agentId) => {
+    if (contextTitle === 'GitHub Repositories')
+        return 'github-repos/github-repositories-hub.md';
+    if (contextTitle === 'GitHub Organizations')
+        return 'github-org-repos/github-organizations-hub.md';
+    if (contextTitle === 'Machine Configuration')
+        return 'machine-config/machine-configuration-hub.md';
+    return join('agents', sanitizeAgentId(agentId), `${slugify(hubTitleForContext(contextTitle))}.md`).replaceAll('\\', '/');
+};
+const normalizeTitle = (title) => title.trim().replace(/\.md$/i, '').toLowerCase();
+const hasCanonicalLink = (content, hubTitle) => extractContextLinkWeights(content).some((link) => normalizeTitle(link.title) === normalizeTitle(hubTitle));
+const linkLine = (hubTitle) => `- [[${hubTitle}]] priority: ${canonicalPriority}`;
+const contextLinksHeading = (line) => line.match(/^(#{2,6})\s+(Context Links|Links de Contexto)\s*$/i);
+export const upsertCanonicalContextLink = (content, hubTitle) => {
+    if (hasCanonicalLink(content, hubTitle)) {
+        return content;
+    }
+    const lines = content.replace(/\s+$/u, '').split('\n');
+    const headingIndex = lines.findIndex((line) => contextLinksHeading(line.trim()));
+    if (headingIndex === -1) {
+        return `${lines.join('\n')}\n\n## Context Links\n\n${linkLine(hubTitle)}\n`;
+    }
+    const heading = contextLinksHeading(lines[headingIndex].trim());
+    const headingDepth = heading?.[1]?.length ?? 2;
+    const insertIndex = lines.findIndex((line, index) => {
+        if (index <= headingIndex)
+            return false;
+        const candidate = line.match(/^(#{2,6})\s+/);
+        return Boolean(candidate && candidate[1].length <= headingDepth);
+    });
+    const targetIndex = insertIndex === -1 ? lines.length : insertIndex;
+    const before = lines.slice(0, targetIndex);
+    const after = lines.slice(targetIndex);
+    const needsSpacer = before[before.length - 1]?.trim() !== '';
+    const nextLines = [...before, ...(needsSpacer ? [''] : []), linkLine(hubTitle), ...after];
+    return `${nextLines.join('\n').replace(/\s+$/u, '')}\n`;
+};
+const buildHubContent = (hubTitle, contextTitle, agentId) => [
+    '---',
+    `title: "${hubTitle.replaceAll('"', '\\"')}"`,
+    `agent: "${sanitizeAgentId(agentId)}"`,
+    '---',
+    '',
+    `# ${hubTitle}`,
+    '',
+    `Canonical hub for the ${contextTitle} context. #memory #hub`,
+    ''
+].join('\n');
+const readNotes = async (vaultPath) => {
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const summaries = await readMarkdownFileSummaries(absoluteVaultPath);
+    return Promise.all(summaries.map(async (summary) => {
+        const content = await readFile(summary.absolutePath, 'utf8');
+        const document = parseMarkdownDocument({
+            absolutePath: summary.absolutePath,
+            vaultPath: absoluteVaultPath,
+            content,
+            createdAt: summary.createdAt,
+            updatedAt: summary.updatedAt
+        });
+        return {
+            summary,
+            content,
+            document
+        };
+    }));
+};
+export const ensureCanonicalContextHub = async (vaultPath, contextTitle, agentId = sharedAgentId) => {
+    const hubTitle = hubTitleForContext(contextTitle);
+    const notes = await readNotes(vaultPath);
+    const existing = notes.find((note) => normalizeTitle(note.document.title) === normalizeTitle(hubTitle));
+    const hubPath = existing?.summary.relativePath ?? hubPathForContext(contextTitle, agentId);
+    if (existing) {
+        return {
+            created: false,
+            title: hubTitle,
+            path: hubPath
+        };
+    }
+    const path = await writeMarkdownFile(vaultPath, hubPath, buildHubContent(hubTitle, contextTitle, agentId));
+    return {
+        created: true,
+        title: hubTitle,
+        path
+    };
+};
+export const canonicalizeContextLinks = async (vaultPath, options = {}) => {
+    const agentId = options.agentId ? sanitizeAgentId(options.agentId) : undefined;
+    const createMissingHubs = options.createMissingHubs !== false;
+    const notes = await readNotes(vaultPath);
+    const scopedNotes = agentId ? notes.filter((note) => note.document.agentId === agentId) : notes;
+    const knownTitles = new Set(notes.map((note) => normalizeTitle(note.document.title)));
+    const entries = [];
+    const ensureHub = async (contextTitle, hubTitle, targetAgentId) => {
+        if (knownTitles.has(normalizeTitle(hubTitle))) {
+            return true;
+        }
+        const path = hubPathForContext(contextTitle, targetAgentId);
+        if (!createMissingHubs) {
+            entries.push({
+                path,
+                title: hubTitle,
+                context: contextTitle,
+                hubTitle,
+                changed: false,
+                reason: 'missing-hub'
+            });
+            return false;
+        }
+        knownTitles.add(normalizeTitle(hubTitle));
+        if (!options.dryRun) {
+            await writeMarkdownFile(vaultPath, path, buildHubContent(hubTitle, contextTitle, targetAgentId));
+        }
+        entries.push({
+            path,
+            title: hubTitle,
+            context: contextTitle,
+            hubTitle,
+            changed: true,
+            reason: 'created-hub'
+        });
+        return true;
+    };
+    for (const note of scopedNotes) {
+        const context = inferVisualGraphContext(note.document);
+        const hubTitle = hubTitleForContext(context.title);
+        const isHub = normalizeTitle(note.document.title) === normalizeTitle(hubTitle);
+        if (isHub) {
+            entries.push({
+                path: note.summary.relativePath,
+                title: note.document.title,
+                context: context.title,
+                hubTitle,
+                changed: false,
+                reason: 'hub-note'
+            });
+            continue;
+        }
+        const hubAvailable = await ensureHub(context.title, hubTitle, note.document.agentId || sharedAgentId);
+        if (!hubAvailable) {
+            continue;
+        }
+        if (hasCanonicalLink(note.content, hubTitle)) {
+            entries.push({
+                path: note.summary.relativePath,
+                title: note.document.title,
+                context: context.title,
+                hubTitle,
+                changed: false,
+                reason: 'already-linked'
+            });
+            continue;
+        }
+        const nextContent = upsertCanonicalContextLink(note.content, hubTitle);
+        if (!options.dryRun) {
+            await writeMarkdownFile(vaultPath, note.summary.relativePath, nextContent);
+        }
+        entries.push({
+            path: note.summary.relativePath,
+            title: note.document.title,
+            context: context.title,
+            hubTitle,
+            changed: true,
+            reason: 'added-context-link'
+        });
+    }
+    const changed = entries.filter((entry) => entry.changed).length;
+    const createdHubs = entries.filter((entry) => entry.reason === 'created-hub' && entry.changed).length;
+    return {
+        dryRun: options.dryRun === true,
+        scanned: scopedNotes.length,
+        changed,
+        createdHubs,
+        skipped: entries.length - changed,
+        entries
+    };
+};
+export const addCanonicalContextLinkToContent = (title, content) => {
+    const context = inferVisualGraphContext({
+        id: '',
+        agentId: sharedAgentId,
+        title,
+        path: '',
+        content,
+        tags: [],
+    });
+    const hubTitle = hubTitleForContext(context.title);
+    const nextContent = normalizeTitle(title) === normalizeTitle(hubTitle) ? content : upsertCanonicalContextLink(content, hubTitle);
+    return {
+        content: nextContent,
+        context: context.title,
+        hubTitle,
+        changed: nextContent !== content
+    };
+};

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

@@ -1,10 +1,11 @@
 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 = 4;
+const graphLayoutVersion = 5;
 const graphLayoutCache = new Map();
 const safeCacheSegment = (value, fallback) => value?.replace(/[^a-zA-Z0-9_-]/g, '_') || fallback;
 const graphLayoutStoragePath = (vaultPath, options) => {
@@ -82,7 +83,7 @@ export const getGraphLayout = async (vaultPath, optionsOrAgentId) => {
             layout: persisted.layout
         };
     }
-    const graph = await getGraphSummary(vaultPath, options.agentId);
+    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);

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

@@ -302,7 +302,7 @@ 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') {

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

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.154",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",