@andespindola/brainlink 0.1.0-beta.37 → 0.1.0-beta.39

package/README.md

@@ -69,6 +69,7 @@ Legacy `.jsonl.gz` packs are upgraded to `.blpk` automatically on first search/c
 - Backlinks, broken-link reports, orphan detection and validation.
 - Full-text, semantic and hybrid retrieval on a local file index.
 - Middle-out context assembly around the strongest chunk per document.
+- In-process index and context caching with automatic invalidation on index updates.
 - Compressed-space prefiltering for `.blpk` packs before decryption and scan.
 - Agent namespaces under `agents/<agent-id>/`.
 - S3-compatible bucket vaults through `s3://bucket/prefix` URIs.
@@ -515,6 +516,8 @@ Available tools:
 - `brainlink_recommendations`: return an automatic action plan so agents can run Brainlink in the recommended order.
 - `brainlink_context`: read indexed context for a task or question.
 - `brainlink_search`: search indexed notes.
+- `brainlink_dedupe`: detect duplicate candidates using exact hash + semantic similarity scores.
+- `brainlink_resolve_duplicate`: resolve duplicate pairs (`merge`, `link`, `ignore`) with connectivity-safe fallback edges.
 - `brainlink_add_note`: write durable Markdown memory and reindex.
 - `brainlink_add_file`: ingest a local file as a note and reindex.
 - `brainlink_index`: rebuild the vault index.
@@ -716,6 +719,28 @@ blink add "Note Title" --vault ./vault --content-file ./notes.md --no-auto-index
 
 Creates a Markdown note under `agents/<agent-id>/`. Common secret patterns are blocked by default; use `--allow-sensitive` only for an intentionally protected vault.
 To avoid disconnected memory, Brainlink auto-adds a fallback wiki edge when a note is written without links, creating agent hub notes when needed.
+`add` also returns `possibleDuplicates` (exact hash + semantic candidates) so agents can resolve duplicate memory right after writes.
+
+### `dedupe`
+
+```bash
+blink dedupe --vault ./vault --json
+blink dedupe --vault ./vault --agent coding-agent --limit 20 --min-score 0.92 --json
+blink dedupe --vault ./vault --no-semantic --json
+```
+
+Detects `possibleDuplicate` pairs using exact content hashes and optional semantic similarity.
+
+### `dedupe-resolve`
+
+```bash
+blink dedupe-resolve --vault ./vault --left agents/shared/a.md --right agents/shared/b.md --action merge --json
+blink dedupe-resolve --vault ./vault --left agents/shared/a.md --right agents/shared/b.md --action link --json
+blink dedupe-resolve --vault ./vault --left agents/shared/a.md --right agents/shared/b.md --action ignore --json
+```
+
+Resolves a duplicate pair with `merge`, `link` or `ignore`.
+When action is not `merge`, Brainlink still creates a low-priority related edge (`#related-to`) so notes remain connected.
 
 ### `index`
 
