@andespindola/brainlink 1.6.12 → 1.6.14

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.6.14
+
+- **Images in notes and context.** New `brainlink_add_image` MCP tool (and application use-case) stores an image inside the vault (content-addressed, encrypted at rest when the vault is), and can attach it to a note that embeds it. Markdown image references (`![[image.png]]` embeds and `![alt](path)`) are now extracted per document without leaking into wiki-link graph edges, and image descriptors (path, mime, alt) are surfaced alongside text in retrieved context — never the raw bytes. Additive: image-free notes are unchanged.
+
+## 1.6.13
+
+- **Admin impersonation for the exposed graph.** New opt-in `GET /api/admin-session?token=<jwt>` on `brainlink server --expose`: a control-plane can open a tenant's graph authenticated WITHOUT the web password by presenting a short-lived HS256 JWT signed with `BRAINLINK_ADMIN_SESSION_SECRET` (claims bind `sub`/`aud` to the server's web user; `exp` ≤ 600s). Off by default — when the secret is unset the endpoint 404s and nothing changes. On success it mints the same session cookie as `/api/login` and redirects to `/`.
+
 ## 1.6.12
 
 - **Wiki links keep a `#` that is part of the title.** A link target such as `[[note (PR #34)]]` was truncated at the `#` — the parser always treated `#` as the start of a heading anchor (`[[Note#Heading]]`) — so the link resolved to a non-existent `note (PR ` title and surfaced as a broken link. A `#` is now treated as a heading anchor only when it directly follows the note name with no whitespace before it; a `#` preceded by a space is kept as part of the title. Existing `[[Note#Heading]]` anchor links keep resolving to `Note`.

package/dist/application/add-image.js

@@ -0,0 +1,67 @@
+import { basename, extname } from 'node:path';
+import { createStableId } from '../domain/ids.js';
+import { imageMimeForRef } from '../domain/image-refs.js';
+import { sanitizeAgentId, sharedAgentId } from '../domain/agents.js';
+import { ensureVault, writeVaultBinaryFile } from '../infrastructure/file-system-vault.js';
+import { encryptVaultContent, readOrCreateVaultKey } from '../infrastructure/vault-crypto.js';
+import { vaultEncryptionEnabled } from './vault-encryption.js';
+import { addNoteWithMetadata } from './add-note.js';
+// Images live under a dedicated, git-ignored assets tree inside the vault's
+// `.brainlink` directory (already secured to 0o700). This keeps binary bytes
+// out of the Markdown/graph git-versioning flow while still being addressable by
+// a stable vault-relative path referenced from notes. When the vault is
+// encrypted at rest, the bytes are stored as ciphertext (a `.enc` payload) so
+// nothing readable is written to disk.
+const assetsRoot = '.brainlink/assets';
+const knownImageExtensions = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'bmp', 'avif', 'heic']);
+const extensionForImage = (sourceName, mimeType) => {
+    const fromName = sourceName ? extname(sourceName).replace(/^\./, '').toLowerCase() : '';
+    if (knownImageExtensions.has(fromName)) {
+        return fromName;
+    }
+    const fromMime = mimeType?.split('/')[1]?.toLowerCase();
+    if (fromMime && knownImageExtensions.has(fromMime === 'jpeg' ? 'jpg' : fromMime)) {
+        return fromMime === 'jpeg' ? 'jpg' : fromMime;
+    }
+    return 'png';
+};
+const buildImageNoteContent = (embed) => [embed, '', '#image'].join('\n');
+// Persist an image into the vault and return its stable vault-relative path plus
+// an embed string a note can reference. Optionally creates a note that embeds
+// the image so retrieval can surface it in context.
+export const addImage = async (input) => {
+    if (input.data.byteLength === 0) {
+        throw new Error('Refusing to store an empty image.');
+    }
+    const vaultRoot = await ensureVault(input.vaultPath);
+    const agentId = sanitizeAgentId(input.agentId ?? sharedAgentId);
+    const mimeType = input.mimeType ?? imageMimeForRef(input.sourceName ?? '') ?? 'image/png';
+    const extension = extensionForImage(input.sourceName, mimeType);
+    const digest = createStableId(input.data.toString('base64'));
+    const assetPath = `${assetsRoot}/${agentId}/${digest}.${extension}`;
+    const encrypted = await vaultEncryptionEnabled();
+    const storedPath = encrypted ? `${assetPath}.enc` : assetPath;
+    const payload = encrypted
+        ? encryptVaultContent(await readOrCreateVaultKey(vaultRoot), input.data)
+        : input.data;
+    const absolutePath = await writeVaultBinaryFile(input.vaultPath, storedPath, payload);
+    const alt = input.alt?.trim() || basename(input.sourceName ?? assetPath);
+    const embed = `![${alt}](${assetPath})`;
+    const note = input.noteTitle
+        ? await addNoteWithMetadata(input.vaultPath, input.noteTitle, buildImageNoteContent(embed), agentId, {
+            autoContextLinks: input.autoContextLinks,
+            context: input.noteContext
+        })
+        : undefined;
+    return {
+        assetPath,
+        absolutePath,
+        mimeType,
+        bytes: input.data.byteLength,
+        alt,
+        encrypted,
+        embed,
+        agentId,
+        ...(note ? { note } : {})
+    };
+};

