@andespindola/brainlink 1.0.4 → 1.0.6

package/dist/infrastructure/file-index.js

@@ -1,6 +1,7 @@
 import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { cosineSimilarity } from '../domain/embeddings.js';
+import { createEmbeddingBuckets, dotProduct } from '../domain/embeddings.js';
+import { selectSemanticCandidates } from './semantic-prefilter.js';
 const queryTokenPattern = /[\p{L}\p{N}_-]+/gu;
 const indexCacheMaxEntries = 16;
 const indexCache = new Map();
@@ -106,7 +107,7 @@ const textScore = (row, tokens) => {
         return score + titleHits * 5 + tagHits * 4 + pathHits * 2 + Math.min(contentHits, 6);
     }, 0);
 };
-const semanticScore = (row, queryEmbedding) => queryEmbedding.length > 0 && row.embedding.length > 0 ? cosineSimilarity(queryEmbedding, row.embedding) : 0;
+const semanticScore = (row, queryEmbedding) => queryEmbedding.length > 0 && row.embedding.length > 0 ? dotProduct(queryEmbedding, row.embedding) : 0;
 const toResult = (row, mode, text, semantic) => {
     const score = mode === 'fts' ? text : mode === 'semantic' ? semantic : text + semantic * 8;
     return {
@@ -206,12 +207,20 @@ export const openFileIndex = (vaultPath) => {
                         chunkOrdinal: chunk.ordinal,
                         content: chunk.content,
                         tags: document.tags,
-                        embedding: chunk.embedding
+                        embedding: chunk.embedding,
+                        buckets: chunk.buckets
                     }
                 ];
             });
             const tokens = tokenize(query);
