@andespindola/brainlink 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/infrastructure/session-state.js

@@ -3,13 +3,15 @@ import { dirname, join } from 'node:path';
 import { getBrainlinkHomePath } from './paths.js';
 const defaultPolicy = {
     enforceBootstrap: true,
+    enforceContextFirst: true,
     autoBootstrapOnRead: true,
     autoBootstrapOnStartup: true,
     staleAfterMinutes: 120
 };
 const defaultState = {
     policy: defaultPolicy,
-    bootstraps: []
+    bootstraps: [],
+    contexts: []
 };
 const sessionStatePath = () => join(getBrainlinkHomePath(), 'session-state.json');
 const normalizeAgent = (agent) => agent?.trim() ? agent.trim() : '*';
@@ -21,6 +23,7 @@ const sanitizeState = (value) => {
     const record = value;
     const policyRecord = typeof record.policy === 'object' && record.policy !== null ? record.policy : {};
     const rawBootstraps = Array.isArray(record.bootstraps) ? record.bootstraps : [];
+    const rawContexts = Array.isArray(record.contexts) ? record.contexts : [];
     const bootstraps = rawBootstraps.flatMap((entry) => {
         if (typeof entry !== 'object' || entry === null) {
             return [];
@@ -31,9 +34,22 @@ const sanitizeState = (value) => {
         const lastBootstrappedAt = typeof row.lastBootstrappedAt === 'string' && row.lastBootstrappedAt.trim().length > 0 ? row.lastBootstrappedAt.trim() : undefined;
         return vault && agent && lastBootstrappedAt ? [{ vault, agent, lastBootstrappedAt }] : [];
     });
+    const contexts = rawContexts.flatMap((entry) => {
+        if (typeof entry !== 'object' || entry === null) {
+            return [];
+        }
+        const row = entry;
+        const vault = typeof row.vault === 'string' && row.vault.trim().length > 0 ? row.vault.trim() : undefined;
+        const agent = typeof row.agent === 'string' && row.agent.trim().length > 0 ? row.agent.trim() : undefined;
+        const lastContextAt = typeof row.lastContextAt === 'string' && row.lastContextAt.trim().length > 0 ? row.lastContextAt.trim() : undefined;
+        return vault && agent && lastContextAt ? [{ vault, agent, lastContextAt }] : [];
+    });
     return {
         policy: {
             enforceBootstrap: typeof policyRecord.enforceBootstrap === 'boolean' ? policyRecord.enforceBootstrap : defaultPolicy.enforceBootstrap,
+            enforceContextFirst: typeof policyRecord.enforceContextFirst === 'boolean'
+                ? policyRecord.enforceContextFirst
+                : defaultPolicy.enforceContextFirst,
             autoBootstrapOnRead: typeof policyRecord.autoBootstrapOnRead === 'boolean'
                 ? policyRecord.autoBootstrapOnRead
                 : defaultPolicy.autoBootstrapOnRead,
@@ -42,7 +58,8 @@ const sanitizeState = (value) => {
                 : defaultPolicy.autoBootstrapOnStartup,
             staleAfterMinutes: safePositive(policyRecord.staleAfterMinutes, defaultPolicy.staleAfterMinutes)
         },
-        bootstraps
+        bootstraps,
+        contexts
     };
 };
 const readState = async () => {
@@ -68,6 +85,7 @@ export const setBootstrapPolicy = async (patch) => {
     const state = await readState();
     const next = {
         enforceBootstrap: typeof patch.enforceBootstrap === 'boolean' ? patch.enforceBootstrap : state.policy.enforceBootstrap,
+        enforceContextFirst: typeof patch.enforceContextFirst === 'boolean' ? patch.enforceContextFirst : state.policy.enforceContextFirst,
         autoBootstrapOnRead: typeof patch.autoBootstrapOnRead === 'boolean' ? patch.autoBootstrapOnRead : state.policy.autoBootstrapOnRead,
         autoBootstrapOnStartup: typeof patch.autoBootstrapOnStartup === 'boolean' ? patch.autoBootstrapOnStartup : state.policy.autoBootstrapOnStartup,
         staleAfterMinutes: safePositive(patch.staleAfterMinutes, state.policy.staleAfterMinutes)
@@ -96,6 +114,24 @@ export const touchBootstrapSession = async (vault, agent) => {
     });
     return entry;
 };
+export const touchContextSession = async (vault, agent) => {
+    const state = await readState();
+    const normalizedAgent = normalizeAgent(agent);
+    const entry = {
+        vault,
+        agent: normalizedAgent,
+        lastContextAt: new Date().toISOString()
+    };
+    const contexts = [
+        entry,
+        ...state.contexts.filter((item) => !(item.vault === entry.vault && item.agent === entry.agent))
+    ].slice(0, 500);
+    await writeState({
+        ...state,
+        contexts
+    });
+    return entry;
+};
 export const getBootstrapSessionStatus = async (vault, agent) => {
     const state = await readState();
     const normalizedAgent = normalizeAgent(agent);
@@ -115,3 +151,22 @@ export const getBootstrapSessionStatus = async (vault, agent) => {
         ageMinutes
     };
 };
+export const getContextSessionStatus = async (vault, agent) => {
+    const state = await readState();
+    const normalizedAgent = normalizeAgent(agent);
+    const match = state.contexts.find((entry) => entry.vault === vault && entry.agent === normalizedAgent);
+    if (!match) {
+        return {
+            ready: false,
+            stale: true
+        };
+    }
+    const ageMinutes = Math.max(0, (Date.now() - new Date(match.lastContextAt).getTime()) / 60000);
+    const stale = ageMinutes > state.policy.staleAfterMinutes;
+    return {
+        ready: !stale,
+        stale,
+        lastContextAt: match.lastContextAt,
+        ageMinutes
+    };
+};

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,13 +4,14 @@ 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';
 import { resolveAgentRuntimeDefaults, sanitizeSearchMode } from '../infrastructure/config.js';
 import { loadBrainlinkConfig } from '../infrastructure/config.js';
 import { assertVaultAllowed } from '../infrastructure/file-system-vault.js';
-import { getBootstrapPolicy, getBootstrapSessionStatus, setBootstrapPolicy, touchBootstrapSession } from '../infrastructure/session-state.js';
+import { getBootstrapPolicy, getBootstrapSessionStatus, getContextSessionStatus, setBootstrapPolicy, touchBootstrapSession, touchContextSession } from '../infrastructure/session-state.js';
 const positiveInteger = (fallback) => z
     .number()
     .int()
@@ -143,6 +144,73 @@ const ensureBootstrapReady = async (context, input, toolName) => {
         }, nextActions))
     };
 };
