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

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,7 +596,7 @@ 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

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-js.js

@@ -298,51 +298,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 +323,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)
@@ -431,7 +401,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)

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/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/package.json

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