@andespindola/brainlink 1.0.3 → 1.0.4

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

@@ -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.

package/docs/QUICKSTART.md

@@ -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.4",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",