@andespindola/brainlink 1.0.3 → 1.0.5

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

@@ -3,6 +3,7 @@ import { buildContextPackage, readContextDataSignature } from '../../application
 import { getGraph } from '../../application/get-graph.js';
 import { listAgents } from '../../application/list-agents.js';
 import { listBacklinks, listLinks } from '../../application/list-links.js';
+import { explainSearchResults } from '../../application/memory-suggestions.js';
 import { searchKnowledge } from '../../application/search-knowledge.js';
 import { sanitizeContextStrategy, sanitizeSearchMode } from '../../infrastructure/config.js';
 import { clearContextPacks, listContextPacks } from '../../infrastructure/context-packs.js';
@@ -15,12 +16,24 @@ export const registerReadCommands = (program) => {
         .option('-a, --agent <agent>', 'filter by agent memory namespace')
         .option('-l, --limit <limit>', 'maximum results')
         .option('-m, --mode <mode>', 'search mode: fts, semantic or hybrid')
+        .option('--explain', 'include match reasons and score components')
         .option('--json', 'print machine-readable JSON')
         .description('search indexed knowledge')
         .action(async (query, options) => {
         const resolved = await resolveOptions(options);
         const limit = parsePositiveInteger(options.limit ?? String(resolved.defaults.defaultSearchLimit), resolved.defaults.defaultSearchLimit);
         const mode = sanitizeSearchMode(options.mode, resolved.defaults.defaultSearchMode);
+        if (options.explain) {
+            const results = await explainSearchResults(resolved.vault, query, limit, resolved.agent, mode);
+            print(options.json, { query, agent: resolved.agent, limit, mode, results }, () => results
+                .map((result, index) => [
+                `${index + 1}. ${result.title} (${result.path}) score=${result.score.toFixed(3)} mode=${result.searchMode}`,
+                ...result.reasons.map((reason) => `  - ${reason}`),
+                result.content
+            ].join('\n'))
+                .join('\n\n'));
+            return;
+        }
         const results = await searchKnowledge(resolved.vault, query, limit, resolved.agent, mode);
         print(options.json, { query, agent: resolved.agent, limit, mode, results }, () => results
             .map((result, index) => [`${index + 1}. ${result.title} (${result.path}) score=${result.score.toFixed(3)} mode=${result.searchMode}`, result.content].join('\n'))

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

@@ -17,6 +17,7 @@ import { createOfflinePackBackup } from '../../application/offline-pack-backup.j
 import { startServer } from '../../application/start-server.js';
 import { startVaultWatcher } from '../../application/watch-vault.js';
 import { doctorVault, getStats, validateVault } from '../../application/analyze-vault.js';
+import { buildActionableDoctor } from '../../application/operational-workflows.js';
 import { defaultBrainlinkConfig, sanitizeContextStrategy, sanitizeSearchMode } from '../../infrastructure/config.js';
 import { loadBrainlinkConfig } from '../../infrastructure/config.js';
 import { assertVaultAllowed, ensureVault, isBucketVaultPath } from '../../infrastructure/file-system-vault.js';
@@ -1060,10 +1061,22 @@ export const registerWriteCommands = (program) => {
     program
         .command('doctor')
         .option('-v, --vault <vault>', 'vault directory')
+        .option('--actionable', 'include prioritized commands for fixing or improving vault health')
         .option('--json', 'print machine-readable JSON')
         .description('run Brainlink environment and vault checks')
         .action(async (options) => {
         const resolved = await resolveOptions(options);
+        if (options.actionable) {
+            const report = await buildActionableDoctor(resolved.vault);
+            print(options.json, report, () => [
+                ...report.doctor.checks.map((check) => `${check.ok ? 'OK' : 'FAIL'} ${check.name}: ${check.message}`),
+                '',
+                'Actionable next steps:',
+                ...report.actions.map((action) => `- [${action.severity}] ${action.command} (${action.reason})`)
+            ].join('\n'));
+            process.exitCode = report.doctor.ok ? 0 : 1;
+            return;
+        }
         const report = await doctorVault(resolved.vault);
         print(options.json, report, () => {
             const checks = report.checks.map((check) => `${check.ok ? 'OK' : 'FAIL'} ${check.name}: ${check.message}`).join('\n');

package/dist/cli/main.js

@@ -5,6 +5,7 @@ import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { registerAgentCommands } from './commands/agent-commands.js';
 import { registerConfigCommands } from './commands/config-commands.js';
+import { registerPracticalCommands } from './commands/practical-commands.js';
 import { registerReadCommands } from './commands/read-commands.js';
 import { registerVaultCommands } from './commands/vault-commands.js';
 import { registerWriteCommands } from './commands/write-commands.js';
@@ -24,6 +25,7 @@ program
     .version(readPackageVersion());
 registerWriteCommands(program);
 registerReadCommands(program);
+registerPracticalCommands(program);
 registerConfigCommands(program);
 registerVaultCommands(program);
 registerAgentCommands(program);

package/dist/infrastructure/config.js

@@ -11,9 +11,9 @@ export const defaultBrainlinkConfig = {
     defaultAgent: undefined,
     autoIndexOnWrite: true,
     autoCanonicalContextLinks: true,
-    defaultSearchLimit: 10,
-    defaultContextTokens: 2000,
-    defaultContextStrategy: 'rag',
+    defaultSearchLimit: 8,
+    defaultContextTokens: 1500,
+    defaultContextStrategy: 'auto',
     defaultContextCacheTtlMs: 120_000,
     embeddingProvider: 'local',
     defaultSearchMode: 'hybrid',
@@ -46,7 +46,7 @@ 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;
 export const sanitizeSearchMode = (value, fallback = defaultBrainlinkConfig.defaultSearchMode) => typeof value === 'string' && searchModes.has(value) ? value : fallback;
-export const sanitizeContextStrategy = (value, fallback = 'rag') => typeof value === 'string' && contextStrategies.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) : [];
 const sanitizePositiveNumber = (value) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
 const sanitizeIntegerInRange = (value, fallback, minimum, maximum) => {

package/dist/mcp/server.js

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, deleteNoteInputSchema, deleteNoteTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, canonicalizeContextLinksInputSchema, canonicalizeContextLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools.js';
+import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, deleteNoteInputSchema, deleteNoteTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, canonicalizeContextLinksInputSchema, canonicalizeContextLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, doctorActionsInputSchema, doctorActionsTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, explainInputSchema, explainTool, indexInputSchema, indexTool, inboxAddInputSchema, inboxAddTool, inboxListInputSchema, inboxListTool, inboxProcessInputSchema, inboxProcessTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, projectInitInputSchema, projectInitTool, recommendationsInputSchema, recommendationsTool, rememberInputSchema, rememberTool, repairLinksInputSchema, repairLinksTool, searchInputSchema, searchTool, sessionCloseInputSchema, sessionCloseTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, syncInputSchema, syncTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools.js';
 import { getRuntimeVersion } from './runtime.js';
 export const createBrainlinkMcpServer = () => {
     const server = new McpServer({
@@ -43,6 +43,11 @@ export const createBrainlinkMcpServer = () => {
         description: 'Search indexed Brainlink notes with FTS, semantic or hybrid retrieval.',
         inputSchema: searchInputSchema
     }, searchTool);
+    server.registerTool('brainlink_explain', {
+        title: 'Explain Brainlink Search Results',
+        description: 'Explain why indexed notes matched a query, including score components and match reasons.',
+        inputSchema: explainInputSchema
+    }, explainTool);
     server.registerTool('brainlink_dedupe', {
         title: 'Detect Duplicate Notes',
         description: 'Detect possible duplicate notes using exact content hash and semantic similarity scoring.',
@@ -58,6 +63,26 @@ 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_remember', {
+        title: 'Capture Assisted Brainlink Memory',
+        description: 'Capture durable memory with inferred title, tags and Context Links. Supports dry-run preview before writing.',
+        inputSchema: rememberInputSchema
+    }, rememberTool);
+    server.registerTool('brainlink_inbox_add', {
+        title: 'Add Brainlink Inbox Item',
+        description: 'Capture a quick untriaged memory item tagged for later processing.',
+        inputSchema: inboxAddInputSchema
+    }, inboxAddTool);
+    server.registerTool('brainlink_inbox_list', {
+        title: 'List Brainlink Inbox Items',
+        description: 'List quick untriaged memory items from the vault.',
+        inputSchema: inboxListInputSchema
+    }, inboxListTool);
+    server.registerTool('brainlink_inbox_process', {
+        title: 'Process Brainlink Inbox Items',
+        description: 'Suggest titles, tags and Context Links for untriaged inbox items.',
+        inputSchema: inboxProcessInputSchema
+    }, inboxProcessTool);
     server.registerTool('brainlink_delete_note', {
         title: 'Delete Brainlink Note',
         description: 'Delete a durable Markdown note from the vault after explicit confirmation. Select by title or path; reindexes by default.',
@@ -93,6 +118,11 @@ export const createBrainlinkMcpServer = () => {
         description: 'Read indexed vault statistics, including node, edge and tag totals.',
         inputSchema: statsInputSchema
     }, statsTool);
+    server.registerTool('brainlink_doctor_actions', {
+        title: 'Get Actionable Brainlink Doctor Plan',
+        description: 'Run vault readiness checks and return prioritized executable next actions.',
+        inputSchema: doctorActionsInputSchema
+    }, doctorActionsTool);
     server.registerTool('brainlink_validate', {
         title: 'Validate Brainlink Vault',
         description: 'Validate indexed graph health, including broken links and orphan notes.',
@@ -118,10 +148,30 @@ export const createBrainlinkMcpServer = () => {
         description: 'List unresolved indexed wiki links.',
         inputSchema: brokenLinksInputSchema
     }, brokenLinksTool);
+    server.registerTool('brainlink_suggest_links', {
+        title: 'Suggest Brainlink Links',
+        description: 'Suggest Context Links for content or likely fixes for unresolved wiki links.',
+        inputSchema: suggestLinksInputSchema
+    }, suggestLinksTool);
+    server.registerTool('brainlink_repair_links', {
+        title: 'Repair Brainlink Broken Links',
+        description: 'Repair unresolved wiki links by retargeting safe high-confidence matches or creating placeholder target notes.',
+        inputSchema: repairLinksInputSchema
+    }, repairLinksTool);
     server.registerTool('brainlink_orphans', {
         title: 'List Brainlink Orphans',
         description: 'List indexed notes without incoming or outgoing graph links.',
         inputSchema: orphansInputSchema
     }, orphansTool);
+    server.registerTool('brainlink_session_close', {
+        title: 'Write Brainlink Session Handoff',
+        description: 'Write or preview a session handoff note with vault health and workspace git status.',
+        inputSchema: sessionCloseInputSchema
+    }, sessionCloseTool);
+    server.registerTool('brainlink_project_init', {
+        title: 'Initialize Project Memory',
+        description: 'Seed Brainlink memory from project documents such as AGENTS.md, README.md and architecture docs.',
+        inputSchema: projectInitInputSchema
+    }, projectInitTool);
     return server;
 };

package/dist/mcp/tools.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { basename, extname } from 'node:path';
+import { basename, extname, resolve } from 'node:path';
 import { z } from 'zod';
 import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../application/analyze-vault.js';
 import { addNoteWithMetadata } from '../application/add-note.js';
@@ -9,7 +9,11 @@ import { deleteNote } from '../application/delete-note.js';
 import { resolveDuplicateNotes, scanDuplicateNotes } from '../application/dedupe-notes.js';
 import { getGraph } from '../application/get-graph.js';
 import { getGraphContexts } from '../application/get-graph-contexts.js';
+import { addInboxItem, listInboxItems, processInboxItems } from '../application/inbox.js';
 import { indexVault } from '../application/index-vault.js';
+import { buildRememberSuggestion, explainSearchResults, suggestBrokenLinkFixes, suggestContextLinks } from '../application/memory-suggestions.js';
+import { buildActionableDoctor, closeSession, initializeProjectMemory } from '../application/operational-workflows.js';
+import { repairBrokenLinks } from '../application/repair-broken-links.js';
 import { searchKnowledge } from '../application/search-knowledge.js';
 import { resolveAgentRuntimeDefaults, sanitizeContextStrategy, sanitizeSearchMode } from '../infrastructure/config.js';
 import { clearContextPacks, listContextPacks } from '../infrastructure/context-packs.js';
@@ -249,6 +253,13 @@ export const searchInputSchema = {
     query: z.string().min(1).describe('Search query.'),
     limit: optionalPositiveInteger().describe('Maximum result count.')
 };
+export const explainInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    ...searchModeInput,
+    query: z.string().min(1).describe('Search query to explain.'),
+    limit: optionalPositiveInteger().describe('Maximum result count.')
+};
 export const addNoteInputSchema = {
     ...vaultInput,
     title: z.string().min(1).describe('Markdown note title.'),
@@ -264,6 +275,34 @@ export const addNoteInputSchema = {
         .optional()
         .describe('Automatically add canonical Context Links to the inferred visual context hub. Defaults to Brainlink config.')
 };
+export const rememberInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    title: z.string().min(1).optional().describe('Optional note title. When omitted, Brainlink infers it from content.'),
+    content: z.string().min(1).describe('Memory content to capture as a durable Markdown note.'),
+    tags: z.array(z.string()).optional().default([]).describe('Extra tags to include.'),
+    links: z.array(z.string()).optional().default([]).describe('Explicit Context Links to include.'),
+    linkLimit: positiveInteger(5).describe('Maximum suggested Context Links to include.'),
+    dryRun: z.boolean().optional().default(false).describe('Preview inferred note without writing it.'),
+    allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after writing note.')
+};
+export const inboxAddInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    content: z.string().min(1).describe('Quick memory content to store as an untriaged inbox note.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after writing inbox item.')
+};
+export const inboxListInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    limit: positiveInteger(20).describe('Maximum inbox items to return.')
+};
+export const inboxProcessInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    limit: positiveInteger(10).describe('Maximum inbox items to inspect.')
+};
 export const deleteNoteInputSchema = {
     ...vaultInput,
     ...agentInput,
@@ -313,6 +352,10 @@ export const validateInputSchema = {
     ...vaultInput,
     ...agentInput
 };
+export const doctorActionsInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
 export const graphInputSchema = {
     ...vaultInput,
     ...agentInput
@@ -325,6 +368,22 @@ export const brokenLinksInputSchema = {
     ...vaultInput,
     ...agentInput
 };
+export const suggestLinksInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    content: z.string().min(1).optional().describe('Content to inspect for Context Link suggestions. Required unless broken=true.'),
+    broken: z.boolean().optional().default(false).describe('Suggest fixes for unresolved wiki links instead of content links.'),
+    limit: positiveInteger(5).describe('Maximum suggestions to return.')
+};
+export const repairLinksInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    dryRun: z.boolean().optional().default(false).describe('Preview repairs without writing files.'),
+    createMissing: z.boolean().optional().default(true).describe('Create placeholder notes for unresolved targets without a safe existing match.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after repairs.'),
+    minScore: z.number().min(0).max(1).optional().default(0.88).describe('Minimum similarity score for automatic retargeting.'),
+    margin: z.number().min(0).max(1).optional().default(0.12).describe('Minimum score gap between first and second candidate.')
+};
 export const orphansInputSchema = {
     ...vaultInput,
     ...agentInput
@@ -375,6 +434,19 @@ export const versionInputSchema = {
     ...vaultInput,
     ...agentInput
 };
+export const sessionCloseInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    content: z.string().min(1).optional().describe('Optional extra session notes to include in the handoff.'),
+    cwd: z.string().min(1).optional().describe('Workspace path used for git status. Defaults to current process working directory.'),
+    dryRun: z.boolean().optional().default(false).describe('Preview handoff note without writing it.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after writing handoff.')
+};
+export const projectInitInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    projectPath: z.string().min(1).optional().describe('Project path to inspect. Defaults to current process working directory.')
+};
 export const recommendationsInputSchema = {
     ...vaultInput,
     ...agentInput,
@@ -472,6 +544,30 @@ export const searchTool = async (input) => {
         results
     });
 };
+export const explainTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_explain');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_explain');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const limit = input.limit ?? context.defaults.defaultSearchLimit;
+    const results = await explainSearchResults(context.vault, input.query, limit, context.agent, mode);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        query: input.query,
+        limit,
+        mode,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        results
+    });
+};
 export const addNoteTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const shouldIndex = isTruthy(input.autoIndex);
@@ -504,6 +600,75 @@ export const addNoteTool = async (input) => {
         ...(index ? { index } : {})
     });
 };
+export const rememberTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const suggestion = await buildRememberSuggestion({
+        vaultPath: context.vault,
+        content: input.content,
+        agentId: context.agent,
+        title: input.title,
+        tags: input.tags,
+        links: input.links,
+        linkLimit: input.linkLimit
+    });
+    if (input.dryRun) {
+        return jsonResult({
+            dryRun: true,
+            vault: context.vault,
+            agent: context.agent,
+            suggestion
+        });
+    }
+    const added = await addNoteWithMetadata(context.vault, suggestion.title, suggestion.content, context.agent, {
+        allowSensitive: input.allowSensitive,
+        autoContextLinks: false
+    });
+    const index = input.autoIndex ? await indexVault(context.vault) : undefined;
+    return jsonResult({
+        dryRun: false,
+        vault: context.vault,
+        agent: context.agent,
+        suggestion,
+        path: added.path,
+        ...(index ? { index } : {})
+    });
+};
+export const inboxAddTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await addInboxItem({
+        vaultPath: context.vault,
+        content: input.content,
+        agentId: context.agent,
+        autoIndex: input.autoIndex
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...result
+    });
+};
+export const inboxListTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const items = await listInboxItems(context.vault, input.limit);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        items
+    });
+};
+export const inboxProcessTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const items = await processInboxItems({
+        vaultPath: context.vault,
+        agentId: context.agent,
+        limit: input.limit
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        items
+    });
+};
 export const deleteNoteTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const result = await deleteNote(context.vault, {
@@ -613,6 +778,25 @@ export const validateTool = async (input) => {
         ...validation
     });
 };