package/dist/application/server/admin-session.js

@@ -0,0 +1,125 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+// Admin impersonation for the exposed graph server.
+//
+// An external control-plane (the brainlink-saas admin) can open a tenant's
+// graph authenticated WITHOUT the tenant's web password by redirecting the
+// admin's browser to `GET /api/admin-session?token=<jwt>`. The token is a
+// short-lived, compact HS256 JWT that the server verifies against a shared
+// secret. This is OPT-IN and OFF by default: with no secret configured the
+// endpoint is disabled and nothing about the existing auth changes.
+//
+// Token contract (so the SaaS can mint compatible tokens):
+//   - Format: compact JWT `base64url(header).base64url(payload).base64url(sig)`.
+//   - Header:  { "alg": "HS256", "typ": "JWT" } — alg MUST be HS256.
+//   - Payload claims:
+//       - `sub` and/or `aud`: MUST equal the server's configured web user
+//         (BRAINLINK_WEB_USER). At least one must be present and match — this
+//         binds the token to THIS tenant so it cannot be replayed elsewhere.
+//       - `iat`: issued-at, seconds since epoch.
+//       - `exp`: expiry, seconds since epoch. REQUIRED, must be in the future,
+//         and MUST be within `maxTtlSeconds` (600s) of `iat` — long-lived
+//         tokens are rejected server-side.
+//   - Signature: HMAC-SHA256 over `base64url(header).base64url(payload)` using
+//     the raw UTF-8 bytes of BRAINLINK_ADMIN_SESSION_SECRET.
+export const ADMIN_SESSION_SECRET_ENV = 'BRAINLINK_ADMIN_SESSION_SECRET';
+// Server-side cap on how far in the future an admin token may be valid. A token
+// whose lifetime (exp - iat) exceeds this is rejected regardless of signature.
+export const adminSessionMaxTtlSeconds = 600;
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
+// The signing secret for admin impersonation, or null when the feature is
+// disabled (no secret configured). Read from env exactly like the other
+// exposed-server auth material, so no new wiring through the CLI is required.
+export const getAdminSessionSecret = () => {
+    const secret = process.env[ADMIN_SESSION_SECRET_ENV]?.trim();
+    return isNonEmptyString(secret) ? secret : null;
+};
+const constantTimeEqual = (a, b) => {
+    const actual = Buffer.from(a, 'utf8');
+    const expected = Buffer.from(b, 'utf8');
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+};
+const parseHeader = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return null;
+    }
+    const candidate = value;
+    return isNonEmptyString(candidate.alg) ? { alg: candidate.alg } : null;
+};
+const parseClaims = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return null;
+    }
+    const candidate = value;
+    if (typeof candidate.iat !== 'number' || typeof candidate.exp !== 'number') {
+        return null;
+    }
+    if (!Number.isFinite(candidate.iat) || !Number.isFinite(candidate.exp)) {
+        return null;
+    }
+    const sub = isNonEmptyString(candidate.sub) ? candidate.sub : undefined;
+    const aud = isNonEmptyString(candidate.aud) ? candidate.aud : undefined;
+    return {
+        ...(sub === undefined ? {} : { sub }),
+        ...(aud === undefined ? {} : { aud }),
+        iat: candidate.iat,
+        exp: candidate.exp
+    };
+};
+const decodeSegment = (segment) => {
+    const json = Buffer.from(segment, 'base64url').toString('utf8');
+    return JSON.parse(json);
+};
+// Verify a compact HS256 admin-session token. Returns true only when the
+// signature is valid, the algorithm is HS256, the token is bound to
+// `expectedUser` via `sub`/`aud`, it is unexpired, and its lifetime is within
+// the server-side cap. Never throws and never leaks token/secret detail.
+export const verifyAdminSessionToken = (token, secret, expectedUser, nowMs, maxTtlSeconds = adminSessionMaxTtlSeconds) => {
+    try {
+        if (!isNonEmptyString(token) || !isNonEmptyString(secret) || !isNonEmptyString(expectedUser)) {
+            return false;
+        }
+        const parts = token.split('.');
+        if (parts.length !== 3) {
+            return false;
+        }
+        const [headerB64, payloadB64, signature] = parts;
+        if (!isNonEmptyString(headerB64) || !isNonEmptyString(payloadB64) || !isNonEmptyString(signature)) {
+            return false;
+        }
+        const header = parseHeader(decodeSegment(headerB64));
+        if (header === null || header.alg !== 'HS256') {
+            return false;
+        }
+        const expectedSignature = createHmac('sha256', secret)
+            .update(`${headerB64}.${payloadB64}`)
+            .digest('base64url');
+        if (!constantTimeEqual(signature, expectedSignature)) {
+            return false;
+        }
+        const claims = parseClaims(decodeSegment(payloadB64));
+        if (claims === null) {
+            return false;
+        }
+        // Bind the token to this server's web user: at least one of sub/aud must be
+        // present and equal to the configured user, so a token minted for one tenant
+        // cannot authenticate a different tenant's server.
+        const audienceMatches = (claims.sub !== undefined && constantTimeEqual(claims.sub, expectedUser)) ||
+            (claims.aud !== undefined && constantTimeEqual(claims.aud, expectedUser));
+        if (!audienceMatches) {
+            return false;
+        }
+        // exp must be present, in the future, and the token lifetime must not exceed
+        // the server-side cap (reject long-lived tokens even if correctly signed).
+        const nowSeconds = Math.floor(nowMs / 1000);
+        if (claims.exp <= nowSeconds) {
+            return false;
+        }
+        if (claims.exp - claims.iat > maxTtlSeconds) {
+            return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+};

package/dist/application/server/routes.js

@@ -24,6 +24,7 @@ import { createClientWorkerJs } from '../frontend/client-worker-js.js';
 import { createClientRenderWorkerJs } from '../frontend/client-render-worker-js.js';
 import { createLoginPageHtml, createChangePasswordPageHtml } from '../frontend/login-page.js';
 import { buildClearSessionCookie, buildSessionSetCookie, changeWebPassword, createSessionToken, parseCookies, resolveWebAuth, SESSION_COOKIE_NAME, verifySessionToken, verifyWebPassword } from './web-auth.js';
+import { getAdminSessionSecret, verifyAdminSessionToken } from './admin-session.js';
 import { getGraphVersion } from './graph-version.js';
 import { readAuthStatus, readEditableSettings, updateEditableSettings } from './settings-store.js';
 import { connectVaultRemote, ensureDeployKey, readVersioningStatus } from './versioning.js';
@@ -124,6 +125,26 @@ const runAuthGate = async (request, url) => {
         }
         return createResponse(createJsonResponse({ error: 'Invalid username or password' }), 401, contentTypes['.json']);
     }
+    // Admin impersonation (opt-in, off by default). When BRAINLINK_ADMIN_SESSION_SECRET
+    // is configured, an external control-plane can open this tenant's graph by
+    // redirecting the admin's browser to /api/admin-session?token=<jwt>. A valid,
+    // short-lived, audience-bound token mints a normal session cookie — identical
+    // to /api/login — and 302-redirects to the graph. Without the secret the
+    // endpoint is disabled and indistinguishable from any other unknown path.
+    if (isReadMethod(request) && url.pathname === '/api/admin-session') {
+        const secret = getAdminSessionSecret();
+        if (secret === null) {
+            return createResponse(createJsonResponse({ error: 'Not found' }), 404, contentTypes['.json']);
+        }
+        const token = url.searchParams.get('token') ?? '';
+        if (!verifyAdminSessionToken(token, secret, auth.user, Date.now())) {
+            return createResponse(createJsonResponse({ error: 'Unauthorized' }), 401, contentTypes['.json']);
+        }
+        const sessionToken = createSessionToken(auth, sessionTtlMs, Date.now());
+        return withHeaders(redirectResponse('/'), {
+            'set-cookie': buildSessionSetCookie(sessionToken, { secure: requestIsSecure(request), ttlMs: sessionTtlMs })
+        });
+    }
     if (request.method === 'POST' && url.pathname === '/api/logout') {
         return withHeaders(createResponse(createJsonResponse({ ok: true }), 200, contentTypes['.json']), {
             'set-cookie': buildClearSessionCookie()

package/dist/domain/context.js

@@ -1,3 +1,4 @@
+import { extractImageRefs } from './image-refs.js';
 import { middleOutIndices } from './middle-out.js';
 import { estimateTokenCount } from './tokens.js';
 import { orderByMaximalMarginalRelevance } from './diversity.js';
@@ -27,6 +28,22 @@ const estimateFramingTokens = (result) => {
     return estimateTokenCount(framing) + sectionSeparatorTokens;
 };
 const estimateSectionTokens = (result) => contentTokens(result) + estimateFramingTokens(result);
+// Build a context section from a retrieval result, attaching image descriptors
+// derived from the (possibly truncated) content that will actually be rendered.
+// Descriptors travel alongside the text so a client can fetch/render the image
+// without the raw bytes ever being inlined into the context.
+const toSection = (result, content) => {
+    const images = extractImageRefs(content);
+    return {
+        title: result.title,
+        path: result.path,
+        content,
+        score: result.score,
+        searchMode: result.searchMode,
+        tags: result.tags,
+        ...(images.length > 0 ? { images } : {})
+    };
+};
 const byScore = (left, right) => right.score - left.score || left.title.localeCompare(right.title);
 const byOrdinal = (left, right) => (left.chunkOrdinal ?? Number.MAX_SAFE_INTEGER) - (right.chunkOrdinal ?? Number.MAX_SAFE_INTEGER);
 const middleOutDocumentResults = (results) => {
@@ -72,17 +89,7 @@ export const selectContextSections = (results, maxTokens) => {
                 break;
             }
             usedTokens += tokenCost;
-            sections = [
-                ...sections,
-                {
-                    title: result.title,
-                    path: result.path,
-                    content: result.content,
-                    score: result.score,
-                    searchMode: result.searchMode,
-                    tags: result.tags
-                }
-            ];
+            sections = [...sections, toSection(result, result.content)];
             seenChunks = new Set([...seenChunks, result.chunkId]);
         }
         return {
@@ -106,16 +113,7 @@ export const selectContextSections = (results, maxTokens) => {
     const topResult = [...results].sort(byScore)[0];
     const framingTokens = estimateFramingTokens(topResult);
     const contentTokenBudget = maxTokens - headerReserveTokens - framingTokens;
-    return [
-        {
-            title: topResult.title,
-            path: topResult.path,
-            content: truncateToTokens(topResult.content, contentTokenBudget),
-            score: topResult.score,
-            searchMode: topResult.searchMode,
-            tags: topResult.tags
-        }
-    ];
+    return [toSection(topResult, truncateToTokens(topResult.content, contentTokenBudget))];
 };
 export const formatContextPackage = (query, sections) => {
     const body = sections
@@ -125,6 +123,11 @@ export const formatContextPackage = (query, sections) => {
         section.tags.length > 0 ? `Tags: ${section.tags.map((tag) => `#${tag}`).join(' ')}` : null,
         `Score: ${section.score.toFixed(3)}`,
         `Mode: ${section.searchMode}`,
+        section.images && section.images.length > 0
+            ? `Images: ${section.images
+                .map((image) => `${image.ref}${image.mime ? ` (${image.mime})` : ''}${image.alt ? ` — ${image.alt}` : ''}`)
+                .join('; ')}`
+            : null,
         section.volatile ? `Volatile: true${section.expiresAt ? `, expires ${section.expiresAt}` : ''}` : null,
         '',
         section.content

package/dist/domain/image-refs.js

@@ -0,0 +1,63 @@
+// Obsidian-style embed: ![[path/to/image.png|optional alt]]. The leading "!"
+// distinguishes it from a plain [[wiki link]] and must be consumed here so wiki
+// link extraction (which now ignores a "!"-prefixed opener) does not also treat
+// the embed target as a graph link.
+const imageEmbedPattern = /!\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g;
+// Standard Markdown image: ![alt](path). The target may carry an optional
+// "title" in quotes, which is dropped — only the resource path is kept.
+const markdownImagePattern = /!\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const imageMimeByExtension = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+    bmp: 'image/bmp',
+    avif: 'image/avif',
+    heic: 'image/heic'
+};
+const extensionOf = (ref) => {
+    const withoutQuery = ref.split(/[?#]/)[0] ?? ref;
+    const dot = withoutQuery.lastIndexOf('.');
+    return dot >= 0 ? withoutQuery.slice(dot + 1).toLowerCase() : '';
+};
+// Inferred image mime for a reference, or undefined when the extension is not a
+// recognized image type (e.g. a remote URL without an extension).
+export const imageMimeForRef = (ref) => imageMimeByExtension[extensionOf(ref)];
+const isImageRef = (ref) => imageMimeForRef(ref) !== undefined;
+const withMime = (partial) => {
+    const mime = imageMimeForRef(partial.ref);
+    return mime ? { ...partial, mime } : partial;
+};
+const dedupe = (refs) => {
+    const seen = new Set();
+    return refs.filter((image) => {
+        const key = `${image.kind}:${image.ref}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+};
+// Extract image references from raw Markdown text. Embeds (![[...]]) always
+// count as images; inline images (![alt](path)) count only when the target has
+// a recognizable image extension, so ![text](note.md) style non-image links are
+// not misread. Callers that must ignore fenced code blocks should pre-filter
+// the content — this operates on the text it is given.
+export const extractImageRefs = (content) => {
+    const embeds = Array.from(content.matchAll(imageEmbedPattern), (match) => withMime({
+        kind: 'embed',
+        ref: match[1].trim(),
+        alt: (match[2] ?? match[1]).trim()
+    }));
+    const inline = Array.from(content.matchAll(markdownImagePattern), (match) => withMime({
+        kind: 'inline',
+        ref: match[2].trim(),
+        alt: match[1].trim()
+    })).filter((image) => isImageRef(image.ref));
+    return dedupe([...embeds, ...inline]);
+};
+// True when the content carries at least one image reference.
+export const hasImageRefs = (content) => extractImageRefs(content).length > 0;

package/dist/domain/markdown.js

@@ -1,13 +1,17 @@
 import { basename, relative } from 'node:path';
 import { resolveAgentIdFromPath, sanitizeAgentId } from './agents.js';
 import { createStableId } from './ids.js';
+import { extractImageRefs } from './image-refs.js';
 import { estimateTokenCount } from './tokens.js';
 const frontmatterPattern = /^---\n([\s\S]*?)\n---\n?/;
 // Target captures everything up to an optional "|alias" or the closing "]]",
 // INCLUDING "#" — the heading anchor is stripped later, and only when it is a
 // real anchor (see stripHeadingAnchor). Keeping "#" here means a title such as
 // "note (PR #34)" is not truncated at the "#".
-const wikiLinkPattern = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
+// The negative lookbehind keeps a "!"-prefixed opener (an image embed
+// ![[image.png]]) out of graph links: the embed target is an image reference,
+// not a note link, and is captured separately by extractImageRefs.
+const wikiLinkPattern = /(?<!!)\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
 const tagPattern = /(^|\s)#([A-Za-z0-9][A-Za-z0-9_-]*)/g;
 const headingPattern = /^#\s+(.+)$/m;
 const contextLinksHeadingPattern = /^(#{1,6})\s+(?:context\s+links?|links?\s+de\s+contexto)\b/i;
@@ -168,6 +172,13 @@ const extractTitle = (filePath, content, frontmatter) => {
 };
 export const extractWikiLinks = (content) => unique(extractWikiLinkReferences(content).map((reference) => reference.title));
 export const extractTags = (content) => unique(Array.from(stripFencedCodeBlocks(stripFrontmatter(content)).matchAll(tagPattern), (match) => match[2]));
+// Image references from the visible Markdown (fenced code blocks excluded, so a
+// fenced example embed is not treated as a real image), mirroring how wiki
+// links and tags ignore code blocks.
+export const extractDocumentImageRefs = (content) => extractImageRefs(visibleMarkdownLines(content)
+    .filter((line) => !line.fenced)
+    .map((line) => line.content)
+    .join('\n'));
 const normalizeChunkContent = (content) => content
     .split('\n')
     .map((line) => line.trim())
@@ -241,6 +252,7 @@ export const parseMarkdownDocument = (input) => {
     const frontmatter = parseFrontmatter(input.content);
     const title = extractTitle(input.absolutePath, input.content, frontmatter);
     const agentId = frontmatter.agent ? sanitizeAgentId(frontmatter.agent) : resolveAgentIdFromPath(relativePath);
+    const images = extractDocumentImageRefs(input.content);
     return {
         id: createStableId(relativePath),
         agentId,
@@ -250,6 +262,9 @@ export const parseMarkdownDocument = (input) => {
         tags: extractTags(input.content),
         links: extractWikiLinks(input.content),
         contextLinks: extractContextLinkWeights(input.content).map((link) => link.title),
+        // Keep the field absent (not an empty array) for image-free notes so the
+        // shape matches documents parsed before image support.
+        ...(images.length > 0 ? { images } : {}),
         frontmatter,
         createdAt: input.createdAt.toISOString(),
         updatedAt: input.updatedAt.toISOString()

package/dist/infrastructure/file-system-vault.js

@@ -109,6 +109,26 @@ export const writeMarkdownFile = async (vaultPath, filename, content) => {
     await chmod(absolutePath, fileMode);
     return absolutePath;
 };
+// Persist an arbitrary binary asset (e.g. an image) under a vault-relative
+// path. Unlike writeMarkdownFile this keeps the caller-provided extension and
+// writes raw bytes, but shares the same containment guard so nothing is written
+// outside the vault. Encryption-at-rest for versioning is layered on by the
+// caller (add-image), which mirrors the plaintext asset to a ".enc" file the
+// same way Markdown notes are handled.
+export const writeVaultBinaryFile = async (vaultPath, filename, data) => {
+    if (isBucketVaultUri(vaultPath)) {
+        throw new Error('Writing binary assets to bucket vaults is not supported yet.');
+    }
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const absolutePath = resolve(absoluteVaultPath, filename);
+    if (!isPathInside(absoluteVaultPath, absolutePath)) {
+        throw new Error(`Refusing to write outside vault: ${absolutePath}`);
+    }
+    await secureDirectory(dirname(absolutePath));
+    await writeFile(absolutePath, data, { mode: fileMode });
+    await chmod(absolutePath, fileMode);
+    return absolutePath;
+};
 export const deleteMarkdownFile = async (vaultPath, filename) => {
     if (isBucketVaultUri(vaultPath)) {
         throw new Error('Deleting bucket vault notes is not supported from Brainlink yet. Remove bucket objects with your storage provider tooling.');

package/dist/mcp/server.js

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, addNotesInputSchema, addNotesTool, deleteNoteInputSchema, deleteNoteTool, deleteNotesInputSchema, deleteNotesTool, 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, similarNotesInputSchema, similarNotesTool, sessionCloseInputSchema, sessionCloseTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, syncInputSchema, syncTool, validateInputSchema, validateTool, vaultBundleListInputSchema, vaultBundleListTool, vaultCommitInputSchema, vaultCommitTool, vaultExportBundleInputSchema, vaultExportBundleTool, vaultExportInputSchema, vaultExportTool, vaultHistoryInputSchema, vaultHistoryTool, vaultImportBundleInputSchema, vaultImportBundleTool, vaultImportInputSchema, vaultImportTool, vaultInitInputSchema, vaultInitTool, vaultMergeAgentsInputSchema, vaultMergeAgentsTool, vaultProvisionInputSchema, vaultProvisionTool, vaultPullInputSchema, vaultPullTool, vaultRestoreInputSchema, vaultRestoreTool, vaultStatusInputSchema, vaultStatusTool, versionInputSchema, versionTool } from './tools.js';
+import { addNoteInputSchema, addFileInputSchema, addFileTool, addImageInputSchema, addImageTool, addNoteTool, addNotesInputSchema, addNotesTool, deleteNoteInputSchema, deleteNoteTool, deleteNotesInputSchema, deleteNotesTool, 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, similarNotesInputSchema, similarNotesTool, sessionCloseInputSchema, sessionCloseTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, syncInputSchema, syncTool, validateInputSchema, validateTool, vaultBundleListInputSchema, vaultBundleListTool, vaultCommitInputSchema, vaultCommitTool, vaultExportBundleInputSchema, vaultExportBundleTool, vaultExportInputSchema, vaultExportTool, vaultHistoryInputSchema, vaultHistoryTool, vaultImportBundleInputSchema, vaultImportBundleTool, vaultImportInputSchema, vaultImportTool, vaultInitInputSchema, vaultInitTool, vaultMergeAgentsInputSchema, vaultMergeAgentsTool, vaultProvisionInputSchema, vaultProvisionTool, vaultPullInputSchema, vaultPullTool, vaultRestoreInputSchema, vaultRestoreTool, vaultStatusInputSchema, vaultStatusTool, versionInputSchema, versionTool } from './tools.js';
 import { getRuntimeVersion } from './runtime.js';
 import { brainlinkServerInstructions } from './server-instructions.js';
 import { guardToolHandler } from './tool-guard.js';
@@ -126,6 +126,11 @@ export const createBrainlinkMcpServer = () => {
         description: 'Read a local markdown/text file and ingest it as a Brainlink note. Reindex defaults to true.',
         inputSchema: addFileInputSchema
     }, addFileTool);
+    server.registerTool('brainlink_add_image', {
+        title: 'Add Brainlink Image',
+        description: 'Store an image in the vault (encrypted at rest when vault encryption is on) and address it by a stable vault-relative path. Provide imageBase64 or filePath. Optionally pass noteTitle to create a note that embeds the image so retrieval can surface it in context. Alt text is included in the returned context descriptor.',
+        inputSchema: addImageInputSchema
+    }, addImageTool);
     server.registerTool('brainlink_canonicalize_context_links', {
         title: 'Canonicalize Brainlink Context Links',
         description: 'Ensure notes have canonical Context Links to inferred context hubs. Supports dry-run and can create missing hub notes.',

package/dist/mcp/tools/write-tools.js

@@ -1,5 +1,7 @@
 import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
 import { z } from 'zod';
+import { addImage } from '../../application/add-image.js';
 import { addNoteWithMetadata } from '../../application/add-note.js';
 import { deleteNote } from '../../application/delete-note.js';
 import { scanDuplicateNotes } from '../../application/dedupe-notes.js';
@@ -353,6 +355,89 @@ export const volatileClearTool = async (input) => {
         cleared
     });
 };
+export const addImageInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    imageBase64: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Base64-encoded image bytes. Provide this or filePath.'),
+    filePath: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Local filesystem path to an image file to read. Provide this or imageBase64.'),
+    fileName: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Original image file name (used to infer extension/mime when passing imageBase64).'),
+    mimeType: z.string().min(1).optional().describe('Explicit image mime type, e.g. image/png. Inferred from the name when omitted.'),
+    alt: z.string().min(1).optional().describe('Alt text / description for the image, surfaced in retrieved context.'),
+    noteTitle: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('When set, create a Markdown note that embeds the stored image so retrieval can surface it in context.'),
+    context: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Domain context for the generated note (partitions it under a "<context> Hub"). Only used with noteTitle.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after storing the image (only meaningful when a note is created).')
+};
+export const addImageTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    if (!input.imageBase64 && !input.filePath) {
+        throw new Error('Provide either imageBase64 or filePath to add an image.');
+    }
+    if (input.imageBase64 && input.filePath) {
+        throw new Error('Provide only one of imageBase64 or filePath, not both.');
+    }
+    const data = input.filePath ? await readFile(input.filePath) : Buffer.from(input.imageBase64 ?? '', 'base64');
+    const sourceName = input.fileName ?? (input.filePath ? basename(input.filePath) : undefined);
+    const result = await addImage({
+        vaultPath: context.vault,
+        data,
+        agentId: context.agent,
+        sourceName,
+        mimeType: input.mimeType,
+        alt: input.alt,
+        noteTitle: input.noteTitle,
+        noteContext: input.context,
+        autoContextLinks: context.config.autoCanonicalContextLinks
+    });
+    const index = result.note && isTruthy(input.autoIndex) ? await indexVault(context.vault) : undefined;
+    return jsonResult({
+        vault: context.vault,
+        agent: result.agentId,
+        image: {
+            path: result.assetPath,
+            mime: result.mimeType,
+            bytes: result.bytes,
+            alt: result.alt,
+            encrypted: result.encrypted,
+            embed: result.embed
+        },
+        ...(result.note
+            ? {
+                note: {
+                    title: input.noteTitle,
+                    path: result.note.path,
+                    writeConnectivity: {
+                        autoLinked: result.note.autoLinked,
+                        linkTarget: result.note.linkTarget,
+                        context: result.note.context,
+                        hubCreated: result.note.hubCreated,
+                        guaranteedEdge: result.note.autoLinked
+                    }
+                }
+            }
+            : {}),
+        ...(index ? { index } : {})
+    });
+};
 export const addFileTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const content = await readFile(input.filePath, 'utf8');

package/dist/mcp/tools.js

@@ -1,4 +1,4 @@
 export { brokenLinksInputSchema, brokenLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, doctorActionsInputSchema, doctorActionsTool, explainInputSchema, explainTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, orphansInputSchema, orphansTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, similarNotesInputSchema, similarNotesTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools/read-tools.js';
-export { addFileInputSchema, addFileTool, addNoteInputSchema, addNoteTool, addNotesInputSchema, addNotesTool, deleteNoteInputSchema, deleteNoteTool, deleteNotesInputSchema, deleteNotesTool, inboxAddInputSchema, inboxAddTool, inboxListInputSchema, inboxListTool, inboxProcessInputSchema, inboxProcessTool, rememberInputSchema, rememberTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool } from './tools/write-tools.js';
+export { addFileInputSchema, addFileTool, addImageInputSchema, addImageTool, addNoteInputSchema, addNoteTool, addNotesInputSchema, addNotesTool, deleteNoteInputSchema, deleteNoteTool, deleteNotesInputSchema, deleteNotesTool, inboxAddInputSchema, inboxAddTool, inboxListInputSchema, inboxListTool, inboxProcessInputSchema, inboxProcessTool, rememberInputSchema, rememberTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool } from './tools/write-tools.js';
 export { bootstrapInputSchema, bootstrapTool, canonicalizeContextLinksInputSchema, canonicalizeContextLinksTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, indexInputSchema, indexTool, policyInputSchema, policyTool, projectInitInputSchema, projectInitTool, repairLinksInputSchema, repairLinksTool, sessionCloseInputSchema, sessionCloseTool, syncInputSchema, syncTool } from './tools/maintenance-tools.js';
 export { vaultBundleListInputSchema, vaultBundleListTool, vaultCommitInputSchema, vaultCommitTool, vaultExportBundleInputSchema, vaultExportBundleTool, vaultExportInputSchema, vaultExportTool, vaultHistoryInputSchema, vaultHistoryTool, vaultImportBundleInputSchema, vaultImportBundleTool, vaultImportInputSchema, vaultImportTool, vaultInitInputSchema, vaultInitTool, vaultMergeAgentsInputSchema, vaultMergeAgentsTool, vaultProvisionInputSchema, vaultProvisionTool, vaultPullInputSchema, vaultPullTool, vaultRestoreInputSchema, vaultRestoreTool, vaultStatusInputSchema, vaultStatusTool } from './tools/vault-tools.js';

package/package.json

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