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

package/AGENTS.md

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

package/README.md

@@ -62,6 +62,7 @@ Markdown is the source of truth. `.brainlink/brainlink.db` is only a rebuildable
 
 - Local-first Markdown vault.
 - Obsidian-compatible `[[wiki links]]` and `#tags`.
+- Weighted graph edges so agents can rank relationship importance and priority.
 - Backlinks, broken-link reports, orphan detection and validation.
 - Full-text, semantic and hybrid retrieval modes.
 - SQLite-backed semantic candidate buckets for larger vaults.
@@ -390,12 +391,21 @@ Available tools:
 - `brainlink_add_note`: write durable Markdown memory and reindex.
 - `brainlink_index`: rebuild the vault index.
 - `brainlink_validate`: validate broken links and orphan notes.
-- `brainlink_graph`: read indexed graph nodes and links.
+- `brainlink_graph`: read indexed graph nodes and weighted links.
 - `brainlink_broken_links`: list unresolved wiki links.
 - `brainlink_orphans`: list disconnected notes.
 
 The same linking rule applies through MCP: `brainlink_context` is read-only, and real graph links require Markdown notes with explicit `[[wiki links]]` followed by indexing.
 
+Agents can raise the importance of a relationship by putting priority markers on the same line as a wiki link:
+
+```md
+- [ ] Review [[Architecture]] priority: high
+Related: [[Incident Runbook]] #critical
+```
+
+Indexed edges expose `weight` and `priority` (`low`, `normal`, `high`, `critical`) through CLI JSON, HTTP graph APIs and `brainlink_graph`.
+
 ## Graph UI
 
 Start the local frontend:
@@ -409,7 +419,7 @@ By default, the server uses `$HOME/.brainlink/vault`. Pass `--vault ./vault` onl
 The graph UI shows:
 
 - notes as nodes
-- `[[wiki links]]` as edges
+- `[[wiki links]]` as weighted edges
 - backlinks and outgoing links
 - full Markdown content for the selected note
 - neutral graph nodes with segment/group metadata
@@ -523,7 +533,7 @@ blink links --vault ./vault
 blink links --vault ./vault --agent coding-agent
 ```
 
-Lists indexed wiki links.
+Lists indexed wiki links. JSON output includes `weight` and `priority` for each relationship.
 
 ### `backlinks`
 
@@ -532,7 +542,7 @@ blink backlinks "Architecture" --vault ./vault
 blink backlinks "Architecture" --vault ./vault --agent coding-agent
 ```
 
-Lists notes pointing to a target title.
+Lists notes pointing to a target title, ordered by strongest relationship first. JSON output includes `weight` and `priority`.
 
 ### `graph`
 
@@ -541,7 +551,7 @@ blink graph --vault ./vault --json
 blink graph --vault ./vault --agent coding-agent --json
 ```
 
-Prints indexed graph data.
+Prints indexed graph data. Edges include `weight` and `priority` so agents can categorize importance.
 
 ### `stats`
 

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

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

package/dist/domain/graph-layout.js

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

package/dist/domain/markdown.js

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

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

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

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

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

package/dist/infrastructure/sqlite/schema.js

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

package/dist/infrastructure/sqlite-index.js

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

package/dist/mcp/server.js

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

package/dist/mcp/tools.js

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

package/docs/AGENT_USAGE.md

@@ -133,6 +133,7 @@ Rules:
 
 - Use a clear title.
 - Use `[[Note Title]]` for relationships.
+- Put priority markers near links when the relationship is important.
 - Use tags for retrieval.
 - Keep each note focused.
 - Prefer summaries over raw transcripts.
@@ -144,6 +145,15 @@ Brainlink only builds graph edges from Markdown `[[wiki links]]`.
 
 The `context` command is read-only. It retrieves indexed notes and returns a compact package for the model, but it does not write memory, create backlinks, infer relationships or modify the graph. If an agent reads context and then learns something durable, the agent must write a note with explicit links before that knowledge becomes connected memory.
 
+Graph edges are weighted during indexing. Repeated links increase weight. Links inside headings or task-list lines receive a small boost. Priority markers on the same line as a link raise its priority:
+
+```md
+- [ ] Review [[Architecture]] priority: high
+Related: [[Incident Runbook]] #critical
+```
+
+Agents should use weighted graph output to sort relationships by importance. Edges expose `weight` and `priority`, where priority is one of `low`, `normal`, `high` or `critical`.
+
 Required write behavior:
 
 1. Choose a clear title for the new note.
@@ -464,6 +474,8 @@ Available MCP tools:
 
 MCP clients can pass `vault` and `agent` arguments per tool call. Set `BRAINLINK_ALLOWED_VAULTS` when exposing Brainlink to an external agent process so a tool cannot pass arbitrary vault paths:
 
+`brainlink_graph` returns weighted edges. Agents should prefer higher `weight` and stronger `priority` when deciding which related notes matter most.
+
 ```bash
 export BRAINLINK_ALLOWED_VAULTS="/absolute/path/to/project-vault"
 ```

package/docs/ARCHITECTURE.md

@@ -218,6 +218,23 @@ source note -> target note
 
 The `backlinks` command queries indexed links pointing to a target title. With `--agent`, it only returns links from that namespace.
 
+## Weighted Links
+
+Each indexed wiki link is stored as a graph edge with:
+
+- `weight`: numeric relationship strength.
+- `priority`: one of `low`, `normal`, `high` or `critical`.
+
+The parser derives weight from repeated links, task-list context, heading context and priority markers on the same line as a wiki link. Examples:
+
+```md
+Related: [[Architecture]]
+- [ ] Review [[Architecture]] priority: high
+Escalate [[Incident Runbook]] #critical
+```
+
+Backlink and graph readers return those fields to CLI JSON, HTTP API and MCP clients. Backlink queries use the normalized `to_title_key` column instead of applying `lower(...)` at read time.
+
 ## Context Building
 
 `context` uses search results and selects one chunk per document while staying inside an estimated token budget.

package/package.json

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