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

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/docs/ARCHITECTURE.md

@@ -154,8 +154,10 @@ server command
   -> optional index rebuild
   -> HTTP server
   -> /api/agents lists indexed namespaces
+  -> /api/graph-contexts lists visual graph contexts
   -> /api/graph reads indexed documents and links
   -> /api/graph-layout derives a star layout from indexed graph data
+  -> optional context query narrows the layout to a segment-scoped star subgraph
   -> browser renders graph canvas
 ```
 

package/package.json

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