@andespindola/brainlink 0.1.0-alpha.8 → 0.1.0-beta.0

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

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="./assets/brainlink-logo.svg" alt="Brainlink" width="720">
+</p>
+
 # Brainlink
 
 Local-first memory and knowledge graph for AI agents.
@@ -58,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.
@@ -252,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
@@ -355,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:
@@ -374,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
@@ -391,7 +436,7 @@ blink server --vault ./vault --no-index
 
 The HTTP API is read-only and exists only to power the graph UI and local inspection workflows.
 
-The server refuses non-loopback hosts by default. Use `--allow-public` only behind your own authentication, authorization and TLS.
+The server always refuses non-loopback hosts. Brainlink HTTP only runs on localhost.
 
 Routes:
 
@@ -488,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`
 
@@ -497,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`
 
@@ -506,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`
 
@@ -566,7 +611,7 @@ blink server --vault ./vault --watch
 
 Starts the local read-only graph UI and HTTP API.
 
-To bind outside localhost, pass `--allow-public` and put the server behind your own auth and TLS.
+The HTTP server only binds to loopback hosts such as `127.0.0.1`, `localhost` or `::1`.
 
 ## Machine-Readable Output
 
@@ -592,22 +637,39 @@ Brainlink reads `brainlink.config.json` or `.brainlink.json` from the current wo
   "host": "127.0.0.1",
   "port": 4321,
   "allowedVaults": [".brainlink-vault"],
+  "defaultAgent": "shared",
   "defaultSearchLimit": 10,
   "defaultContextTokens": 2000,
   "embeddingProvider": "local",
   "defaultSearchMode": "hybrid",
   "chunkSize": 1200
 }
+
+`defaultAgent` is optional. When set, CLI and MCP calls that omit `--agent`/`agent` use this value automatically. If not set, behavior remains as before.
 ```
 
 Use `"embeddingProvider": "none"` when you want FTS-only indexing.
 
+For local security checks, set your Snyk token in the environment:
+
+```bash
+export SNYK_TOKEN="snyk_..."
+```
+
+For GitHub Actions, add a repository secret `SNYK_TOKEN` and the CI/publish workflows will consume it automatically during build/test.
+
 Set `BRAINLINK_ALLOWED_VAULTS` for external wrappers, including MCP servers, so a tool cannot pass arbitrary `--vault` paths:
 
 ```bash
 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:
@@ -714,6 +776,7 @@ The alpha includes local semantic retrieval. Remote embedding providers, remote
 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.
 - Treat `.brainlink/brainlink.db` as disposable derived data.
@@ -727,3 +790,20 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 ## License
 
 MIT. See [LICENSE](LICENSE).
+
+### Memory Optimization Loop (1-7)
+
+Use this when your agent work needs consistent memory quality:
+
+1. Start with `blink context "<task>" --agent "$BLINK_AGENT" --json`.
+2. Keep notes focused with explicit `[[wiki links]]` and `#tags`.
+3. Route agent-specific knowledge to dedicated namespaces under `agents/<agent-id>/`.
+4. Keep `shared` as a curated global layer only.
+5. Use targeted queries (`--limit`, explicit terms, `--mode hybrid`) before broad scans.
+6. Run the sync command after writing notes:
+
+```bash
+npm run brainlink:sync -- --vault ./vault --agent "$BLINK_AGENT"
+```
+
+7. Before final response, keep the returned context sources as the grounding baseline.

package/SECURITY.md

@@ -5,7 +5,7 @@ Brainlink is local-first.
 ## Defaults
 
 - The HTTP server binds to `127.0.0.1` by default.
-- The HTTP server refuses non-loopback hosts unless `--allow-public` is passed.
+- The HTTP server always refuses non-loopback hosts.
 - The HTTP server is read-only and does not expose note creation, indexing or update routes.
 - The SQLite database is a derived local index.
 - Markdown files are user-owned source data.
@@ -14,7 +14,7 @@ Brainlink is local-first.
 
 ## Remote Exposure
 
-Do not expose the HTTP server on a public interface without adding authentication, authorization and transport security.
+Brainlink HTTP is intentionally localhost-only. It does not support binding to a public interface.
 
 ## Sensitive Memory
 