+const ensureContextReady = async (context, input, toolName) => {
+    const policy = await getBootstrapPolicy();
+    if (!policy.enforceContextFirst) {
+        return {
+            context: {
+                policy,
+                statusBefore: {
+                    ready: true,
+                    stale: false
+                },
+                reason: 'Context-first enforcement is disabled by policy.'
+            }
+        };
+    }
+    const status = await getContextSessionStatus(context.vault, context.agent);
+    if (status.ready) {
+        return {
+            context: {
+                policy,
+                statusBefore: status,
+                reason: 'Context session is already fresh for this vault/agent.'
+            }
+        };
+    }
+    const queryFromInput = typeof input.query === 'string' && input.query.trim().length > 0
+        ? input.query
+        : typeof input.contextQuery === 'string' && input.contextQuery.trim().length > 0
+            ? input.contextQuery
+            : '<task>';
+    const mode = sanitizeSearchMode(typeof input.mode === 'string' ? input.mode : undefined, context.defaults.defaultSearchMode);
+    const limit = typeof input.limit === 'number' && Number.isFinite(input.limit) && input.limit > 0
+        ? input.limit
+        : typeof input.contextLimit === 'number' && Number.isFinite(input.contextLimit) && input.contextLimit > 0
+            ? input.contextLimit
+            : context.defaults.defaultSearchLimit;
+    const tokens = typeof input.tokens === 'number' && Number.isFinite(input.tokens) && input.tokens > 0
+        ? input.tokens
+        : typeof input.contextTokens === 'number' && Number.isFinite(input.contextTokens) && input.contextTokens > 0
+            ? input.contextTokens
+            : context.defaults.defaultContextTokens;
+    const contextArgs = {
+        vault: context.vault,
+        ...(context.agent ? { agent: context.agent } : {}),
+        query: queryFromInput,
+        mode,
+        limit,
+        tokens
+    };
+    const nextActions = [
+        {
+            tool: 'brainlink_context',
+            reason: 'Context must be loaded first so Brainlink is the primary retrieval source before other read tools.',
+            args: contextArgs
+        }
+    ];
+    return {
+        preflight: preflightResult(withNextActions({
+            vault: context.vault,
+            agent: context.agent,
+            blockedTool: toolName,
+            policy,
+            contextStatus: status,
+            guidance: 'Run brainlink_context first for this vault/agent before other read tools so answers are grounded on Brainlink context.',
+            contextArgs
+        }, nextActions))
+    };
+};
 export const contextInputSchema = {
     ...vaultInput,
     ...agentInput,
@@ -225,6 +293,7 @@ export const policyInputSchema = {
     ...agentInput,
     preset: z.enum(['fully-auto', 'strict']).optional().describe('Apply an opinionated policy preset before explicit overrides.'),
     enforceBootstrap: z.boolean().optional().describe('Enable or disable bootstrap enforcement for MCP read tools.'),
+    enforceContextFirst: z.boolean().optional().describe('Require brainlink_context before other MCP read tools.'),
     autoBootstrapOnRead: z
         .boolean()
         .optional()
@@ -243,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');
@@ -253,12 +336,14 @@ export const contextTool = async (input) => {
     const limit = input.limit ?? context.defaults.defaultSearchLimit;
     const tokens = input.tokens ?? context.defaults.defaultContextTokens;
     const contextPackage = await buildContextPackage(context.vault, input.query, limit, tokens, context.agent, mode);
+    const contextSession = await touchContextSession(context.vault, context.agent);
     return jsonResult({
         vault: context.vault,
         agent: context.agent,
         mode,
         limit,
         tokens,
+        contextSession,
         ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
         ...contextPackage
     });
@@ -269,6 +354,10 @@ export const searchTool = async (input) => {
     if (readiness.preflight) {
         return readiness.preflight;
     }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_search');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
     const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
     const limit = input.limit ?? context.defaults.defaultSearchLimit;
     const results = await searchKnowledge(context.vault, input.query, limit, context.agent, mode);
@@ -279,6 +368,7 @@ export const searchTool = async (input) => {
         limit,
         mode,
         ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
         results
     });
 };
@@ -289,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,
@@ -299,6 +397,7 @@ export const addNoteTool = async (input) => {
             linkTarget: added.linkTarget,
             guaranteedEdge: true
         },
+        possibleDuplicates,
         ...(index ? { index } : {})
     });
 };