@@ -764,6 +789,7 @@ blink context "question" --vault ./vault --agent coding-agent --mode hybrid --js
 ```
 
 Builds a compact context package for an agent.
+Repeated calls with the same vault, agent, query, mode and token/limit settings are served from a short in-memory cache while the index is unchanged.
 
 ### `links`
 

package/dist/application/build-context.js

@@ -1,13 +1,68 @@
+import { stat } from 'node:fs/promises';
 import { formatContextPackage, selectContextSections } from '../domain/context.js';
+import { indexStoragePath } from '../infrastructure/file-index.js';
 import { searchKnowledge } from './search-knowledge.js';
+const contextCacheTtlMs = 45_000;
+const contextCacheMaxEntries = 200;
+const contextCache = new Map();
+const readIndexMtimeMs = async (vaultPath) => {
+    try {
+        return (await stat(indexStoragePath(vaultPath))).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+};
+const toCacheKey = (vaultPath, query, limit, maxTokens, agentId, mode) => JSON.stringify({
+    vaultPath,
+    query: query.trim().toLowerCase(),
+    limit,
+    maxTokens,
+    agentId: agentId?.trim().toLowerCase() ?? '*',
+    mode: mode ?? 'default'
+});
+const contextCacheGet = (key, indexMtimeMs) => {
+    const entry = contextCache.get(key);
+    if (!entry) {
+        return undefined;
+    }
+    const fresh = Date.now() - entry.createdAt <= contextCacheTtlMs && entry.indexMtimeMs === indexMtimeMs;
+    if (!fresh) {
+        contextCache.delete(key);
+        return undefined;
+    }
+    return entry.context;
+};
+const contextCacheSet = (entry) => {
+    contextCache.set(entry.key, entry);
+    if (contextCache.size <= contextCacheMaxEntries) {
+        return;
+    }
+    const overflow = contextCache.size - contextCacheMaxEntries;
+    const keys = Array.from(contextCache.keys()).slice(0, overflow);
+    keys.forEach((key) => contextCache.delete(key));
+};
 export const buildContextPackage = async (vaultPath, query, limit, maxTokens, agentId, mode) => {
+    const cacheKey = toCacheKey(vaultPath, query, limit, maxTokens, agentId, mode);
+    const indexMtimeMs = await readIndexMtimeMs(vaultPath);
+    const cached = contextCacheGet(cacheKey, indexMtimeMs);
+    if (cached) {
+        return cached;
+    }
     const results = await searchKnowledge(vaultPath, query, limit, agentId, mode);
     const sections = selectContextSections(results, maxTokens);
-    return {
+    const context = {
         query,
         sections,
         content: formatContextPackage(query, sections)
     };
+    contextCacheSet({
+        key: cacheKey,
+        createdAt: Date.now(),
+        indexMtimeMs,
+        context
+    });
+    return context;
 };
 export const buildContext = async (vaultPath, query, limit, maxTokens, agentId, mode) => {
     const contextPackage = await buildContextPackage(vaultPath, query, limit, maxTokens, agentId, mode);

package/dist/application/dedupe-notes.js

@@ -0,0 +1,226 @@
+import { createHash } from 'node:crypto';
+import { createEmbeddingBuckets, createLocalEmbedding, cosineSimilarity } from '../domain/embeddings.js';
+import { parseMarkdownDocument } from '../domain/markdown.js';
+import { writeMarkdownFile, ensureVault, readMarkdownFiles } from '../infrastructure/file-system-vault.js';
+import { indexVault } from './index-vault.js';
+const tokenPattern = /[\p{L}\p{N}_-]+/gu;
+const frontmatterPattern = /^---\n[\s\S]*?\n---\n?/m;
+const rootHeadingPattern = /^#\s+.+\n+/m;
+const maxCandidatesPerBucket = 240;
+const normalizePath = (path) => path.replaceAll('\\', '/').replace(/^\.\//, '');
+const toComparableBody = (content) => content
+    .replace(frontmatterPattern, '')
+    .replace(rootHeadingPattern, '')
+    .replaceAll('\r\n', '\n')
+    .trim();
+const normalizeStrictContent = (content) => toComparableBody(content);
+const normalizeSemanticContent = (content) => toComparableBody(content)
+    .replace(/\s+/g, ' ')
+    .trim();
+const toHash = (value) => createHash('sha256').update(value, 'utf8').digest('hex');
+const toCandidateId = (leftPath, rightPath) => [normalizePath(leftPath), normalizePath(rightPath)].sort((left, right) => left.localeCompare(right)).join('|');
+const hasSharedTokens = (left, right) => {
+    const leftTokens = new Set((left.match(tokenPattern) ?? []).map((token) => token.toLowerCase()).filter((token) => token.length > 2));
+    const rightTokens = new Set((right.match(tokenPattern) ?? []).map((token) => token.toLowerCase()).filter((token) => token.length > 2));
+    if (leftTokens.size === 0 || rightTokens.size === 0) {
+        return false;
+    }
+    for (const token of leftTokens) {
+        if (rightTokens.has(token)) {
+            return true;
+        }
+    }
+    return false;
+};
+const relatedMarker = (targetTitle) => `Related: [[${targetTitle}]] priority: low #related-to`;
+const ensureRelatedEdgeLine = (content, targetTitle) => {
+    const linkPattern = new RegExp(`\\[\\[\\s*${targetTitle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*(?:[\\]|#])?`, 'i');
+    if (linkPattern.test(content)) {
+        return content;
+    }
+    const trimmed = content.trimEnd();
+    return `${trimmed}\n\n${relatedMarker(targetTitle)}\n`;
+};
+const ensureMergedMarker = (content, targetTitle) => {
+    const marker = `Merged into [[${targetTitle}]]`;
+    if (content.includes(marker)) {
+        return content;
+    }
+    return `${content.trimEnd()}\n\n${marker} priority: low #related-to\n`;
+};
+const appendMergedContent = (baseContent, mergedTitle, mergedContent) => {
+    const marker = `## Merged Memory From [[${mergedTitle}]]`;
+    if (baseContent.includes(marker)) {
+        return baseContent;
+    }
+    const mergedBody = normalizeSemanticContent(mergedContent);
+    return `${baseContent.trimEnd()}\n\n${marker}\n\n${mergedBody}\n`;
+};
+const loadNoteRecords = async (vaultPath, agentId) => {
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const files = await readMarkdownFiles(vaultPath);
+    return files
+        .map((file) => {
+        const parsed = parseMarkdownDocument({
+            absolutePath: file.absolutePath,
+            vaultPath: absoluteVaultPath,
+            content: file.content,
+            createdAt: file.createdAt,
+            updatedAt: file.updatedAt
+        });
+        const strict = normalizeStrictContent(parsed.content);
+        const semantic = normalizeSemanticContent(parsed.content);
+        const embedding = createLocalEmbedding(`${parsed.title}\n${semantic}`);
+        return {
+            title: parsed.title,
+            path: normalizePath(parsed.path),
+            agentId: parsed.agentId,
+            content: parsed.content,
+            normalizedStrictContent: strict,
+            semanticContent: semantic,
+            embedding,
+            buckets: createEmbeddingBuckets(embedding, 20)
+        };
+    })
+        .filter((record) => (agentId ? record.agentId === agentId : true));
+};
+const pairToCandidate = (left, right, kind, score, reason) => ({
+    id: toCandidateId(left.path, right.path),
+    possibleDuplicate: true,
+    kind,
+    score: Number(score.toFixed(4)),
+    left: {
+        title: left.title,
+        path: left.path,
+        agentId: left.agentId
+    },
+    right: {
+        title: right.title,
+        path: right.path,
+        agentId: right.agentId
+    },
+    reason
+});
+const indexCandidatePairs = (notes) => {
+    const bucketMap = new Map();
+    notes.forEach((note, index) => {
+        note.buckets.forEach((bucket) => {
+            const current = bucketMap.get(bucket) ?? [];
+            if (current.length < maxCandidatesPerBucket) {
+                current.push(index);
+                bucketMap.set(bucket, current);
+            }
+        });
+    });
+    const pairKeys = new Set();
+    const pairs = [];
+    bucketMap.forEach((indexes) => {
+        for (let leftIndex = 0; leftIndex < indexes.length; leftIndex += 1) {
+            for (let rightIndex = leftIndex + 1; rightIndex < indexes.length; rightIndex += 1) {
+                const left = Math.min(indexes[leftIndex] ?? 0, indexes[rightIndex] ?? 0);
+                const right = Math.max(indexes[leftIndex] ?? 0, indexes[rightIndex] ?? 0);
+                const key = `${left}|${right}`;
+                if (!pairKeys.has(key)) {
+                    pairKeys.add(key);
+                    pairs.push([left, right]);
+                }
+            }
+        }
+    });
+    return pairs;
+};
+export const scanDuplicateNotes = async (vaultPath, options = {}) => {
+    const notes = await loadNoteRecords(vaultPath, options.agentId);
+    if (notes.length < 2) {
+        return [];
+    }
+    const minSemanticScore = options.minSemanticScore ?? 0.92;
+    const includeSemantic = options.includeSemantic !== false;
+    const seen = new Map();
+    const byHash = notes.reduce((state, note) => {
+        const key = toHash(note.normalizedStrictContent);
+        const current = state.get(key) ?? [];
+        current.push(note);
+        state.set(key, current);
+        return state;
+    }, new Map());
+    byHash.forEach((group) => {
+        if (group.length < 2) {
+            return;
+        }
+        const [base, ...rest] = group.sort((left, right) => left.path.localeCompare(right.path));
+        rest.forEach((note) => {
+            const candidate = pairToCandidate(base, note, 'exact', 1, 'Exact content hash match');
+            seen.set(candidate.id, candidate);
+        });
+    });
+    if (includeSemantic) {
+        const pairs = indexCandidatePairs(notes);
+        pairs.forEach(([leftIndex, rightIndex]) => {
+            const left = notes[leftIndex];
+            const right = notes[rightIndex];
+            if (!left || !right || left.path === right.path) {
+                return;
+            }
+            const id = toCandidateId(left.path, right.path);
+            if (seen.has(id)) {
+                return;
+            }
+            const score = cosineSimilarity(left.embedding, right.embedding);
+            const titleShared = hasSharedTokens(left.title, right.title);
+            const contentShared = hasSharedTokens(left.semanticContent, right.semanticContent);
+            if (score >= minSemanticScore && (titleShared || contentShared || score >= 0.975)) {
+                const candidate = pairToCandidate(left, right, 'semantic', score, 'High semantic similarity');
+                seen.set(id, candidate);
+            }
+        });
+    }
+    const focusPath = options.focusPath ? normalizePath(options.focusPath) : undefined;
+    const limited = Array.from(seen.values())
+        .filter((item) => (focusPath ? item.left.path === focusPath || item.right.path === focusPath : true))
+        .sort((left, right) => right.score - left.score || left.left.path.localeCompare(right.left.path))
+        .slice(0, Math.max(1, options.limit ?? 25));
+    return limited;
+};
+export const resolveDuplicateNotes = async (vaultPath, options) => {
+    const leftPath = normalizePath(options.leftPath);
+    const rightPath = normalizePath(options.rightPath);
+    if (leftPath === rightPath) {
+        throw new Error('leftPath and rightPath must be different notes.');
+    }
+    const notes = await loadNoteRecords(vaultPath);
+    const byPath = new Map(notes.map((note) => [note.path, note]));
+    const left = byPath.get(leftPath);
+    const right = byPath.get(rightPath);
+    if (!left || !right) {
+        throw new Error(`Duplicate resolution paths were not found in vault index source: ${leftPath}, ${rightPath}`);
+    }
+    const updates = new Map();
+    const leftRelated = ensureRelatedEdgeLine(left.content, right.title);
+    const rightRelated = ensureRelatedEdgeLine(right.content, left.title);
+    if (options.action === 'link') {
+        updates.set(left.path, leftRelated);
+        updates.set(right.path, rightRelated);
+    }
+    else if (options.action === 'ignore') {
+        updates.set(left.path, leftRelated);
+    }
+    else {
+        const mergedLeft = appendMergedContent(leftRelated, right.title, right.content);
+        const mergedRight = ensureMergedMarker(rightRelated, left.title);
+        updates.set(left.path, mergedLeft);
+        updates.set(right.path, mergedRight);
+    }
+    for (const [path, content] of updates) {
+        await writeMarkdownFile(vaultPath, path, content);
+    }
+    const shouldIndex = options.autoIndex !== false;
+    const index = shouldIndex ? await indexVault(vaultPath) : undefined;
+    return {
+        action: options.action,
+        leftPath,
+        rightPath,
+        updatedPaths: Array.from(updates.keys()).sort((leftValue, rightValue) => leftValue.localeCompare(rightValue)),
+        ...(index ? { index } : {})
+    };
+};

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

