@andespindola/brainlink 1.6.14 → 1.6.15

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.6.15
+
+- **Retrieve image bytes (`brainlink_get_image`).** A new MCP tool + `get-image` use-case reads an image previously stored by `brainlink_add_image` back out of the vault as base64 bytes + mime, decrypting when the vault is encrypted. Path is validated to stay inside `.brainlink/assets` (no traversal). This closes the cross-agent loop: one agent adds an image to the shared vault, another fetches and uses it.
+
 ## 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.

package/dist/application/get-image.js

@@ -0,0 +1,63 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { imageMimeForRef } from '../domain/image-refs.js';
+import { ensureVault } from '../infrastructure/file-system-vault.js';
+import { decryptVaultContent, isEncryptedVaultPayload, readOrCreateVaultKey } from '../infrastructure/vault-crypto.js';
+// The assets tree images are stored under; the only location get-image is
+// allowed to read from. Mirrors the constant used by add-image.
+const assetsRoot = '.brainlink/assets';
+const isInside = (parent, child) => {
+    const rel = relative(parent, child);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+};
+// Normalize the requested path to the logical (plaintext) asset path so the
+// returned descriptor is stable regardless of whether the caller passed the
+// `.enc` mirror or the plaintext path.
+const toLogicalPath = (assetPath) => assetPath.toLowerCase().endsWith('.enc') ? assetPath.slice(0, -'.enc'.length) : assetPath;
+// Read the raw bytes for a stored image, decrypting transparently when the
+// bytes on disk are an encrypted-at-rest payload. Prefers the plaintext file
+// and falls back to the `.enc` mirror, so it works whether the vault is
+// encrypted or not.
+const readAssetBytes = async (vaultRoot, logicalAbsolute) => {
+    const decryptIfNeeded = async (raw) => {
+        if (!isEncryptedVaultPayload(raw)) {
+            return { bytes: raw, encrypted: false };
+        }
+        // Only touch the key when the on-disk bytes are actually ciphertext, so a
+        // plaintext vault never mints a versioning key just to read an image.
+        const vaultKey = await readOrCreateVaultKey(vaultRoot);
+        return { bytes: decryptVaultContent(vaultKey, raw), encrypted: true };
+    };
+    try {
+        return await decryptIfNeeded(await readFile(logicalAbsolute));
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    return decryptIfNeeded(await readFile(`${logicalAbsolute}.enc`));
+};
+// Retrieve a stored image's raw bytes (base64) and mime so a second agent can
+// pull an image another agent added to the shared vault. The path is validated
+// to live inside `.brainlink/assets` (no traversal), and encrypted-at-rest
+// payloads are decrypted with the existing vault key.
+export const getImage = async (input) => {
+    const vaultRoot = await ensureVault(input.vaultPath);
+    const logicalPath = toLogicalPath(input.path);
+    const logicalAbsolute = resolve(vaultRoot, logicalPath);
+    const assetsAbsolute = join(vaultRoot, assetsRoot);
+    if (!isInside(assetsAbsolute, logicalAbsolute)) {
+        throw new Error(`Refusing to read image outside the vault assets tree: ${input.path}`);
+    }
+    const { bytes, encrypted } = await readAssetBytes(vaultRoot, logicalAbsolute);
+    const mime = imageMimeForRef(logicalPath) ?? 'application/octet-stream';
+    const relativePath = relative(vaultRoot, logicalAbsolute).split('\\').join('/');
+    return {
+        path: relativePath,
+        mime,
+        bytes: bytes.toString('base64'),
+        encrypted,
+        ...(input.alt?.trim() ? { alt: input.alt.trim() } : {})
+    };
+};

package/dist/mcp/server.js

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.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 { 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, getImageInputSchema, getImageTool, 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';
@@ -131,6 +131,11 @@ export const createBrainlinkMcpServer = () => {
         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_get_image', {
+        title: 'Get Brainlink Image',
+        description: 'Retrieve the raw bytes of an image stored in the vault by a stable vault-relative asset path (as returned by brainlink_add_image). Returns the descriptor plus base64-encoded bytes so a second agent can fetch and use an image another agent added to the shared vault. Decrypts transparently when the vault stores images encrypted at rest; the path must resolve inside .brainlink/assets.',
+        inputSchema: getImageInputSchema
+    }, getImageTool);
     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/read-tools.js

@@ -3,6 +3,7 @@ import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from
 import { buildContextPackage, readContextDataSignature, readVolatileSignature } from '../../application/build-context.js';
 import { getGraph } from '../../application/get-graph.js';
 import { getGraphContexts } from '../../application/get-graph-contexts.js';
+import { getImage } from '../../application/get-image.js';
 import { explainSearchResults, suggestBrokenLinkFixes, suggestContextLinks } from '../../application/memory-suggestions.js';
 import { buildActionableDoctor } from '../../application/operational-workflows.js';
 import { searchKnowledge } from '../../application/search-knowledge.js';
@@ -539,3 +540,28 @@ export const recommendationsTool = async (input) => {
         recommendations
     });
 };
+export const getImageInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    path: z
+        .string()
+        .min(1)
+        .describe('Vault-relative asset path to fetch, as returned by brainlink_add_image (e.g. ".brainlink/assets/shared/<sha>.png"). Must resolve inside the vault .brainlink/assets tree.'),
+    alt: z.string().min(1).optional().describe('Optional alt text / description to echo back in the descriptor.')
+};
+// Fetch the raw bytes of a stored image so another agent can retrieve and use an
+// image a first agent added to the shared vault. Decrypts transparently when the
+// bytes are stored encrypted-at-rest, and rejects paths outside .brainlink/assets.
+export const getImageTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const image = await getImage({
+        vaultPath: context.vault,
+        path: input.path,
+        alt: input.alt
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        image
+    });
+};

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 { brokenLinksInputSchema, brokenLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, doctorActionsInputSchema, doctorActionsTool, explainInputSchema, explainTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, getImageInputSchema, getImageTool, orphansInputSchema, orphansTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, similarNotesInputSchema, similarNotesTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools/read-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.14",
+  "version": "1.6.15",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",