@@ -343,11 +442,16 @@ export const validateTool = async (input) => {
     if (readiness.preflight) {
         return readiness.preflight;
     }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_validate');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
     const validation = await validateVault(context.vault, context.agent);
     return jsonResult({
         vault: context.vault,
         agent: context.agent,
         ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
         ...validation
     });
 };
@@ -357,11 +461,16 @@ export const graphTool = async (input) => {
     if (readiness.preflight) {
         return readiness.preflight;
     }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_graph');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
     const graph = await getGraph(context.vault, context.agent);
     return jsonResult({
         vault: context.vault,
         agent: context.agent,
         ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
         ...graph
     });
 };
@@ -371,11 +480,16 @@ export const brokenLinksTool = async (input) => {
     if (readiness.preflight) {
         return readiness.preflight;
     }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_broken_links');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
     const brokenLinks = await getBrokenLinksReport(context.vault, context.agent);
     return jsonResult({
         vault: context.vault,
         agent: context.agent,
         ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
         brokenLinks
     });
 };
@@ -385,11 +499,16 @@ export const orphansTool = async (input) => {
     if (readiness.preflight) {
         return readiness.preflight;
     }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_orphans');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
     const orphans = await getOrphansReport(context.vault, context.agent);
     return jsonResult({
         vault: context.vault,
         agent: context.agent,
         ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
         orphans
     });
 };
@@ -399,11 +518,16 @@ export const statsTool = async (input) => {
     if (readiness.preflight) {
         return readiness.preflight;
     }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_stats');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
     const stats = await getStats(context.vault, context.agent);
     return jsonResult({
         vault: context.vault,
         agent: context.agent,
         ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
         stats
     });
 };
