@andespindola/brainlink 0.1.0-beta.151 → 0.1.0-beta.153

package/AGENTS.md

@@ -6,7 +6,7 @@ This file tells coding agents and AI assistants how to use this repository.
 
 Brainlink is a local-first knowledge memory for agents.
 
-It reads a Markdown vault, extracts `[[wiki links]]` and `#tags`, builds a local file index at `.brainlink/index.json`, and returns compact context packages that agents can inject into prompts.
+It reads a Markdown vault, extracts concise graph links from `## Context Links`, extracts `#tags`, builds a local file index at `.brainlink/index.json`, and returns compact context packages that agents can inject into prompts.
 
 ## Source Of Truth
 
@@ -27,15 +27,15 @@ By default, the installed Brainlink CLI uses `$HOME/.brainlink/vault` as its vau
 Use this loop when using Brainlink as memory:
 
 1. Write durable knowledge into Markdown notes.
-2. Link related notes with explicit `[[Note Title]]` wiki links inside the note body.
+2. Link related notes with explicit `[[Note Title]]` wiki links inside a `## Context Links` section.
 3. Add explicit `#tags` for retrieval.
 4. Run `index` after writes.
 5. Run `context "<task or question>"` before answering.
 6. Use the returned sources as grounded context.
 
-`context` is read-only. It does not create notes, backlinks, graph edges or durable memory by itself. A relationship exists only when a Markdown note contains a `[[wiki link]]` to another note and the vault has been indexed after that write.
+`context` is read-only. It does not create notes, backlinks, graph edges or durable memory by itself. A relationship exists only when a Markdown note contains a `[[wiki link]]` inside `## Context Links` and the vault has been indexed after that write.
 
-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.
+When an agent adds durable memory, it should add only the canonical relationships to `## Context Links`. Prefer exact note titles in links, for example `[[Architecture]]`, and run `broken-links`, `orphans` or `validate` when graph health matters.
 
 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.
 

package/README.md

@@ -210,19 +210,19 @@ Only store knowledge that is likely to matter later:
 ```bash
 blink add "Testing Policy" \
   --agent "$BLINK_AGENT" \
-  --content "Run npm run check before final delivery. Related: [[Release Checklist]]. #testing #process"
+  --content $'Run npm run check before final delivery. #testing #process\n\n## Context Links\n\n- [[Release Checklist]]'
 ```
 
-Brainlink does not infer durable graph relationships from generated context. A context result is only a read package for the model. To create a real link in the knowledge graph, the agent must write Markdown that contains an explicit `[[Note Title]]` wiki link.
+Brainlink does not infer durable graph relationships from generated context. A context result is only a read package for the model. To create a real graph link, write a concise `## Context Links` section and put the canonical `[[Note Title]]` links there.
 
 Writes with `blink add` reindex the vault automatically by default. This can be disabled with `--no-auto-index` and controlled globally with `autoIndexOnWrite` in `brainlink.config.json`.
 
 When adding memory, follow this contract:
 
-- Link the new note to at least one existing note when there is a related concept.
+- Link the new note to existing notes through `## Context Links` when there is a related concept.
 - Use the exact target note title inside `[[...]]`.
 - Add retrieval tags such as `#architecture`, `#decision`, `#runbook` or `#preference`.
-- Do not leave isolated notes unless they are intentionally root concepts.
+- General wiki-link mentions outside `## Context Links` remain searchable Markdown content, but they do not become graph edges.
 
 If you disable auto-index, run `blink index` after batched writes.
 
@@ -554,7 +554,7 @@ If you disable `autoBootstrapOnRead` through `brainlink_policy`, read tools retu
 `brainlink_bootstrap`, `brainlink_policy` and preflight responses include structured `nextActions` so MCP clients can continue automatically without custom parsing.
 For one-call planning, use `brainlink_recommendations` to get the recommended tool sequence for the current vault/agent/query.
 
-The same linking rule applies through MCP: `brainlink_context` is read-only, and real graph links require Markdown notes with explicit `[[wiki links]]`. `brainlink_add_note` and `brainlink_add_file` reindex by default and include index + `writeConnectivity` metadata. Brainlink guarantees at least one edge per new note by auto-linking when needed.
+The same linking rule applies through MCP: `brainlink_context` is read-only, and real graph links require Markdown notes with explicit `## Context Links` sections. `brainlink_add_note` and `brainlink_add_file` reindex by default and include index + `writeConnectivity` metadata. Brainlink does not auto-link new notes to fallback hubs.
 
 Agents can raise the importance of a relationship by putting priority markers on the same line as a wiki link:
 
@@ -563,7 +563,14 @@ Agents can raise the importance of a relationship by putting priority markers on
 Related: [[Incident Runbook]] #critical
 ```
 
-Indexed edges expose `weight` and `priority` (`low`, `normal`, `high`, `critical`) through CLI JSON, HTTP graph APIs and `brainlink_graph`. Brainlink indexes every non-self Markdown `[[wiki link]]` as a graph edge, including structural hub links such as `Memory Hub`, `Knowledge Root`, `MOC` and map notes. Old indexes are rebuilt automatically when their graph link model version is missing or stale.
+Indexed edges expose `weight` and `priority` (`low`, `normal`, `high`, `critical`) through CLI JSON, HTTP graph APIs and `brainlink_graph`. Brainlink indexes every non-self `[[wiki link]]` inside `## Context Links` as a graph edge. Old indexes are rebuilt automatically when their graph link model version is missing or stale.
+
+To migrate older vaults without deleting existing Markdown, generate concise context-link sections from current wiki-link mentions:
+
+```bash
+blink migrate-context-links --vault ./vault --limit 5
+blink index --vault ./vault --full
+```
 
 ## Graph UI
 
@@ -589,11 +596,12 @@ When native GUI is used, the GUI window automatically closes when the `blink ser
 The graph UI shows:
 
 - notes as nodes
-- all non-self `[[wiki links]]` as weighted edges
+- all non-self `[[wiki links]]` inside `## Context Links` as weighted edges
 - default star layout centered on the primary hub, without rewriting or flattening underlying relationships
 - details opened in a non-modal side panel (tags, outgoing links, backlinks, full Markdown content), so zoom and pan remain available while inspecting data
 - neutral graph nodes with segment/group metadata
 - agent selector (id-only labels) for isolated views
+- context selector for segment-scoped star subgraphs derived from the visual graph context
 - graph filter matches title, path, tags and note content
 - graph filter keeps hub context nodes visible (`Memory Hub`/`MOC`/high-degree fallback) to preserve relationship readability
 - realtime refresh while `--watch` is enabled
