@andespindola/brainlink 1.0.6 → 1.0.7

package/dist/infrastructure/config.js

@@ -18,6 +18,7 @@ export const defaultBrainlinkConfig = {
     defaultContextStrategy: 'auto',
     defaultContextCacheTtlMs: 120_000,
     embeddingProvider: 'local',
+    embedding: {},
     defaultSearchMode: 'hybrid',
     chunkSize: 1200,
     searchPack: {
@@ -43,10 +44,34 @@ const safeCwd = () => {
     }
 };
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-const embeddingProviders = new Set(['none', 'local']);
+const embeddingProviders = new Set(['none', 'local', 'ollama', 'openai']);
 const searchModes = new Set(['fts', 'semantic', 'hybrid']);
 const contextStrategies = new Set(['rag', 'cag', 'auto']);
 const sanitizeEmbeddingProvider = (value) => typeof value === 'string' && embeddingProviders.has(value) ? value : defaultBrainlinkConfig.embeddingProvider;
+const sanitizeOptionalString = (value) => typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+const sanitizeEmbeddingConfig = (value) => {
+    if (!isRecord(value)) {
+        return {};
+    }
+    const url = sanitizeOptionalString(value.url);
+    const model = sanitizeOptionalString(value.model);
+    const apiKeyEnv = sanitizeOptionalString(value.apiKeyEnv);
+    const timeoutMs = sanitizePositiveNumber(value.timeoutMs);
+    const batchSize = sanitizePositiveNumber(value.batchSize);
+    return {
+        ...(url ? { url } : {}),
+        ...(model ? { model } : {}),
+        ...(apiKeyEnv ? { apiKeyEnv } : {}),
+        ...(timeoutMs ? { timeoutMs: Math.floor(timeoutMs) } : {}),
+        ...(batchSize ? { batchSize: Math.floor(batchSize) } : {})
+    };
+};
+// Stable identity of the embedding space, used to decide when stored vectors
+// must be rebuilt. A model swap on an external provider changes the space even
+// though the provider name is unchanged, so the model is folded in.
+export const embeddingSignature = (config) => config.embeddingProvider === 'ollama' || config.embeddingProvider === 'openai'
+    ? `${config.embeddingProvider}:${config.embedding.model?.trim() || 'default'}`
+    : config.embeddingProvider;
 export const sanitizeSearchMode = (value, fallback = defaultBrainlinkConfig.defaultSearchMode) => typeof value === 'string' && searchModes.has(value) ? value : fallback;
 export const sanitizeContextStrategy = (value, fallback = defaultBrainlinkConfig.defaultContextStrategy) => typeof value === 'string' && contextStrategies.has(value) ? value : fallback;
 const sanitizeAllowedVaults = (value) => Array.isArray(value) ? value.filter((item) => typeof item === 'string' && item.trim().length > 0) : [];
@@ -197,6 +222,7 @@ const sanitizeConfig = (value) => ({
     chunkSize: typeof value.chunkSize === 'number' && value.chunkSize > 0 ? value.chunkSize : defaultBrainlinkConfig.chunkSize,
     searchPack: sanitizeSearchPackConfig(value.searchPack),
     embeddingProvider: sanitizeEmbeddingProvider(value.embeddingProvider),
+    embedding: sanitizeEmbeddingConfig(value.embedding),
     defaultSearchMode: sanitizeSearchMode(value.defaultSearchMode),
     agentProfiles: sanitizeAgentProfiles(value.agentProfiles)
 });

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 { createEmbeddingBuckets, dotProduct } from '../domain/embeddings.js';
+import { bm25TermScore, minMaxNormalize } from '../domain/scoring.js';
 import { selectSemanticCandidates } from './semantic-prefilter.js';
 const queryTokenPattern = /[\p{L}\p{N}_-]+/gu;
 const indexCacheMaxEntries = 16;
@@ -12,8 +13,48 @@ const emptyIndex = () => ({
     chunks: [],
     links: []
 });
+// Raised when index.json exists but cannot be parsed. Search treats it as a
+// signal to fall back to the independent compressed search packs instead of
+// silently returning an empty result set.
+export class IndexCorruptionError extends Error {
+    indexPath;
+    constructor(indexPath, cause) {
+        super(`Corrupted index at ${indexPath}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.indexPath = indexPath;
+        this.name = 'IndexCorruptionError';
+    }
+}
 export const indexStoragePath = (vaultPath) => join(vaultPath, '.brainlink', 'index.json');
-const readIndex = async (vaultPath) => {
+const isMissingFileError = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
+// Paths already reported as corrupt, so a non-removable corrupt index (read-only
+// vault, locked file) does not spam stderr on every read. Cleared when a fresh
+// index is written to the path.
+const warnedCorruptIndexPaths = new Set();
+// Move a corrupt index aside so it is not read again and the next index run
+// rebuilds from Markdown source, and surface a warning instead of failing
+// silently. Quarantine is best-effort: a read-only vault simply keeps the file.
+const quarantineCorruptIndex = async (path, cause) => {
+    indexCache.delete(path);
+    if (!warnedCorruptIndexPaths.has(path)) {
+        warnedCorruptIndexPaths.add(path);
+        process.stderr.write(`brainlink: index at ${path} is unreadable and was quarantined; rebuild with 'index --full' (${cause instanceof Error ? cause.message : String(cause)})\n`);
+    }
+    try {
+        await rename(path, `${path}.corrupt`);
+    }
+    catch {
+        // The primary name can already exist (a prior corruption on a filesystem
+        // where rename does not overwrite, e.g. Windows). Fall back to a unique name
+        // so the damaged file is still moved out of the read path.
+        try {
+            await rename(path, `${path}.corrupt-${Date.now()}`);
+        }
+        catch {
+            // Leave the file in place when it cannot be renamed; the warning still fired.
+        }
+    }
+};
+const readIndex = async (vaultPath, strict = false) => {
     const path = indexStoragePath(vaultPath);
     let stats = null;
     try {
@@ -21,9 +62,8 @@ const readIndex = async (vaultPath) => {
         stats = { mtimeMs: fileStats.mtimeMs, size: fileStats.size };
     }
     catch (error) {
-        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+        if (isMissingFileError(error)) {
             indexCache.delete(path);
-            return emptyIndex();
         }
         return emptyIndex();
     }
@@ -31,31 +71,46 @@ const readIndex = async (vaultPath) => {
     if (cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) {
         return cached.index;
     }
+    let raw;
     try {
-        const parsed = JSON.parse(await readFile(path, 'utf8'));
-        const loaded = {
-            version: 1,
-            updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
-            documents: Array.isArray(parsed.documents) ? parsed.documents : [],
-            chunks: Array.isArray(parsed.chunks) ? parsed.chunks : [],
-            links: Array.isArray(parsed.links) ? parsed.links : []
-        };
-        indexCache.set(path, { ...stats, index: loaded });
-        if (indexCache.size > indexCacheMaxEntries) {
-            const oldest = indexCache.keys().next().value;
-            if (typeof oldest === 'string') {
-                indexCache.delete(oldest);
-            }
+        raw = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        indexCache.delete(path);
+        // The file existed at stat but vanished before the read — a concurrent
+        // rebuild or quarantine. Strict (search) callers throw so they fall back to
+        // packs rather than racing to an empty result; tolerant callers get empty.
+        if (strict) {
+            throw new IndexCorruptionError(path, error);
         }
-        return loaded;
+        return emptyIndex();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
     }
     catch (error) {
-        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
-            indexCache.delete(path);
-            return emptyIndex();
+        await quarantineCorruptIndex(path, error);
+        if (strict) {
+            throw new IndexCorruptionError(path, error);
         }
         return emptyIndex();
     }
+    const loaded = {
+        version: 1,
+        updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+        documents: Array.isArray(parsed.documents) ? parsed.documents : [],
+        chunks: Array.isArray(parsed.chunks) ? parsed.chunks : [],
+        links: Array.isArray(parsed.links) ? parsed.links : []
+    };
+    indexCache.set(path, { ...stats, index: loaded });
+    if (indexCache.size > indexCacheMaxEntries) {
+        const oldest = indexCache.keys().next().value;
+        if (typeof oldest === 'string') {
+            indexCache.delete(oldest);
+        }
+    }
+    return loaded;
 };
 const writeIndex = async (vaultPath, index) => {
     const target = indexStoragePath(vaultPath);
@@ -63,6 +118,7 @@ const writeIndex = async (vaultPath, index) => {
     await mkdir(dirname(target), { recursive: true, mode: 0o700 });
     await writeFile(temp, `${JSON.stringify(index)}\n`, { encoding: 'utf8', mode: 0o600 });
     await rename(temp, target);
+    warnedCorruptIndexPaths.delete(target);
     const fileStats = await stat(target);
     indexCache.set(target, {
         mtimeMs: fileStats.mtimeMs,
@@ -91,40 +147,89 @@ const countOccurrences = (text, token) => {
     }
     return hits;
 };
-const textScore = (row, tokens) => {
+const titleFieldWeight = 5;
+const tagFieldWeight = 4;
+const pathFieldWeight = 2;
+const contentHitCap = 6;
+const hybridTextWeight = 0.6;
+const hybridSemanticWeight = 0.4;
+const normalizeFields = (row) => ({
+    title: normalizeToken(row.title),
+    path: normalizeToken(row.path),
+    content: normalizeToken(row.content),
+    tags: normalizeToken(row.tags.join(' '))
+});
+// Field-weighted term frequency: title/tag/path matches count more than body
+// matches, and body hits saturate at a cap so a term repeated many times in one
+// chunk cannot dominate. This weighted frequency feeds BM25 below.
+const weightedTermFrequency = (fields, token) => {
+    const titleHits = countOccurrences(fields.title, token);
+    const tagHits = countOccurrences(fields.tags, token);
+    const pathHits = countOccurrences(fields.path, token);
+    const contentHits = countOccurrences(fields.content, token);
+    return (titleHits * titleFieldWeight +
+        tagHits * tagFieldWeight +
+        pathHits * pathFieldWeight +
+        Math.min(contentHits, contentHitCap));
+};
+// Naive additive field score retained for graph-node title/path lookup, where
+// the candidate set is documents (not chunks) and corpus-wide BM25 statistics
+// add no signal over a direct weighted hit count.
+const lexicalFieldScore = (row, tokens) => {
     if (tokens.length === 0) {
         return 0;
     }
-    const title = normalizeToken(row.title);
-    const path = normalizeToken(row.path);
-    const content = normalizeToken(row.content);
-    const tags = normalizeToken(row.tags.join(' '));
-    return tokens.reduce((score, token) => {
-        const titleHits = countOccurrences(title, token);
-        const tagHits = countOccurrences(tags, token);
-        const pathHits = countOccurrences(path, token);
-        const contentHits = countOccurrences(content, token);
-        return score + titleHits * 5 + tagHits * 4 + pathHits * 2 + Math.min(contentHits, 6);
-    }, 0);
+    const fields = normalizeFields(row);
+    return tokens.reduce((score, token) => score + weightedTermFrequency(fields, token), 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;
+// A single chunk with a non-finite cached tokenCount (legacy index, partial
+// write, manual edit) would otherwise poison the shared averageLength and zero
+// out lexical scoring for the whole corpus, so coerce to a safe positive length.
+const safeDocumentLength = (tokenCount) => Number.isFinite(tokenCount) && tokenCount > 0 ? tokenCount : 1;
+const buildCorpusStatistics = (prepared, tokens) => {
+    const documentCount = prepared.length;
+    const totalLength = prepared.reduce((sum, entry) => sum + safeDocumentLength(entry.row.tokenCount), 0);
+    const documentFrequencyByTerm = new Map();
+    for (const term of tokens) {
+        let documentFrequency = 0;
+        for (const entry of prepared) {
+            if ((entry.weightedTermFrequencies.get(term) ?? 0) > 0) {
+                documentFrequency += 1;
+            }
+        }
+        documentFrequencyByTerm.set(term, documentFrequency);
+    }
     return {
-        documentId: row.documentId,
-        agentId: row.agentId,
-        title: row.title,
-        path: row.path,
-        chunkId: row.chunkId,
-        chunkOrdinal: row.chunkOrdinal,
-        content: row.content,
-        score,
-        textScore: text,
-        semanticScore: semantic,
-        searchMode: mode,
-        tags: row.tags
+        documentCount,
+        averageLength: documentCount > 0 ? totalLength / documentCount : 0,
+        documentFrequencyByTerm
     };
 };
+const bm25TextScore = (entry, tokens, stats) => tokens.reduce((score, term) => score +
+    bm25TermScore({
+        termFrequency: entry.weightedTermFrequencies.get(term) ?? 0,
+        documentLength: safeDocumentLength(entry.row.tokenCount),
+        documentCount: stats.documentCount,
+        documentFrequency: stats.documentFrequencyByTerm.get(term) ?? 0,
+        averageLength: stats.averageLength
+    }), 0);
+const semanticScore = (row, queryEmbedding) => queryEmbedding.length > 0 && row.embedding.length > 0 ? dotProduct(queryEmbedding, row.embedding) : 0;
+const rangeOf = (values) => values.reduce((range, value) => ({ min: Math.min(range.min, value), max: Math.max(range.max, value) }), { min: Infinity, max: -Infinity });
+const toResult = (row, mode, score, text, semantic) => ({
+    documentId: row.documentId,
+    agentId: row.agentId,
+    title: row.title,
+    path: row.path,
+    chunkId: row.chunkId,
+    chunkOrdinal: row.chunkOrdinal,
+    content: row.content,
+    score,
+    textScore: text,
+    semanticScore: semantic,
+    tokenCount: row.tokenCount,
+    searchMode: mode,
+    tags: row.tags
+});
 const toGraphLink = (link, documentsById) => {
     const source = documentsById.get(link.fromDocumentId);
     const target = link.toDocumentId ? documentsById.get(link.toDocumentId) : undefined;
@@ -187,7 +292,9 @@ export const openFileIndex = (vaultPath) => {
                 .sort((left, right) => left.document.path.localeCompare(right.document.path));
         },
         search: async (query, limit, agentId, mode = 'hybrid', queryEmbedding = []) => {
-            const index = await load();
+            // Strict load: a corrupt index throws so the caller can fall back to the
+            // independent search packs rather than reporting "no results".
+            const index = await readIndex(vaultPath, true);
             const documentsById = new Map(index.documents.map((document) => [document.id, document]));
             const rows = index.chunks.flatMap((chunk) => {
                 const document = documentsById.get(chunk.documentId);
@@ -206,6 +313,7 @@ export const openFileIndex = (vaultPath) => {
                         chunkId: chunk.id,
                         chunkOrdinal: chunk.ordinal,
                         content: chunk.content,
+                        tokenCount: chunk.tokenCount,
                         tags: document.tags,
                         embedding: chunk.embedding,
                         buckets: chunk.buckets
@@ -217,19 +325,68 @@ export const openFileIndex = (vaultPath) => {
             // 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
+            const candidates = 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);
-                return toResult(row, mode, text, semantic);
-            })
-                .filter((row) => row.score > 0 || tokens.length === 0)
+            // Pass 1: field-weighted term frequencies per candidate, then corpus-wide
+            // statistics (document frequency, average length) needed for BM25 IDF and
+            // length normalization.
+            const prepared = candidates.map((row) => {
+                const fields = normalizeFields(row);
+                const weightedTermFrequencies = new Map();
+                for (const term of tokens) {
+                    const frequency = weightedTermFrequency(fields, term);
+                    if (frequency > 0) {
+                        weightedTermFrequencies.set(term, frequency);
+                    }
+                }
+                return { row, weightedTermFrequencies };
+            });
+            const stats = buildCorpusStatistics(prepared, tokens);
+            // Pass 2: raw lexical (BM25) and semantic (cosine) component scores.
+            const componentScored = prepared.map((entry) => ({
+                row: entry.row,
+                text: tokens.length > 0 ? bm25TextScore(entry, tokens, stats) : 0,
+                semantic: semanticScore(entry.row, queryEmbedding)
+            }));
+            // Filter on raw relevance before normalization so a legitimate match that
+            // happens to be the weakest in its mode is never min-max scaled to zero
+            // and dropped. fts stays lexical-only and semantic stays vector-only.
+            const relevant = componentScored.filter((entry) => {
+                if (tokens.length === 0) {
+                    return true;
+                }
+                if (mode === 'fts') {
+                    return entry.text > 0;
+                }
+                if (mode === 'semantic') {
+                    return entry.semantic > 0;
+                }
+                return entry.text > 0 || entry.semantic > 0;
+            });
+            if (relevant.length === 0) {
+                return [];
+            }
+            const textRange = rangeOf(relevant.map((entry) => entry.text));
+            const semanticRange = rangeOf(relevant.map((entry) => entry.semantic));
+            const finalScore = (entry) => {
+                if (mode === 'fts') {
+                    return entry.text;
+                }
+                if (mode === 'semantic') {
+                    return entry.semantic;
+                }
+                // Hybrid mixes the two components on a shared [0, 1] scale so neither the
+                // unbounded BM25 magnitude nor the bounded cosine value can swamp the
+                // other, replacing the previous fixed `text + semantic * 8` blend.
+                const textNorm = minMaxNormalize(entry.text, textRange.min, textRange.max);
+                const semanticNorm = minMaxNormalize(entry.semantic, semanticRange.min, semanticRange.max);
+                return textNorm * hybridTextWeight + semanticNorm * hybridSemanticWeight;
+            };
+            return relevant
+                .map((entry) => toResult(entry.row, mode, finalScore(entry), entry.text, entry.semantic))
                 .sort((left, right) => right.score - left.score || left.title.localeCompare(right.title))
                 .slice(0, Math.max(0, limit));
-            return results;
         },
         listLinks: async (agentId) => {
             const index = await load();
@@ -335,7 +492,7 @@ export const openFileIndex = (vaultPath) => {
             const scored = index.documents
                 .filter((document) => (!agentId || document.agentId === agentId))
                 .map((document) => {
-                const score = textScore({
+                const score = lexicalFieldScore({
                     documentId: document.id,
                     agentId: document.agentId,
                     title: document.title,
@@ -343,6 +500,7 @@ export const openFileIndex = (vaultPath) => {
                     chunkId: document.id,
                     chunkOrdinal: 0,
                     content: document.content,
+                    tokenCount: 0,
                     tags: document.tags,
                     embedding: []
                 }, tokens);

package/dist/mcp/server.js

@@ -1,5 +1,5 @@
 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 { addNoteInputSchema, addFileInputSchema, addFileTool, 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, 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, versionInputSchema, versionTool } from './tools.js';
 import { getRuntimeVersion } from './runtime.js';
 import { guardToolHandler } from './tool-guard.js';
 export const createBrainlinkMcpServer = () => {
@@ -50,6 +50,11 @@ export const createBrainlinkMcpServer = () => {
         description: 'Search indexed Brainlink notes with FTS, semantic or hybrid retrieval.',
         inputSchema: searchInputSchema
     }, searchTool);
+    server.registerTool('brainlink_similar_notes', {
+        title: 'Find Similar Brainlink Notes',
+        description: 'Find the notes most similar to a given note (selected by title or path), using the note content as the retrieval query and excluding the note itself.',
+        inputSchema: similarNotesInputSchema
+    }, similarNotesTool);
     server.registerTool('brainlink_explain', {
         title: 'Explain Brainlink Search Results',
         description: 'Explain why indexed notes matched a query, including score components and match reasons.',
@@ -70,6 +75,11 @@ export const createBrainlinkMcpServer = () => {
         description: 'Write durable Markdown memory, then reindex the vault. Include explicit [[wiki links]] for connected graph memory. Add priority markers near links, such as priority: high, #important or #critical, when a relationship should be weighted higher.',
         inputSchema: addNoteInputSchema
     }, addNoteTool);
+    server.registerTool('brainlink_add_notes', {
+        title: 'Add Brainlink Notes (batch)',
+        description: 'Write several durable Markdown notes in one call, reindexing the vault once after all are written. Use for bulk capture instead of repeated brainlink_add_note calls.',
+        inputSchema: addNotesInputSchema
+    }, addNotesTool);
     server.registerTool('brainlink_remember', {
         title: 'Capture Assisted Brainlink Memory',
         description: 'Capture durable memory with inferred title, tags and Context Links. Supports dry-run preview before writing.',
@@ -95,6 +105,11 @@ export const createBrainlinkMcpServer = () => {
         description: 'Delete a durable Markdown note from the vault after explicit confirmation. Select by title or path; reindexes by default.',
         inputSchema: deleteNoteInputSchema
     }, deleteNoteTool);
+    server.registerTool('brainlink_delete_notes', {
+        title: 'Delete Brainlink Notes (batch)',
+        description: 'Delete several notes in one confirmed call, reindexing once after the batch. Each note is selected by exactly one of title or path; per-note failures are reported without aborting the batch.',
+        inputSchema: deleteNotesInputSchema
+    }, deleteNotesTool);
     server.registerTool('brainlink_volatile_add', {
         title: 'Add Volatile Brainlink Memory',
         description: 'Write temporary agent-decided memory with TTL. Use for transient task state without polluting durable Markdown memory.',

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

@@ -6,6 +6,7 @@ import { getGraphContexts } from '../../application/get-graph-contexts.js';
 import { explainSearchResults, suggestBrokenLinkFixes, suggestContextLinks } from '../../application/memory-suggestions.js';
 import { buildActionableDoctor } from '../../application/operational-workflows.js';
 import { searchKnowledge } from '../../application/search-knowledge.js';
+import { findSimilarNotes } from '../../application/find-similar-notes.js';
 import { sanitizeContextStrategy, sanitizeSearchMode } from '../../infrastructure/config.js';
 import { clearContextPacks, listContextPacks } from '../../infrastructure/context-packs.js';
 import { getBootstrapPolicy, getBootstrapSessionStatus, getContextSessionStatus, touchContextSession } from '../../infrastructure/session-state.js';
@@ -40,6 +41,14 @@ export const explainInputSchema = {
     query: z.string().min(1).describe('Search query to explain.'),
     limit: optionalPositiveInteger().describe('Maximum result count.')
 };
+export const similarNotesInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    ...searchModeInput,
+    title: z.string().min(1).optional().describe('Title of the note to find neighbors for. Use agent to disambiguate.'),
+    path: z.string().min(1).optional().describe('Vault-relative or absolute path of the note to find neighbors for.'),
+    limit: optionalPositiveInteger().describe('Maximum number of similar notes to return. Defaults to the configured search limit.')
+};
 export const validateInputSchema = {
     ...vaultInput,
     ...agentInput
@@ -162,6 +171,30 @@ export const searchTool = async (input) => {
         results
     });
 };
+export const similarNotesTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_similar_notes');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const limit = input.limit ?? context.defaults.defaultSearchLimit;
+    const result = await findSimilarNotes(context.vault, {
+        title: input.title,
+        path: input.path,
+        agentId: context.agent,
+        limit,
+        mode
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        mode,
+        limit,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...result
+    });
+};
 export const explainTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const readiness = await ensureBootstrapReady(context, input, 'brainlink_explain');

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

@@ -59,6 +59,38 @@ export const deleteNoteInputSchema = {
     confirm: z.boolean().describe('Must be true to confirm deletion.'),
     autoIndex: z.boolean().optional().default(true).describe('Reindex vault after deletion. Defaults to true.')
 };
+export const addNotesInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    notes: z
+        .array(z.object({
+        title: z.string().min(1).describe('Markdown note title.'),
+        content: z.string().min(1).describe('Durable Markdown memory. Include [[wiki links]] and #tags to connect it.')
+    }))
+        .min(1)
+        .max(100)
+        .describe('Notes to add in a single batch. The vault is reindexed once after all notes are written.'),
+    allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault once after writing all notes.'),
+    autoContextLinks: z
+        .boolean()
+        .optional()
+        .describe('Automatically add canonical Context Links to the inferred context hub. Defaults to Brainlink config.')
+};
+export const deleteNotesInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    notes: z
+        .array(z.object({
+        title: z.string().min(1).optional().describe('Note title to delete.'),
+        path: z.string().min(1).optional().describe('Vault-relative or absolute Markdown note path to delete.')
+    }))
+        .min(1)
+        .max(100)
+        .describe('Notes to delete in a single batch, each selected by exactly one of title or path.'),
+    confirm: z.boolean().describe('Must be true to confirm deletion of every listed note.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault once after all deletions.')
+};
 export const volatileAddInputSchema = {
     ...vaultInput,
     ...agentInput,
@@ -196,6 +228,80 @@ export const deleteNoteTool = async (input) => {
         ...result
     });
 };
+export const addNotesTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const autoContextLinks = input.autoContextLinks ?? context.config.autoCanonicalContextLinks;
+    // Per-note isolation mirrors deleteNotesTool: one failing note (secret,
+    // validation, FS error) is reported without discarding the notes that did
+    // write or skipping the single end-of-batch reindex.
+    const notes = [];
+    for (const note of input.notes) {
+        try {
+            const added = await addNoteWithMetadata(context.vault, note.title, note.content, context.agent, {
+                allowSensitive: input.allowSensitive,
+                autoContextLinks
+            });
+            notes.push({
+                ok: true,
+                title: note.title,
+                path: added.path,
+                writeConnectivity: {
+                    autoLinked: added.autoLinked,
+                    linkTarget: added.linkTarget,
+                    context: added.context,
+                    hubCreated: added.hubCreated,
+                    guaranteedEdge: added.autoLinked
+                }
+            });
+        }
+        catch (error) {
+            notes.push({ ok: false, title: note.title, error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    const added = notes.filter((entry) => entry.ok === true).length;
+    const index = isTruthy(input.autoIndex) && added > 0 ? await indexVault(context.vault) : undefined;
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        added,
+        failed: notes.length - added,
+        notes,
+        ...(index ? { index } : {})
+    });
+};
+export const deleteNotesTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    if (!input.confirm) {
+        throw new Error('Refusing to delete notes without explicit confirmation.');
+    }
+    const results = [];
+    for (const note of input.notes) {
+        try {
+            // Defer indexing: reindex once after the whole batch instead of per note.
+            const result = await deleteNote(context.vault, {
+                title: note.title,
+                path: note.path,
+                agentId: context.agent,
+                confirm: true,
+                autoIndex: false
+            });
+            results.push({ ok: true, title: result.title, path: result.relativePath });
+        }
+        catch (error) {
+            results.push({ ok: false, selector: note, error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    const deleted = results.filter((entry) => entry.ok === true).length;
+    const index = isTruthy(input.autoIndex) && deleted > 0 ? await indexVault(context.vault) : undefined;
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        deleted,
+        failed: results.length - deleted,
+        results,
+        ...(index ? { index } : {})
+    });
+};
 export const volatileAddTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const entry = await addVolatileMemory(context.vault, input.content, context.agent ?? 'shared', input.ttlMinutes ?? 240, input.tags);

package/dist/mcp/tools.js

@@ -1,3 +1,3 @@
-export { brokenLinksInputSchema, brokenLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, doctorActionsInputSchema, doctorActionsTool, explainInputSchema, explainTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, orphansInputSchema, orphansTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools/read-tools.js';
-export { addFileInputSchema, addFileTool, addNoteInputSchema, addNoteTool, deleteNoteInputSchema, deleteNoteTool, inboxAddInputSchema, inboxAddTool, inboxListInputSchema, inboxListTool, inboxProcessInputSchema, inboxProcessTool, rememberInputSchema, rememberTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool } from './tools/write-tools.js';
+export { brokenLinksInputSchema, brokenLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, doctorActionsInputSchema, doctorActionsTool, explainInputSchema, explainTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, orphansInputSchema, orphansTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, similarNotesInputSchema, similarNotesTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools/read-tools.js';
+export { addFileInputSchema, addFileTool, 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';