@andespindola/brainlink 0.1.0-beta.150 → 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/CHANGELOG.md

@@ -14,6 +14,9 @@
 - Added default MCP startup bootstrap behavior controlled by `brainlink_policy.autoBootstrapOnStartup`.
 - Added CLI MCP policy presets through `blink agent policy --preset fully-auto|strict`.
 - Added write-time non-orphan enforcement by auto-linking notes without wiki edges to agent hub notes.
+- Changed graph indexing to keep every non-self Markdown wiki link as a weighted graph edge so the default star graph represents complete note connectivity.
+- Added `blink index --full` and MCP `brainlink_index` `full=true` for complete source reindexing without clearing the existing index first.
+- Improved index migration so stale graph link model metadata automatically triggers a complete source reindex.
 - Added MCP `brainlink_policy` presets (`fully-auto`, `strict`) for one-call policy switching.
 - Added MCP write connectivity metadata in `brainlink_add_note`/`brainlink_add_file` responses.
 - Added MCP `brainlink_recommendations` tool for plug-and-play workflow guidance.

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.
 
@@ -538,7 +538,7 @@ Available tools:
 - `brainlink_add_file`: ingest a local file as a note and reindex.
 - `brainlink_volatile_add`: write temporary agent-decided memory with TTL; volatile sections are included in context and never create durable graph edges.
 - `brainlink_volatile_clear`: clear temporary memory for the current vault/agent namespace.
-- `brainlink_index`: rebuild the vault index.
+- `brainlink_index`: rebuild the vault index. Pass `full=true` for a complete source reindex.
 - `brainlink_stats`: read indexed vault statistics.
 - `brainlink_validate`: validate broken links and orphan notes.
 - `brainlink_sync`: run index, stats, validation, broken-link and orphan checks in one call.
@@ -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 promotes only representative graph links per note: high-priority and high-weight links win, structural hub links such as `Memory Hub`, `Knowledge Root`, `MOC` and map notes are suppressed when stronger direct links exist, and 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,8 +596,8 @@ When native GUI is used, the GUI window automatically closes when the `blink ser
 The graph UI shows:
 
 - notes as nodes
-- representative `[[wiki links]]` as weighted edges
-- star layout centered on the primary hub, without rewriting or flattening underlying relationships
+- 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
@@ -777,9 +784,12 @@ When action is not `merge`, Brainlink still creates a low-priority related edge
 ```bash
 blink index
 blink index --vault ./vault
