@andespindola/brainlink 1.10.1 → 1.11.0

package/README.md

@@ -585,6 +585,7 @@ Available tools:
 - `brainlink_vault_transfer_export` / `brainlink_vault_transfer_import`: move a vault **between two Brainlinks over MCP** without a file on disk. An agent connected to both servers calls `transfer_export` on the source (returns the vault as an encrypted, base64 payload) and `transfer_import` on the target (applies the payload and reindexes). A shared `passphrase` (min 8 chars) is mandatory since the payload travels through the agent's context. Same checksum verification and `*.conflict-<ts>.md` preservation as snapshot import.
 - `brainlink_vault_merge_agents`: losslessly merge one agent namespace into another within the same vault (e.g. `claude-code` → `shared`). Identical notes are skipped, colliding slugs with different content are kept under a `-from-<agent>` name, everything else is moved, and merged notes are aggregated into domain `<context> Hub` notes. Source notes are kept unless `deleteSource` is set; `dryRun` previews the plan.
 - `brainlink_graph`: read indexed graph nodes and weighted links.
+- `brainlink_neighbors`: traverse the wiki-link graph outward from a root note (by `title` or `path`) up to `depth` hops, returning the reached nodes annotated with hop distance plus the edges between them. `limit` caps the node count (default 50) and reports `truncated` when it stops early. Complements `brainlink_graph` (whole graph) and `brainlink_similar_notes` (semantic neighbors).
 - `brainlink_graph_contexts`: list the visual graph contexts used by the local server.
 - `brainlink_broken_links`: list unresolved wiki links.
 - `brainlink_suggest_links`: suggest Context Links for content or fixes for unresolved wiki links.

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

@@ -0,0 +1,44 @@
+import { resolve } from 'node:path';
+import { traverseGraphNeighbors } from '../domain/graph-neighbors.js';
+import { ensureVault } from '../infrastructure/file-system-vault.js';
+import { getGraph } from './get-graph.js';
+const defaultDepth = 1;
+const defaultLimit = 50;
+const normalizeTitleKey = (title) => title.trim().replace(/\.md$/i, '').toLowerCase();
+const resolveRoot = (absoluteVaultPath, nodes, input) => {
+    if (input.path != null && input.path.trim().length > 0) {
+        const expected = resolve(absoluteVaultPath, input.path);
+        const match = nodes.find((node) => resolve(absoluteVaultPath, node.path) === expected);
+        if (!match) {
+            throw new Error(`No note found at path: ${input.path}`);
+        }
+        return match;
+    }
+    const expectedTitle = normalizeTitleKey(input.title ?? '');
+    const matches = nodes.filter((node) => normalizeTitleKey(node.title) === expectedTitle);
+    if (matches.length === 0) {
+        throw new Error(`No note found with title: ${input.title}`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`Multiple notes match title "${input.title}". Use path instead: ${matches.map((node) => node.path).join(', ')}`);
+    }
+    return matches[0];
+};
+// Expand the wiki-link graph outward from a single root note, selected by title
+// or path, up to a bounded hop distance. This is the traversal counterpart to
+// `getGraph` (whole graph) and `findSimilarNotes` (semantic neighbors).
+export const getGraphNeighbors = async (vaultPath, input) => {
+    const hasTitle = input.title != null && input.title.trim().length > 0;
+    const hasPath = input.path != null && input.path.trim().length > 0;
+    if (hasTitle === hasPath) {
+        throw new Error('Use exactly one selector: title or path.');
+    }
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const graph = await getGraph(vaultPath, input.agentId);
+    const root = resolveRoot(absoluteVaultPath, graph.nodes, input);
+    const neighborhood = traverseGraphNeighbors(graph, root.id, {
+        depth: input.depth ?? defaultDepth,
+        limit: input.limit ?? defaultLimit
+    });
+    return { ...neighborhood, root: { id: root.id, title: root.title, path: root.path } };
+};

package/dist/cli/commands/read-commands.js

