@andespindola/brainlink 0.1.0-alpha.10 → 0.1.0-alpha.12

package/AGENTS.md

@@ -37,6 +37,8 @@ Use this loop when using Brainlink as memory:
 
 When an agent adds durable memory, it should connect the new note to at least one existing concept unless the note is intentionally a root concept. Prefer exact note titles in links, for example `[[Architecture]]`, and run `broken-links`, `orphans` or `validate` when the graph looks disconnected.
 
+Agents can mark important relationships by placing priority hints on the same line as a wiki link, for example `[[Architecture]] priority: high`, `[[Incident Runbook]] #important` or `[[Incident Runbook]] #critical`. Indexed graph edges expose `weight` and `priority` so agents can sort related notes by importance.
+
 ## Commands
 
 ```bash

package/README.md

@@ -62,10 +62,12 @@ Markdown is the source of truth. `.brainlink/brainlink.db` is only a rebuildable
 
 - Local-first Markdown vault.
 - Obsidian-compatible `[[wiki links]]` and `#tags`.
+- Weighted graph edges so agents can rank relationship importance and priority.
 - Backlinks, broken-link reports, orphan detection and validation.
 - Full-text, semantic and hybrid retrieval modes.
 - SQLite-backed semantic candidate buckets for larger vaults.
 - Agent namespaces under `agents/<agent-id>/`.
+- S3-compatible bucket vaults through `s3://bucket/prefix` URIs.
 - CLI with machine-readable `--json` output.
 - Short CLI alias: `blink`.
 - Built-in MCP stdio server for agent tool integration.
@@ -256,6 +258,36 @@ http://127.0.0.1:4321
 
 When `--vault` is omitted, commands use the default vault at `$HOME/.brainlink/vault`. Pass `--vault` or configure `vault` in `brainlink.config.json` when you want a custom project-local vault.
 
+## Bucket Vaults
+
+Brainlink can use an S3-compatible bucket as the Markdown source of truth:
+
+```bash
+export AWS_REGION="us-east-1"
+export AWS_ACCESS_KEY_ID="..."
+export AWS_SECRET_ACCESS_KEY="..."
+
+blink add "Architecture" \
+  --vault "s3://my-memory-bucket/brainlink" \
+  --content "Bucket Markdown is the source of truth. #architecture"
+
+blink index --vault "s3://my-memory-bucket/brainlink"
+blink context "architecture" --vault "s3://my-memory-bucket/brainlink"
+```
+
+For Cloudflare R2, MinIO or another S3-compatible endpoint:
+
+```bash
+export BRAINLINK_S3_ENDPOINT="https://<account-id>.r2.cloudflarestorage.com"
+export BRAINLINK_S3_FORCE_PATH_STYLE=1
+```
+
+Bucket vaults mirror Markdown into a local cache under
+`$BRAINLINK_HOME/bucket-cache`. The bucket remains canonical; the local
+`.brainlink/brainlink.db` stays a disposable index. Run `index` after remote
+bucket changes before relying on `search`, `context`, graph or validation
+commands. Watch mode is only supported for local filesystem vaults.
+
 ## Core Model
 
 ```txt
@@ -359,12 +391,21 @@ Available tools:
 - `brainlink_add_note`: write durable Markdown memory and reindex.
 - `brainlink_index`: rebuild the vault index.
 - `brainlink_validate`: validate broken links and orphan notes.
-- `brainlink_graph`: read indexed graph nodes and links.
+- `brainlink_graph`: read indexed graph nodes and weighted links.
 - `brainlink_broken_links`: list unresolved wiki links.
 - `brainlink_orphans`: list disconnected notes.
 
 The same linking rule applies through MCP: `brainlink_context` is read-only, and real graph links require Markdown notes with explicit `[[wiki links]]` followed by indexing.
 
+Agents can raise the importance of a relationship by putting priority markers on the same line as a wiki link:
+
+```md
+- [ ] Review [[Architecture]] priority: high
+Related: [[Incident Runbook]] #critical
+```
+
+Indexed edges expose `weight` and `priority` (`low`, `normal`, `high`, `critical`) through CLI JSON, HTTP graph APIs and `brainlink_graph`.
+
 ## Graph UI
 
 Start the local frontend:
@@ -378,7 +419,7 @@ By default, the server uses `$HOME/.brainlink/vault`. Pass `--vault ./vault` onl
 The graph UI shows:
 
 - notes as nodes
-- `[[wiki links]]` as edges
+- `[[wiki links]]` as weighted edges
 - backlinks and outgoing links
 - full Markdown content for the selected note
 - neutral graph nodes with segment/group metadata
@@ -492,7 +533,7 @@ blink links --vault ./vault
 blink links --vault ./vault --agent coding-agent
 ```
 
-Lists indexed wiki links.
+Lists indexed wiki links. JSON output includes `weight` and `priority` for each relationship.
 
 ### `backlinks`
 
@@ -501,7 +542,7 @@ blink backlinks "Architecture" --vault ./vault
 blink backlinks "Architecture" --vault ./vault --agent coding-agent
 ```
 
-Lists notes pointing to a target title.
+Lists notes pointing to a target title, ordered by strongest relationship first. JSON output includes `weight` and `priority`.
 
 ### `graph`
 
@@ -510,7 +551,7 @@ blink graph --vault ./vault --json
 blink graph --vault ./vault --agent coding-agent --json
 ```
 
-Prints indexed graph data.
+Prints indexed graph data. Edges include `weight` and `priority` so agents can categorize importance.
 
 ### `stats`
 
