@andespindola/brainlink 1.0.5 → 1.0.7

package/dist/domain/scoring.js

@@ -0,0 +1,42 @@
+// Pure retrieval scoring primitives: BM25 lexical relevance and min-max
+// normalization. Kept dependency-free and deterministic so the hot retrieval
+// loop in the infrastructure layer stays testable and the domain owns the
+// ranking math.
+export const defaultBm25Parameters = {
+    k1: 1.2,
+    b: 0.75
+};
+// Robertson/Sparck-Jones probabilistic IDF with the +0.5 smoothing that keeps
+// the value finite for terms present in every chunk. Floored at 0 so a term
+// shared by the whole candidate set can never push a score negative.
+export const inverseDocumentFrequency = (documentCount, documentFrequency) => {
+    if (documentCount <= 0) {
+        return 0;
+    }
+    const raw = Math.log(1 + (documentCount - documentFrequency + 0.5) / (documentFrequency + 0.5));
+    return raw > 0 ? raw : 0;
+};
+// BM25 contribution for a single query term given its (field-weighted)
+// frequency in a chunk. `documentLength` and `averageLength` are in the same
+// weighted unit so length normalization stays consistent with how the caller
+// counts terms.
+export const bm25TermScore = (params) => {
+    if (params.termFrequency <= 0) {
+        return 0;
+    }
+    const { k1, b } = params.parameters ?? defaultBm25Parameters;
+    const idf = inverseDocumentFrequency(params.documentCount, params.documentFrequency);
+    const normalizedLength = params.averageLength > 0 ? params.documentLength / params.averageLength : 1;
+    const denominator = params.termFrequency + k1 * (1 - b + b * normalizedLength);
+    return denominator > 0 ? (idf * (params.termFrequency * (k1 + 1))) / denominator : 0;
+};
+// Scale a value into [0, 1] given the observed range. When every candidate
+// shares the same score (range collapses) a positive score maps to 1 and a
+// zero score to 0, so a single result is never silently nulled out.
+export const minMaxNormalize = (value, minimum, maximum) => {
+    if (maximum <= minimum) {
+        return value > 0 ? 1 : 0;
+    }
+    const scaled = (value - minimum) / (maximum - minimum);
+    return scaled < 0 ? 0 : scaled > 1 ? 1 : scaled;
+};

package/dist/domain/tokens.js

@@ -1 +1,17 @@
-export const estimateTokenCount = (content) => Math.ceil(content.trim().split(/\s+/).filter(Boolean).join(' ').length / 4);
+// Subword tokenizers emit roughly 1.3 tokens per whitespace word for natural
+// language. Pure prose tracks that ratio; punctuation- or symbol-dense content
+// (code, URLs, long unbroken strings) tokenizes far denser, which the word
+// count alone underestimates. Taking the max with the character heuristic keeps
+// the estimate conservative — never below chars/4 — so callers that budget
+// against it can rely on the rendered output staying within the token limit.
+const tokensPerWord = 1.3;
+const charactersPerToken = 4;
+export const estimateTokenCount = (content) => {
+    const words = content.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0) {
+        return 0;
+    }
+    const characterEstimate = Math.ceil(words.join(' ').length / charactersPerToken);
+    const wordEstimate = Math.ceil(words.length * tokensPerWord);
+    return Math.max(characterEstimate, wordEstimate);
+};

package/dist/infrastructure/config.js

@@ -11,11 +11,14 @@ export const defaultBrainlinkConfig = {
     defaultAgent: undefined,
     autoIndexOnWrite: true,
     autoCanonicalContextLinks: true,
+    autoUpdateCheck: true,
+    updateCheckIntervalMs: 86_400_000,
     defaultSearchLimit: 8,
     defaultContextTokens: 1500,
     defaultContextStrategy: 'auto',
     defaultContextCacheTtlMs: 120_000,
     embeddingProvider: 'local',
+    embedding: {},
     defaultSearchMode: 'hybrid',
     chunkSize: 1200,
     searchPack: {
@@ -41,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) : [];
@@ -177,6 +204,10 @@ const sanitizeConfig = (value) => ({
     autoCanonicalContextLinks: typeof value.autoCanonicalContextLinks === 'boolean'
         ? value.autoCanonicalContextLinks
         : defaultBrainlinkConfig.autoCanonicalContextLinks,
+    autoUpdateCheck: typeof value.autoUpdateCheck === 'boolean' ? value.autoUpdateCheck : defaultBrainlinkConfig.autoUpdateCheck,
+    updateCheckIntervalMs: typeof value.updateCheckIntervalMs === 'number' && Number.isFinite(value.updateCheckIntervalMs) && value.updateCheckIntervalMs > 0
+        ? Math.floor(value.updateCheckIntervalMs)
+        : defaultBrainlinkConfig.updateCheckIntervalMs,
     defaultSearchLimit: typeof value.defaultSearchLimit === 'number' && value.defaultSearchLimit > 0
         ? value.defaultSearchLimit
         : defaultBrainlinkConfig.defaultSearchLimit,
@@ -191,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,8 @@
 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 { bm25TermScore, minMaxNormalize } from '../domain/scoring.js';
+import { selectSemanticCandidates } from './semantic-prefilter.js';
 const queryTokenPattern = /[\p{L}\p{N}_-]+/gu;
 const indexCacheMaxEntries = 16;
 const indexCache = new Map();
@@ -11,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 {
@@ -20,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();
     }
@@ -30,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);
@@ -62,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,
@@ -90,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 ? cosineSimilarity(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;
@@ -186,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);
@@ -205,22 +313,80 @@ export const openFileIndex = (vaultPath) => {
                         chunkId: chunk.id,
                         chunkOrdinal: chunk.ordinal,
                         content: chunk.content,
+                        tokenCount: chunk.tokenCount,
                         tags: document.tags,
-                        embedding: chunk.embedding
+                        embedding: chunk.embedding,
+                        buckets: chunk.buckets
                     }
                 ];
             });
             const tokens = tokenize(query);
-            const results = rows
-                .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)
+            // 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 candidates = mode === 'semantic' && queryEmbedding.length > 0
+                ? selectSemanticCandidates(rows, createEmbeddingBuckets(queryEmbedding), limit)
+                : rows;
+            // 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();
@@ -326,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,
@@ -334,6 +500,7 @@ export const openFileIndex = (vaultPath) => {
                     chunkId: document.id,
                     chunkOrdinal: 0,
                     content: document.content,
+                    tokenCount: 0,
                     tags: document.tags,
                     embedding: []
                 }, tokens);

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 { 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 = () => {
     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.',
@@ -43,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.',
@@ -63,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.',
@@ -88,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/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);
+    }
+};