@@ -1,6 +1,7 @@
 import { getBrokenLinksReport, getExtendedStats, getOrphansReport, getStats, validateVault } from '../../application/analyze-vault.js';
 import { buildContextPackage, readContextDataSignature, readVolatileSignature } from '../../application/build-context.js';
 import { getGraph } from '../../application/get-graph.js';
+import { getGraphNeighbors } from '../../application/get-graph-neighbors.js';
 import { listAgents } from '../../application/list-agents.js';
 import { listBacklinks, listLinks } from '../../application/list-links.js';
 import { explainSearchResults } from '../../application/memory-suggestions.js';
@@ -133,6 +134,33 @@ export const registerReadCommands = (program) => {
         const graph = await getGraph(resolved.vault, resolved.agent);
         print(options.json, graph, () => JSON.stringify(graph, null, 2));
     });
+    program
+        .command('neighbors')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'filter by agent memory namespace')
+        .option('-t, --title <title>', 'title of the root note to expand from')
+        .option('-p, --path <path>', 'path of the root note to expand from')
+        .option('-d, --depth <depth>', 'number of hops to traverse outward (default 1)')
+        .option('-l, --limit <limit>', 'maximum nodes to return including the root (default 50)')
+        .option('--json', 'print machine-readable JSON')
+        .description('traverse the wiki-link graph outward from a root note up to a given depth')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const depth = options.depth != null ? parsePositiveInteger(options.depth, 1) : undefined;
+        const limit = options.limit != null ? parsePositiveInteger(options.limit, 50) : undefined;
+        const result = await getGraphNeighbors(resolved.vault, {
+            title: options.title,
+            path: options.path,
+            agentId: resolved.agent,
+            depth,
+            limit
+        });
+        print(options.json, result, () => [
+            `root: ${result.root.title} (${result.root.path})`,
+            `depth=${result.depth} reached=${result.reachedDepth} nodes=${result.nodes.length}${result.truncated ? ' (truncated)' : ''}`,
+            ...result.nodes.map((node) => `  [${node.depth}] ${node.title} (${node.path})`)
+        ].join('\n'));
+    });
     program
         .command('agents')
         .option('-v, --vault <vault>', 'vault directory')

package/dist/domain/graph-neighbors.js

@@ -0,0 +1,79 @@
+const priorityRank = {
+    low: 0,
+    normal: 1,
+    high: 2,
+    critical: 3
+};
+// Rank an edge so the traversal expands the strongest links first. Weight is the
+// primary signal; priority breaks ties between equally weighted links.
+const edgeStrength = (edge) => edge.weight + priorityRank[edge.priority] * 0.001;
+// Build an undirected adjacency map from the directed wiki-link edges. A note is
+// a neighbor whether it links out to the current node or is linked from it, so
+// each resolved edge contributes in both directions. Unresolved edges (null
+// target) lead nowhere and are skipped.
+const buildAdjacency = (edges) => {
+    const map = new Map();
+    const connect = (from, to, strength) => {
+        const list = map.get(from) ?? [];
+        list.push({ nodeId: to, strength });
+        map.set(from, list);
+    };
+    for (const edge of edges) {
+        if (edge.target == null) {
+            continue;
+        }
+        const strength = edgeStrength(edge);
+        connect(edge.source, edge.target, strength);
+        connect(edge.target, edge.source, strength);
+    }
+    return new Map(Array.from(map.entries(), ([nodeId, neighbors]) => [
+        nodeId,
+        [...neighbors].sort((left, right) => right.strength - left.strength || left.nodeId.localeCompare(right.nodeId))
+    ]));
+};
+// Breadth-first expansion from a root node up to `depth` hops, capped at `limit`
+// nodes. Pure over the graph so it is trivially testable and reusable by the CLI
+// and MCP surfaces.
+export const traverseGraphNeighbors = (graph, rootId, options) => {
+    const maxDepth = Math.max(0, Math.floor(options.depth));
+    const limit = Math.max(1, Math.floor(options.limit));
+    const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
+    if (!nodeById.has(rootId)) {
+        throw new Error(`Root node is not part of the graph: ${rootId}`);
+    }
+    const adjacency = buildAdjacency(graph.edges);
+    const depthById = new Map([[rootId, 0]]);
+    const order = [rootId];
+    let reachedDepth = 0;
+    let truncated = false;
+    for (let head = 0; head < order.length; head += 1) {
+        const currentId = order[head];
+        const currentDepth = depthById.get(currentId) ?? 0;
+        if (currentDepth >= maxDepth) {
+            continue;
+        }
+        for (const { nodeId } of adjacency.get(currentId) ?? []) {
+            if (depthById.has(nodeId) || !nodeById.has(nodeId)) {
+                continue;
+            }
+            if (order.length >= limit) {
+                truncated = true;
+                break;
+            }
+            const nextDepth = currentDepth + 1;
+            depthById.set(nodeId, nextDepth);
+            order.push(nodeId);
+            reachedDepth = Math.max(reachedDepth, nextDepth);
+        }
+        if (truncated) {
+            break;
+        }
+    }
+    const includedIds = new Set(order);
+    const nodes = order.map((id) => {
+        const { content: _content, ...rest } = nodeById.get(id);
+        return { ...rest, depth: depthById.get(id) ?? 0 };
+    });
+    const edges = graph.edges.filter((edge) => edge.target != null && includedIds.has(edge.source) && includedIds.has(edge.target));
+    return { rootId, depth: maxDepth, reachedDepth, nodes, edges, truncated };
+};