@@ -3,8 +3,9 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, resolve } from 'node:path';
 import { platform, tmpdir } from 'node:os';
 import { spawn, spawnSync } from 'node:child_process';
-import { addNote } from '../../application/add-note.js';
+import { addNoteWithMetadata } from '../../application/add-note.js';
 import { buildContextPackage } from '../../application/build-context.js';
+import { resolveDuplicateNotes, scanDuplicateNotes } from '../../application/dedupe-notes.js';
 import { importLegacySqliteDatabase } from '../../application/import-legacy-sqlite.js';
 import { indexVault } from '../../application/index-vault.js';
 import { migrateVaultContent, planVaultMigration, previewVaultMigration, shouldMigrateDefaultVault } from '../../application/migrate-vault.js';
@@ -26,6 +27,16 @@ const resolveAddContent = (options) => {
     }
     return readFileSync(options.contentFile, 'utf8');
 };
+const parseScore = (value, fallback) => {
+    if (value == null) {
+        return fallback;
+    }
+    const parsed = Number.parseFloat(value);
+    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+        throw new Error(`Invalid score value: ${value}. Expected a number between 0 and 1.`);
+    }
+    return parsed;
+};
 const spawnDetached = (command, args) => {
     try {
         const child = spawn(command, args, { detached: true, stdio: 'ignore' });
@@ -494,12 +505,95 @@ export const registerWriteCommands = (program) => {
         .action(async (title, options) => {
         const resolved = await resolveOptions(options);
         const content = resolveAddContent(options);
-        const notePath = await addNote(resolved.vault, title, content, resolved.agent, {
+        const added = await addNoteWithMetadata(resolved.vault, title, content, resolved.agent, {
             allowSensitive: Boolean(options.allowSensitive)
         });
         const shouldAutoIndex = options.autoIndex !== false && resolved.config.autoIndexOnWrite;
         const index = shouldAutoIndex ? await indexVault(resolved.vault) : undefined;
-        print(options.json, { title, agent: resolved.agent ?? 'shared', path: notePath, ...(index ? { index } : {}) }, () => `Created note at ${notePath}`);
+        const absoluteVaultPath = await ensureVault(resolved.vault);
+        const focusPath = added.path.startsWith(absoluteVaultPath)
+            ? relative(absoluteVaultPath, added.path).replaceAll('\\', '/')
+            : added.path.includes('agents/')
+                ? added.path.slice(added.path.indexOf('agents/')).replaceAll('\\', '/')
+                : undefined;
+        const possibleDuplicates = await scanDuplicateNotes(resolved.vault, {
+            agentId: resolved.agent,
+            focusPath,
+            limit: 5,
+            minSemanticScore: 0.92,
+            includeSemantic: true
+        });
+        print(options.json, {
+            title,
+            agent: resolved.agent ?? 'shared',
+            path: added.path,
+            writeConnectivity: {
+                autoLinked: added.autoLinked,
+                linkTarget: added.linkTarget,
+                guaranteedEdge: true
+            },
+            possibleDuplicates,
+            ...(index ? { index } : {})
+        }, () => {
+            const duplicateMessage = possibleDuplicates.length > 0
+                ? `\nPotential duplicates: ${possibleDuplicates.length}. Use "blink dedupe --json" or "blink dedupe-resolve".`
+                : '';
+            return `Created note at ${added.path}${duplicateMessage}`;
+        });
+    });
+    program
+        .command('dedupe')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('-l, --limit <limit>', 'maximum duplicate candidate pairs')
+        .option('--min-score <score>', 'minimum semantic similarity score between 0 and 1', '0.92')
+        .option('--no-semantic', 'disable semantic duplicate detection and keep exact-content matching only')
+        .option('--json', 'print machine-readable JSON')
+        .description('detect possible duplicate notes with exact hash and semantic similarity scores')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const duplicates = await scanDuplicateNotes(resolved.vault, {
+            agentId: resolved.agent,
+            limit: parsePositiveInteger(options.limit ?? '25', 25),
+            minSemanticScore: parseScore(options.minScore, 0.92),
+            includeSemantic: options.semantic !== false
+        });
+        print(options.json, { vault: resolved.vault, agent: resolved.agent, duplicates }, () => {
+            if (duplicates.length === 0) {
+                return 'No possible duplicates found.';
+            }
+            return duplicates
+                .map((item, index) => `${index + 1}. [${item.kind}] score=${item.score.toFixed(4)} ${item.left.path} <-> ${item.right.path} (${item.reason})`)
+                .join('\n');
+        });
+    });
+    program
+        .command('dedupe-resolve')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('--left <path>', 'left note relative path from dedupe result')
+        .option('--right <path>', 'right note relative path from dedupe result')
+        .option('--action <action>', 'resolution action: merge, link or ignore')
+        .option('--no-auto-index', 'skip reindex after duplicate resolution')
+        .option('--json', 'print machine-readable JSON')
+        .description('resolve a duplicate candidate with merge, link or ignore')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        if (!options.left || !options.right) {
+            throw new Error('Use --left <path> and --right <path> to resolve a duplicate pair.');
+        }
+        if (options.action !== 'merge' && options.action !== 'link' && options.action !== 'ignore') {
+            throw new Error('Use --action merge|link|ignore.');
+        }
+        const result = await resolveDuplicateNotes(resolved.vault, {
+            leftPath: options.left,
+            rightPath: options.right,
+            action: options.action,
+            autoIndex: options.autoIndex !== false
+        });
+        print(options.json, {
+            vault: resolved.vault,
+            ...result
+        }, () => `Resolved duplicate (${result.action}) for ${result.leftPath} <-> ${result.rightPath}`);
     });
     program
         .command('index')

package/dist/infrastructure/file-index.js

@@ -1,7 +1,9 @@
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { cosineSimilarity } from '../domain/embeddings.js';
 const queryTokenPattern = /[\p{L}\p{N}_-]+/gu;
+const indexCacheMaxEntries = 16;
+const indexCache = new Map();
 const emptyIndex = () => ({
     version: 1,
     updatedAt: new Date().toISOString(),
@@ -11,18 +13,44 @@ const emptyIndex = () => ({
 });
 export const indexStoragePath = (vaultPath) => join(vaultPath, '.brainlink', 'index.json');
 const readIndex = async (vaultPath) => {
+    const path = indexStoragePath(vaultPath);
+    let stats = null;
     try {
-        const parsed = JSON.parse(await readFile(indexStoragePath(vaultPath), 'utf8'));
-        return {
+        const fileStats = await stat(path);
+        stats = { mtimeMs: fileStats.mtimeMs, size: fileStats.size };
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            indexCache.delete(path);
+            return emptyIndex();
+        }
+        return emptyIndex();
+    }
+    const cached = indexCache.get(path);
+    if (cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) {
+        return cached.index;
+    }
+    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);
+            }
+        }
+        return loaded;
     }
     catch (error) {
         if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            indexCache.delete(path);
             return emptyIndex();
         }
         return emptyIndex();