@@ -625,6 +633,7 @@ The server always refuses non-loopback hosts. Brainlink HTTP only runs on localh
 Routes:
 
 - `GET /api/agents`
+- `GET /api/graph-contexts`
 - `GET /api/graph`
 - `GET /api/graph-layout`
 - `GET /api/graph-view?x=<x>&y=<y>&w=<width>&h=<height>&scale=<scale>`
@@ -643,6 +652,7 @@ Read routes accept `agent=<agent-id>`:
 
 ```txt
 /api/graph-layout?agent=coding-agent
+/api/graph-layout?agent=coding-agent&context=Architecture
 /api/search?q=typescript&agent=coding-agent&mode=hybrid
 /api/context?q=module-boundaries&agent=coding-agent&mode=semantic
 ```

package/dist/application/add-note.js

@@ -1,8 +1,5 @@
-import { access } from 'node:fs/promises';
-import { join } from 'node:path';
 import { writeMarkdownFile } from '../infrastructure/file-system-vault.js';
 import { sanitizeAgentId, sharedAgentId } from '../domain/agents.js';
-import { extractWikiLinks } from '../domain/markdown.js';
 import { validateNoteInput } from '../domain/note-safety.js';
 import { ensureVault } from '../infrastructure/file-system-vault.js';
 const slugify = (title) => title
