@andespindola/brainlink 1.8.1 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.8.2
+
+- **Connect page AGENTS.md now instructs proactive capture.** The ready operating contract on the `/connect` page changed its "After you learn" guidance from only writing back "durable learnings" to capturing proactively — decisions and their rationale, project maps/paths, conventions, runbooks, recent state, and recurring pitfalls; when in doubt, capture (using volatile memory only for the truly ephemeral), then reindex. So agents wired to a brainlink persist everything worth reusing, not just occasional highlights.
+
 ## 1.8.1
 
 - **Fix the Connect page's Codex snippet auth.** The `/connect` page's Codex `config.toml` block passed the bearer token via a `MCP_AUTHORIZATION` env var, but `mcp-remote` does not read that env — so the request went out unauthenticated and `mcp-remote` fell back to a hanging OAuth flow. The token is now passed as an `mcp-remote` `--header "Authorization: Bearer <token>"` argument (verified to connect), and both the remote and local Codex snippets gained `startup_timeout_sec = 60` so Codex doesn't time out the cold-start MCP handshake.

package/README.md

@@ -562,8 +562,8 @@ Available tools:
 - `brainlink_sync`: run index, stats, validation, broken-link and orphan checks in one call.
 - `brainlink_vault_provision`: create a private GitHub repository for the vault with the authenticated `gh` CLI, wire it as `origin`, push the first snapshot, and enable `autoVersion` so later indexed changes are committed and pushed automatically. By default the repository is **encrypted** (`vaultEncryption`): it holds AES-256-GCM ciphertext, decryptable only by a Brainlink instance with the local key.
 - `brainlink_vault_status` / `brainlink_vault_init` / `brainlink_vault_commit` / `brainlink_vault_history` / `brainlink_vault_pull` / `brainlink_vault_restore`: version the vault's canonical Markdown with git (the derived index is git-ignored). Pull and restore reindex changed files automatically so the vault stays immediately searchable.
-- `brainlink_vault_export` / `brainlink_vault_import`: write and read a portable `.blvault` snapshot (gzip envelope of the Markdown with per-file SHA-256). Import verifies checksums, preserves divergent local files as `*.conflict-<ts>.md`, and reindexes.
-- `brainlink_vault_export_bundle` / `brainlink_vault_bundle_list` / `brainlink_vault_import_bundle`: export **every known vault** (the config vault plus `allowedVaults`) into a single portable `.blbundle`, inspect the vaults inside a bundle, and import them back — all vaults to their recorded paths, or a single one via `only` (optionally into `targetVault`). Same checksum verification and conflict preservation as the single-vault snapshot.
+- `brainlink_vault_export` / `brainlink_vault_import`: write and read a portable `.blvault` snapshot (gzip envelope of the Markdown with per-file SHA-256). Encrypted with AES-256-GCM when a `passphrase` (or `BRAINLINK_VAULT_KEY`) is available, otherwise plaintext gzip; import auto-detects and decrypts. Import verifies checksums, preserves divergent local files as `*.conflict-<ts>.md`, and reindexes.
+- `brainlink_vault_export_bundle` / `brainlink_vault_bundle_list` / `brainlink_vault_import_bundle`: export **every known vault** (the config vault plus `allowedVaults`) into a single portable `.blbundle`, inspect the vaults inside a bundle, and import them back — all vaults to their recorded paths, or a single one via `only` (optionally into `targetVault`). Same encryption (via `passphrase`/`BRAINLINK_VAULT_KEY`), checksum verification and conflict preservation as the single-vault snapshot.
 - `brainlink_vault_merge_agents`: losslessly merge one agent namespace into another within the same vault (e.g. `claude-code` → `shared`). Identical notes are skipped, colliding slugs with different content are kept under a `-from-<agent>` name, everything else is moved, and merged notes are aggregated into domain `<context> Hub` notes. Source notes are kept unless `deleteSource` is set; `dryRun` previews the plan.
 - `brainlink_graph`: read indexed graph nodes and weighted links.
 - `brainlink_graph_contexts`: list the visual graph contexts used by the local server.
@@ -884,7 +884,7 @@ blink add "Note Title" --vault ./vault --content-file ./notes.md --no-auto-index
 
 `--content` and `--content-file` are mutually exclusive. Add `--no-auto-index` when you want to defer reindexing.
 
-Creates a Markdown note under `agents/<agent-id>/`. Common secret patterns are blocked by default; use `--allow-sensitive` only for an intentionally protected vault.
+Creates a Markdown note under `agents/<agent-id>/`. Secrets (tokens, keys, passwords) can be stored freely — Brainlink is the canonical secret store — but recognized secrets are **masked** at user-facing read surfaces (the CLI and the graph web UI). MCP tool responses are unmasked so a consulting agent receives the real value.
 To avoid disconnected memory, Brainlink auto-adds a fallback wiki edge when a note is written without links, creating agent hub notes when needed.
 `add` also returns `possibleDuplicates` (exact hash + semantic candidates) so agents can resolve duplicate memory right after writes.
 
@@ -977,13 +977,15 @@ blink vault-clone git@github.com:you/your-vault.git ./vault   # clone + build in
 blink vault-status
 
 # Portable snapshot (self-contained, index excluded; import rebuilds it)