+export const doctorActionsTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_doctor_actions');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_doctor_actions');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const report = await buildActionableDoctor(context.vault);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        ...report
+    });
+};
 export const graphTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const readiness = await ensureBootstrapReady(context, input, 'brainlink_graph');
@@ -670,6 +854,56 @@ export const brokenLinksTool = async (input) => {
         brokenLinks
     });
 };
+export const suggestLinksTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_suggest_links');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_suggest_links');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    if (input.broken) {
+        const suggestions = await suggestBrokenLinkFixes(context.vault, context.agent, input.limit);
+        return jsonResult({
+            vault: context.vault,
+            agent: context.agent,
+            mode: 'broken-links',
+            ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+            ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+            suggestions
+        });
+    }
+    if (!input.content || input.content.trim().length === 0) {
+        throw new Error('content is required when broken=false.');
+    }
+    const suggestions = await suggestContextLinks(context.vault, input.content, context.agent, input.limit);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        mode: 'content',
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        suggestions
+    });
+};
+export const repairLinksTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await repairBrokenLinks(context.vault, {
+        agentId: context.agent,
+        dryRun: input.dryRun,
+        createMissing: input.createMissing,
+        autoIndex: input.autoIndex,
+        minScore: input.minScore,
+        margin: input.margin
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...result
+    });
+};
 export const orphansTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const readiness = await ensureBootstrapReady(context, input, 'brainlink_orphans');