-            const results = rows
+            // Pure-semantic scoring on a large vault can skip chunks that share no
+            // embedding bucket with the query. Hybrid/fts keep every row so lexical
+            // matches are never dropped; the prefilter also falls back to a full scan
+            // on small or partially-indexed vaults.
+            const scored = mode === 'semantic' && queryEmbedding.length > 0
+                ? selectSemanticCandidates(rows, createEmbeddingBuckets(queryEmbedding), limit)
+                : rows;
+            const results = scored
                 .map((row) => {
                 const text = textScore(row, tokens);
                 const semantic = semanticScore(row, queryEmbedding);

package/dist/infrastructure/semantic-prefilter.js

@@ -0,0 +1,24 @@
+// Below this chunk count a full scan is already sub-millisecond, so the
+// prefilter only engages on large vaults where pruning candidates pays off.
+export const semanticPrefilterMinChunks = 4000;
+// Pure-semantic candidate prefilter. Returns the subset of rows that share at
+// least one embedding bucket with the query, or ALL rows when the prefilter
+// should not or cannot safely engage:
+//   - the index is small (full scan is cheap),
+//   - the query produced no buckets,
+//   - any row is missing buckets (a pre-feature / partially indexed vault), or
+//   - too few candidates survive (protect recall — fall back to a full scan).
+// It is only sound for pure-semantic scoring; hybrid/fts must keep every row so
+// lexical matches are not dropped.
+export const selectSemanticCandidates = (rows, queryBuckets, limit, minChunks = semanticPrefilterMinChunks) => {
+    if (rows.length <= minChunks || queryBuckets.length === 0) {
+        return rows;
+    }
+    if (rows.some((row) => !row.buckets || row.buckets.length === 0)) {
+        return rows;
+    }
+    const bucketSet = new Set(queryBuckets);
+    const candidates = rows.filter((row) => row.buckets.some((bucket) => bucketSet.has(bucket)));
+    const recallFloor = Math.max(limit * 4, 64);
+    return candidates.length >= recallFloor ? candidates : rows;
+};

package/dist/mcp/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, deleteNoteInputSchema, deleteNoteTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, canonicalizeContextLinksInputSchema, canonicalizeContextLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, doctorActionsInputSchema, doctorActionsTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, explainInputSchema, explainTool, indexInputSchema, indexTool, inboxAddInputSchema, inboxAddTool, inboxListInputSchema, inboxListTool, inboxProcessInputSchema, inboxProcessTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, projectInitInputSchema, projectInitTool, recommendationsInputSchema, recommendationsTool, rememberInputSchema, rememberTool, repairLinksInputSchema, repairLinksTool, searchInputSchema, searchTool, sessionCloseInputSchema, sessionCloseTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, syncInputSchema, syncTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools.js';
 import { getRuntimeVersion } from './runtime.js';
+import { guardToolHandler } from './tool-guard.js';
 export const createBrainlinkMcpServer = () => {
     const server = new McpServer({
         name: 'brainlink',
@@ -8,6 +9,12 @@ export const createBrainlinkMcpServer = () => {
         version: getRuntimeVersion(),
         description: 'Local-first Markdown memory tools for AI agents.'
     });
+    // Route every tool registration through the error guard so a thrown handler
+    // returns a structured isError result instead of propagating to the client.
+    // Wrapping registerTool once keeps the call sites below unchanged and also
+    // covers any tools added later.
+    const baseRegisterTool = server.registerTool.bind(server);
+    server.registerTool = ((name, config, handler) => baseRegisterTool(name, config, guardToolHandler(name, handler)));
     server.registerTool('brainlink_bootstrap', {
         title: 'Bootstrap Brainlink For A Task (Default Entrypoint)',
         description: 'Default entrypoint for agents. Run this first to index/check memory state, then optionally retrieve context for the current task query.',

package/dist/mcp/tool-guard.js

@@ -0,0 +1,29 @@
+const errorResult = (toolName, error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    const payload = {
+        error: message,
+        tool: toolName
+    };
+    return {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(payload, null, 2)
+            }
+        ],
+        structuredContent: payload
+    };
+};
+// Wrap a tool handler so an unexpected throw becomes a structured error result
+// instead of propagating a raw exception to the MCP client. Agents then receive
+// an actionable `isError` payload naming the failing tool rather than a stack
+// trace or a dropped call.
+export const guardToolHandler = (toolName, handler) => async (args, extra) => {
+    try {
+        return await handler(args, extra);
+    }
+    catch (error) {
+        return errorResult(toolName, error);
+    }
+};

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

@@ -0,0 +1,409 @@
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../../application/analyze-vault.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 { indexVault } from '../../application/index-vault.js';
+import { closeSession, initializeProjectMemory } from '../../application/operational-workflows.js';
+import { repairBrokenLinks } from '../../application/repair-broken-links.js';
+import { sanitizeContextStrategy, sanitizeSearchMode } from '../../infrastructure/config.js';
+import { getBootstrapPolicy, getBootstrapSessionStatus, getContextSessionStatus, setBootstrapPolicy, touchBootstrapSession, touchContextSession } from '../../infrastructure/session-state.js';
+import { getRuntimeMetadata } from '../runtime.js';
+import { agentInput, contextStrategyInput, ensureBootstrapReady, ensureContextReady, isTruthy, jsonResult, optionalPositiveInteger, positiveInteger, resolveExecutionContext, searchModeInput, vaultInput, withNextActions } from './shared.js';
+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
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Force a complete reindex from Markdown source without reusing unchanged index entries.')
+};
+export const repairLinksInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    dryRun: z.boolean().optional().default(false).describe('Preview repairs without writing files.'),
+    createMissing: z.boolean().optional().default(true).describe('Create placeholder notes for unresolved targets without a safe existing match.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after repairs.'),
+    minScore: z.number().min(0).max(1).optional().default(0.88).describe('Minimum similarity score for automatic retargeting.'),
+    margin: z.number().min(0).max(1).optional().default(0.12).describe('Minimum score gap between first and second candidate.')
+};
+export const syncInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    contextQuery: z.string().min(1).optional().describe('Optional context smoke query. Omit to skip context probe.'),
+    mode: z.enum(['fts', 'semantic', 'hybrid']).optional().describe('Search mode for the optional context probe. Defaults to config value.'),
+    strategy: z.enum(['rag', 'cag', 'auto']).optional().describe('Context strategy for the optional context probe. Defaults to the Brainlink config value.'),
+    contextLimit: optionalPositiveInteger().describe('Context smoke result limit when contextQuery is provided.'),
+    contextTokens: optionalPositiveInteger().describe('Context smoke token target when contextQuery is provided.')
+};
+export const bootstrapInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    ...searchModeInput,
+    ...contextStrategyInput,
+    query: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Optional task query. When provided, Brainlink also returns a context package in the same call.'),
+    limit: optionalPositiveInteger().describe('Context limit used when query is provided.'),
+    tokens: optionalPositiveInteger().describe('Context token target used when query is provided.')
+};
+export const policyInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    preset: z.enum(['fully-auto', 'strict']).optional().describe('Apply an opinionated policy preset before explicit overrides.'),
+    enforceBootstrap: z.boolean().optional().describe('Enable or disable bootstrap enforcement for MCP read tools.'),
+    enforceContextFirst: z.boolean().optional().describe('Require brainlink_context before other MCP read tools.'),
+    autoBootstrapOnRead: z
+        .boolean()
+        .optional()
+        .describe('When bootstrap is missing/stale, run automatic bootstrap on read tools instead of returning preflight-required responses.'),
+    autoBootstrapOnStartup: z
+        .boolean()
+        .optional()
+        .describe('Run automatic bootstrap during MCP server startup using configured default vault/agent.'),
+    staleAfterMinutes: positiveInteger(120).describe('Bootstrap freshness window in minutes before read tools require a new bootstrap.')
+};
+export const sessionCloseInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    content: z.string().min(1).optional().describe('Optional extra session notes to include in the handoff.'),
+    cwd: z.string().min(1).optional().describe('Workspace path used for git status. Defaults to current process working directory.'),
+    dryRun: z.boolean().optional().default(false).describe('Preview handoff note without writing it.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after writing handoff.')
+};
+export const projectInitInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    projectPath: z.string().min(1).optional().describe('Project path to inspect. Defaults to current process working directory.')
+};
+export const dedupeInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    limit: optionalPositiveInteger().describe('Maximum duplicate candidate pairs to return.'),
+    minScore: z.number().min(0).max(1).optional().describe('Minimum semantic similarity score between 0 and 1.'),
+    semantic: z.boolean().optional().default(true).describe('Enable semantic duplicate detection in addition to exact content hash matches.')
+};
+export const dedupeResolveInputSchema = {
+    ...vaultInput,
+    leftPath: z.string().min(1).describe('Left note path from dedupe results.'),
+    rightPath: z.string().min(1).describe('Right note path from dedupe results.'),
+    action: z.enum(['merge', 'link', 'ignore']).describe('Resolution action.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex after duplicate resolution.')
+};
+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, {
+        full: input.full === true
+    });
+    return jsonResult({
+        vault: context.vault,
+        ...result
+    });
+};
+export const repairLinksTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await repairBrokenLinks(context.vault, {
+        agentId: context.agent,
+        dryRun: input.dryRun,
+        createMissing: input.createMissing,
+        autoIndex: input.autoIndex,
+        minScore: input.minScore,
+        margin: input.margin
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...result
+    });
+};
+export const syncTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_sync');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_sync');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const index = await indexVault(context.vault);
+    const stats = await getStats(context.vault, context.agent);
+    const validation = await validateVault(context.vault, context.agent);
+    const brokenLinks = await getBrokenLinksReport(context.vault, context.agent);
+    const orphans = await getOrphansReport(context.vault, context.agent);
+    const response = {
+        vault: context.vault,
+        agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        index,
+        stats,
+        validation,
+        brokenLinks,
+        orphans
+    };
+    if (!input.contextQuery) {
+        return jsonResult(response);
+    }
+    const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const strategy = sanitizeContextStrategy(input.strategy, context.defaults.defaultContextStrategy);
+    const contextLimit = input.contextLimit ?? context.defaults.defaultSearchLimit;
+    const contextTokens = input.contextTokens ?? context.defaults.defaultContextTokens;
+    const contextPackage = await buildContextPackage(context.vault, input.contextQuery, contextLimit, contextTokens, context.agent, mode, strategy, context.defaults.defaultContextCacheTtlMs);
+    const contextSession = await touchContextSession(context.vault, context.agent);
+    return jsonResult({
+        ...response,
+        context: {
+            mode,
+            strategy,
+            contextSession,
+            ...contextPackage
+        }
+    });
+};
+export const bootstrapTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const index = await indexVault(context.vault);
+    const stats = await getStats(context.vault, context.agent);
+    const validation = await validateVault(context.vault, context.agent);
+    const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const strategy = sanitizeContextStrategy(input.strategy, context.defaults.defaultContextStrategy);
+    const limit = input.limit ?? context.defaults.defaultSearchLimit;
+    const tokens = input.tokens ?? context.defaults.defaultContextTokens;
+    const contextPackage = input.query
+        ? await buildContextPackage(context.vault, input.query, limit, tokens, context.agent, mode, strategy, context.defaults.defaultContextCacheTtlMs)
+        : undefined;
+    const contextSession = input.query ? await touchContextSession(context.vault, context.agent) : undefined;
+    const guidance = stats.documentCount === 0
+        ? 'Vault indexed with zero documents. Add durable notes with brainlink_add_note, then run brainlink_bootstrap again.'
+        : input.query
+            ? 'Use returned context as grounding baseline, then write durable updates with brainlink_add_note when needed.'
+            : 'Run brainlink_context with the current task query to retrieve grounded context before answering.';
+    const session = await touchBootstrapSession(context.vault, context.agent);
+    const policy = await getBootstrapPolicy();
+    const nextActions = stats.documentCount === 0
+        ? [
+            {
+                tool: 'brainlink_add_note',
+                reason: 'No indexed documents were found. Add durable Markdown memory first.',
+                args: {
+                    vault: context.vault,
+                    ...(context.agent ? { agent: context.agent } : {}),
+                    title: 'Architecture',
+                    content: 'Durable memory with explicit [[links]] and #tags.'
+                }
+            },
+            {
+                tool: 'brainlink_bootstrap',
+                reason: 'Re-run bootstrap after writing notes so context tools can work on fresh index state.',
+                args: {
+                    vault: context.vault,
+                    ...(context.agent ? { agent: context.agent } : {}),
+                    mode
+                }
+            }
+        ]
+        : input.query
+            ? [
+                {
+                    tool: 'brainlink_add_note',
+                    reason: 'Persist relevant outcomes from this task as durable memory.',
+                    args: {
+                        vault: context.vault,
+                        ...(context.agent ? { agent: context.agent } : {}),
+                        title: 'Task Update',
+                        content: 'Summarize durable findings and connect with [[existing notes]].'
+                    }
+                }
+            ]
+            : [
+                {
+                    tool: 'brainlink_context',
+                    reason: 'Fetch grounded context for the current task.',
+                    args: {
+                        vault: context.vault,
+                        ...(context.agent ? { agent: context.agent } : {}),
+                        query: '<task>',
+                        mode,
+                        strategy,
+                        limit,
+                        tokens
+                    }
+                }
+            ];
+    return jsonResult(withNextActions({
+        vault: context.vault,
+        agent: context.agent,
+        mode,
+        strategy,
+        limit,
+        tokens,
+        index,
+        stats,
+        validation,
+        policy,
+        session,
+        guidance,
+        ...(contextPackage ? { context: contextPackage } : {}),
+        ...(contextSession ? { contextSession } : {})
+    }, nextActions));
+};
+export const policyTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const presetPatch = input.preset === 'strict'
+        ? {
+            enforceBootstrap: true,
+            enforceContextFirst: true,
+            autoBootstrapOnRead: false,
+            autoBootstrapOnStartup: false
+        }
+        : input.preset === 'fully-auto'
+            ? {
+                enforceBootstrap: true,
+                enforceContextFirst: true,
+                autoBootstrapOnRead: true,
+                autoBootstrapOnStartup: true
+            }
+            : {};
+    const policy = input.preset !== undefined ||
+        typeof input.enforceBootstrap === 'boolean' ||
+        typeof input.enforceContextFirst === 'boolean' ||
+        typeof input.autoBootstrapOnRead === 'boolean' ||
+        typeof input.autoBootstrapOnStartup === 'boolean' ||
+        typeof input.staleAfterMinutes === 'number'
+        ? await setBootstrapPolicy({
+            ...presetPatch,
+            ...(typeof input.enforceBootstrap === 'boolean' ? { enforceBootstrap: input.enforceBootstrap } : {}),
+            ...(typeof input.enforceContextFirst === 'boolean' ? { enforceContextFirst: input.enforceContextFirst } : {}),
+            ...(typeof input.autoBootstrapOnRead === 'boolean' ? { autoBootstrapOnRead: input.autoBootstrapOnRead } : {}),
+            ...(typeof input.autoBootstrapOnStartup === 'boolean' ? { autoBootstrapOnStartup: input.autoBootstrapOnStartup } : {}),
+            ...(typeof input.staleAfterMinutes === 'number' ? { staleAfterMinutes: input.staleAfterMinutes } : {})
+        })
+        : await getBootstrapPolicy();
+    const bootstrapStatus = await getBootstrapSessionStatus(context.vault, context.agent);
+    const contextStatus = await getContextSessionStatus(context.vault, context.agent);
+    const nextActions = bootstrapStatus.ready
+        ? []
+        : [
+            {
+                tool: 'brainlink_bootstrap',
+                reason: 'Bootstrap status is not ready. Run bootstrap before using read tools.',
+                args: {
+                    vault: context.vault,
+                    ...(context.agent ? { agent: context.agent } : {}),
+                    mode: context.defaults.defaultSearchMode,
+                    strategy: context.defaults.defaultContextStrategy
+                }
+            }
+        ];
+    const withContextAction = policy.enforceContextFirst && !contextStatus.ready
+        ? [
+            ...nextActions,
+            {
+                tool: 'brainlink_context',
+                reason: 'Context-first policy is enabled. Load context before other read tools.',
+                args: {
+                    vault: context.vault,
+                    ...(context.agent ? { agent: context.agent } : {}),
+                    query: '<task>',
+                    mode: context.defaults.defaultSearchMode,
+                    strategy: context.defaults.defaultContextStrategy,
+                    limit: context.defaults.defaultSearchLimit,
+                    tokens: context.defaults.defaultContextTokens
+                }
+            }
+        ]
+        : nextActions;
+    return jsonResult(withNextActions({
+        vault: context.vault,
+        agent: context.agent,
+        runtime: getRuntimeMetadata(),
+        policy,
+        bootstrapStatus,
+        contextStatus,
+        ...(input.preset ? { presetApplied: input.preset } : {})
+    }, withContextAction));
+};
+export const sessionCloseTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await closeSession({
+        vaultPath: context.vault,
+        agentId: context.agent,
+        cwd: resolve(input.cwd ?? process.cwd()),
+        content: input.content,
+        write: input.dryRun !== true,
+        autoIndex: input.autoIndex
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        dryRun: input.dryRun === true,
+        ...result
+    });
+};
+export const projectInitTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await initializeProjectMemory({
+        vaultPath: context.vault,
+        projectPath: resolve(input.projectPath ?? process.cwd()),
+        agentId: context.agent
+    });
+    return jsonResult({
+        agent: context.agent,
+        ...result
+    });
+};
+export const dedupeTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const duplicates = await scanDuplicateNotes(context.vault, {
+        agentId: context.agent,
+        limit: input.limit ?? 25,
+        minSemanticScore: input.minScore ?? 0.92,
+        includeSemantic: input.semantic !== false
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        duplicates
+    });
+};
+export const dedupeResolveTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await resolveDuplicateNotes(context.vault, {
+        leftPath: input.leftPath,
+        rightPath: input.rightPath,
+        action: input.action,
+        autoIndex: isTruthy(input.autoIndex)
+    });
+    return jsonResult({
+        vault: context.vault,
+        ...result
+    });
+};