-blink vault-export -o vault.blvault
-blink vault-import vault.blvault  # conflicting local edits preserved as *.conflict-<ts>.md
+# Encrypted (AES-256-GCM) with a passphrase; without one it warns and writes plaintext gzip.
+blink vault-export --passphrase "$PHRASE" -o vault.blvault
+blink vault-import vault.blvault --passphrase "$PHRASE"  # conflicting local edits preserved as *.conflict-<ts>.md
+blink vault-export --no-encrypt -o vault.blvault         # force legacy plaintext gzip
 
 # Multi-vault bundle: every known vault (config vault + allowedVaults) in one file
-blink vault-export --all -o vaults.blbundle
-blink vault-import vaults.blbundle              # restore all vaults to their recorded paths
-blink vault-import vaults.blbundle --only shared --vault ./restored  # restore just one
+blink vault-export --all --passphrase "$PHRASE" -o vaults.blbundle
+blink vault-import vaults.blbundle --passphrase "$PHRASE"              # restore all vaults to their recorded paths
+blink vault-import vaults.blbundle --only shared --vault ./restored --passphrase "$PHRASE"  # restore just one
 ```
 
 Inline credentials in a remote URL are rejected — use SSH or a git credential helper.
@@ -1476,8 +1478,9 @@ Brainlink is local-first by default.
 
 - Do not expose the HTTP server publicly without authentication.
 - Brainlink HTTP is localhost-only and refuses non-loopback hosts.
-- Brainlink blocks common secret patterns by default when adding notes. Use `--allow-sensitive` only for intentional, protected vaults.
-- Do not store secrets, credentials, API keys or regulated personal data unless the vault is protected by your own storage controls.
+- Secrets stored in notes are masked at the CLI and graph web UI, but delivered unmasked to MCP agents that consult them. Masking is a display safeguard, not access control — anyone with filesystem access to the vault (or MCP access) can read the plaintext.
+- Notes are stored as plaintext Markdown on disk. Keep the vault on an encrypted volume and/or use encrypted vault versioning (`vaultEncryption`) and encrypted snapshots (`--passphrase`) for at-rest protection of regulated data.
+- Context packs, the JSON index and search packs cache note content; they are written owner-only (`0o600`) but are not a substitute for disk encryption.
 - Treat `.brainlink/index.json` and `.brainlink/search-packs/` as disposable derived artifacts.
 
 See [SECURITY.md](SECURITY.md).

package/dist/application/frontend/connect-page.js

@@ -41,10 +41,15 @@ it as the continuity of your cognition, not an optional lookup.
 - Retrieve with \`strategy: "auto"\` (CAG on a fresh pack, RAG otherwise) and
   \`mode: "hybrid"\` (FTS + semantic) unless a narrower mode clearly fits.
 
-## After you learn
-- Write durable learnings back with \`brainlink_remember\` (or
-  \`brainlink_add_note\` for structured notes), then reindex with
-  \`brainlink_index\`.
+## Capture proactively — save everything worth reusing
+- Do not wait for an explicit "durable learning". After anything worth reusing,
+  write it back: decisions and their rationale, project maps and paths,
+  conventions, runbooks, recent state (last actions / open work), and recurring
+  pitfalls plus how you worked around them.
+- When in doubt, capture — the cost is low and reuse is likely. Use volatile
+  memory only for the truly ephemeral.
+- Persist with \`brainlink_remember\` (or \`brainlink_add_note\` for structured
+  notes), then reindex with \`brainlink_index\`.
 - Write connected memory: include \`[[wiki links]]\`, tags, and priority markers
   so notes join the knowledge graph instead of sitting orphaned.
 `;

package/dist/application/server/http.js