@@ -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/assets/brainlink-logo.svg

@@ -0,0 +1,25 @@
+<svg width="900" height="220" viewBox="0 0 900 220" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">Brainlink</title>
+  <desc id="desc">Brainlink logo with a linked memory graph mark and wordmark.</desc>
+  <rect width="900" height="220" fill="transparent"/>
+  <g transform="translate(42 24)">
+    <rect x="6" y="6" width="160" height="160" rx="36" fill="#F8FAFC"/>
+    <rect x="6" y="6" width="160" height="160" rx="36" stroke="#111827" stroke-width="8"/>
+    <path d="M47 84C47 65.225 62.225 50 81 50H92C110.775 50 126 65.225 126 84C126 102.775 110.775 118 92 118H81C62.225 118 47 102.775 47 84Z" stroke="#111827" stroke-width="12" stroke-linecap="round"/>
+    <path d="M67 84C67 76.268 73.268 70 81 70H92C99.732 70 106 76.268 106 84C106 91.732 99.732 98 92 98H81C73.268 98 67 91.732 67 84Z" fill="#FFFFFF"/>
+    <path d="M54 132L43 121L54 110" stroke="#2563EB" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
+    <path d="M118 110L129 121L118 132" stroke="#2563EB" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
+    <circle cx="55" cy="43" r="12" fill="#14B8A6"/>
+    <circle cx="121" cy="43" r="12" fill="#2563EB"/>
+    <circle cx="86" cy="136" r="12" fill="#111827"/>
+    <path d="M66.5 47.5L109.5 47.5" stroke="#94A3B8" stroke-width="7" stroke-linecap="round"/>
+    <path d="M62 54L79 125" stroke="#94A3B8" stroke-width="7" stroke-linecap="round"/>
+    <path d="M115 54L92 125" stroke="#94A3B8" stroke-width="7" stroke-linecap="round"/>
+  </g>
+  <g transform="translate(244 68)">
+    <text x="0" y="62" fill="#111827" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="72" font-weight="760">Brainlink</text>
+    <text x="4" y="102" fill="#475569" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="24" font-weight="500">Local-first memory for AI agents</text>
+    <path d="M0 124H268" stroke="#14B8A6" stroke-width="8" stroke-linecap="round"/>
+    <path d="M292 124H392" stroke="#2563EB" stroke-width="8" stroke-linecap="round"/>
+  </g>
+</svg>

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 }
@@ -101,9 +103,20 @@ const createLayout = graph => {
   return { nodes, edges }
 }
 
+const encodeEntityTag = (value) => {
+  const utf8 = new TextEncoder().encode(value)
+  let binary = ''
+
+  for (let index = 0; index < utf8.length; index += 1) {
+    binary += String.fromCharCode(utf8[index])
+  }
+
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '')
+}
+
 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 +220,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 +254,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 +274,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