package/dist/mcp/server.js

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { addNoteInputSchema, addFileInputSchema, addFileTool, addImageInputSchema, addImageTool, addNoteTool, addNotesInputSchema, addNotesTool, deleteNoteInputSchema, deleteNoteTool, deleteNotesInputSchema, deleteNotesTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, canonicalizeContextLinksInputSchema, canonicalizeContextLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, doctorActionsInputSchema, doctorActionsTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, getImageInputSchema, getImageTool, explainInputSchema, explainTool, indexInputSchema, indexTool, inboxAddInputSchema, inboxAddTool, inboxListInputSchema, inboxListTool, inboxProcessInputSchema, inboxProcessTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, projectInitInputSchema, projectInitTool, recommendationsInputSchema, recommendationsTool, rememberInputSchema, rememberTool, repairLinksInputSchema, repairLinksTool, searchInputSchema, searchTool, similarNotesInputSchema, similarNotesTool, sessionCloseInputSchema, sessionCloseTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, syncInputSchema, syncTool, validateInputSchema, validateTool, vaultBundleListInputSchema, vaultBundleListTool, vaultCommitInputSchema, vaultCommitTool, vaultExportBundleInputSchema, vaultExportBundleTool, vaultExportInputSchema, vaultExportTool, vaultHistoryInputSchema, vaultHistoryTool, vaultImportBundleInputSchema, vaultImportBundleTool, vaultImportInputSchema, vaultImportTool, vaultInitInputSchema, vaultInitTool, vaultMergeAgentsInputSchema, vaultMergeAgentsTool, vaultProvisionInputSchema, vaultProvisionTool, vaultPullInputSchema, vaultPullTool, vaultRestoreInputSchema, vaultRestoreTool, vaultStatusInputSchema, vaultStatusTool, vaultTransferExportInputSchema, vaultTransferExportTool, vaultTransferImportInputSchema, vaultTransferImportTool, versionInputSchema, versionTool } from './tools.js';
+import { addNoteInputSchema, addFileInputSchema, addFileTool, addImageInputSchema, addImageTool, addNoteTool, addNotesInputSchema, addNotesTool, deleteNoteInputSchema, deleteNoteTool, deleteNotesInputSchema, deleteNotesTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, canonicalizeContextLinksInputSchema, canonicalizeContextLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, doctorActionsInputSchema, doctorActionsTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, neighborsInputSchema, neighborsTool, getImageInputSchema, getImageTool, explainInputSchema, explainTool, indexInputSchema, indexTool, inboxAddInputSchema, inboxAddTool, inboxListInputSchema, inboxListTool, inboxProcessInputSchema, inboxProcessTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, projectInitInputSchema, projectInitTool, recommendationsInputSchema, recommendationsTool, rememberInputSchema, rememberTool, repairLinksInputSchema, repairLinksTool, searchInputSchema, searchTool, similarNotesInputSchema, similarNotesTool, sessionCloseInputSchema, sessionCloseTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, syncInputSchema, syncTool, validateInputSchema, validateTool, vaultBundleListInputSchema, vaultBundleListTool, vaultCommitInputSchema, vaultCommitTool, vaultExportBundleInputSchema, vaultExportBundleTool, vaultExportInputSchema, vaultExportTool, vaultHistoryInputSchema, vaultHistoryTool, vaultImportBundleInputSchema, vaultImportBundleTool, vaultImportInputSchema, vaultImportTool, vaultInitInputSchema, vaultInitTool, vaultMergeAgentsInputSchema, vaultMergeAgentsTool, vaultProvisionInputSchema, vaultProvisionTool, vaultPullInputSchema, vaultPullTool, vaultRestoreInputSchema, vaultRestoreTool, vaultStatusInputSchema, vaultStatusTool, vaultTransferExportInputSchema, vaultTransferExportTool, vaultTransferImportInputSchema, vaultTransferImportTool, versionInputSchema, versionTool } from './tools.js';
 import { getRuntimeVersion } from './runtime.js';
 import { brainlinkServerInstructions } from './server-instructions.js';
 import { guardToolHandler } from './tool-guard.js';