@@ -924,6 +1158,35 @@ export const versionTool = async (input) => {
         runtime: getRuntimeMetadata()
     });
 };
+export const sessionCloseTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await closeSession({
+        vaultPath: context.vault,
+        agentId: context.agent,
+        cwd: resolve(input.cwd ?? process.cwd()),
+        content: input.content,
+        write: input.dryRun !== true,
+        autoIndex: input.autoIndex
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        dryRun: input.dryRun === true,
+        ...result
+    });
+};
+export const projectInitTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await initializeProjectMemory({
+        vaultPath: context.vault,
+        projectPath: resolve(input.projectPath ?? process.cwd()),
+        agentId: context.agent
+    });
+    return jsonResult({
+        agent: context.agent,
+        ...result
+    });
+};
 export const recommendationsTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const policy = await getBootstrapPolicy();

package/docs/AGENT_USAGE.md

@@ -585,7 +585,7 @@ Context assembly uses middle-out ordering inside each note: the highest-scoring
 ### Build Agent Context
 
 ```bash
-blink context "how does authentication work?" --vault ./vault --limit 12 --tokens 2000
+blink context "how does authentication work?" --vault ./vault --limit 8 --tokens 1500
 blink context "how does authentication work?" --vault ./vault --json
 blink context "how does authentication work?" --vault ./vault --agent coding-agent --json
 blink context "how does authentication work?" --vault ./vault --agent coding-agent --mode hybrid --json
@@ -596,7 +596,7 @@ blink context-packs --vault ./vault --stale --clear
 ```
 
 This returns a Markdown context package optimized for prompt injection.