@@ -377,9 +395,21 @@ const loadAgents = async () => {
 }
 
 const loadGraph = async (options = { reset: false }) => {
-  const response = await fetch('/api/graph-layout' + agentQuery())
-  const graph = await response.json()
-  const signature = graphSignature(graph)
+  const response = await fetch('/api/graph-layout' + agentQuery(), {
+    headers: state.graphSignature
+      ? {
+          'if-none-match': encodeEntityTag(state.graphSignature)
+        }
+      : undefined
+  })
+
+  if (response.status === 304) {
+    return
+  }
+
+  const payload = await response.json()
+  const graph = payload?.layout ?? payload
+  const signature = payload?.signature ?? graphSignature(graph)
   if (!options.reset && signature === state.graphSignature) return
   const selectedId = state.selected?.id
   const layout = createLayout(graph)
@@ -402,15 +432,47 @@ requestAnimationFrame(() => {
   resize()
   resetView()
 })
-loadAgents().then(() => loadGraph({ reset: true })).then(() => {
-  requestAnimationFrame(render)
-  setInterval(() => {
-    loadAgents().then(() => loadGraph()).catch(error => {
-      elements.stats.textContent = 'Failed to refresh graph'
+
+const pollIntervalMs = 5000
+let tickCounter = 0
+
+const refreshGraphLoop = () => {
+  if (document.hidden) {
+    return
+  }
+
+  loadGraph().catch((error) => {
+    elements.stats.textContent = 'Failed to refresh graph'
+    console.error(error)
+  })
+
+  tickCounter += 1
+  if (tickCounter % 3 === 0) {
+    loadAgents().catch((error) => {
       console.error(error)
     })
-  }, 2000)
-}).catch(error => {
-  elements.stats.textContent = 'Failed to load graph'
-  console.error(error)
-})`;
+  }
+}
+
+loadAgents()
+  .then(() => loadGraph({ reset: true }))
+  .then(() => {
+    requestAnimationFrame(render)
+    setInterval(refreshGraphLoop, pollIntervalMs)
+  })
+  .catch(error => {
+    elements.stats.textContent = 'Failed to load graph'
+    console.error(error)
+  })
+
+document.addEventListener('visibilitychange', () => {
+  if (document.hidden) {
+    return
+  }
+
+  loadGraph({ reset: true }).catch(error => {
+    elements.stats.textContent = 'Failed to refresh graph'
+    console.error(error)
+  })
+})
+`;

package/dist/application/get-graph-layout.js

@@ -1,3 +1,28 @@
 import { createCauliflowerGraphLayout } from '../domain/graph-layout.js';
 import { getGraph } from './get-graph.js';
-export const getGraphLayout = async (vaultPath, agentId) => createCauliflowerGraphLayout(await getGraph(vaultPath, agentId));
+const graphLayoutCache = new Map();
+const createGraphSignature = (graph) => {
+    const nodesSignature = graph.nodes.map((node) => `${node.id}|${node.agentId}|${node.title}|${node.path}`).join('\n');
+    const edgesSignature = graph.edges
+        .map((edge) => `${edge.source}|${edge.target ?? ''}|${edge.targetTitle}|${edge.weight}|${edge.priority}`)
+        .join('\n');
+    return `${graph.nodes.length}:${nodesSignature}|${graph.edges.length}:${edgesSignature}`;
+};
+export const getGraphLayout = async (vaultPath, agentId) => {
+    const graph = await getGraph(vaultPath, agentId);
+    const signature = createGraphSignature(graph);
+    const cacheKey = `${vaultPath}:${agentId ?? ''}`;
+    const cached = graphLayoutCache.get(cacheKey);
+    if (cached?.signature === signature) {
+        return {
+            signature,
+            layout: cached.layout
+        };
+    }
+    const layout = createCauliflowerGraphLayout(graph);
+    graphLayoutCache.set(cacheKey, { signature, layout });
+    return {
+        signature,
+        layout
+    };
+};

package/dist/application/index-vault.js

@@ -6,10 +6,18 @@ import { ensureVault, readMarkdownFiles } from '../infrastructure/file-system-va
 import { openSqliteIndex } from '../infrastructure/sqlite-index.js';
 const toTitleKey = (title) => title.toLowerCase();
 const appendTitleEntry = (map, document) => {
-    map.set(toTitleKey(document.title), document.id);
+    const key = toTitleKey(document.title);
+    if (!map.has(key)) {
+        map.set(key, {
+            id: document.id,
+            path: document.path
+        });
+    }
     return map;
 };
-const createTitleMaps = (documents) => documents.reduce((state, document) => {
+const createTitleMaps = (documents) => [...documents]
+    .sort((left, right) => left.path.localeCompare(right.path))
+    .reduce((state, document) => {
     const agentMap = state.byAgent.get(document.agentId) ?? new Map();
     appendTitleEntry(agentMap, document);
     state.byAgent.set(document.agentId, agentMap);
@@ -22,7 +30,7 @@ const createTitleMaps = (documents) => documents.reduce((state, document) => {
     byAgent: new Map()
 });
 const createScopedTitleResolver = (document, titleMaps) => ({
-    get: (title) => titleMaps.byAgent.get(document.agentId)?.get(title) ?? titleMaps.shared.get(title)
+    get: (title) => titleMaps.byAgent.get(document.agentId)?.get(title)?.id ?? titleMaps.shared.get(title)?.id
 });
 const embedIndexedDocuments = async (documents, providerName) => {
     const provider = createEmbeddingProvider(providerName);

package/dist/application/server/host-security.js

@@ -1,6 +1,6 @@
 export const isLoopbackHost = (host) => host === 'localhost' || host === '::1' || host === '[::1]' || host.startsWith('127.');
-export const assertPublicBindAllowed = (host, allowPublic = false) => {
-    if (!allowPublic && !isLoopbackHost(host)) {
-        throw new Error(`Refusing to bind Brainlink server to non-loopback host ${host}. Pass --allow-public only behind your own auth and TLS.`);
+export const assertLoopbackHost = (host) => {
+    if (!isLoopbackHost(host)) {
+        throw new Error(`Refusing to bind Brainlink server to non-loopback host ${host}. Brainlink HTTP only runs on localhost.`);
     }
 };

package/dist/application/server/routes.js

@@ -26,6 +26,28 @@ const createResponse = (body, statusCode = 200, contentType = 'text/plain; chars
         'cache-control': 'no-store'
     }
 });
+const normalizeHeaderToken = (value) => value?.trim().replace(/^"|"$/g, '') ?? '';
+const decodeEntityTag = (candidate) => {
+    const token = normalizeHeaderToken(candidate);
+    if (!/^[A-Za-z0-9_-]+$/.test(token))
+        return token;
+    try {
+        return Buffer.from(token, 'base64url').toString('utf8');
+    }
+    catch {
+        return token;
+    }
+};
+const encodeEntityTag = (signature) => JSON.stringify(Buffer.from(signature, 'utf8').toString('base64url'));
+const sameEntityTag = (candidate, signature) => {
+    if (Array.isArray(candidate)) {
+        return candidate.some((value) => sameEntityTag(value, signature));
+    }
+    if (candidate === undefined) {
+        return false;
+    }
+    return decodeEntityTag(candidate) === signature;
+};
 const readAgentQuery = (url) => url.searchParams.get('agent') ?? undefined;
 export const route = async (request, url, vaultPath) => {
     if (isReadMethod(request) && (url.pathname === '/' || url.pathname === '/index.html')) {
@@ -41,7 +63,29 @@ export const route = async (request, url, vaultPath) => {
         return createResponse(createJsonResponse(await getGraph(vaultPath, readAgentQuery(url))), 200, contentTypes['.json']);
     }
     if (isReadMethod(request) && url.pathname === '/api/graph-layout') {
-        return createResponse(createJsonResponse(await getGraphLayout(vaultPath, readAgentQuery(url))), 200, contentTypes['.json']);
+        const { signature, layout } = await getGraphLayout(vaultPath, readAgentQuery(url));
+        const requestEtags = request.headers['if-none-match'];
+        const notModified = sameEntityTag(requestEtags, signature);
+        const etag = encodeEntityTag(signature);
+        const body = createJsonResponse({ signature, layout });
+        const jsonResponse = createResponse(body, 200, contentTypes['.json']);
+        const notModifiedResponse = createResponse('', 304, contentTypes['.json']);
+        if (notModified) {
+            return {
+                ...notModifiedResponse,
+                headers: {
+                    ...notModifiedResponse.headers,
+                    etag
+                }
+            };
+        }
+        return {
+            ...jsonResponse,
+            headers: {
+                ...jsonResponse.headers,
+                etag
+            }
+        };
     }
     if (isReadMethod(request) && url.pathname === '/api/agents') {
         return createResponse(createJsonResponse({ agents: await listAgents(vaultPath) }), 200, contentTypes['.json']);

package/dist/application/start-server.js

@@ -1,11 +1,11 @@
 import { createServer } from 'node:http';
 import { indexVault } from './index-vault.js';
 import { startVaultWatcher } from './watch-vault.js';
-import { assertPublicBindAllowed } from './server/host-security.js';
+import { assertLoopbackHost } from './server/host-security.js';
 import { contentTypes, createJsonResponse, isHttpError } from './server/http.js';
 import { route } from './server/routes.js';
 export const startServer = async (input) => {
-    assertPublicBindAllowed(input.host, input.allowPublic);
+    assertLoopbackHost(input.host);
     if (input.shouldIndex) {
         await indexVault(input.vaultPath);
     }

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;