@@ -11,10 +8,6 @@ const slugify = (title) => title
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '');
-const systemHubTitle = 'Memory Hub';
-const systemRootTitle = 'Knowledge Root';
-const normalizeTitle = (title) => title.trim().replace(/\.md$/i, '').toLowerCase();
-const noteFilename = (agentId, title) => `agents/${agentId}/${slugify(title) || 'untitled'}.md`;
 const buildNote = (title, content, agentId) => [
     `---`,
     `title: "${title.replaceAll('"', '\\"')}"`,
@@ -26,38 +19,6 @@ const buildNote = (title, content, agentId) => [
     content.trim(),
     ''
 ].join('\n');
-const ensureSystemNote = async (vaultPath, absoluteVaultPath, agentId, title, content) => {
-    const filename = noteFilename(agentId, title);
-    const absolutePath = join(absoluteVaultPath, filename);
-    try {
-        await access(absolutePath);
-        return;
-    }
-    catch { }
-    await writeMarkdownFile(vaultPath, filename, buildNote(title, content, agentId));
-};
-const ensureNonOrphanContent = async (vaultPath, absoluteVaultPath, title, content, agentId) => {
-    const links = extractWikiLinks(content).filter((link) => normalizeTitle(link) !== normalizeTitle(title));
-    if (links.length > 0) {
-        return {
-            content: content.trim(),
-            autoLinked: false,
-            linkTarget: null
-        };
-    }
-    const fallbackTitle = normalizeTitle(title) === normalizeTitle(systemHubTitle) ? systemRootTitle : systemHubTitle;
-    if (fallbackTitle === systemRootTitle) {
-        await ensureSystemNote(vaultPath, absoluteVaultPath, agentId, systemRootTitle, `Entry point for agent memory. [[${systemHubTitle}]] #memory #root`);
-    }
-    else {
-        await ensureSystemNote(vaultPath, absoluteVaultPath, agentId, systemHubTitle, 'Central memory index for this agent namespace. #memory #hub');
-    }
-    return {
-        content: `${content.trim()}\n\nRelated: [[${fallbackTitle}]]`,
-        autoLinked: true,
-        linkTarget: fallbackTitle
-    };
-};
 export const addNoteWithMetadata = async (vaultPath, title, content, agentId = sharedAgentId, options = {}) => {
     validateNoteInput({
         title,
@@ -65,15 +26,14 @@ export const addNoteWithMetadata = async (vaultPath, title, content, agentId = s
         allowSensitive: options.allowSensitive
     });
     const sanitizedAgentId = sanitizeAgentId(agentId);
-    const absoluteVaultPath = await ensureVault(vaultPath);
     const filename = `agents/${sanitizedAgentId}/${slugify(title) || 'untitled'}.md`;
-    const linkedContent = await ensureNonOrphanContent(vaultPath, absoluteVaultPath, title, content, sanitizedAgentId);
-    const note = buildNote(title, linkedContent.content, sanitizedAgentId);
+    await ensureVault(vaultPath);
+    const note = buildNote(title, content.trim(), sanitizedAgentId);
     const path = await writeMarkdownFile(vaultPath, filename, note);
     return {
         path,
-        autoLinked: linkedContent.autoLinked,
-        linkTarget: linkedContent.linkTarget
+        autoLinked: false,
+        linkTarget: null
     };
 };
 export const addNote = async (vaultPath, title, content, agentId = sharedAgentId, options = {}) => (await addNoteWithMetadata(vaultPath, title, content, agentId, options)).path;

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

@@ -113,7 +113,8 @@ select {
   min-width: 220px;
 }
 
-.agent-filter {
+.agent-filter,
+.context-filter {
   width: min(220px, 28vw);
 }
 
@@ -125,7 +126,8 @@ select {
 }
 
 .search input,
-.agent-filter select {
+.agent-filter select,
+.context-filter select {
   width: 100%;
   height: 40px;
   border: 1px solid var(--line);
@@ -137,7 +139,8 @@ select {
 }
 
 .search input:focus,
-.agent-filter select:focus {
+.agent-filter select:focus,
+.context-filter select:focus {
   border-color: var(--accent);
 }
 
@@ -405,7 +408,8 @@ li small {
     order: 3;
   }
 
-  .agent-filter {
+  .agent-filter,
+  .context-filter {
     width: 100%;
   }
 

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

@@ -35,6 +35,9 @@ export const createClientHtml = () => `<!doctype html>
             <label class="agent-filter">
               <select id="agent"></select>
             </label>
+            <label class="context-filter">
+              <select id="context"></select>
+            </label>
             <div class="toolbar" aria-label="Graph controls">
               <button id="zoomIn" type="button" title="Zoom in">+</button>
               <button id="zoomOut" type="button" title="Zoom out">-</button>

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

@@ -4,6 +4,7 @@ const byId = (id) => document.getElementById(id)
 const elements = {
   search: byId('search'),
   agent: byId('agent'),
+  context: byId('context'),
   nodeCount: byId('nodeCount'),
   edgeCount: byId('edgeCount'),
   tagCount: byId('tagCount'),
@@ -49,6 +50,7 @@ const state = {
   rendererMode: 'worker',
   renderWorker: null,
   agentId: '',
+  contextId: '',
   graphSignature: '',
   graphMode: 'near',
   chunk: {
@@ -77,6 +79,7 @@ const zoomRange = {
 }
 
 const selectedAgentStorageKey = 'brainlink:selected-agent'
+const selectedContextStorageKey = 'brainlink:selected-context'
 
 const escapeHtml = (value) => String(value)
   .replaceAll('&', '&')
@@ -104,6 +107,25 @@ const writeStoredAgent = (agentId) => {
   } catch {}
 }
 
+const readStoredContext = () => {
+  try {
+    const value = window.localStorage.getItem(selectedContextStorageKey)?.trim() ?? ''
+    return value.length > 0 ? value : ''
+  } catch {
+    return ''
+  }
+}
+
+const writeStoredContext = (contextId) => {
+  try {
+    if (!contextId) {
+      window.localStorage.removeItem(selectedContextStorageKey)
+      return
+    }
+    window.localStorage.setItem(selectedContextStorageKey, contextId)
+  } catch {}
+}
+
 const syncAgentInUrl = (agentId) => {
   try {
     const url = new URL(window.location.href)
@@ -116,6 +138,18 @@ const syncAgentInUrl = (agentId) => {
   } catch {}
 }
 
+const syncContextInUrl = (contextId) => {
+  try {
+    const url = new URL(window.location.href)
+    if (contextId && contextId.trim().length > 0) {
+      url.searchParams.set('context', contextId)
+    } else {
+      url.searchParams.delete('context')
+    }
+    window.history.replaceState({}, '', url.toString())
+  } catch {}
+}
+
 const initialAgentFromUrl = (() => {
   try {
     const raw = new URL(window.location.href).searchParams.get('agent')
@@ -126,7 +160,28 @@ const initialAgentFromUrl = (() => {
   }
 })()
 
-const agentQuery = (separator = '?') => state.agentId ? separator + 'agent=' + encodeURIComponent(state.agentId) : ''
+const initialContextFromUrl = (() => {
+  try {
+    const raw = new URL(window.location.href).searchParams.get('context')
+    const value = raw?.trim() ?? ''
+    return value.length > 0 ? value : ''
+  } catch {
+    return ''
+  }
+})()
+
+const scopeQuery = (separator = '?') => {
+  const params = new URLSearchParams()
+  if (state.agentId) {
+    params.set('agent', state.agentId)
+  }
+  if (state.contextId) {
+    params.set('context', state.contextId)
+  }
+  const query = params.toString()
+
+  return query ? separator + query : ''
+}
 
 const parseColor = (hex) => {
   const normalized = String(hex || '#ffffff').replace('#', '')
@@ -298,51 +353,6 @@ const list = (items) => {
     .join('')
 }
 
-const extractContextLinks = (content) => {
-  if (typeof content !== 'string' || content.length === 0) {
-    return []
-  }
-  const lines = content.split(/\\r?\\n/)
-  let start = -1
-  for (let index = 0; index < lines.length; index += 1) {
-    if (/^#{1,6}\\s+(?:context\\s+links?|links?\\s+de\\s+contexto)\\b/i.test(lines[index].trim())) {
-      start = index + 1
-      break
-    }
-  }
-  if (start < 0) {
-    return []
-  }
-
-  const links = []
-  const seenTitles = new Set()
-  for (let index = start; index < lines.length; index += 1) {
-    const line = lines[index].trim()
-    if (!line) {
-      continue
-    }
-    if (/^#{1,6}\\s+/.test(line)) {
-      break
-    }
-    const matches = Array.from(line.matchAll(/\\[\\[([^\\]]+)\\]\\]/g))
-    if (matches.length === 0) {
-      continue
-    }
-    const priorityMatch = line.match(/#(critical|important)\\b|priority:\\s*(high|critical)/i)
-    const priority = priorityMatch ? String(priorityMatch[1] || priorityMatch[2] || 'normal').toLowerCase() : 'normal'
-
-    for (let matchIndex = 0; matchIndex < matches.length; matchIndex += 1) {
-      const title = String(matches[matchIndex][1] || '').trim()
-      if (!title || seenTitles.has(title.toLowerCase())) {
-        continue
-      }
-      seenTitles.add(title.toLowerCase())
-      links.push({ title, priority })
-    }
-  }
-  return links
-}
-
 const buildFacts = (node, outgoingCount, incomingCount) => {
   const content = typeof node?.content === 'string' ? node.content : ''
   const words = content.trim().length > 0 ? content.trim().split(/\\s+/).length : 0
@@ -368,6 +378,21 @@ const listContextLinks = (links) => {
     .join('')
 }
 
+const nodeContextLinks = (node, outgoing) => {
+  const titles = Array.isArray(node?.contextLinks) ? node.contextLinks : []
+  const outgoingByTitle = new Map(normalizeList(outgoing).map((link) => [String(link.title || '').toLowerCase(), link]))
+
+  return titles
+    .map((title) => {
+      const match = outgoingByTitle.get(String(title).toLowerCase())
+      return {
+        title,
+        priority: match?.priority || 'normal'
+      }
+    })
+    .filter((link) => typeof link.title === 'string' && link.title.trim().length > 0)
+}
+
 const linkedNodes = (node) => {
   const nodeById = new Map((state.chunk.nodes || []).map((item) => [item[0], item]))
   const edges = normalizeList(state.chunk.edges)
@@ -405,7 +430,7 @@ const loadNodeDetails = async (nodeId) => {
     return
   }
 
-  const response = await fetch('/api/graph-node?id=' + encodeURIComponent(nodeId) + agentQuery('&'))
+  const response = await fetch('/api/graph-node?id=' + encodeURIComponent(nodeId) + scopeQuery('&'))
   if (!response.ok) {
     throw new Error('Failed to load graph node details')
   }
@@ -431,7 +456,7 @@ const loadNodeDetails = async (nodeId) => {
     : '<span>No tags</span>'
 
   const related = linkedNodes(node)
-  const contextLinks = extractContextLinks(node.content)
+  const contextLinks = nodeContextLinks(node, related.outgoing)
   const facts = buildFacts(node, related.outgoing.length, related.incoming.length)
   elements.contentFacts.innerHTML = listFacts(facts)
   elements.contentContextLinks.innerHTML = listContextLinks(contextLinks)
@@ -509,6 +534,9 @@ const fetchChunk = async ({ fit } = { fit: false }) => {
   if (state.agentId) {
     params.set('agent', state.agentId)
   }
+  if (state.contextId) {
+    params.set('context', state.contextId)
+  }
 
   const response = await fetch('/api/graph-stream?' + params.toString(), { signal: controller.signal })
   if (!response.ok) {
@@ -781,7 +809,7 @@ const setupControls = () => {
       return
     }
 
-    fetch('/api/graph-filter?q=' + encodeURIComponent(query) + '&limit=1800' + agentQuery('&'))
+    fetch('/api/graph-filter?q=' + encodeURIComponent(query) + '&limit=1800' + scopeQuery('&'))
       .then((response) => response.json())
       .then((payload) => {
         if (token !== state.searchToken) {
@@ -825,12 +853,50 @@ const loadAgents = async () => {
     state.agentId = elements.agent.value || ''
     writeStoredAgent(state.agentId)
     syncAgentInUrl(state.agentId)
-    scheduleChunkFetch({ fit: true })
+    loadContexts().then(() => scheduleChunkFetch({ fit: true })).catch((error) => console.error(error))
   })
 
   syncAgentInUrl(state.agentId)
 }
 
+const loadContexts = async () => {
+  const response = await fetch('/api/graph-contexts' + (state.agentId ? '?agent=' + encodeURIComponent(state.agentId) : ''))
+  if (!response.ok) {
+    throw new Error('Failed to load graph contexts')
+  }
+
+  const payload = await response.json()
+  const contexts = Array.isArray(payload?.contexts) ? payload.contexts : []
+  const options = [
+    '<option value="">All contexts</option>',
+    ...contexts.map((context) => {
+      const id = String(context?.id || '')
+      const title = String(context?.title || id || 'Untitled')
+      const count = Number.isFinite(context?.nodeCount) ? context.nodeCount : 0
+      return '<option value="' + escapeHtml(id) + '">' + escapeHtml(title) + ' (' + count + ')</option>'
+    })
+  ]
+
+  elements.context.innerHTML = options.join('')
+
+  const preferredContext = initialContextFromUrl || readStoredContext()
+  const hasPreferred = preferredContext && contexts.some((context) => context?.id === preferredContext)
+  state.contextId = hasPreferred ? preferredContext : ''
+  elements.context.value = state.contextId
+  writeStoredContext(state.contextId)
+  syncContextInUrl(state.contextId)
+}
+
+const setupContextControl = () => {
+  elements.context.addEventListener('change', () => {
+    state.contextId = elements.context.value || ''
+    state.selectedNodeId = null
+    writeStoredContext(state.contextId)
+    syncContextInUrl(state.contextId)
+    scheduleChunkFetch({ fit: true })
+  })
+}
+
 const setupRenderWorker = () => {
   const hasWorker = typeof Worker !== 'undefined'
   const canTransfer = typeof canvas.transferControlToOffscreen === 'function'
@@ -922,6 +988,7 @@ const bootstrap = async () => {
   setupRenderWorker()
   setupInput()
   setupControls()
+  setupContextControl()
   wireNodeLinkClicks()
 
   window.addEventListener('resize', () => {
@@ -930,12 +997,11 @@ const bootstrap = async () => {
   })
 
   await loadAgents()
+  await loadContexts()
   updateTotals()
   updateTagCount()
 
-  if (state.rendererMode === 'fallback') {
-    scheduleChunkFetch({ fit: true })
-  }
+  scheduleChunkFetch({ fit: true })
 }
 
 bootstrap().catch((error) => {

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

@@ -0,0 +1,19 @@
+import { getGraphLayout } from './get-graph-layout.js';
+export const getGraphContexts = async (vaultPath, agentId) => {
+    const { layout } = await getGraphLayout(vaultPath, { agentId });
+    const nodeIdsByContext = layout.nodes.reduce((contexts, node) => {
+        const title = node.segment || node.group || 'root';
+        const nodeIds = contexts.get(title) ?? new Set();
+        nodeIds.add(node.id);
+        contexts.set(title, nodeIds);
+        return contexts;
+    }, new Map());
+    return Array.from(nodeIdsByContext.entries())
+        .map(([title, nodeIds]) => ({
+        id: title,
+        title,
+        nodeCount: nodeIds.size,
+        edgeCount: layout.edges.filter((edge) => nodeIds.has(edge.source) && Boolean(edge.target && nodeIds.has(edge.target))).length
+    }))
+        .sort((left, right) => right.nodeCount - left.nodeCount || left.title.localeCompare(right.title));
+};

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

@@ -4,20 +4,25 @@ import { dirname, join } from 'node:path';
 import { createStarGraphLayout } from '../domain/graph-layout.js';
 import { indexStoragePath } from '../infrastructure/file-index.js';
 import { getGraphSummary } from './get-graph-summary.js';
-const graphLayoutVersion = 3;
+const graphLayoutVersion = 4;
 const graphLayoutCache = new Map();
-const graphLayoutStoragePath = (vaultPath, agentId) => join(vaultPath, '.brainlink', `graph-layout-${agentId?.replace(/[^a-zA-Z0-9_-]/g, '_') ?? 'all'}.json`);
-const readPersistedLayout = async (vaultPath, databaseSignature, agentId) => {
+const safeCacheSegment = (value, fallback) => value?.replace(/[^a-zA-Z0-9_-]/g, '_') || fallback;
+const graphLayoutStoragePath = (vaultPath, options) => {
+    const agent = safeCacheSegment(options.agentId, 'all');
+    const context = safeCacheSegment(options.context, 'all-contexts');
+    return join(vaultPath, '.brainlink', `graph-layout-${agent}-${context}.json`);
+};
+const readPersistedLayout = async (vaultPath, databaseSignature, options) => {
     try {
-        const parsed = JSON.parse(await readFile(graphLayoutStoragePath(vaultPath, agentId), 'utf8'));
+        const parsed = JSON.parse(await readFile(graphLayoutStoragePath(vaultPath, options), 'utf8'));
         return parsed.databaseSignature === databaseSignature && parsed.layoutVersion === graphLayoutVersion ? parsed : null;
     }
     catch {
         return null;
     }
 };
-const writePersistedLayout = async (vaultPath, agentId, cached) => {
-    const target = graphLayoutStoragePath(vaultPath, agentId);
+const writePersistedLayout = async (vaultPath, options, cached) => {
+    const target = graphLayoutStoragePath(vaultPath, options);
     const temp = `${target}.tmp`;
     await mkdir(dirname(target), { recursive: true, mode: 0o700 });
     await writeFile(temp, `${JSON.stringify(cached)}\n`, { encoding: 'utf8', mode: 0o600 });
@@ -41,9 +46,27 @@ const createGraphSignature = (graph) => {
         .update(`${graph.nodes.length}:${nodesSignature}|${graph.edges.length}:${edgesSignature}`)
         .digest('hex');
 };
-export const getGraphLayout = async (vaultPath, agentId) => {
+const createLayout = (graph) => {
+    const rawLayout = createStarGraphLayout(graph);
+    return {
+        ...rawLayout,
+        nodes: rawLayout.nodes.map((node) => ({ ...node, content: '' }))
+    };
+};
+const filterGraphByContext = (graph, context) => {
+    const baseLayout = createStarGraphLayout(graph);
+    const selectedNodeIds = new Set(baseLayout.nodes
+        .filter((node) => node.segment === context)
+        .map((node) => node.id));
+    return {
+        nodes: graph.nodes.filter((node) => selectedNodeIds.has(node.id)),
+        edges: graph.edges.filter((edge) => selectedNodeIds.has(edge.source) && Boolean(edge.target && selectedNodeIds.has(edge.target)))
+    };
+};
+export const getGraphLayout = async (vaultPath, optionsOrAgentId) => {
+    const options = typeof optionsOrAgentId === 'string' ? { agentId: optionsOrAgentId } : optionsOrAgentId ?? {};
     const databaseSignature = await readDatabaseSignature(vaultPath);
-    const cacheKey = `${vaultPath}:${agentId ?? ''}`;
+    const cacheKey = `${vaultPath}:${options.agentId ?? ''}:${options.context ?? ''}`;
     const cached = graphLayoutCache.get(cacheKey);
     if (cached?.databaseSignature === databaseSignature && cached.layoutVersion === graphLayoutVersion) {
         return {
@@ -51,7 +74,7 @@ export const getGraphLayout = async (vaultPath, agentId) => {
             layout: cached.layout
         };
     }
-    const persisted = await readPersistedLayout(vaultPath, databaseSignature, agentId);
+    const persisted = await readPersistedLayout(vaultPath, databaseSignature, options);
     if (persisted) {
         graphLayoutCache.set(cacheKey, persisted);
         return {
@@ -59,16 +82,13 @@ export const getGraphLayout = async (vaultPath, agentId) => {
             layout: persisted.layout
         };
     }
-    const graph = await getGraphSummary(vaultPath, agentId);
-    const signature = createGraphSignature(graph);
-    const rawLayout = createStarGraphLayout(graph);
-    const layout = {
-        ...rawLayout,
-        nodes: rawLayout.nodes.map((node) => ({ ...node, content: '' }))
-    };
+    const graph = await getGraphSummary(vaultPath, options.agentId);
+    const scopedGraph = options.context ? filterGraphByContext(graph, options.context) : graph;
+    const signature = createGraphSignature(scopedGraph);
+    const layout = createLayout(scopedGraph);
     const nextCache = { layoutVersion: graphLayoutVersion, databaseSignature, signature, layout };
     graphLayoutCache.set(cacheKey, nextCache);
-    await writePersistedLayout(vaultPath, agentId, nextCache);
+    await writePersistedLayout(vaultPath, options, nextCache);
     return {
         signature,
         layout

package/dist/application/get-graph-stream-chunk.js

@@ -244,7 +244,10 @@ const normalizeBudget = (value, fallback, min, max) => {
 export const getGraphStreamChunk = async (vaultPath, input) => {
     const nodeBudget = normalizeBudget(input.nodeBudget, 1800, 80, 12_000);
     const edgeBudget = normalizeBudget(input.edgeBudget, 5000, 120, 60_000);
-    const { signature, layout } = await getGraphLayout(vaultPath, input.agentId);
+    const { signature, layout } = await getGraphLayout(vaultPath, {
+        agentId: input.agentId,
+        context: input.context
+    });
     const groups = layout.groups ?? [];
     const cache = getOrCreateLayoutCache(signature, layout.nodes, layout.edges, groups);
     if (layout.nodes.length === 0) {

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

@@ -180,7 +180,10 @@ const arrangeChildGraphNodes = (nodes, group, degrees) => {
 };
 const limitEdges = (edges) => edges.slice(0, edgeLimit);
 export const getGraphView = async (vaultPath, input) => {
-    const { signature, layout } = await getGraphLayout(vaultPath, input.agentId);
+    const { signature, layout } = await getGraphLayout(vaultPath, {
+        agentId: input.agentId,
+        context: input.context
+    });
     const groups = layout.groups ?? [];
     const degrees = degreeMap(layout.edges);
     const groupById = new Map(groups.map((group) => [group.id, group]));

package/dist/application/import-legacy-sqlite.js

@@ -3,7 +3,7 @@ import { access } from 'node:fs/promises';
 import { basename, extname, join, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { promisify } from 'node:util';
-import { extractTags, extractWikiLinks } from '../domain/markdown.js';
+import { extractTags } from '../domain/markdown.js';
 import { sanitizeAgentId, sharedAgentId } from '../domain/agents.js';
 import { ensureVault, listVaultFiles, writeMarkdownFile } from '../infrastructure/file-system-vault.js';
 import { getBrainlinkHomePath } from '../infrastructure/paths.js';
@@ -17,9 +17,6 @@ const agentColumnCandidates = ['agent', 'agent_id', 'namespace', 'scope'];
 const tagColumnCandidates = ['tags', 'tag_list', 'keywords'];
 const createdColumnCandidates = ['created_at', 'createdat', 'created', 'ctime'];
 const updatedColumnCandidates = ['updated_at', 'updatedat', 'updated', 'mtime'];
-const systemHubTitle = 'Memory Hub';
-const systemRootTitle = 'Knowledge Root';
-const normalizeTitle = (title) => title.trim().replace(/\.md$/i, '').toLowerCase();
 const slugify = (title) => title
     .normalize('NFKD')
     .replace(/[\u0300-\u036f]/g, '')
@@ -203,31 +200,6 @@ const reserveUniquePath = (agentId, title, reserved) => {
     }
     throw new Error(`Could not allocate unique path for imported note: ${title}`);
 };
-const ensureSystemNote = async (vaultPath, reserved, created, agentId, title, content, dryRun) => {
-    const filename = noteRelativePath(agentId, slugify(title));
-    if (reserved.has(filename)) {
-        return;
-    }
-    reserved.add(filename);
-    created.add(filename);
-    if (dryRun) {
-        return;
-    }
-    await writeMarkdownFile(vaultPath, filename, buildNote(title, content, agentId));
-};
-const applyConnectivityRule = async (vaultPath, reserved, created, title, content, agentId, dryRun) => {
-    const links = extractWikiLinks(content).filter((link) => normalizeTitle(link) !== normalizeTitle(title));
-    if (links.length > 0) {
-        return content.trim();
-    }
-    const normalized = normalizeTitle(title);
-    if (normalized === normalizeTitle(systemHubTitle)) {
-        await ensureSystemNote(vaultPath, reserved, created, agentId, systemRootTitle, `Entry point for agent memory. [[${systemHubTitle}]] #memory #root`, dryRun);
-        return `${content.trim()}\n\nRelated: [[${systemRootTitle}]]`;
-    }
-    await ensureSystemNote(vaultPath, reserved, created, agentId, systemHubTitle, 'Central memory index for this agent namespace. #memory #hub', dryRun);
-    return `${content.trim()}\n\nRelated: [[${systemHubTitle}]]`;
-};
 const importRowsFromMapping = async (vaultPath, dbPath, mapping, options, reserved) => {
     const limit = Number.isFinite(options.limit) && (options.limit ?? 0) > 0 ? Math.floor(options.limit ?? 0) : undefined;
     const sql = [
@@ -243,7 +215,6 @@ const importRowsFromMapping = async (vaultPath, dbPath, mapping, options, reserv
         ...(limit ? [`LIMIT ${limit}`] : [])
     ].join(' ');
     const rows = await runSqliteQuery(dbPath, sql);
-    const createdSystemNotes = new Set();
     const importedFiles = [];
     let imported = 0;
     let skipped = 0;
@@ -256,8 +227,7 @@ const importRowsFromMapping = async (vaultPath, dbPath, mapping, options, reserv
         const agentId = sanitizeAgentId(options.agentOverride || row.agent || sharedAgentId);
         const filename = reserveUniquePath(agentId, row.title, reserved);
         const mergedContent = appendMissingTags(row.content, row.tags);
-        const connectedContent = await applyConnectivityRule(vaultPath, reserved, createdSystemNotes, row.title, mergedContent, agentId, options.dryRun === true);
-        const note = buildNote(row.title, connectedContent, agentId);
+        const note = buildNote(row.title, mergedContent.trim(), agentId);
         if (options.dryRun !== true) {
             await writeMarkdownFile(vaultPath, filename, note);
         }
@@ -268,7 +238,7 @@ const importRowsFromMapping = async (vaultPath, dbPath, mapping, options, reserv
         rowsRead: rows.length,
         imported,
         skipped,
-        createdSystemNotes: createdSystemNotes.size,
+        createdSystemNotes: 0,
         importedFiles
     };
 };

package/dist/application/migrate-context-links.js

@@ -0,0 +1,79 @@
+import { readFile } from 'node:fs/promises';
+import { ensureVault, readMarkdownFileSummaries, writeMarkdownFile } from '../infrastructure/file-system-vault.js';
+import { extractContextLinkWeights, extractWikiLinkWeights, hasContextLinksSection, parseMarkdownDocument } from '../domain/markdown.js';
+const defaultContextLinkLimit = 5;
+const normalizeTitle = (title) => title.trim().replace(/\.md$/i, '').toLowerCase();
+const formatPriority = (priority) => priority === 'normal' ? '' : ` priority: ${priority}`;
+const formatContextLinksSection = (links) => [
+    '## Context Links',
+    '',
+    ...links.map((link) => `- [[${link.title}]]${formatPriority(link.priority)}`)
+].join('\n');
+const appendContextLinksSection = (content, links) => `${content.trimEnd()}\n\n${formatContextLinksSection(links)}\n`;
+const selectContextLinkCandidates = (content, title, limit) => extractWikiLinkWeights(content)
+    .filter((link) => normalizeTitle(link.title) !== normalizeTitle(title))
+    .slice(0, limit)
+    .map((link) => ({
+    title: link.title,
+    priority: link.priority,
+    weight: link.weight
+}));
+export const migrateContextLinks = async (vaultPath, options = {}) => {
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const limit = Math.max(1, Math.floor(options.limit ?? defaultContextLinkLimit));
+    const summaries = await readMarkdownFileSummaries(absoluteVaultPath);
+    const entries = [];
+    for (const summary of summaries) {
+        const content = await readFile(summary.absolutePath, 'utf8');
+        const document = parseMarkdownDocument({
+            absolutePath: summary.absolutePath,
+            vaultPath: absoluteVaultPath,
+            content,
+            createdAt: summary.createdAt,
+            updatedAt: summary.updatedAt
+        });
+        if (options.agentId && document.agentId !== options.agentId) {
+            continue;
+        }
+        if (hasContextLinksSection(content)) {
+            entries.push({
+                path: summary.relativePath,
+                title: document.title,
+                changed: false,
+                reason: 'already-has-context-links',
+                links: extractContextLinkWeights(content)
+            });
+            continue;
+        }
+        const links = selectContextLinkCandidates(content, document.title, limit);
+        if (links.length === 0) {
+            entries.push({
+                path: summary.relativePath,
+                title: document.title,
+                changed: false,
+                reason: 'no-link-candidates',
+                links
+            });
+            continue;
+        }
+        if (!options.dryRun) {
+            await writeMarkdownFile(vaultPath, summary.relativePath, appendContextLinksSection(content, links));
+        }
+        entries.push({
+            path: summary.relativePath,
+            title: document.title,
+            changed: true,
+            reason: 'added-context-links',
+            links
+        });
+    }
+    const changed = entries.filter((entry) => entry.changed).length;
+    return {
+        dryRun: options.dryRun === true,
+        scanned: entries.length,
+        changed,
+        skipped: entries.length - changed,
+        limit,
+        entries
+    };
+};

package/dist/application/search-graph-node-ids.js

@@ -1,10 +1,61 @@
+import { stat } from 'node:fs/promises';
 import { ensureVault } from '../infrastructure/file-system-vault.js';
-import { openFileIndex } from '../infrastructure/file-index.js';
+import { indexStoragePath, openFileIndex } from '../infrastructure/file-index.js';
+const graphSearchCacheTtlMs = 20_000;
+const graphSearchCacheMaxEntries = 120;
+const graphSearchCache = new Map();
+const readIndexSignature = async (vaultPath) => {
+    try {
+        const info = await stat(indexStoragePath(vaultPath));
+        return `${Math.floor(info.mtimeMs)}:${info.size}`;
+    }
+    catch {
+        return '0:0';
+    }
+};
+const cacheKey = (vaultPath, query, limit, agentId) => JSON.stringify({
+    vaultPath,
+    query: query.trim().toLowerCase(),
+    limit,
+    agentId: agentId?.trim().toLowerCase() ?? '*'
+});
+const readCached = (key, indexSignature) => {
+    const entry = graphSearchCache.get(key);
+    if (!entry) {
+        return undefined;
+    }
+    const fresh = Date.now() - entry.createdAt <= graphSearchCacheTtlMs && entry.indexSignature === indexSignature;
+    if (!fresh) {
+        graphSearchCache.delete(key);
+        return undefined;
+    }
+    return entry.nodeIds;
+};
+const writeCached = (key, entry) => {
+    graphSearchCache.set(key, entry);
+    if (graphSearchCache.size <= graphSearchCacheMaxEntries) {
+        return;
+    }
+    const overflow = graphSearchCache.size - graphSearchCacheMaxEntries;
+    Array.from(graphSearchCache.keys()).slice(0, overflow).forEach((cacheKey) => graphSearchCache.delete(cacheKey));
+};
 export const searchGraphNodeIds = async (vaultPath, query, limit, agentId) => {
     const absoluteVaultPath = await ensureVault(vaultPath);
+    const indexSignature = await readIndexSignature(absoluteVaultPath);
+    const key = cacheKey(absoluteVaultPath, query, limit, agentId);
+    const cached = readCached(key, indexSignature);
+    if (cached) {
+        return cached;
+    }
     const index = openFileIndex(absoluteVaultPath);
     try {
-        return await index.searchGraphNodeIds(query, limit, agentId);
+        const nodeIds = await index.searchGraphNodeIds(query, limit, agentId);
+        writeCached(key, {
+            createdAt: Date.now(),
+            indexSignature,
+            nodeIds
+        });
+        return nodeIds;
     }
     finally {
         index.close();

package/dist/application/server/routes.js

@@ -1,6 +1,7 @@
 import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../analyze-vault.js';
 import { buildContextPackage } from '../build-context.js';
 import { getGraph } from '../get-graph.js';
+import { getGraphContexts } from '../get-graph-contexts.js';
 import { getGraphNode } from '../get-graph-node.js';
 import { getGraphLayout } from '../get-graph-layout.js';
 import { getGraphView } from '../get-graph-view.js';
@@ -55,6 +56,10 @@ const sameEntityTag = (candidate, signature) => {
     return decodeEntityTag(candidate) === signature;
 };
 const readAgentQuery = (url) => url.searchParams.get('agent') ?? undefined;
+const readContextQuery = (url) => {
+    const value = url.searchParams.get('context')?.trim() ?? '';
+    return value.length > 0 ? value : undefined;
+};
 const parseNumber = (value, fallback) => {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : fallback;
@@ -218,7 +223,10 @@ 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') {
-        const { signature, layout } = await getGraphLayout(vaultPath, readAgentQuery(url));
+        const { signature, layout } = await getGraphLayout(vaultPath, {
+            agentId: readAgentQuery(url),
+            context: readContextQuery(url)
+        });
         const requestEtags = request.headers['if-none-match'];
         const notModified = sameEntityTag(requestEtags, signature);
         const etag = encodeEntityTag(signature);
@@ -253,7 +261,8 @@ export const route = async (request, url, vaultPath) => {
             width: parseNumber(url.searchParams.get('w'), 2000),
             height: parseNumber(url.searchParams.get('h'), 2000),
             scale: parseNumber(url.searchParams.get('scale'), 1),
-            agentId: readAgentQuery(url)
+            agentId: readAgentQuery(url),
+            context: readContextQuery(url)
         })), 200, contentTypes['.json']);
     }
     if (isReadMethod(request) && url.pathname === '/api/graph-stream') {
@@ -272,7 +281,8 @@ export const route = async (request, url, vaultPath) => {
             scale,
             nodeBudget,
             edgeBudget,
-            agentId: readAgentQuery(url)
+            agentId: readAgentQuery(url),
+            context: readContextQuery(url)
         })), 200, contentTypes['.json']);
     }
     if (isReadMethod(request) && url.pathname === '/api/graph-node') {
@@ -298,6 +308,9 @@ export const route = async (request, url, vaultPath) => {
     if (isReadMethod(request) && url.pathname === '/api/agents') {
         return createResponse(createJsonResponse({ agents: await listAgents(vaultPath) }), 200, contentTypes['.json']);
     }
+    if (isReadMethod(request) && url.pathname === '/api/graph-contexts') {
+        return createResponse(createJsonResponse({ contexts: await getGraphContexts(vaultPath, readAgentQuery(url)) }), 200, contentTypes['.json']);
+    }
     if (isReadMethod(request) && url.pathname === '/api/search') {
         const query = url.searchParams.get('q') ?? '';
         const limit = parsePositiveInteger(url.searchParams.get('limit'), 10);

package/dist/cli/commands/write-commands.js

@@ -8,6 +8,7 @@ import { buildContextPackage } from '../../application/build-context.js';
 import { resolveDuplicateNotes, scanDuplicateNotes } from '../../application/dedupe-notes.js';
 import { importLegacySqliteDatabase } from '../../application/import-legacy-sqlite.js';
 import { indexVault, indexVaultWithOptions } from '../../application/index-vault.js';
+import { migrateContextLinks } from '../../application/migrate-context-links.js';
 import { migrateVaultContent, planVaultMigration, previewVaultMigration, shouldMigrateDefaultVault } from '../../application/migrate-vault.js';
 import { createOfflinePackBackup } from '../../application/offline-pack-backup.js';
 import { startServer } from '../../application/start-server.js';
@@ -699,6 +700,37 @@ export const registerWriteCommands = (program) => {
             return `${summary}${indexMessage}${reportMessage}`;
         });
     });
+    program
+        .command('migrate-context-links')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('-l, --limit <limit>', 'maximum context links to add per note', '5')
+        .option('--dry-run', 'preview context-link migration without writing files')
+        .option('--no-index', 'skip reindexing after migration')
+        .option('--json', 'print machine-readable JSON')
+        .description('add concise Context Links sections from existing wiki-link mentions')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const result = await migrateContextLinks(resolved.vault, {
+            dryRun: options.dryRun === true,
+            limit: parsePositiveInteger(options.limit ?? '5', 5),
+            agentId: resolved.agent
+        });
+        const shouldIndex = options.index !== false && !result.dryRun && result.changed > 0;
+        const index = shouldIndex ? await indexVault(resolved.vault, { full: true }) : undefined;
+        print(options.json, {
+            vault: resolved.vault,
+            agent: resolved.agent ?? 'shared',
+            ...result,
+            ...(index ? { index } : {})
+        }, () => {
+            const mode = result.dryRun ? 'Previewed' : 'Migrated';
+            const indexMessage = index
+                ? ` Fully reindexed ${index.documentCount} documents, ${index.chunkCount} chunks and ${index.linkCount} context links.`
+                : '';
+            return `${mode} ${result.scanned} notes: changed=${result.changed}, skipped=${result.skipped}, limit=${result.limit}.${indexMessage}`;
+        });
+    });
     program
         .command('db-import')
         .option('-v, --vault <vault>', 'vault directory')
@@ -792,7 +824,7 @@ export const registerWriteCommands = (program) => {
             writeConnectivity: {
                 autoLinked: added.autoLinked,
                 linkTarget: added.linkTarget,
-                guaranteedEdge: true
+                guaranteedEdge: false
             },
             possibleDuplicates,
             ...(index ? { index } : {})

package/dist/domain/markdown.js

@@ -6,6 +6,7 @@ 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 contextLinksHeadingPattern = /^(#{1,6})\s+(?:context\s+links?|links?\s+de\s+contexto)\b/i;
 const priorityRanks = {
     low: 0,
     normal: 1,
@@ -18,7 +19,7 @@ const priorityBoosts = {
     high: 3,
     critical: 6
 };
-export const graphLinkModelVersion = 3;
+export const graphLinkModelVersion = 4;
 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],
@@ -113,6 +114,35 @@ const compareGraphLinks = (left, right) => {
 export const selectGraphWikiLinkWeights = (links) => {
     return [...links].sort(compareGraphLinks);
 };
+const contextLinkLines = (content) => {
+    const lines = visibleMarkdownLines(content);
+    const selected = [];
+    let insideContextLinks = false;
+    let headingDepth = 0;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        const trimmed = line.content.trim();
+        if (line.fenced) {
+            continue;
+        }
+        const heading = trimmed.match(/^(#{1,6})\s+/);
+        const contextHeading = trimmed.match(contextLinksHeadingPattern);
+        if (contextHeading) {
+            insideContextLinks = true;
+            headingDepth = contextHeading[1].length;
+            continue;
+        }
+        if (insideContextLinks && heading && heading[1].length <= headingDepth) {
+            insideContextLinks = false;
+        }
+        if (insideContextLinks) {
+            selected.push(line.content);
+        }
+    }
+    return selected;
+};
+export const hasContextLinksSection = (content) => visibleMarkdownLines(content).some((line) => !line.fenced && contextLinksHeadingPattern.test(line.content.trim()));
+export const extractContextLinkWeights = (content) => selectGraphWikiLinkWeights(extractWikiLinkWeights(contextLinkLines(content).join('\n')));
 const extractTitle = (filePath, content, frontmatter) => {
     if (frontmatter.title) {
         return normalizeTitle(frontmatter.title);
@@ -197,6 +227,7 @@ export const parseMarkdownDocument = (input) => {
         content: input.content,
         tags: extractTags(input.content),
         links: extractWikiLinks(input.content),
+        contextLinks: extractContextLinkWeights(input.content).map((link) => link.title),
         frontmatter,
         createdAt: input.createdAt.toISOString(),
         updatedAt: input.updatedAt.toISOString()
@@ -204,7 +235,7 @@ export const parseMarkdownDocument = (input) => {
 };
 export const createIndexedDocument = (document, titleToDocumentId, maxChunkCharacters = 1200) => {
     const chunks = splitIntoChunks(document.id, document.content, maxChunkCharacters);
-    const graphLinkWeights = selectGraphWikiLinkWeights(extractWikiLinkWeights(document.content).filter((link) => link.title.toLowerCase() !== document.title.toLowerCase()));
+    const graphLinkWeights = selectGraphWikiLinkWeights(extractContextLinkWeights(document.content).filter((link) => link.title.toLowerCase() !== document.title.toLowerCase()));
     const linkWeights = new Map(graphLinkWeights.map((link) => [link.title.toLowerCase(), link]));
     const links = graphLinkWeights
         .map((link) => ({

package/dist/infrastructure/file-index.js

@@ -266,7 +266,8 @@ export const openFileIndex = (vaultPath) => {
                     title: document.title,
                     path: document.path,
                     content: document.content,
-                    tags: document.tags
+                    tags: document.tags,
+                    contextLinks: document.contextLinks ?? []
                 })),
                 edges
             };
@@ -292,7 +293,8 @@ export const openFileIndex = (vaultPath) => {
                         title: document.title,
                         path: document.path,
                         content: '',
-                        tags: document.tags
+                        tags: document.tags,
+                        contextLinks: document.contextLinks ?? []
                     })),
                     edges
                 };
@@ -309,7 +311,8 @@ export const openFileIndex = (vaultPath) => {
                     title: document.title,
                     path: document.path,
                     content: document.content,
-                    tags: document.tags
+                    tags: document.tags,
+                    contextLinks: document.contextLinks ?? []
                 }
                 : undefined;
         },

package/dist/mcp/tools.js

@@ -420,7 +420,7 @@ export const addNoteTool = async (input) => {
         writeConnectivity: {
             autoLinked: added.autoLinked,
             linkTarget: added.linkTarget,
-            guaranteedEdge: true
+            guaranteedEdge: false
         },
         possibleDuplicates,
         ...(index ? { index } : {})
@@ -467,7 +467,7 @@ export const addFileTool = async (input) => {
         writeConnectivity: {
             autoLinked: added.autoLinked,
             linkTarget: added.linkTarget,
-            guaranteedEdge: true
+            guaranteedEdge: false
         },
         ...(index ? { index } : {})
     });

package/docs/ARCHITECTURE.md

@@ -154,8 +154,10 @@ server command
   -> optional index rebuild
   -> HTTP server
   -> /api/agents lists indexed namespaces
+  -> /api/graph-contexts lists visual graph contexts
   -> /api/graph reads indexed documents and links
   -> /api/graph-layout derives a star layout from indexed graph data
+  -> optional context query narrows the layout to a segment-scoped star subgraph
   -> browser renders graph canvas
 ```
 

package/package.json

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