+blink index --vault ./vault --full
 ```
 
-Rebuilds the local index from Markdown files.
+Rebuilds the local index from Markdown files. By default, unchanged notes reuse existing indexed chunks for speed.
+Use `--full` to force a complete source reindex of every Markdown note. Full reindex builds the replacement index before persisting it, so existing context is not cleared first.
+Brainlink also performs this complete source reindex automatically when it detects that the stored graph link model is older than the current model.
 
 ### `bench`
 

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/index-vault.js

@@ -85,8 +85,8 @@ const readChangedDocuments = async (absoluteVaultPath, changedSummaries) => {
     })));
     return new Map(parsed.map((document) => [document.path, document]));
 };
-export const indexVault = async (vaultPath) => {
-    return indexVaultWithOptions(vaultPath, {});
+export const indexVault = async (vaultPath, options = {}) => {
+    return indexVaultWithOptions(vaultPath, options);
 };
 export const indexVaultWithOptions = async (vaultPath, options) => {
     const startedAt = process.hrtime.bigint();
@@ -113,6 +113,7 @@ export const indexVaultWithOptions = async (vaultPath, options) => {
         markdownFiles: summaries.length,
         hasPreviousState: previousState != null
     });
+    const fullReindex = options.full === true;
     const index = openFileIndex(absoluteVaultPath);
     try {
         const existingIndexedDocuments = await index.getIndexedDocuments();
@@ -120,10 +121,13 @@ export const indexVaultWithOptions = async (vaultPath, options) => {
         const currentSnapshot = toSnapshot(summaries);
         const currentSnapshotMap = createSnapshotMap(currentSnapshot);
         const previousSnapshotMap = createSnapshotMap(previousState?.files ?? []);
+        const graphLinkModelChanged = previousState != null &&
+            previousState.graphLinkModelVersion !== graphLinkModelVersion;
+        const fullSourceReindex = fullReindex || graphLinkModelChanged;
         const settingsChanged = previousState == null ||
             previousState.chunkSize !== config.chunkSize ||
             previousState.embeddingProvider !== config.embeddingProvider ||
-            previousState.graphLinkModelVersion !== graphLinkModelVersion;
+            graphLinkModelChanged;
         const packSettingsChanged = previousState == null ||
             previousState.searchPackRowChunkSize !== config.searchPack.rowChunkSize ||
             previousState.searchPackCompressionLevel !== config.searchPack.compressionLevel ||
@@ -132,7 +136,8 @@ export const indexVaultWithOptions = async (vaultPath, options) => {
         for (let index = 0; index < summaries.length; index += 1) {
             const summary = summaries[index];
             const previous = previousSnapshotMap.get(summary.relativePath);
-            const changed = settingsChanged ||
+            const changed = fullSourceReindex ||
+                settingsChanged ||
                 previous == null ||
                 previous.mtimeMs !== summary.updatedAt.getTime() ||
                 previous.size !== summary.size ||
@@ -148,7 +153,8 @@ export const indexVaultWithOptions = async (vaultPath, options) => {
         if (changedPaths.size === 0 &&
             !hasDeletes &&
             existingIndexedDocuments.length === summaries.length &&
-            previousState != null) {
+            previousState != null &&
+            !fullReindex) {
             const result = {
                 ...toIndexResult(existingIndexedDocuments),
                 elapsedMs: elapsedMs(),
@@ -205,7 +211,6 @@ export const indexVaultWithOptions = async (vaultPath, options) => {
             return needsRelink ? relinkIndexedDocument(existing, titleMaps) : existing;
         });
         emit('persist', 'start', 'Persisting index');
-        await index.reset();
         await index.saveDocuments(indexedDocuments);
         emit('persist', 'finish', 'Index persisted', {
             indexedDocuments: indexedDocuments.length
@@ -217,6 +222,8 @@ export const indexVaultWithOptions = async (vaultPath, options) => {
         const previousPendingPackChanges = previousState?.pendingPackChanges ?? 0;
         const pendingPackChanges = previousPendingPackChanges + changedCount;
         const shouldRebuildPacks = !existingPackManifest ||
+            fullReindex ||
+            graphLinkModelChanged ||
             settingsChanged ||
             packSettingsChanged ||
             hasDeletes ||
@@ -226,21 +233,25 @@ export const indexVaultWithOptions = async (vaultPath, options) => {
         let packResult;
         const packReason = !existingPackManifest
             ? 'Missing pack manifest'
-            : manifestRecovery.repaired
-                ? 'Pack manifest repaired from existing packs'
-                : settingsChanged
-                    ? 'Index settings changed'
-                    : packSettingsChanged
-                        ? 'Search pack settings changed'
-                        : hasDeletes
-                            ? 'Document deletions detected'
-                            : changedCount >= 400
-                                ? 'Changed file count threshold reached'
-                                : changeRatio >= 0.04
-                                    ? 'Change ratio threshold reached'
-                                    : pendingPackChanges >= 1200
-                                        ? 'Pending pack changes threshold reached'
-                                        : 'Pack rebuild skipped';
+            : fullReindex
+                ? 'Full reindex requested'
+                : graphLinkModelChanged
+                    ? 'Graph link model changed'
+                    : manifestRecovery.repaired
+                        ? 'Pack manifest repaired from existing packs'
+                        : settingsChanged
+                            ? 'Index settings changed'
+                            : packSettingsChanged
+                                ? 'Search pack settings changed'
+                                : hasDeletes
+                                    ? 'Document deletions detected'
+                                    : changedCount >= 400
+                                        ? 'Changed file count threshold reached'
+                                        : changeRatio >= 0.04
+                                            ? 'Change ratio threshold reached'
+                                            : pendingPackChanges >= 1200
+                                                ? 'Pending pack changes threshold reached'
+                                                : 'Pack rebuild skipped';
         if (shouldRebuildPacks) {
             emit('packs', 'start', 'Rebuilding compressed search packs', {
                 reason: packReason

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 } : {})
@@ -860,12 +892,17 @@ export const registerWriteCommands = (program) => {
     program
         .command('index')
         .option('-v, --vault <vault>', 'vault directory')
+        .option('--full', 'force a complete reindex from Markdown source without reusing unchanged index entries')
         .option('--json', 'print machine-readable JSON')
         .description('index markdown notes, links, tags and chunks')
         .action(async (options) => {
         const resolved = await resolveOptions(options);
-        const result = await indexVault(resolved.vault);
-        print(options.json, result, () => `Indexed ${result.documentCount} documents, ${result.chunkCount} chunks and ${result.linkCount} links`);
+        const result = await indexVault(resolved.vault, {
+            full: options.full === true
+        });
+        print(options.json, result, () => options.full === true
+            ? `Fully reindexed ${result.documentCount} documents, ${result.chunkCount} chunks and ${result.linkCount} links`
+            : `Indexed ${result.documentCount} documents, ${result.chunkCount} chunks and ${result.linkCount} links`);
     });
     program
         .command('bench')

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,9 +19,7 @@ const priorityBoosts = {
     high: 3,
     critical: 6
 };
-const graphLinkLimit = 4;
-export const graphLinkModelVersion = 2;
-const hubLinkTitlePattern = /\b(?:memory\s*hub|knowledge\s*root|moc|map)\b/i;
+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],
@@ -34,7 +33,6 @@ const priorityPatterns = [
 const normalizeTitle = (title) => title.trim().replace(/\.md$/i, '');
 const unique = (values) => Array.from(new Set(values.map((value) => value.trim()).filter(Boolean)));
 const maxPriority = (left, right) => priorityRanks[left] >= priorityRanks[right] ? left : right;
-const isHubLinkTitle = (title) => hubLinkTitlePattern.test(title);
 const parseFrontmatter = (content) => {
     const match = content.match(frontmatterPattern);
     if (!match) {
@@ -114,12 +112,37 @@ const compareGraphLinks = (left, right) => {
     return left.title.localeCompare(right.title);
 };
 export const selectGraphWikiLinkWeights = (links) => {
-    const sorted = [...links].sort(compareGraphLinks);
-    const structuralLinks = sorted.filter((link) => isHubLinkTitle(link.title) && !['high', 'critical'].includes(link.priority));
-    const directLinks = sorted.filter((link) => !structuralLinks.includes(link));
-    const selected = (directLinks.length > 0 ? directLinks : sorted).slice(0, graphLinkLimit);
-    return selected.length > 0 ? selected : structuralLinks.slice(0, graphLinkLimit);
+    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);
@@ -204,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()
@@ -211,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/server.js

@@ -70,7 +70,7 @@ export const createBrainlinkMcpServer = () => {
     }, addFileTool);
     server.registerTool('brainlink_index', {
         title: 'Index Brainlink Vault',
-        description: 'Rebuild the local Brainlink index from Markdown notes.',
+        description: 'Rebuild the local Brainlink index from Markdown notes. Pass full=true to force a complete source rebuild.',
         inputSchema: indexInputSchema
     }, indexTool);
     server.registerTool('brainlink_stats', {

package/dist/mcp/tools.js

@@ -262,7 +262,12 @@ export const addFileInputSchema = {
     allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.')
 };
 export const indexInputSchema = {
-    ...vaultInput
+    ...vaultInput,
+    full: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Force a complete reindex from Markdown source without reusing unchanged index entries.')
 };
 export const validateInputSchema = {
     ...vaultInput,
@@ -415,7 +420,7 @@ export const addNoteTool = async (input) => {
         writeConnectivity: {
             autoLinked: added.autoLinked,
             linkTarget: added.linkTarget,
-            guaranteedEdge: true
+            guaranteedEdge: false
         },
         possibleDuplicates,
         ...(index ? { index } : {})
@@ -462,14 +467,16 @@ export const addFileTool = async (input) => {
         writeConnectivity: {
             autoLinked: added.autoLinked,
             linkTarget: added.linkTarget,
-            guaranteedEdge: true
+            guaranteedEdge: false
         },
         ...(index ? { index } : {})
     });
 };
 export const indexTool = async (input) => {
     const context = await resolveExecutionContext(input);
-    const result = await indexVault(context.vault);
+    const result = await indexVault(context.vault, {
+        full: input.full === true
+    });
     return jsonResult({
         vault: context.vault,
         ...result

package/docs/AGENT_USAGE.md

@@ -161,7 +161,7 @@ Brainlink only builds graph edges from Markdown `[[wiki links]]`.
 
 The `context` command is read-only. It retrieves indexed notes and returns a compact package for the model, but it does not write memory, create backlinks, infer relationships or modify the graph. If an agent reads context and then learns something durable, the agent must write a note with explicit links before that knowledge becomes connected memory.
 
-Graph edges are weighted during indexing. Repeated links increase weight. Links inside headings or task-list lines receive a small boost. Priority markers on the same line as a link raise its priority. The graph relationship model promotes only representative links per note: high-priority and high-weight links win, structural hub links such as `Memory Hub`, `Knowledge Root`, `MOC` and map notes are not promoted when stronger direct links exist, and each note emits a small bounded set of graph edges. Older indexes without the current graph link model version are automatically rebuilt on the next index run.
+Graph edges are weighted during indexing. Repeated links increase weight. Links inside headings or task-list lines receive a small boost. Priority markers on the same line as a link raise its priority. The graph relationship model indexes every non-self Markdown `[[wiki link]]` as an edge, including structural hub links such as `Memory Hub`, `Knowledge Root`, `MOC` and map notes. Older indexes without the current graph link model version are automatically rebuilt on the next index run.
 
 ```md
 - [ ] Review [[Architecture]] priority: high
@@ -292,6 +292,8 @@ blink add "Implementation Boundary" \
 blink index
 ```
 
+Use `blink index --full` when you need to rebuild every note from Markdown source. Full reindexing builds the replacement index before persisting it, preserving the previous context until the new index is ready. Brainlink also runs this complete source reindex automatically when it detects an older stored graph link model.
+
 ### Claude Code-Style Agent
 
 Use Brainlink as a preflight memory read before editing files:

package/package.json

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