@@ -1,3 +1,4 @@
+import { maskSensitiveDeep } from '../../domain/note-safety.js';
 export const contentTypes = {
     '.html': 'text/html; charset=utf-8',
     '.css': 'text/css; charset=utf-8',
@@ -5,6 +6,10 @@ export const contentTypes = {
     '.json': 'application/json; charset=utf-8'
 };
 export const createJsonResponse = (value) => JSON.stringify(value, null, 2);
+// The graph web UI is a user-facing surface: any secret stored in a note is
+// masked before it reaches the browser. Use this for content-bearing endpoints
+// (graph/search/context); auth and control endpoints keep createJsonResponse.
+export const createMaskedJsonResponse = (value) => JSON.stringify(maskSensitiveDeep(value), null, 2);
 export const parsePositiveInteger = (value, fallback) => {
     const parsed = Number.parseInt(value ?? '', 10);
     return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;

package/dist/application/server/routes.js

@@ -30,7 +30,7 @@ import { readAuthStatus, readEditableSettings, updateEditableSettings } from './
 import { connectVaultRemote, ensureDeployKey, readVersioningStatus } from './versioning.js';
 import { createSettingsPageHtml } from '../frontend/settings-page.js';
 import { createConnectPageHtml } from '../frontend/connect-page.js';
-import { contentTypes, createJsonResponse, isReadMethod, parsePositiveInteger } from './http.js';
+import { contentTypes, createJsonResponse, createMaskedJsonResponse, isReadMethod, parsePositiveInteger } from './http.js';
 import { parseMultipartForm } from './multipart.js';
 const readRuntimeDefaults = async (url) => {
     const config = await loadBrainlinkConfig();
@@ -423,7 +423,7 @@ export const route = async (request, url, vaultPath, options = {}) => {
         return createResponse(readClientRenderWorkerJs(), 200, contentTypes['.js']);
     }
     if (isReadMethod(request) && url.pathname === '/api/graph') {
-        return createResponse(createJsonResponse(await getGraph(vaultPath, readAgentQuery(url))), 200, contentTypes['.json']);
+        return createResponse(createMaskedJsonResponse(await getGraph(vaultPath, readAgentQuery(url))), 200, contentTypes['.json']);
     }
     if (isReadMethod(request) && url.pathname === '/api/graph-layout') {
         const { signature, layout } = await getGraphLayout(vaultPath, {
@@ -444,7 +444,7 @@ export const route = async (request, url, vaultPath, options = {}) => {
             };
         }
         const cachedBody = readGraphLayoutBody(signature);
-        const body = cachedBody ?? createJsonResponse({ signature, ...encodeLayoutPayload(layout) });
+        const body = cachedBody ?? createMaskedJsonResponse({ signature, ...encodeLayoutPayload(layout) });
         if (!cachedBody) {
             storeGraphLayoutBody(signature, body);
         }
@@ -458,7 +458,7 @@ export const route = async (request, url, vaultPath, options = {}) => {
         };
     }
     if (isReadMethod(request) && url.pathname === '/api/graph-view') {
-        return createResponse(createJsonResponse(await getGraphView(vaultPath, {
+        return createResponse(createMaskedJsonResponse(await getGraphView(vaultPath, {
             x: parseNumber(url.searchParams.get('x'), -1000),
             y: parseNumber(url.searchParams.get('y'), -1000),
             width: parseNumber(url.searchParams.get('w'), 2000),
@@ -476,7 +476,7 @@ export const route = async (request, url, vaultPath, options = {}) => {
         const scale = parseNumber(url.searchParams.get('scale'), 0.24);
         const nodeBudget = parsePositiveInteger(url.searchParams.get('nodeBudget'), 1800);
         const edgeBudget = parsePositiveInteger(url.searchParams.get('edgeBudget'), 5000);
-        return createResponse(createJsonResponse(await getGraphStreamChunk(vaultPath, {
+        return createResponse(createMaskedJsonResponse(await getGraphStreamChunk(vaultPath, {
             x,
             y,
             width,
@@ -554,7 +554,7 @@ export const route = async (request, url, vaultPath, options = {}) => {
         if (!node) {
             return createResponse(createJsonResponse({ error: 'Node not found' }), 404, contentTypes['.json']);
         }
-        return createResponse(createJsonResponse({ node }), 200, contentTypes['.json']);
+        return createResponse(createMaskedJsonResponse({ node }), 200, contentTypes['.json']);
     }
     if (isReadMethod(request) && url.pathname === '/api/graph-filter') {
         const query = url.searchParams.get('q')?.trim() ?? '';
@@ -625,7 +625,7 @@ export const route = async (request, url, vaultPath, options = {}) => {
         if (hasInvalidSearchMode(url)) {
             return createResponse(createJsonResponse({ error: 'Invalid mode. Use fts, semantic or hybrid.' }), 400, contentTypes['.json']);
         }
-        return createResponse(createJsonResponse({ query, agent: readAgentQuery(url), limit, mode, results: await searchKnowledge(vaultPath, query, limit, readAgentQuery(url), mode) }), 200, contentTypes['.json']);
+        return createResponse(createMaskedJsonResponse({ query, agent: readAgentQuery(url), limit, mode, results: await searchKnowledge(vaultPath, query, limit, readAgentQuery(url), mode) }), 200, contentTypes['.json']);
     }
     if (isReadMethod(request) && url.pathname === '/api/context') {
         const query = url.searchParams.get('q') ?? '';
@@ -642,7 +642,7 @@ export const route = async (request, url, vaultPath, options = {}) => {
         if (hasInvalidContextStrategy(url)) {
             return createResponse(createJsonResponse({ error: 'Invalid strategy. Use rag, cag or auto.' }), 400, contentTypes['.json']);
         }
-        return createResponse(createJsonResponse(await buildContextPackage(vaultPath, query, limit, tokens, readAgentQuery(url), mode, strategy, contextCacheTtlMs, cagPackTtlMs)), 200, contentTypes['.json']);
+        return createResponse(createMaskedJsonResponse(await buildContextPackage(vaultPath, query, limit, tokens, readAgentQuery(url), mode, strategy, contextCacheTtlMs, cagPackTtlMs)), 200, contentTypes['.json']);
     }
     if (isReadMethod(request) && url.pathname === '/api/links') {
         return createResponse(createJsonResponse({ links: await listLinks(vaultPath, readAgentQuery(url)) }), 200, contentTypes['.json']);

package/dist/application/vault-bundle.js

@@ -2,12 +2,23 @@
 // snapshot per vault, built on the reusable single-vault snapshot helpers. Exports
 // all known vaults (or a chosen subset) into one movable file; import restores every
 // bundled vault back to its recorded path or a chosen target, preserving conflicts.
+// Because a bundle spans multiple vaults it has no single per-vault key, so it is
+// encrypted (AES-256-GCM) whenever a passphrase (or BRAINLINK_VAULT_KEY) is
+// available; without one it falls back to legacy plaintext gzip with a warning.
+// Legacy plaintext bundles still import (auto-detected).
 import { readFile, writeFile } from 'node:fs/promises';
 import { gzipSync, gunzipSync } from 'node:zlib';
 import { basename, resolve } from 'node:path';
 import { buildSnapshotEnvelope, applySnapshotEnvelope } from './vault-snapshot.js';
+import { decryptVaultContent, deriveVaultKeyFromPassphrase, encryptVaultContent, isEncryptedVaultPayload } from '../infrastructure/vault-crypto.js';
 const bundleVersion = 1;
 const bundleKind = 'brainlink-vault-bundle';
+// A bundle key comes only from a passphrase or BRAINLINK_VAULT_KEY (no per-vault
+// keyfile, since a bundle spans vaults). Returns null when neither is available.
+const resolveBundleKey = (passphrase) => {
+    const secret = (passphrase && passphrase.length > 0 ? passphrase : process.env.BRAINLINK_VAULT_KEY?.trim()) ?? '';
+    return secret.length > 0 ? deriveVaultKeyFromPassphrase(secret) : null;
+};
 const dedupePaths = (vaultPaths) => {
     const seen = new Set();
     const paths = [];
@@ -20,14 +31,27 @@ const dedupePaths = (vaultPaths) => {
     }
     return paths;
 };
-const parseBundle = (raw) => {
-    const envelope = JSON.parse(gunzipSync(raw).toString('utf8'));
+const parseBundle = (raw, passphrase) => {
+    let gzipped = raw;
+    if (isEncryptedVaultPayload(raw)) {
+        const key = resolveBundleKey(passphrase);
+        if (!key) {
+            throw new Error('Encrypted .blbundle requires --passphrase (or BRAINLINK_VAULT_KEY).');
+        }
+        try {
+            gzipped = decryptVaultContent(key, raw);
+        }
+        catch {
+            throw new Error('Encrypted .blbundle could not be decrypted. Check the --passphrase / BRAINLINK_VAULT_KEY value.');
+        }
+    }
+    const envelope = JSON.parse(gunzipSync(gzipped).toString('utf8'));
     if (!envelope || envelope.kind !== bundleKind || envelope.version !== bundleVersion || !Array.isArray(envelope.vaults)) {
         throw new Error('Unrecognized .blbundle format.');
     }
     return envelope;
 };
-export const exportVaultsBundle = async (vaultPaths, outputFile) => {
+export const exportVaultsBundle = async (vaultPaths, outputFile, options = {}) => {
     const uniquePaths = dedupePaths(vaultPaths);
     const vaults = await Promise.all(uniquePaths.map(async (vaultPath) => {
         const vault = resolve(vaultPath);
@@ -39,13 +63,18 @@ export const exportVaultsBundle = async (vaultPaths, outputFile) => {
         createdAt: new Date().toISOString(),
         vaults
     };
-    const packed = gzipSync(Buffer.from(JSON.stringify(envelope), 'utf8'), { level: 9 });
+    const gzipped = gzipSync(Buffer.from(JSON.stringify(envelope), 'utf8'), { level: 9 });
+    const key = options.encrypt !== false ? resolveBundleKey(options.passphrase) : null;
+    if (options.encrypt !== false && !key) {
+        process.stderr.write('brainlink: bundle exported unencrypted — pass --passphrase (or set BRAINLINK_VAULT_KEY) to encrypt a portable bundle.\n');
+    }
+    const packed = key ? encryptVaultContent(key, gzipped) : gzipped;
     await writeFile(outputFile, packed, { mode: 0o600 });
     const fileCount = vaults.reduce((total, entry) => total + entry.snapshot.files.length, 0);
-    return { file: outputFile, vaultCount: vaults.length, fileCount, bytes: packed.byteLength };
+    return { file: outputFile, vaultCount: vaults.length, fileCount, bytes: packed.byteLength, encrypted: Boolean(key) };
 };
-export const listBundleVaults = async (bundleFile) => {
-    const envelope = parseBundle(await readFile(bundleFile));
+export const listBundleVaults = async (bundleFile, passphrase) => {
+    const envelope = parseBundle(await readFile(bundleFile), passphrase);
     return envelope.vaults.map((entry) => ({
         name: entry.name,
         vault: entry.vault,
@@ -53,7 +82,7 @@ export const listBundleVaults = async (bundleFile) => {
     }));
 };
 export const importVaultsBundle = async (bundleFile, options = {}) => {
-    const envelope = parseBundle(await readFile(bundleFile));
+    const envelope = parseBundle(await readFile(bundleFile), options.passphrase);
     const selected = options.only
         ? envelope.vaults.filter((entry) => entry.name === options.only || entry.vault === options.only)
         : envelope.vaults;

package/dist/application/vault-snapshot.js

@@ -2,14 +2,26 @@
 // canonical Markdown (with per-file SHA-256), self-contained and movable to any
 // machine. The derived index is never included — import rebuilds it so the vault
 // is immediately usable. Conflicts on import are preserved as `*.conflict-<ts>.md`
-// rather than overwriting local edits.
-import { createHash } from 'node:crypto';
+// rather than overwriting local edits. A portable artifact can only be encrypted
+// with a shared secret, so the snapshot is AES-256-GCM encrypted whenever a
+// passphrase (or BRAINLINK_VAULT_KEY) is available and falls back to legacy
+// plaintext gzip (with a warning) otherwise. Legacy gzip snapshots still import
+// (auto-detected); `--no-encrypt` forces plaintext even when a key is present.
 import { gzipSync, gunzipSync } from 'node:zlib';
 import { extname, relative } from 'node:path';
+import { createHash } from 'node:crypto';
 import { readFile, writeFile } from 'node:fs/promises';
 import { indexVault } from './index-vault.js';
 import { ensureVault, listVaultFiles, writeMarkdownFile } from '../infrastructure/file-system-vault.js';
+import { decryptVaultContent, deriveVaultKeyFromPassphrase, encryptVaultContent, isEncryptedVaultPayload } from '../infrastructure/vault-crypto.js';
 const snapshotVersion = 1;
+// A snapshot key comes only from a passphrase or BRAINLINK_VAULT_KEY (never a
+// per-vault keyfile, which would make the "portable" artifact undecryptable on
+// another machine/path). Returns null when neither is available.
+const resolveSnapshotKey = (passphrase) => {
+    const secret = (passphrase && passphrase.length > 0 ? passphrase : process.env.BRAINLINK_VAULT_KEY?.trim()) ?? '';
+    return secret.length > 0 ? deriveVaultKeyFromPassphrase(secret) : null;
+};
 const isMarkdown = (path) => extname(path).toLowerCase() === '.md';
 const toPosix = (path) => path.split('\\').join('/');
 const sha256 = (data) => createHash('sha256').update(data).digest('hex');
@@ -37,14 +49,32 @@ export const buildSnapshotEnvelope = async (vaultPath) => {
         files: entries.map((entry) => entry.file)
     };
 };
-export const exportVaultSnapshot = async (vaultPath, outputFile) => {
+export const exportVaultSnapshot = async (vaultPath, outputFile, options = {}) => {
     const envelope = await buildSnapshotEnvelope(vaultPath);
-    const packed = gzipSync(Buffer.from(JSON.stringify(envelope), 'utf8'), { level: 9 });
+    const gzipped = gzipSync(Buffer.from(JSON.stringify(envelope), 'utf8'), { level: 9 });
+    const key = options.encrypt !== false ? resolveSnapshotKey(options.passphrase) : null;
+    if (options.encrypt !== false && !key) {
+        process.stderr.write('brainlink: snapshot exported unencrypted — pass --passphrase (or set BRAINLINK_VAULT_KEY) to encrypt a portable snapshot.\n');
+    }
+    const packed = key ? encryptVaultContent(key, gzipped) : gzipped;
     await writeFile(outputFile, packed, { mode: 0o600 });
-    return { file: outputFile, fileCount: envelope.files.length, bytes: packed.byteLength };
+    return { file: outputFile, fileCount: envelope.files.length, bytes: packed.byteLength, encrypted: Boolean(key) };
 };
-const parseEnvelope = (raw) => {
-    const envelope = JSON.parse(gunzipSync(raw).toString('utf8'));
+const parseEnvelope = (raw, passphrase) => {
+    let gzipped = raw;
+    if (isEncryptedVaultPayload(raw)) {
+        const key = resolveSnapshotKey(passphrase);
+        if (!key) {
+            throw new Error('Encrypted .blvault requires --passphrase (or BRAINLINK_VAULT_KEY).');
+        }
+        try {
+            gzipped = decryptVaultContent(key, raw);
+        }
+        catch {
+            throw new Error('Encrypted .blvault could not be decrypted. Check the --passphrase / BRAINLINK_VAULT_KEY value.');
+        }
+    }
+    const envelope = JSON.parse(gunzipSync(gzipped).toString('utf8'));
     if (!envelope || envelope.version !== snapshotVersion || !Array.isArray(envelope.files)) {
         throw new Error('Unrecognized .blvault snapshot format.');
     }
@@ -88,6 +118,6 @@ export const applySnapshotEnvelope = async (envelope, vaultPath, options = {}) =
     return { imported, conflicted, index };
 };
 export const importVaultSnapshot = async (snapshotFile, vaultPath, options = {}) => {
-    const envelope = parseEnvelope(await readFile(snapshotFile));
+    const envelope = parseEnvelope(await readFile(snapshotFile), options.passphrase);
     return applySnapshotEnvelope(envelope, vaultPath, options);
 };

package/dist/cli/commands/vault-sync-commands.js

@@ -118,24 +118,28 @@ export const registerVaultSyncCommands = (program) => {
         .option('-o, --output <file>', 'output file (.blvault for one vault, .blbundle with --all)')
         .option('--vault <vault>', 'vault directory')
         .option('--all', 'export every known vault (config vault + allowedVaults) into a single .blbundle')
+        .option('--passphrase <passphrase>', 'encrypt with a portable passphrase (decrypts on any machine that knows it)')
+        .option('--no-encrypt', 'export legacy plaintext gzip (portable but unencrypted)')
         .option('--json', 'print machine-readable JSON')
-        .description('export vault Markdown to a portable snapshot: one vault (.blvault) or all vaults (--all, .blbundle)')
+        .description('export vault Markdown to a portable snapshot: one vault (.blvault) or all vaults (--all, .blbundle); encrypted by default')
         .action(async (options) => {
         const { config, vault } = await resolveOptions(options);
+        const crypto = { passphrase: options.passphrase, encrypt: options.encrypt };
         if (options.all) {
             const vaults = getKnownVaults(config);
-            const result = await exportVaultsBundle(vaults, options.output ?? 'vaults.blbundle');
-            print(options.json, result, () => `Exported ${result.vaultCount} vaults (${result.fileCount} files) to ${result.file} (${result.bytes} bytes).`);
+            const result = await exportVaultsBundle(vaults, options.output ?? 'vaults.blbundle', crypto);
+            print(options.json, result, () => `Exported ${result.vaultCount} vaults (${result.fileCount} files) to ${result.file} (${result.bytes} bytes, ${result.encrypted ? 'encrypted' : 'plaintext'}).`);
             return;
         }
-        const result = await exportVaultSnapshot(vault, options.output ?? 'vault.blvault');
-        print(options.json, result, () => `Exported ${result.fileCount} files to ${result.file} (${result.bytes} bytes).`);
+        const result = await exportVaultSnapshot(vault, options.output ?? 'vault.blvault', crypto);
+        print(options.json, result, () => `Exported ${result.fileCount} files to ${result.file} (${result.bytes} bytes, ${result.encrypted ? 'encrypted' : 'plaintext'}).`);
     });
     program
         .command('vault-import')
         .argument('<file>', 'input .blvault snapshot or .blbundle')
         .option('--vault <vault>', 'target vault directory (single snapshot, or the target for --only)')
         .option('--only <vault>', 'when importing a bundle, restore only this vault (by name or recorded path)')
+        .option('--passphrase <passphrase>', 'passphrase to decrypt an encrypted snapshot/bundle')
         .option('--no-index', 'skip reindexing after import')
         .option('--json', 'print machine-readable JSON')
         .description('import a .blvault snapshot into a vault, or a .blbundle (all vaults, or one via --only)')
@@ -143,12 +147,13 @@ export const registerVaultSyncCommands = (program) => {
         const skipIndex = options.index === false;
         // Auto-detect a bundle so a single command handles both formats. --only is
         // bundle-only, so it forces the bundle path.
-        const bundleEntries = await listBundleVaults(file).catch(() => null);
+        const bundleEntries = await listBundleVaults(file, options.passphrase).catch(() => null);
         if (bundleEntries !== null || options.only !== undefined) {
             const result = await importVaultsBundle(file, {
                 only: options.only,
                 targetVault: options.only !== undefined ? options.vault : undefined,
-                skipIndex
+                skipIndex,
+                passphrase: options.passphrase
             });
             print(options.json, result, () => result.vaults
                 .map((entry) => `${entry.name} → ${entry.vault}: imported ${entry.imported} (${entry.conflicted} conflicts)`)
@@ -156,7 +161,7 @@ export const registerVaultSyncCommands = (program) => {
             return;
         }
         const { vault } = await resolveOptions(options);
-        const result = await importVaultSnapshot(file, vault, { skipIndex });
+        const result = await importVaultSnapshot(file, vault, { skipIndex, passphrase: options.passphrase });
         print(options.json, result, () => `Imported ${result.imported} files (${result.conflicted} conflicts)${result.index ? `; reindexed ${result.index.documentCount} docs` : ''}.`);
     });
 };

package/dist/cli/runtime.js

@@ -1,4 +1,5 @@
 import { autoMigrateConfiguredVaultIfChanged } from '../application/auto-migrate-configured-vault.js';
+import { maskSensitiveDeep, maskSensitiveText } from '../domain/note-safety.js';
 import { loadBrainlinkConfigWithSource, resolveAgentRuntimeDefaults } from '../infrastructure/config.js';
 import { assertVaultAllowed } from '../infrastructure/file-system-vault.js';
 export const parsePositiveInteger = (value, fallback) => {
@@ -25,6 +26,10 @@ export const resolveOptions = async (options) => {
         defaults
     };
 };
+// The CLI is a user-facing surface, so any secret stored in a note is masked
+// here before it reaches the terminal — both for `--json` (deep-masked object)
+// and human-readable output (masked rendered string). MCP tool responses go
+// through a separate path (jsonResult) and stay unmasked for agents.
 export const print = (json, value, human) => {
-    console.log(json ? JSON.stringify(value, null, 2) : human());
+    console.log(json ? JSON.stringify(maskSensitiveDeep(value), null, 2) : maskSensitiveText(human()));
 };

package/dist/domain/note-safety.js

@@ -1,38 +1,70 @@
 const maxTitleLength = 160;
 const maxContentLength = 200_000;
-const sensitivePatterns = [
+const mask = '••••••••';
+const sensitiveRules = [
     {
         label: 'private key',
-        pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/
+        pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+        mask: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+        replace: () => '[redacted: private key]'
     },
     {
         label: 'OpenAI API key',
-        pattern: /\bsk-[A-Za-z0-9_-]{20,}\b/
+        pattern: /\bsk-[A-Za-z0-9_-]{20,}\b/,
+        mask: /\bsk-[A-Za-z0-9_-]{20,}\b/g,
+        replace: () => `sk-${mask}`
     },
     {
         label: 'GitHub token',
-        pattern: /\b(?:ghp|gho|ghs|ghr|github_pat)_[A-Za-z0-9_]{20,}\b/
+        pattern: /\b(?:ghp|gho|ghs|ghr|github_pat)_[A-Za-z0-9_]{20,}\b/,
+        mask: /\b((?:ghp|gho|ghs|ghr|github_pat)_)[A-Za-z0-9_]{20,}\b/g,
+        replace: (_full, prefix) => `${prefix}${mask}`
     },
     {
         label: 'AWS access key',
-        pattern: /\bAKIA[0-9A-Z]{16}\b/
+        pattern: /\bAKIA[0-9A-Z]{16}\b/,
+        mask: /\bAKIA[0-9A-Z]{16}\b/g,
+        replace: () => `AKIA${mask}`
     },
     {
         label: 'Slack token',
-        pattern: /\bxox[abprs]-[A-Za-z0-9-]{20,}\b/
+        pattern: /\bxox[abprs]-[A-Za-z0-9-]{20,}\b/,
+        mask: /\b(xox[abprs]-)[A-Za-z0-9-]{20,}\b/g,
+        replace: (_full, prefix) => `${prefix}${mask}`
     },
     {
         label: 'JWT',
-        pattern: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/
+        pattern: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/,
+        mask: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
+        replace: () => '[redacted: JWT]'
     },
     {
         label: 'secret assignment',
-        pattern: /\b(?:api[_-]?key|secret|password|private[_-]?key|access[_-]?token|auth[_-]?token)\s*[:=]\s*["']?[A-Za-z0-9_./+=-]{12,}/i
+        pattern: /\b(?:api[_-]?key|secret|password|private[_-]?key|access[_-]?token|auth[_-]?token)\s*[:=]\s*["']?[A-Za-z0-9_./+=-]{12,}/i,
+        mask: /\b((?:api[_-]?key|secret|password|private[_-]?key|access[_-]?token|auth[_-]?token)\s*[:=]\s*["']?)[A-Za-z0-9_./+=-]{12,}/gi,
+        replace: (_full, prefix) => `${prefix}${mask}`
     }
 ];
-export const findSensitiveContent = (value) => sensitivePatterns
+export const findSensitiveContent = (value) => sensitiveRules
     .filter(({ pattern }) => pattern.test(value))
     .map(({ label }) => ({ label }));
+// Replace every recognized secret in a string with a masked marker, preserving
+// surrounding text. Used only at user-facing surfaces (CLI, graph web UI).
+export const maskSensitiveText = (value) => sensitiveRules.reduce((masked, rule) => masked.replace(rule.mask, rule.replace), value);
+// Deep-mask every string in an arbitrary JSON-serializable value. Returns a new
+// structure; the original (used to answer MCP agents) is never mutated.
+export const maskSensitiveDeep = (value) => {
+    if (typeof value === 'string') {
+        return maskSensitiveText(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => maskSensitiveDeep(item));
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, maskSensitiveDeep(item)]));
+    }
+    return value;
+};
 export const validateNoteInput = (input) => {
     if (!input.title.trim()) {
         throw new Error('Note title cannot be empty.');
@@ -46,9 +78,4 @@ export const validateNoteInput = (input) => {
     if (input.content.length > maxContentLength) {
         throw new Error(`Note content is too large. Maximum length is ${maxContentLength} characters.`);
     }
-    const findings = findSensitiveContent(`${input.title}\n${input.content}`);
-    if (findings.length > 0 && !input.allowSensitive) {
-        const labels = Array.from(new Set(findings.map((finding) => finding.label))).join(', ');
-        throw new Error(`Sensitive memory blocked (${labels}). Remove secrets or pass --allow-sensitive intentionally.`);
-    }
 };

package/dist/infrastructure/context-packs.js

@@ -155,7 +155,10 @@ export const writeContextPack = async (vaultPath, key, context, meta) => {
             }
         }
     };
-    await mkdir(contextPacksDirectory(vaultPath), { recursive: true });
-    await writeFile(path, `${JSON.stringify(stored, null, 2)}\n`, 'utf8');
+    // Context packs cache raw note/chunk content in plaintext, so keep them
+    // owner-only (0o700 dir, 0o600 file) to match the rest of the vault-on-disk
+    // hardening rather than inheriting a world-readable umask default.
+    await mkdir(contextPacksDirectory(vaultPath), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(stored, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
     return path;
 };

package/dist/infrastructure/vault-crypto.js

@@ -17,6 +17,10 @@ const keyFilePath = (vaultPath) => {
     return join(getBrainlinkHomePath(), 'keys', `vault-versioning-${vaultHash}.key`);
 };
 const deriveKeyFromSecret = (secret) => createHash('sha256').update(secret, 'utf8').digest();
+// Derive a 32-byte AES key from a user-supplied passphrase. Used for portable
+// encrypted snapshots/bundles that must decrypt on another machine carrying only
+// the passphrase (not the per-vault keyfile).
+export const deriveVaultKeyFromPassphrase = (passphrase) => deriveKeyFromSecret(passphrase);
 // Load the vault's versioning key, generating a fresh 48-byte secret on first
 // use. BRAINLINK_VAULT_KEY overrides the file (useful to restore an encrypted
 // vault on another machine by carrying just the secret, not the whole repo).

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

@@ -33,24 +33,39 @@ export const vaultRestoreInputSchema = {
 };
 export const vaultExportInputSchema = {
     ...vaultInput,
-    outputFile: z.string().min(1).describe('Path to write the portable .blvault snapshot to.')
+    outputFile: z.string().min(1).describe('Path to write the portable .blvault snapshot to.'),
+    passphrase: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Encrypt with a portable passphrase (decrypts on any machine that knows it). Omit to use the per-vault key.'),
+    encrypt: z.boolean().optional().default(true).describe('Encrypt the snapshot (AES-256-GCM). Set false for a legacy plaintext gzip snapshot.')
 };
 export const vaultImportInputSchema = {
     ...vaultInput,
     snapshotFile: z.string().min(1).describe('Path to a .blvault snapshot to import. Divergent local files are preserved as *.conflict-<ts>.md.'),
+    passphrase: z.string().min(1).optional().describe('Passphrase to decrypt an encrypted snapshot (if it was exported with one).'),
     skipIndex: z.boolean().optional().default(false).describe('Skip the automatic reindex after importing Markdown.')
 };
 export const vaultExportBundleInputSchema = {
     ...vaultInput,
-    outputFile: z.string().min(1).describe('Path to write the portable .blbundle to (contains every known vault).')
+    outputFile: z.string().min(1).describe('Path to write the portable .blbundle to (contains every known vault).'),
+    passphrase: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Encrypt with a portable passphrase. Without it (or BRAINLINK_VAULT_KEY) the bundle is written as legacy plaintext gzip.'),
+    encrypt: z.boolean().optional().default(true).describe('Encrypt the bundle when a passphrase/key is available. Set false to force plaintext gzip.')
 };
 export const vaultBundleListInputSchema = {
-    bundleFile: z.string().min(1).describe('Path to a .blbundle to inspect.')
+    bundleFile: z.string().min(1).describe('Path to a .blbundle to inspect.'),
+    passphrase: z.string().min(1).optional().describe('Passphrase to decrypt an encrypted bundle before listing its vaults.')
 };
 export const vaultImportBundleInputSchema = {
     bundleFile: z.string().min(1).describe('Path to a .blbundle to import. Divergent local files are preserved as *.conflict-<ts>.md.'),
     only: z.string().min(1).optional().describe('Restore only this vault from the bundle (by name or recorded path). Omit to restore every vault.'),
     targetVault: z.string().min(1).optional().describe('Target directory for the restored vault (only valid with "only"). Defaults to the recorded path.'),
+    passphrase: z.string().min(1).optional().describe('Passphrase to decrypt an encrypted bundle.'),
     skipIndex: z.boolean().optional().default(false).describe('Skip the automatic reindex after importing Markdown.')
 };
 export const vaultProvisionInputSchema = {
@@ -156,7 +171,11 @@ export const vaultRestoreTool = async (input) => {
 export const vaultExportTool = async (input) => {
     const context = await resolveExecutionContext(input);
     try {
-        return jsonResult({ vault: context.vault, ok: true, ...(await exportVaultSnapshot(context.vault, input.outputFile)) });
+        return jsonResult({
+            vault: context.vault,
+            ok: true,
+            ...(await exportVaultSnapshot(context.vault, input.outputFile, { passphrase: input.passphrase, encrypt: input.encrypt }))
+        });
     }
     catch (error) {
         return failure(context.vault, error);
@@ -165,7 +184,10 @@ export const vaultExportTool = async (input) => {
 export const vaultImportTool = async (input) => {
     const context = await resolveExecutionContext(input);
     try {
-        const result = await importVaultSnapshot(input.snapshotFile, context.vault, { skipIndex: input.skipIndex === true });
+        const result = await importVaultSnapshot(input.snapshotFile, context.vault, {
+            skipIndex: input.skipIndex === true,
+            passphrase: input.passphrase
+        });
         return jsonResult({
             vault: context.vault,
             ok: true,
@@ -182,7 +204,10 @@ export const vaultExportBundleTool = async (input) => {
     const context = await resolveExecutionContext(input);
     try {
         const config = await loadBrainlinkConfig();
-        const result = await exportVaultsBundle(getKnownVaults(config), input.outputFile);
+        const result = await exportVaultsBundle(getKnownVaults(config), input.outputFile, {
+            passphrase: input.passphrase,
+            encrypt: input.encrypt
+        });
         return jsonResult({ ok: true, ...result });
     }
     catch (error) {
@@ -191,7 +216,7 @@ export const vaultExportBundleTool = async (input) => {
 };
 export const vaultBundleListTool = async (input) => {
     try {
-        return jsonResult({ ok: true, bundleFile: input.bundleFile, vaults: await listBundleVaults(input.bundleFile) });
+        return jsonResult({ ok: true, bundleFile: input.bundleFile, vaults: await listBundleVaults(input.bundleFile, input.passphrase) });
     }
     catch (error) {
         return jsonResult({ ok: false, bundleFile: input.bundleFile, error: error instanceof Error ? error.message : String(error) });
@@ -202,7 +227,8 @@ export const vaultImportBundleTool = async (input) => {
         const result = await importVaultsBundle(input.bundleFile, {
             only: input.only,
             targetVault: input.targetVault,
-            skipIndex: input.skipIndex === true
+            skipIndex: input.skipIndex === true,
+            passphrase: input.passphrase
         });
         return jsonResult({ ok: true, ...result });
     }

package/package.json

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