@@ -413,6 +537,10 @@ export const syncTool = async (input) => {
     if (readiness.preflight) {
         return readiness.preflight;
     }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_sync');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
     const index = await indexVault(context.vault);
     const stats = await getStats(context.vault, context.agent);
     const validation = await validateVault(context.vault, context.agent);
@@ -422,6 +550,7 @@ export const syncTool = async (input) => {
         vault: context.vault,
         agent: context.agent,
         ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
         index,
         stats,
         validation,
@@ -435,10 +564,12 @@ export const syncTool = async (input) => {
     const contextLimit = input.contextLimit ?? context.defaults.defaultSearchLimit;
     const contextTokens = input.contextTokens ?? context.defaults.defaultContextTokens;
     const contextPackage = await buildContextPackage(context.vault, input.contextQuery, contextLimit, contextTokens, context.agent, mode);
+    const contextSession = await touchContextSession(context.vault, context.agent);
     return jsonResult({
         ...response,
         context: {
             mode,
+            contextSession,
             ...contextPackage
         }
     });
@@ -454,6 +585,7 @@ export const bootstrapTool = async (input) => {
     const contextPackage = input.query
         ? await buildContextPackage(context.vault, input.query, limit, tokens, context.agent, mode)
         : undefined;
+    const contextSession = input.query ? await touchContextSession(context.vault, context.agent) : undefined;
     const guidance = stats.documentCount === 0
         ? 'Vault indexed with zero documents. Add durable notes with brainlink_add_note, then run brainlink_bootstrap again.'
         : input.query
@@ -522,7 +654,8 @@ export const bootstrapTool = async (input) => {
         policy,
         session,
         guidance,
-        ...(contextPackage ? { context: contextPackage } : {})
+        ...(contextPackage ? { context: contextPackage } : {}),
+        ...(contextSession ? { contextSession } : {})
     }, nextActions));
 };
 export const policyTool = async (input) => {
@@ -530,30 +663,35 @@ export const policyTool = async (input) => {
     const presetPatch = input.preset === 'strict'
         ? {
             enforceBootstrap: true,
+            enforceContextFirst: true,
             autoBootstrapOnRead: false,
             autoBootstrapOnStartup: false
         }
         : input.preset === 'fully-auto'
             ? {
                 enforceBootstrap: true,
+                enforceContextFirst: true,
                 autoBootstrapOnRead: true,
                 autoBootstrapOnStartup: true
             }
             : {};
     const policy = input.preset !== undefined ||
         typeof input.enforceBootstrap === 'boolean' ||
+        typeof input.enforceContextFirst === 'boolean' ||
         typeof input.autoBootstrapOnRead === 'boolean' ||
         typeof input.autoBootstrapOnStartup === 'boolean' ||
         typeof input.staleAfterMinutes === 'number'
         ? await setBootstrapPolicy({
             ...presetPatch,
             ...(typeof input.enforceBootstrap === 'boolean' ? { enforceBootstrap: input.enforceBootstrap } : {}),
+            ...(typeof input.enforceContextFirst === 'boolean' ? { enforceContextFirst: input.enforceContextFirst } : {}),
             ...(typeof input.autoBootstrapOnRead === 'boolean' ? { autoBootstrapOnRead: input.autoBootstrapOnRead } : {}),
             ...(typeof input.autoBootstrapOnStartup === 'boolean' ? { autoBootstrapOnStartup: input.autoBootstrapOnStartup } : {}),
             ...(typeof input.staleAfterMinutes === 'number' ? { staleAfterMinutes: input.staleAfterMinutes } : {})
         })
         : await getBootstrapPolicy();
     const bootstrapStatus = await getBootstrapSessionStatus(context.vault, context.agent);
+    const contextStatus = await getContextSessionStatus(context.vault, context.agent);
     const nextActions = bootstrapStatus.ready
         ? []
         : [
@@ -567,18 +705,37 @@ export const policyTool = async (input) => {
                 }
             }
         ];
+    const withContextAction = policy.enforceContextFirst && !contextStatus.ready
+        ? [
+            ...nextActions,
+            {
+                tool: 'brainlink_context',
+                reason: 'Context-first policy is enabled. Load context before other read tools.',
+                args: {
+                    vault: context.vault,
+                    ...(context.agent ? { agent: context.agent } : {}),
+                    query: '<task>',
+                    mode: context.defaults.defaultSearchMode,
+                    limit: context.defaults.defaultSearchLimit,
+                    tokens: context.defaults.defaultContextTokens
+                }
+            }
+        ]
+        : nextActions;
     return jsonResult(withNextActions({
         vault: context.vault,
         agent: context.agent,
         policy,
         bootstrapStatus,
+        contextStatus,
         ...(input.preset ? { presetApplied: input.preset } : {})
-    }, nextActions));
+    }, withContextAction));
 };
 export const recommendationsTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const policy = await getBootstrapPolicy();
     const bootstrapStatus = await getBootstrapSessionStatus(context.vault, context.agent);
+    const contextStatus = await getContextSessionStatus(context.vault, context.agent);
     const stats = await getStats(context.vault, context.agent);
     const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
     const limit = input.limit ?? context.defaults.defaultSearchLimit;
@@ -610,6 +767,22 @@ export const recommendationsTool = async (input) => {
                 }
             ]
             : []),
+        ...(policy.enforceContextFirst && !contextStatus.ready
+            ? [
+                {
+                    tool: 'brainlink_context',
+                    reason: 'Context-first policy is enabled. Load context before other read operations.',
+                    args: {
+                        vault: context.vault,
+                        ...(context.agent ? { agent: context.agent } : {}),
+                        query: query ?? '<task>',
+                        mode,
+                        limit,
+                        tokens
+                    }
+                }
+            ]
+            : []),
         ...(stats.documentCount === 0
             ? [
                 {
@@ -643,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).',
@@ -664,7 +848,35 @@ export const recommendationsTool = async (input) => {
         },
         policy,
         bootstrapStatus,
+        contextStatus,
         stats,
         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
+    });
+};