-The default strategy is configured by `defaultContextStrategy` and starts as `rag`. Use `--strategy cag` when the same agent/task context should be served from a persisted context pack when the index and volatile-memory signatures are unchanged. Use `--strategy auto` when Brainlink should use CAG on fresh pack hits and RAG otherwise. Context responses include `cache`, `metrics`, `requestedStrategy` and `recommendedStrategy` metadata. CAG packs live under `.brainlink/context-packs` and are rebuildable derived artifacts.
+The default strategy is configured by `defaultContextStrategy` and starts as `auto`, so repeated stable context can reuse fresh CAG packs while misses fall back to RAG and refresh a pack for later calls. Use `--strategy cag` when the same agent/task context must be served from a persisted context pack when the index and volatile-memory signatures are unchanged. Use `--strategy rag` when fresh retrieval is required. Context responses include `cache`, `metrics`, `requestedStrategy` and `recommendedStrategy` metadata. CAG packs live under `.brainlink/context-packs` and are rebuildable derived artifacts.
 
 ### Inspect Links
 
@@ -724,9 +724,14 @@ Available MCP tools:
 - `brainlink_context`
 - `brainlink_context_packs`
 - `brainlink_search`
+- `brainlink_explain`
 - `brainlink_dedupe`
 - `brainlink_resolve_duplicate`
 - `brainlink_add_note`