@@ -246,6 +246,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_neighbors', {
+        title: 'Traverse Brainlink Graph Neighbors',
+        description: 'Traverse the wiki-link graph outward from a root note (selected by title or path) up to a given depth (hops), returning the reached nodes annotated with hop distance plus the edges between them. Complements brainlink_graph (whole graph) and brainlink_similar_notes (semantic neighbors).',
+        inputSchema: neighborsInputSchema
+    }, neighborsTool);
     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.',

package/dist/mcp/tools/read-tools.js

@@ -3,6 +3,7 @@ import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from
 import { buildContextPackage, readContextDataSignature, readVolatileSignature } from '../../application/build-context.js';
 import { getGraph } from '../../application/get-graph.js';
 import { getGraphContexts } from '../../application/get-graph-contexts.js';
+import { getGraphNeighbors } from '../../application/get-graph-neighbors.js';
 import { getImage } from '../../application/get-image.js';
 import { explainSearchResults, suggestBrokenLinkFixes, suggestContextLinks } from '../../application/memory-suggestions.js';
 import { buildActionableDoctor } from '../../application/operational-workflows.js';
@@ -66,6 +67,14 @@ export const graphContextsInputSchema = {
     ...vaultInput,
     ...agentInput
 };
+export const neighborsInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    title: z.string().min(1).optional().describe('Title of the root note to expand from. Use agent or path to disambiguate.'),
+    path: z.string().min(1).optional().describe('Vault-relative or absolute path of the root note to expand from.'),
+    depth: optionalPositiveInteger().describe('Number of hops to traverse outward from the root note along wiki-link edges. Defaults to 1.'),
+    limit: optionalPositiveInteger().describe('Maximum number of nodes to return, including the root. Defaults to 50; further nodes are truncated.')
+};
 export const brokenLinksInputSchema = {
     ...vaultInput,
     ...agentInput
@@ -281,6 +290,31 @@ export const graphTool = async (input) => {
         ...graph
     });
 };
+export const neighborsTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_neighbors');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_neighbors');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const result = await getGraphNeighbors(context.vault, {
+        title: input.title,
+        path: input.path,
+        agentId: context.agent,
+        depth: input.depth,
+        limit: input.limit
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        ...result
+    });
+};
 export const graphContextsTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const readiness = await ensureBootstrapReady(context, input, 'brainlink_graph_contexts');

package/dist/mcp/tools.js