@@ -612,6 +653,12 @@ Set `BRAINLINK_ALLOWED_VAULTS` for external wrappers, including MCP servers, so
 export BRAINLINK_ALLOWED_VAULTS="/absolute/path/to/project-vault,/absolute/path/to/team-vault"
 ```
 
+Bucket vaults can be allowlisted with the same variable:
+
+```bash
+export BRAINLINK_ALLOWED_VAULTS="s3://my-memory-bucket/brainlink"
+```
+
 ## Note Format
 
 Brainlink supports Markdown with optional frontmatter:

package/SECURITY.md

@@ -32,4 +32,16 @@ External tool wrappers, including MCP servers, should set `BRAINLINK_ALLOWED_VAU
 export BRAINLINK_ALLOWED_VAULTS="/absolute/path/to/project-vault"
 ```
 
+For bucket vaults, allowlist the S3 URI prefix:
+
+```bash
+export BRAINLINK_ALLOWED_VAULTS="s3://my-memory-bucket/brainlink"
+```
+
 When the allowlist is set, CLI commands fail if `--vault` points outside the allowed roots.
+
+## Bucket Credentials
+
+Bucket vaults use the standard AWS SDK credential chain. Prefer short-lived,
+least-privilege credentials scoped to the specific bucket prefix used by
+Brainlink. Do not store bucket credentials in Markdown notes.

package/dist/application/frontend/client-js.js

@@ -83,6 +83,8 @@ const visibleEdges = () => {
   return state.edges.filter(edge => ids.has(edge.source) && edge.target && ids.has(edge.target))
 }
 
+const edgeWeight = edge => Number.isFinite(edge.weight) ? Math.max(1, edge.weight) : 1
+
 const resetView = () => {
   const rect = canvas.getBoundingClientRect()
   state.transform = { x: Math.max(rect.width, 320) / 2, y: Math.max(rect.height, 320) / 2, scale: 1 }
@@ -103,7 +105,7 @@ const createLayout = graph => {
 
 const graphSignature = graph => JSON.stringify({
   nodes: graph.nodes.map(node => [node.id, node.title, node.path, node.content, node.tags]),
-  edges: graph.edges.map(edge => [edge.source, edge.target, edge.targetTitle])
+  edges: graph.edges.map(edge => [edge.source, edge.target, edge.targetTitle, edge.weight, edge.priority])
 })
 
 const tick = delta => {
@@ -207,7 +209,7 @@ const render = now => {
     ctx.moveTo(edge.sourceNode.x, edge.sourceNode.y)
     ctx.lineTo(edge.targetNode.x, edge.targetNode.y)
     ctx.strokeStyle = selectedEdge ? graphTheme.edgeActive : graphTheme.edge
-    ctx.lineWidth = selectedEdge ? 1.8 : 1
+    ctx.lineWidth = (selectedEdge ? 1.8 : 1) + Math.min(edgeWeight(edge) - 1, 8) * 0.22
     ctx.stroke()
   })
 
@@ -241,7 +243,7 @@ const render = now => {
 }
 
 const list = items => items.length
-  ? items.map(item => '<li>' + (item.id ? '<button type="button" data-node-id="' + escapeHtml(item.id) + '">' + escapeHtml(item.title) + '</button>' : escapeHtml(item.title)) + '<small>' + escapeHtml(item.path) + '</small></li>').join('')
+  ? items.map(item => '<li>' + (item.id ? '<button type="button" data-node-id="' + escapeHtml(item.id) + '">' + escapeHtml(item.title) + '</button>' : escapeHtml(item.title)) + '<small>' + escapeHtml(item.path) + (item.weight ? ' · weight ' + escapeHtml(item.weight) + ' · ' + escapeHtml(item.priority || 'normal') : '') + '</small></li>').join('')
   : '<li><small>No links found.</small></li>'
 
 const allNotesList = () => state.nodes.length
@@ -261,13 +263,18 @@ const selectNode = node => {
     return
   }
   const nodeById = new Map(state.nodes.map(item => [item.id, item]))
+  const withEdgeMeta = (linkedNode, edge) => linkedNode ? {
+    ...linkedNode,
+    weight: edge.weight,
+    priority: edge.priority
+  } : null
   const outgoing = state.graph.edges
     .filter(edge => edge.source === node.id)
-    .map(edge => edge.target ? nodeById.get(edge.target) : { title: edge.targetTitle + ' (unresolved)', path: 'Missing note' })
+    .map(edge => withEdgeMeta(edge.target ? nodeById.get(edge.target) : { title: edge.targetTitle + ' (unresolved)', path: 'Missing note' }, edge))
     .filter(Boolean)
   const incoming = state.graph.edges
     .filter(edge => edge.target === node.id)
-    .map(edge => nodeById.get(edge.source))
+    .map(edge => withEdgeMeta(nodeById.get(edge.source), edge))
     .filter(Boolean)
 
   elements.title.textContent = node.title

package/dist/application/watch-vault.js

@@ -1,6 +1,6 @@
 import { watch } from 'node:fs';
 import { indexVault } from './index-vault.js';
-import { resolveVaultPath } from '../infrastructure/file-system-vault.js';
+import { isBucketVaultPath, resolveVaultPath } from '../infrastructure/file-system-vault.js';
 const shouldIgnore = (filename) => {
     if (!filename) {
         return false;
@@ -8,6 +8,9 @@ const shouldIgnore = (filename) => {
     return filename.includes('.brainlink') || !filename.endsWith('.md');
 };
 export const startVaultWatcher = (input) => {
+    if (isBucketVaultPath(input.vaultPath)) {
+        throw new Error('Watch mode is only supported for local filesystem vaults.');
+    }
     const absoluteVaultPath = resolveVaultPath(input.vaultPath);
     const debounceMs = input.debounceMs ?? 350;
     let timeout = null;

package/dist/domain/graph-layout.js

@@ -34,8 +34,17 @@ const groupKey = (node) => {
     return segments[0] ?? 'root';
 };
 const groupLabel = (key) => groupLabels[key] ?? key;
-const incrementDegree = (degrees, id) => new Map([...degrees, [id, (degrees.get(id) ?? 0) + 1]]);
-const countDegrees = (edges) => edges.reduce((degrees, edge) => (edge.target ? incrementDegree(incrementDegree(degrees, edge.source), edge.target) : incrementDegree(degrees, edge.source)), new Map());
+const incrementDegreeBy = (degrees, id, amount) => {
+    degrees.set(id, (degrees.get(id) ?? 0) + amount);
+    return degrees;
+};
+const edgeDegreeWeight = (edge) => Math.max(1, Math.min(edge.weight, 8));
+const countDegrees = (edges) => edges.reduce((degrees, edge) => {
+    const weight = edgeDegreeWeight(edge);
+    return edge.target
+        ? incrementDegreeBy(incrementDegreeBy(degrees, edge.source, weight), edge.target, weight)
+        : incrementDegreeBy(degrees, edge.source, weight);
+}, new Map());
 const uniqueIds = (ids) => Array.from(new Set(ids));
 const createAdjacency = (nodes, edges) => {
     const nodeIds = new Set(nodes.map((node) => node.id));

package/dist/domain/markdown.js

@@ -6,8 +6,31 @@ const frontmatterPattern = /^---\n([\s\S]*?)\n---\n?/;
 const wikiLinkPattern = /\[\[([^\]|#]+)(?:#[^\]|]+)?(?:\|[^\]]+)?\]\]/g;
 const tagPattern = /(^|\s)#([A-Za-z0-9][A-Za-z0-9_-]*)/g;
 const headingPattern = /^#\s+(.+)$/m;
+const priorityRanks = {
+    low: 0,
+    normal: 1,
+    high: 2,
+    critical: 3
+};
+const priorityBoosts = {
+    low: 0,
+    normal: 1,
+    high: 3,
+    critical: 6
+};
+const priorityPatterns = [
+    ['critical', /\b(?:priority|prioridade|importance|importancia|importância)\s*[:=]\s*(?:critical|critica|crítica|urgent|urgente|p0)\b/i],
+    ['critical', /#(?:critical|critica|crítica|urgent|urgente|p0)\b/i],
+    ['high', /\b(?:priority|prioridade|importance|importancia|importância)\s*[:=]\s*(?:high|alta|important|importante|p1)\b/i],
+    ['high', /#(?:high-priority|important|importante|p1)\b/i],
+    ['normal', /\b(?:priority|prioridade|importance|importancia|importância)\s*[:=]\s*(?:normal|medium|media|média|p2)\b/i],
+    ['normal', /#(?:normal-priority|medium-priority|p2)\b/i],
+    ['low', /\b(?:priority|prioridade|importance|importancia|importância)\s*[:=]\s*(?:low|baixa|p3)\b/i],
+    ['low', /#(?:low-priority|baixa-prioridade|p3)\b/i]
+];
 const normalizeTitle = (title) => title.trim().replace(/\.md$/i, '');
 const unique = (values) => Array.from(new Set(values.map((value) => value.trim()).filter(Boolean)));
+const maxPriority = (left, right) => priorityRanks[left] >= priorityRanks[right] ? left : right;
 const parseFrontmatter = (content) => {
     const match = content.match(frontmatterPattern);
     if (!match) {
@@ -24,6 +47,57 @@ const parseFrontmatter = (content) => {
 };
 const stripFrontmatter = (content) => content.replace(frontmatterPattern, '');
 const stripFencedCodeBlocks = (content) => content.replace(/```[\s\S]*?```/g, '').replace(/~~~[\s\S]*?~~~/g, '');
+const visibleMarkdownLines = (content) => content.split('\n').reduce((state, line) => {
+    const togglesFence = /^\s*(?:```|~~~)/.test(line);
+    const fenced = togglesFence ? !state.fenced : state.fenced;
+    state.lines.push({ content: line, fenced });
+    return {
+        lines: state.lines,
+        fenced
+    };
+}, {
+    lines: [],
+    fenced: false
+}).lines;
+const linePriority = (line) => priorityPatterns.find(([, pattern]) => pattern.test(line))?.[0] ?? null;
+const linkReferenceWeight = (line, priority) => {
+    const headingBoost = /^\s{0,3}#{1,6}\s+/.test(line) ? 2 : 0;
+    const taskBoost = /^\s*[-*]\s+\[[ x]\]/i.test(line) ? 1 : 0;
+    return 1 + (priority ? priorityBoosts[priority] : 0) + headingBoost + taskBoost;
+};
+export const extractWikiLinkReferences = (content) => visibleMarkdownLines(content)
+    .filter((line) => !line.fenced)
+    .flatMap((line) => {
+    const priority = linePriority(line.content);
+    const weight = linkReferenceWeight(line.content, priority);
+    return Array.from(line.content.matchAll(wikiLinkPattern), (match) => ({
+        title: normalizeTitle(match[1]),
+        weight,
+        priority
+    }));
+});
+const priorityFromWeight = (weight) => weight >= 8 ? 'critical' : weight >= 4 ? 'high' : 'normal';
+export const extractWikiLinkWeights = (content) => {
+    const weights = extractWikiLinkReferences(content).reduce((state, reference) => {
+        const titleKey = reference.title.toLowerCase();
+        const current = state.get(titleKey);
+        const weight = (current?.weight ?? 0) + reference.weight;
+        const explicitPriority = reference.priority
+            ? maxPriority(current?.priority ?? reference.priority, reference.priority)
+            : current?.priority;
+        const derivedPriority = priorityFromWeight(weight);
+        const priority = explicitPriority === 'low' && weight === 1
+            ? 'low'
+            : maxPriority(explicitPriority ?? derivedPriority, derivedPriority);
+        state.set(titleKey, {
+            title: current?.title ?? reference.title,
+            weight,
+            priority
+        });
+        return state;
+    }, new Map());
+    return Array.from(weights.values());
+};
 const extractTitle = (filePath, content, frontmatter) => {
     if (frontmatter.title) {
         return normalizeTitle(frontmatter.title);
@@ -34,7 +108,7 @@ const extractTitle = (filePath, content, frontmatter) => {
     }
     return normalizeTitle(basename(filePath));
 };
-export const extractWikiLinks = (content) => unique(Array.from(stripFencedCodeBlocks(content).matchAll(wikiLinkPattern), (match) => normalizeTitle(match[1])));
+export const extractWikiLinks = (content) => unique(extractWikiLinkReferences(content).map((reference) => reference.title));
 export const extractTags = (content) => unique(Array.from(stripFencedCodeBlocks(content).matchAll(tagPattern), (match) => match[2]));
 const normalizeChunkContent = (content) => content
     .split('\n')
@@ -87,10 +161,13 @@ export const parseMarkdownDocument = (input) => {
 };
 export const createIndexedDocument = (document, titleToDocumentId, maxChunkCharacters = 1200) => {
     const chunks = splitIntoChunks(document.id, document.content, maxChunkCharacters);
+    const linkWeights = new Map(extractWikiLinkWeights(document.content).map((link) => [link.title.toLowerCase(), link]));
     const links = document.links.map((toTitle) => ({
         fromDocumentId: document.id,
         toTitle,
-        toDocumentId: titleToDocumentId.get(toTitle.toLowerCase()) ?? null
+        toDocumentId: titleToDocumentId.get(toTitle.toLowerCase()) ?? null,
+        weight: linkWeights.get(toTitle.toLowerCase())?.weight ?? 1,
+        priority: linkWeights.get(toTitle.toLowerCase())?.priority ?? 'normal'
     }));
     return {
         document,

package/dist/infrastructure/bucket-vault.js

@@ -0,0 +1,171 @@
+import { GetObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+import { posix } from 'node:path';
+import { getBrainlinkHomePath } from './paths.js';
+const directoryMode = 0o700;
+const fileMode = 0o600;
+const bucketScheme = 's3:';
+const manifestPath = '.brainlink/bucket-manifest.json';
+const excludedSegments = new Set(['.brainlink', '.git', 'node_modules', 'dist']);
+export const isBucketVaultUri = (value) => value.trim().toLowerCase().startsWith('s3://');
+const trimSlashes = (value) => value.replace(/^\/+|\/+$/g, '');
+const normalizePrefix = (value) => trimSlashes(posix.normalize(trimSlashes(value))).replace(/^\.$/, '');
+export const parseBucketVaultUri = (uri) => {
+    const parsed = new URL(uri);
+    if (parsed.protocol !== bucketScheme || !parsed.hostname) {
+        throw new Error(`Unsupported bucket vault URI: ${uri}. Use s3://bucket/prefix.`);
+    }
+    return {
+        uri: formatBucketVaultUri(parsed.hostname, normalizePrefix(decodeURIComponent(parsed.pathname))),
+        bucket: parsed.hostname,
+        prefix: normalizePrefix(decodeURIComponent(parsed.pathname))
+    };
+};
+export const formatBucketVaultUri = (bucket, prefix) => prefix ? `s3://${bucket}/${prefix}` : `s3://${bucket}`;
+export const getBucketVaultCachePath = (uri) => {
+    const hash = createHash('sha256').update(parseBucketVaultUri(uri).uri).digest('hex').slice(0, 24);
+    return join(getBrainlinkHomePath(), 'bucket-cache', hash);
+};
+const ensureDirectory = async (path) => {
+    await mkdir(path, { recursive: true, mode: directoryMode });
+    await chmod(path, directoryMode);
+};
+const isPathInside = (parent, child) => {
+    const path = relative(parent, child);
+    return path === '' || (!path.startsWith('..') && !isAbsolute(path));
+};
+const toSafeRelativePath = (key) => {
+    const normalized = normalizePrefix(key);
+    if (!normalized || normalized.split('/').some((segment) => segment === '..' || excludedSegments.has(segment))) {
+        return null;
+    }
+    return normalized.endsWith('.md') ? normalized : null;
+};
+const toObjectKey = (reference, relativePath) => reference.prefix ? `${reference.prefix}/${relativePath}` : relativePath;
+const toRelativeObjectKey = (reference, objectKey) => {
+    const relativePath = reference.prefix
+        ? objectKey.startsWith(`${reference.prefix}/`)
+            ? objectKey.slice(reference.prefix.length + 1)
+            : null
+        : objectKey;
+    return relativePath ? toSafeRelativePath(relativePath) : null;
+};
+const createBucketClient = () => new S3Client({
+    region: process.env.AWS_REGION ?? process.env.BRAINLINK_S3_REGION ?? 'us-east-1',
+    endpoint: process.env.BRAINLINK_S3_ENDPOINT ?? process.env.AWS_ENDPOINT_URL,
+    forcePathStyle: process.env.BRAINLINK_S3_FORCE_PATH_STYLE === '1'
+});
+const streamToString = async (body) => {
+    if (body && typeof body === 'object' && 'transformToString' in body && typeof body.transformToString === 'function') {
+        return body.transformToString();
+    }
+    throw new Error('Unsupported S3 object body.');
+};
+const readManifest = async (cachePath) => {
+    try {
+        return JSON.parse(await readFile(join(cachePath, manifestPath), 'utf8'));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return {
+                uri: '',
+                keys: []
+            };
+        }
+        throw error;
+    }
+};
+const writeManifest = async (cachePath, manifest) => {
+    const path = join(cachePath, manifestPath);
+    await ensureDirectory(dirname(path));
+    await writeFile(path, `${JSON.stringify(manifest, null, 2)}\n`, { encoding: 'utf8', mode: fileMode });
+    await chmod(path, fileMode);
+};
+const listBucketMarkdownKeys = async (client, reference) => {
+    const keys = [];
+    let continuationToken;
+    do {
+        const result = await client.send(new ListObjectsV2Command({
+            Bucket: reference.bucket,
+            Prefix: reference.prefix ? `${reference.prefix}/` : undefined,
+            ContinuationToken: continuationToken
+        }));
+        keys.push(...(result.Contents ?? []).flatMap((object) => (object.Key ? [object.Key] : [])));
+        continuationToken = result.NextContinuationToken;
+    } while (continuationToken);
+    return keys.flatMap((key) => {
+        const relativePath = toRelativeObjectKey(reference, key);
+        return relativePath ? [relativePath] : [];
+    });
+};
+const removeStaleCachedFiles = async (cachePath, previousKeys, currentKeys) => {
+    await Promise.all(previousKeys
+        .filter((key) => !currentKeys.has(key))
+        .map(async (key) => {
+        const absolutePath = join(cachePath, key);
+        if (isPathInside(cachePath, absolutePath)) {
+            await rm(absolutePath, { force: true });
+        }
+    }));
+};
+const downloadMarkdownFiles = async (client, reference, cachePath, keys) => {
+    await Promise.all(keys.map(async (key) => {
+        const absolutePath = join(cachePath, key);
+        if (!isPathInside(cachePath, absolutePath)) {
+            throw new Error(`Refusing to cache bucket object outside vault cache: ${key}`);
+        }
+        const result = await client.send(new GetObjectCommand({
+            Bucket: reference.bucket,
+            Key: toObjectKey(reference, key)
+        }));
+        await ensureDirectory(dirname(absolutePath));
+        await writeFile(absolutePath, await streamToString(result.Body), { encoding: 'utf8', mode: fileMode });
+        await chmod(absolutePath, fileMode);
+    }));
+};
+export const syncBucketVaultToCache = async (uri) => {
+    const reference = parseBucketVaultUri(uri);
+    const cachePath = getBucketVaultCachePath(reference.uri);
+    const client = createBucketClient();
+    const previousManifest = await readManifest(cachePath);
+    const keys = await listBucketMarkdownKeys(client, reference);
+    const currentKeys = new Set(keys);
+    await ensureDirectory(join(cachePath, '.brainlink'));
+    await removeStaleCachedFiles(cachePath, previousManifest.uri === reference.uri ? previousManifest.keys : [], currentKeys);
+    await downloadMarkdownFiles(client, reference, cachePath, keys);
+    await writeManifest(cachePath, {
+        uri: reference.uri,
+        keys
+    });
+    return cachePath;
+};
+export const writeBucketMarkdownFile = async (uri, filename, content) => {
+    const reference = parseBucketVaultUri(uri);
+    const cachePath = getBucketVaultCachePath(reference.uri);
+    const relativePath = toSafeRelativePath(filename.endsWith('.md') ? filename : `${filename}.md`);
+    if (!relativePath) {
+        throw new Error(`Invalid bucket Markdown path: ${filename}`);
+    }
+    const absolutePath = join(cachePath, relativePath);
+    if (!isPathInside(cachePath, absolutePath)) {
+        throw new Error(`Refusing to write outside bucket cache: ${absolutePath}`);
+    }
+    await ensureDirectory(join(cachePath, '.brainlink'));
+    await ensureDirectory(dirname(absolutePath));
+    await writeFile(absolutePath, content, { encoding: 'utf8', mode: fileMode });
+    await chmod(absolutePath, fileMode);
+    await createBucketClient().send(new PutObjectCommand({
+        Bucket: reference.bucket,
+        Key: toObjectKey(reference, relativePath),
+        Body: content,
+        ContentType: 'text/markdown; charset=utf-8'
+    }));
+    const manifest = await readManifest(cachePath);
+    await writeManifest(cachePath, {
+        uri: reference.uri,
+        keys: Array.from(new Set([...manifest.keys, relativePath])).sort()
+    });
+    return `${reference.uri}/${relativePath}`;
+};

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

@@ -1,6 +1,7 @@
 import { chmod, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
 import { resolvePath } from './paths.js';
+import { getBucketVaultCachePath, isBucketVaultUri, parseBucketVaultUri, syncBucketVaultToCache, writeBucketMarkdownFile } from './bucket-vault.js';
 const excludedDirectories = new Set(['.brainlink', '.git', 'node_modules', 'dist']);
 const directoryMode = 0o700;
 const fileMode = 0o600;
@@ -15,30 +16,44 @@ const walkMarkdownFiles = async (directory) => {
     }));
     return nested.flat();
 };
-export const resolveVaultPath = (vaultPath) => resolvePath(vaultPath);
+export const resolveVaultPath = (vaultPath) => isBucketVaultUri(vaultPath) ? getBucketVaultCachePath(vaultPath) : resolvePath(vaultPath);
+export const isBucketVaultPath = (vaultPath) => isBucketVaultUri(vaultPath);
 const isPathInside = (parent, child) => {
     const path = relative(parent, child);
     return path === '' || (!path.startsWith('..') && !isAbsolute(path));
 };
+const isBucketPrefixInside = (parent, child) => parent === '' || child === parent || child.startsWith(`${parent}/`);
 const secureDirectory = async (path) => {
     await mkdir(path, { recursive: true, mode: directoryMode });
     await chmod(path, directoryMode);
 };
 export const assertVaultAllowed = (vaultPath, allowedVaults) => {
+    if (isBucketVaultUri(vaultPath)) {
+        const vault = parseBucketVaultUri(vaultPath);
+        const allowed = allowedVaults.filter(isBucketVaultUri).map(parseBucketVaultUri);
+        if (allowedVaults.length > 0 &&
+            !allowed.some((allowedVault) => vault.bucket === allowedVault.bucket && isBucketPrefixInside(allowedVault.prefix, vault.prefix))) {
+            throw new Error(`Vault path is not allowed: ${vault.uri}. Configure BRAINLINK_ALLOWED_VAULTS or allowedVaults.`);
+        }
+        return vault.uri;
+    }
     const absoluteVaultPath = resolveVaultPath(vaultPath);
-    const allowed = allowedVaults.map(resolveVaultPath);
+    const allowed = allowedVaults.filter((allowedVault) => !isBucketVaultUri(allowedVault)).map(resolveVaultPath);
     if (allowed.length > 0 && !allowed.some((allowedPath) => isPathInside(allowedPath, absoluteVaultPath))) {
         throw new Error(`Vault path is not allowed: ${absoluteVaultPath}. Configure BRAINLINK_ALLOWED_VAULTS or allowedVaults.`);
     }
     return absoluteVaultPath;
 };
 export const ensureVault = async (vaultPath) => {
+    if (isBucketVaultUri(vaultPath)) {
+        return syncBucketVaultToCache(vaultPath);
+    }
     const absoluteVaultPath = resolveVaultPath(vaultPath);
     await secureDirectory(join(absoluteVaultPath, '.brainlink'));
     return absoluteVaultPath;
 };
 export const readMarkdownFiles = async (vaultPath) => {
-    const absoluteVaultPath = resolveVaultPath(vaultPath);
+    const absoluteVaultPath = await ensureVault(vaultPath);
     const paths = await walkMarkdownFiles(absoluteVaultPath);
     return Promise.all(paths.map(async (absolutePath) => {
         const [content, stats] = await Promise.all([readFile(absolutePath, 'utf8'), stat(absolutePath)]);
@@ -51,6 +66,9 @@ export const readMarkdownFiles = async (vaultPath) => {
     }));
 };
 export const writeMarkdownFile = async (vaultPath, filename, content) => {
+    if (isBucketVaultUri(vaultPath)) {
+        return writeBucketMarkdownFile(vaultPath, filename, content);
+    }
     const absoluteVaultPath = await ensureVault(vaultPath);
     const absolutePath = resolve(absoluteVaultPath, filename.endsWith('.md') ? filename : `${filename}.md`);
     if (!isPathInside(absoluteVaultPath, absolutePath)) {

package/dist/infrastructure/sqlite/document-writer.js

@@ -1,4 +1,5 @@
 import { createEmbeddingBuckets } from '../../domain/embeddings.js';
+const toTitleKey = (title) => title.toLowerCase();
 export const createIndexWriter = (database) => ({
     reset: () => {
         database.exec(`
@@ -27,8 +28,8 @@ export const createIndexWriter = (database) => ({
       VALUES (?, ?)
     `);
         const insertLink = database.prepare(`
-      INSERT INTO links (from_document_id, to_title, to_document_id)
-      VALUES (?, ?, ?)
+      INSERT INTO links (from_document_id, to_title, to_title_key, to_document_id, weight, priority)
+      VALUES (?, ?, ?, ?, ?, ?)
     `);
         const transaction = database.transaction(() => {
             documents.forEach(({ document, chunks, links }) => {
@@ -41,7 +42,7 @@ export const createIndexWriter = (database) => ({
             });
             documents.forEach(({ links }) => {
                 links.forEach((link) => {
-                    insertLink.run(link.fromDocumentId, link.toTitle, link.toDocumentId);
+                    insertLink.run(link.fromDocumentId, link.toTitle, toTitleKey(link.toTitle), link.toDocumentId, link.weight, link.priority);
                 });
             });
         });

package/dist/infrastructure/sqlite/graph-reader.js

@@ -4,9 +4,12 @@ const toGraphLink = (row) => ({
     fromTitle: row.from_title,
     fromPath: row.from_path,
     toTitle: row.to_title,
-    toPath: row.to_path
+    toPath: row.to_path,
+    weight: row.weight,
+    priority: row.priority
 });
 const normalizeAgentFilter = (agentId) => agentId ? sanitizeAgentId(agentId) : undefined;
+const toTitleKey = (title) => title.toLowerCase();
 export const createGraphReader = (database) => ({
     listLinks: (agentId) => {
         const normalizedAgentId = normalizeAgentFilter(agentId);
@@ -18,12 +21,14 @@ export const createGraphReader = (database) => ({
             source.title AS from_title,
             source.path AS from_path,
             COALESCE(target.title, links.to_title) AS to_title,
-            target.path AS to_path
+            target.path AS to_path,
+            links.weight AS weight,
+            links.priority AS priority
           FROM links
           JOIN documents source ON source.id = links.from_document_id
           LEFT JOIN documents target ON target.id = links.to_document_id
           ${agentFilter}
-          ORDER BY source.title, to_title
+          ORDER BY source.title, links.weight DESC, to_title
         `)
             .all(...(normalizedAgentId ? [normalizedAgentId] : []));
         return rows.map(toGraphLink);
@@ -31,6 +36,7 @@ export const createGraphReader = (database) => ({
     listBacklinks: (title, agentId) => {
         const normalizedAgentId = normalizeAgentFilter(agentId);
         const agentFilter = normalizedAgentId ? 'AND source.agent_id = ?' : '';
+        const titleKey = toTitleKey(title);
         const rows = database
             .prepare(`
           SELECT
@@ -38,15 +44,17 @@ export const createGraphReader = (database) => ({
             source.title AS from_title,
             source.path AS from_path,
             COALESCE(target.title, links.to_title) AS to_title,
-            target.path AS to_path
+            target.path AS to_path,
+            links.weight AS weight,
+            links.priority AS priority
           FROM links
           JOIN documents source ON source.id = links.from_document_id
           LEFT JOIN documents target ON target.id = links.to_document_id
-          WHERE (lower(links.to_title) = lower(?) OR lower(target.title) = lower(?))
+          WHERE links.to_title_key = ?
           ${agentFilter}
-          ORDER BY source.title
+          ORDER BY links.weight DESC, source.title
         `)
-            .all(...(normalizedAgentId ? [title, title, normalizedAgentId] : [title, title]));
+            .all(...(normalizedAgentId ? [titleKey, normalizedAgentId] : [titleKey]));
         return rows.map(toGraphLink);
     },
     getGraph: (agentId) => {
@@ -66,11 +74,13 @@ export const createGraphReader = (database) => ({
           SELECT
             links.from_document_id AS source,
             links.to_document_id AS target,
-            links.to_title AS target_title
+            links.to_title AS target_title,
+            links.weight AS weight,
+            links.priority AS priority
           FROM links
           JOIN documents source ON source.id = links.from_document_id
           ${edgeAgentFilter}
-          ORDER BY links.from_document_id, links.to_title
+          ORDER BY links.from_document_id, links.weight DESC, links.to_title
         `)
             .all(...(normalizedAgentId ? [normalizedAgentId] : []));
         const nodes = nodeRows.map((row) => ({
@@ -84,7 +94,9 @@ export const createGraphReader = (database) => ({
         const edges = edgeRows.map((row) => ({
             source: row.source,
             target: row.target,
-            targetTitle: row.target_title
+            targetTitle: row.target_title,
+            weight: row.weight,
+            priority: row.priority
         }));
         return {
             nodes,

package/dist/infrastructure/sqlite/schema.js

@@ -1,7 +1,8 @@
-const schemaVersion = 4;
+const schemaVersion = 5;
 const requiredTableColumns = {
     documents: ['id', 'agent_id', 'title', 'path', 'content', 'tags_json', 'frontmatter_json', 'created_at', 'updated_at'],
     chunks: ['id', 'document_id', 'ordinal', 'content', 'token_count', 'embedding_provider', 'embedding_json'],
+    links: ['from_document_id', 'to_title', 'to_title_key', 'to_document_id', 'weight', 'priority'],
     chunks_fts: ['chunk_id', 'document_id', 'agent_id', 'title', 'content']
 };
 const getStoredSchemaVersion = (database) => {
@@ -65,6 +66,9 @@ export const createSchema = (database) => {
       FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE CASCADE
     );
 
+    CREATE INDEX IF NOT EXISTS idx_documents_agent_title ON documents(agent_id, title);
+    CREATE INDEX IF NOT EXISTS idx_chunks_document_ordinal ON chunks(document_id, ordinal);
+
     CREATE TABLE IF NOT EXISTS embedding_buckets (
       bucket TEXT NOT NULL,
       chunk_id TEXT NOT NULL,
@@ -77,11 +81,18 @@ export const createSchema = (database) => {
     CREATE TABLE IF NOT EXISTS links (
       from_document_id TEXT NOT NULL,
       to_title TEXT NOT NULL,
+      to_title_key TEXT NOT NULL,
       to_document_id TEXT,
+      weight INTEGER NOT NULL,
+      priority TEXT NOT NULL,
+      PRIMARY KEY (from_document_id, to_title_key),
       FOREIGN KEY (from_document_id) REFERENCES documents(id) ON DELETE CASCADE,
       FOREIGN KEY (to_document_id) REFERENCES documents(id) ON DELETE SET NULL
     );
 
+    CREATE INDEX IF NOT EXISTS idx_links_to_document_id ON links(to_document_id);
+    CREATE INDEX IF NOT EXISTS idx_links_to_title_key ON links(to_title_key);
+
     CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
       chunk_id UNINDEXED,
       document_id UNINDEXED,

package/dist/infrastructure/sqlite-index.js

@@ -9,7 +9,12 @@ export const openSqliteIndex = (vaultPath) => {
     const databasePath = join(vaultPath, '.brainlink', 'brainlink.db');
     const database = new Database(databasePath);
     chmodSync(databasePath, 0o600);
-    database.exec('PRAGMA foreign_keys = ON;');
+    database.exec(`
+    PRAGMA foreign_keys = ON;
+    PRAGMA journal_mode = WAL;
+    PRAGMA synchronous = NORMAL;
+    PRAGMA temp_store = MEMORY;
+  `);
     createSchema(database);
     return {
         ...createIndexWriter(database),

package/dist/mcp/server.js

@@ -27,7 +27,7 @@ export const createBrainlinkMcpServer = () => {
     }, searchTool);
     server.registerTool('brainlink_add_note', {
         title: 'Add Brainlink Note',
-        description: 'Write durable Markdown memory, then reindex the vault. Include explicit [[wiki links]] for connected graph memory.',
+        description: 'Write durable Markdown memory, then reindex the vault. Include explicit [[wiki links]] for connected graph memory. Add priority markers near links, such as priority: high, #important or #critical, when a relationship should be weighted higher.',
         inputSchema: addNoteInputSchema
     }, addNoteTool);
     server.registerTool('brainlink_index', {
@@ -42,7 +42,7 @@ export const createBrainlinkMcpServer = () => {
     }, validateTool);
     server.registerTool('brainlink_graph', {
         title: 'Read Brainlink Graph',
-        description: 'Read indexed graph nodes and wiki-link edges.',
+        description: 'Read indexed graph nodes and wiki-link edges. Edges include weight and priority fields so agents can rank importance and priority.',
         inputSchema: graphInputSchema
     }, graphTool);
     server.registerTool('brainlink_broken_links', {

package/dist/mcp/tools.js

@@ -57,7 +57,7 @@ export const addNoteInputSchema = {
     content: z
         .string()
         .min(1)
-        .describe('Durable Markdown memory. Include explicit [[wiki links]] and #tags when the memory should be connected.'),
+        .describe('Durable Markdown memory. Include explicit [[wiki links]] and #tags when the memory should be connected. Put priority markers near important links, for example priority: high, #important or #critical.'),
     agent: z.string().min(1).optional().default('shared').describe('Agent memory namespace. Defaults to shared.'),
     allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.')
 };

package/docs/AGENT_USAGE.md

@@ -133,6 +133,7 @@ Rules:
 
 - Use a clear title.
 - Use `[[Note Title]]` for relationships.
+- Put priority markers near links when the relationship is important.
 - Use tags for retrieval.
 - Keep each note focused.
 - Prefer summaries over raw transcripts.
@@ -144,6 +145,15 @@ Brainlink only builds graph edges from Markdown `[[wiki links]]`.
 
 The `context` command is read-only. It retrieves indexed notes and returns a compact package for the model, but it does not write memory, create backlinks, infer relationships or modify the graph. If an agent reads context and then learns something durable, the agent must write a note with explicit links before that knowledge becomes connected memory.
 
+Graph edges are weighted during indexing. Repeated links increase weight. Links inside headings or task-list lines receive a small boost. Priority markers on the same line as a link raise its priority:
+
+```md
+- [ ] Review [[Architecture]] priority: high
+Related: [[Incident Runbook]] #critical
+```
+
+Agents should use weighted graph output to sort relationships by importance. Edges expose `weight` and `priority`, where priority is one of `low`, `normal`, `high` or `critical`.
+
 Required write behavior:
 
 1. Choose a clear title for the new note.
@@ -464,6 +474,8 @@ Available MCP tools:
 
 MCP clients can pass `vault` and `agent` arguments per tool call. Set `BRAINLINK_ALLOWED_VAULTS` when exposing Brainlink to an external agent process so a tool cannot pass arbitrary vault paths:
 
+`brainlink_graph` returns weighted edges. Agents should prefer higher `weight` and stronger `priority` when deciding which related notes matter most.
+
 ```bash
 export BRAINLINK_ALLOWED_VAULTS="/absolute/path/to/project-vault"
 ```
@@ -552,4 +564,5 @@ Weak retrieval usually means:
 - Local embeddings are deterministic and provider-free; remote embedding providers are not implemented yet.
 - MCP integration is available through the `brainlink-mcp` stdio server.
 - HTTP API is local and unauthenticated.
-- Watch mode depends on platform filesystem watcher behavior.
+- Bucket vaults support S3-compatible `s3://bucket/prefix` URIs and use a local cache for SQLite indexes.
+- Watch mode depends on platform filesystem watcher behavior and is only supported for local filesystem vaults.

package/docs/ARCHITECTURE.md

@@ -105,13 +105,15 @@ Application code depends on domain rules and infrastructure interfaces.
 The infrastructure layer handles side effects:
 
 - reading Markdown files from disk
+- mirroring S3-compatible bucket Markdown into a local cache
 - writing Markdown notes
 - creating `.brainlink`
 - writing and querying SQLite
 - running FTS, semantic and hybrid retrieval
 - narrowing semantic candidates through SQLite embedding buckets before cosine scoring
 
-SQLite is an index, not the canonical storage model.
+SQLite is an index, not the canonical storage model. For bucket vaults, Markdown
+objects in the bucket remain canonical and SQLite is still local derived data.
 
 ## Indexing Flow
 
@@ -216,6 +218,23 @@ source note -> target note
 
 The `backlinks` command queries indexed links pointing to a target title. With `--agent`, it only returns links from that namespace.
 
+## Weighted Links
+
+Each indexed wiki link is stored as a graph edge with:
+
+- `weight`: numeric relationship strength.
+- `priority`: one of `low`, `normal`, `high` or `critical`.
+
+The parser derives weight from repeated links, task-list context, heading context and priority markers on the same line as a wiki link. Examples:
+
+```md
+Related: [[Architecture]]
+- [ ] Review [[Architecture]] priority: high
+Escalate [[Incident Runbook]] #critical
+```
+
+Backlink and graph readers return those fields to CLI JSON, HTTP API and MCP clients. Backlink queries use the normalized `to_title_key` column instead of applying `lower(...)` at read time.
+
 ## Context Building
 
 `context` uses search results and selects one chunk per document while staying inside an estimated token budget.
@@ -240,6 +259,7 @@ Relevant content
 Permanent:
 
 - Markdown files
+- S3-compatible Markdown objects when the vault is `s3://bucket/prefix`
 - optional Git history around the vault
 
 Canonical agent memory lives under:
@@ -251,6 +271,7 @@ vault/agents/<agent-id>/**/*.md
 Rebuildable:
 
 - `.brainlink/brainlink.db`
+- `$BRAINLINK_HOME/bucket-cache`
 - FTS records
 - local embedding vectors
 - local embedding bucket index

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.12",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",
@@ -54,6 +54,7 @@
     "pack:smoke": "npm pack --dry-run"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1038.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.9.0",
     "commander": "^14.0.2",