@andespindola/brainlink 1.0.2 → 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

@@ -430,6 +430,17 @@ blink db-import --vault ./team-vault --db ./legacy/brainlink.db --table legacy_n
 Without `--db`, Brainlink auto-detects common legacy database paths.
 Use `--agent` to force namespace, `--limit` for staged migration, `--dry-run` to preview writes, and `--no-index` to postpone indexing.
 
+### Import A Document File
+
+```bash
+blink import-file ./report.pdf --vault ./team-vault
+blink import-file ./report.pdf --vault ./team-vault --agent coding-agent
+blink import-file ./report.pdf --vault ./team-vault --title "Quarterly Report"
+```
+
+`import-file` converts a source document with Docling, writes the converted Markdown as a durable note, and indexes the result by default.
+The `docling` executable must be installed and available in `PATH`. The graph UI exposes the same import path through its upload modal.
+
 ### Install Agent Integration
 
 ```bash
@@ -636,7 +647,7 @@ blink server --vault ./vault --host 127.0.0.1 --port 4321
 blink server --vault ./vault --host 127.0.0.1 --port 4321 --no-open
 ```
 
-This starts a local frontend for inspecting the knowledge graph.
+This starts a local frontend for inspecting the knowledge graph and importing document files into the selected vault.
 By default it tries to open the graph in a native desktop GUI window:
 - macOS: Swift + WebKit
 - Windows: PowerShell WinForms WebBrowser
@@ -713,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`
@@ -723,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.
@@ -764,9 +786,10 @@ GET  /api/stats
 GET  /api/broken-links
 GET  /api/orphans
 GET  /api/validate
+POST /api/import-file
 ```
 
-The HTTP API is read-only. Use the CLI for writes and indexing.
+The HTTP API is read-oriented, with `POST /api/import-file` reserved for the local upload modal. Use the CLI for other writes and indexing.
 
 Indexing writes private encrypted search packs at `.brainlink/search-packs/*.blpk` for resilient retrieval and portability.
 Pack search now uses compressed-space prefiltering (token bloom index per pack) before decrypting/reading pack payloads.

package/docs/ARCHITECTURE.md

@@ -165,9 +165,10 @@ server command
   -> /api/graph-layout derives a cauliflower hub layout from indexed graph data
   -> optional context query narrows the layout to a segment-scoped cauliflower subgraph
   -> browser renders graph canvas
+  -> /api/import-file converts uploaded documents and writes Markdown notes
 ```
 
-The graph UI is intentionally read-only. Markdown remains the write interface and index artifacts remain derived data.
+The graph UI is primarily an inspection surface. Its upload modal is the narrow write path: uploaded files are converted to Markdown notes through the same application import use case used by the CLI. Markdown remains the source of truth and index artifacts remain derived data.
 The cauliflower layout is a visual projection over the indexed graph. Indexed weighted wiki-link edges remain unchanged for backlinks, ranking, graph reads and context traversal. The browser layout renders a simplified hierarchy instead: primary hub -> segment hubs -> local context nodes. This avoids unstable cross-context visual edges while preserving the real relationship model outside the render layer. Zoomed-out graph streams summarize those lobes as segment clusters before revealing individual nodes on zoom-in.
 
 ## HTTP API Flow
@@ -181,7 +182,7 @@ HTTP request
 ```
 
 The HTTP API is local-first and unauthenticated. It is meant for local agents, browser UI, and development workflows.
-The route adapter caches generated frontend assets (`/`, `/styles.css`, `/app.js`, `/app-worker.js`) and graph-layout JSON payloads by layout signature to reduce repeated CPU and allocation pressure during navigation.
+The route adapter caches generated frontend assets (`/`, `/styles.css`, `/app.js`, `/app-worker.js`) and graph-layout JSON payloads by layout signature to reduce repeated CPU and allocation pressure during navigation. File upload conversion is intentionally routed through the import-file use case instead of writing vault files directly in the HTTP adapter.
 
 ## MCP Flow
 

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