@@ -1,4 +1,4 @@
-export { brokenLinksInputSchema, brokenLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, doctorActionsInputSchema, doctorActionsTool, explainInputSchema, explainTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, getImageInputSchema, getImageTool, orphansInputSchema, orphansTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, similarNotesInputSchema, similarNotesTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools/read-tools.js';
+export { brokenLinksInputSchema, brokenLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, doctorActionsInputSchema, doctorActionsTool, explainInputSchema, explainTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, neighborsInputSchema, neighborsTool, getImageInputSchema, getImageTool, orphansInputSchema, orphansTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, similarNotesInputSchema, similarNotesTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools/read-tools.js';
 export { addFileInputSchema, addFileTool, addImageInputSchema, addImageTool, addNoteInputSchema, addNoteTool, addNotesInputSchema, addNotesTool, deleteNoteInputSchema, deleteNoteTool, deleteNotesInputSchema, deleteNotesTool, inboxAddInputSchema, inboxAddTool, inboxListInputSchema, inboxListTool, inboxProcessInputSchema, inboxProcessTool, rememberInputSchema, rememberTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool } from './tools/write-tools.js';
 export { bootstrapInputSchema, bootstrapTool, canonicalizeContextLinksInputSchema, canonicalizeContextLinksTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, indexInputSchema, indexTool, policyInputSchema, policyTool, projectInitInputSchema, projectInitTool, repairLinksInputSchema, repairLinksTool, sessionCloseInputSchema, sessionCloseTool, syncInputSchema, syncTool } from './tools/maintenance-tools.js';
 export { vaultBundleListInputSchema, vaultBundleListTool, vaultCommitInputSchema, vaultCommitTool, vaultExportBundleInputSchema, vaultExportBundleTool, vaultExportInputSchema, vaultExportTool, vaultHistoryInputSchema, vaultHistoryTool, vaultImportBundleInputSchema, vaultImportBundleTool, vaultImportInputSchema, vaultImportTool, vaultInitInputSchema, vaultInitTool, vaultMergeAgentsInputSchema, vaultMergeAgentsTool, vaultProvisionInputSchema, vaultProvisionTool, vaultPullInputSchema, vaultPullTool, vaultRestoreInputSchema, vaultRestoreTool, vaultStatusInputSchema, vaultStatusTool, vaultTransferExportInputSchema, vaultTransferExportTool, vaultTransferImportInputSchema, vaultTransferImportTool } from './tools/vault-tools.js';

package/docs/AGENT_USAGE.md

@@ -750,6 +750,7 @@ Available MCP tools:
 - `brainlink_validate`
 - `brainlink_sync`
 - `brainlink_graph`
+- `brainlink_neighbors`
 - `brainlink_graph_contexts`
 - `brainlink_broken_links`
 - `brainlink_suggest_links`
@@ -770,6 +771,7 @@ MCP context is plug-and-play: agents may omit `strategy` for the configured defa
 MCP clients can pass `vault` and `agent` arguments per tool call. Set `BRAINLINK_ALLOWED_VAULTS` when exposing Brainlink to an external agent process so a tool cannot pass arbitrary vault paths:
 
 `brainlink_graph` returns weighted edges. Agents should prefer higher `weight` and stronger `priority` when deciding which related notes matter most.
+`brainlink_neighbors` traverses those edges outward from one root note (by `title` or `path`) up to `depth` hops, returning each reached node with its hop distance and the edges among the reached set. It expands the strongest links first and caps the result at `limit` nodes (default 50), setting `truncated: true` when it stops early. Prefer it over `brainlink_graph` when only the local neighborhood of a note matters instead of the whole graph.
 `brainlink_add_note` and `brainlink_add_file` return `writeConnectivity` metadata and guarantee at least one edge for new notes.
 Agents should use `brainlink_volatile_add` for temporary task state, hypotheses, local execution details and unconfirmed findings. Volatile memory is included in `brainlink_context` with `Volatile: true`, expires by TTL and does not create durable Markdown notes or graph edges.
 

package/package.json

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