+- `brainlink_remember`
+- `brainlink_inbox_add`
+- `brainlink_inbox_list`
+- `brainlink_inbox_process`
 - `brainlink_delete_note`
 - `brainlink_add_file`
 - `brainlink_canonicalize_context_links`
@@ -734,14 +739,20 @@ Available MCP tools:
 - `brainlink_volatile_clear`
 - `brainlink_index`
 - `brainlink_stats`
+- `brainlink_doctor_actions`
 - `brainlink_validate`
 - `brainlink_sync`
 - `brainlink_graph`
 - `brainlink_graph_contexts`
 - `brainlink_broken_links`
+- `brainlink_suggest_links`
+- `brainlink_repair_links`
 - `brainlink_orphans`
+- `brainlink_session_close`
+- `brainlink_project_init`
 
 Recommended start of every memory-dependent task: call `brainlink_bootstrap` first, then `brainlink_context`. By default, Brainlink enforces context-first for non-context MCP reads (`enforceContextFirst=true`), and also enforces bootstrap with auto-bootstrap on reads when state is missing or stale (`autoBootstrapOnRead=true`).
+MCP is expected to stay functionally aligned with practical Brainlink CLI workflows whenever the operation is safe and useful for tool clients.
 MCP startup also bootstraps the configured default vault/agent automatically (`autoBootstrapOnStartup=true`), so sessions start warm without manual calls.
 If `autoBootstrapOnRead` or `enforceContextFirst` are disabled through `brainlink_policy`, behavior is relaxed accordingly; otherwise read tools return preflight-required responses when requirements are not satisfied.
 `brainlink_bootstrap`, `brainlink_policy` and preflight responses include structured `nextActions` so clients can continue tool flows automatically.