@@ -34,6 +62,12 @@ 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);
+    const fileStats = await stat(target);
+    indexCache.set(target, {
+        mtimeMs: fileStats.mtimeMs,
+        size: fileStats.size,
+        index
+    });
 };
 const normalizeToken = (value) => value
     .normalize('NFKD')

package/dist/mcp/server.js

@@ -2,7 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, contextInputSchema, contextTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool } from './tools.js';
+import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, contextInputSchema, contextTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool } from './tools.js';
 const readPackageVersion = () => {
     const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
     const metadata = JSON.parse(readFileSync(packagePath, 'utf8'));
@@ -40,6 +40,16 @@ export const createBrainlinkMcpServer = () => {
         description: 'Search indexed Brainlink notes with FTS, semantic or hybrid retrieval.',
         inputSchema: searchInputSchema
     }, searchTool);
+    server.registerTool('brainlink_dedupe', {
+        title: 'Detect Duplicate Notes',
+        description: 'Detect possible duplicate notes using exact content hash and semantic similarity scoring.',
+        inputSchema: dedupeInputSchema
+    }, dedupeTool);
+    server.registerTool('brainlink_resolve_duplicate', {
+        title: 'Resolve Duplicate Notes',
+        description: 'Resolve a duplicate pair with merge, link or ignore. Non-merge actions still create low-priority related edges.',
+        inputSchema: dedupeResolveInputSchema
+    }, dedupeResolveTool);
     server.registerTool('brainlink_add_note', {
         title: 'Add Brainlink Note',
         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.',

package/dist/mcp/tools.js

@@ -4,6 +4,7 @@ import { z } from 'zod';
 import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../application/analyze-vault.js';
 import { addNoteWithMetadata } from '../application/add-note.js';
 import { buildContextPackage } from '../application/build-context.js';
+import { resolveDuplicateNotes, scanDuplicateNotes } from '../application/dedupe-notes.js';
 import { getGraph } from '../application/get-graph.js';
 import { indexVault } from '../application/index-vault.js';
 import { searchKnowledge } from '../application/search-knowledge.js';
@@ -311,6 +312,20 @@ export const recommendationsInputSchema = {
     limit: optionalPositiveInteger().describe('Optional context limit override for generated recommendations.'),
     tokens: optionalPositiveInteger().describe('Optional context token budget override for generated recommendations.')
 };
+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 contextTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const readiness = await ensureBootstrapReady(context, input, 'brainlink_context');
@@ -364,6 +379,14 @@ export const addNoteTool = async (input) => {
         allowSensitive: input.allowSensitive
     });
     const index = shouldIndex ? await indexVault(context.vault) : undefined;
+    const focusPath = added.path.includes('agents/') ? added.path.slice(added.path.indexOf('agents/')).replaceAll('\\', '/') : undefined;
+    const possibleDuplicates = await scanDuplicateNotes(context.vault, {
+        agentId: context.agent,
+        focusPath,
+        limit: 5,
+        minSemanticScore: 0.92,
+        includeSemantic: true
+    });
     return jsonResult({
         vault: context.vault,
         title: input.title,
@@ -374,6 +397,7 @@ export const addNoteTool = async (input) => {
             linkTarget: added.linkTarget,
             guaranteedEdge: true
         },
+        possibleDuplicates,
         ...(index ? { index } : {})
     });
 };