@@ -767,8 +778,8 @@ GET  /api/graph-layout
 GET  /api/graph-view?x=<x>&y=<y>&w=<width>&h=<height>&scale=<scale>
 GET  /api/graph-node?id=<node-id>
 GET  /api/graph-filter?q=<query>&limit=<n>
-GET  /api/search?q=<query>&limit=10&mode=hybrid
-GET  /api/context?q=<query>&limit=12&tokens=2000&mode=hybrid
+GET  /api/search?q=<query>&limit=8&mode=hybrid
+GET  /api/context?q=<query>&limit=8&tokens=1500&mode=hybrid
 GET  /api/links
 GET  /api/backlinks?title=<title>
 GET  /api/stats

package/docs/QUICKSTART.md

@@ -50,7 +50,7 @@ Optional per-agent retrieval defaults in `brainlink.config.json`:
     "coding-agent": {
       "defaultSearchMode": "semantic",
       "defaultSearchLimit": 8,
-      "defaultContextTokens": 2400,
+      "defaultContextTokens": 1500,
       "defaultContextStrategy": "auto",
       "defaultContextCacheTtlMs": 120000
     }
@@ -75,6 +75,15 @@ blink context "what should I know before this task?" --mode hybrid --json
 
 ```bash
 blink add "Architecture Decision" --content "Use explicit [[Bounded Context]] links and #tags. #architecture #decision"
+blink remember --content "Use explicit [[Bounded Context]] links and #tags. #architecture #decision"
+```
+
+Use `remember` when you want Brainlink to infer a title, tags and Context Links. Use `inbox add` for quick capture, then `inbox process` to triage later.
+
+```bash
+blink inbox add --content "Quick note to classify later"
+blink inbox process --json
+blink session-close --content "Validated the current task"
 ```
 
 ## 6) Validate Health
@@ -82,7 +91,11 @@ blink add "Architecture Decision" --content "Use explicit [[Bounded Context]] li
 ```bash
 blink validate
 blink doctor
+blink doctor --actionable
 blink stats --extended --json
+blink suggest-links --broken
+blink repair-links
+blink search "architecture" --explain
 ```
 
 ## 7) Migrate Existing Memory (Optional)

package/package.json

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