@@ -792,6 +816,17 @@ export const recommendationsTool = async (input) => {
                 tokens
             }
         },
+        {
+            tool: 'brainlink_dedupe',
+            reason: 'Detect and resolve duplicate durable notes to keep memory quality high.',
+            args: {
+                vault: context.vault,
+                ...(context.agent ? { agent: context.agent } : {}),
+                limit: 10,
+                minScore: 0.92,
+                semantic: true
+            }
+        },
         {
             tool: 'brainlink_add_note',
             reason: 'Persist durable outcomes after task completion (write responses include connectivity metadata).',
@@ -818,3 +853,30 @@ export const recommendationsTool = async (input) => {
         recommendations
     });
 };
+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
+    });
+};

package/docs/AGENT_USAGE.md

@@ -429,6 +429,25 @@ This creates a slugged Markdown file with frontmatter and a heading.
 
 The CLI blocks common secret patterns by default. Do not use `--allow-sensitive` unless the vault is intentionally protected.
 Brainlink also auto-connects notes that have no `[[wiki links]]` by adding a fallback edge to an agent hub note, so new memory does not stay disconnected.
+`add` also returns `possibleDuplicates` (exact hash + semantic candidates) so agents can decide duplicate resolution immediately.
+
+### Detect Duplicate Notes
+
+```bash
+blink dedupe --vault ./vault --json
+blink dedupe --vault ./vault --agent coding-agent --limit 20 --min-score 0.92 --json
+blink dedupe --vault ./vault --no-semantic --json
+```
+
+### Resolve Duplicate Notes
+
+```bash
+blink dedupe-resolve --vault ./vault --left agents/shared/a.md --right agents/shared/b.md --action merge --json
+blink dedupe-resolve --vault ./vault --left agents/shared/a.md --right agents/shared/b.md --action link --json
+blink dedupe-resolve --vault ./vault --left agents/shared/a.md --right agents/shared/b.md --action ignore --json
+```
+
+`dedupe-resolve` keeps connectivity: non-merge actions still create a low-priority related edge (`#related-to`).
 
 For agent-private memory:
 
@@ -613,6 +632,8 @@ Available MCP tools:
 - `brainlink_recommendations`
 - `brainlink_context`
 - `brainlink_search`
+- `brainlink_dedupe`
+- `brainlink_resolve_duplicate`
 - `brainlink_add_note`
 - `brainlink_add_file`
 - `brainlink_index`

package/package.json

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