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

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

@@ -2,7 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { addNoteInputSchema, addNoteTool, brokenLinksInputSchema, brokenLinksTool, contextInputSchema, contextTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, searchInputSchema, searchTool, validateInputSchema, validateTool } from './tools.js';
+import { addNoteInputSchema, addNoteTool, brokenLinksInputSchema, brokenLinksTool, contextInputSchema, contextTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool } from './tools.js';
 const readPackageVersion = () => {
     const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
     const metadata = JSON.parse(readFileSync(packagePath, 'utf8'));
@@ -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', {
@@ -35,14 +35,24 @@ export const createBrainlinkMcpServer = () => {
         description: 'Rebuild the local Brainlink index from Markdown notes.',
         inputSchema: indexInputSchema
     }, indexTool);
+    server.registerTool('brainlink_stats', {
+        title: 'Get Brainlink Vault Stats',
+        description: 'Read indexed vault statistics, including node, edge and tag totals.',
+        inputSchema: statsInputSchema
+    }, statsTool);
     server.registerTool('brainlink_validate', {
         title: 'Validate Brainlink Vault',
         description: 'Validate indexed graph health, including broken links and orphan notes.',
         inputSchema: validateInputSchema
     }, validateTool);
+    server.registerTool('brainlink_sync', {
+        title: 'Run Brainlink Sync Flow',
+        description: 'Run index, stats, validate, broken-links and orphans checks in one call. Optionally run context probe.',
+        inputSchema: syncInputSchema
+    }, syncTool);
     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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { getBrokenLinksReport, getOrphansReport, validateVault } from '../application/analyze-vault.js';
+import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../application/analyze-vault.js';
 import { addNote } from '../application/add-note.js';
 import { buildContextPackage } from '../application/build-context.js';
 import { getGraph } from '../application/get-graph.js';
@@ -18,14 +18,24 @@ const vaultInput = {
     vault: z.string().min(1).optional().describe('Vault directory. Omit to use the configured Brainlink default vault.')
 };
 const agentInput = {
-    agent: z.string().min(1).optional().describe('Agent memory namespace. Omit to read shared/default indexed memory.')
+    agent: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Agent memory namespace. Omit to use Brainlink.config defaultAgent, otherwise read all agent namespaces.')
 };
 const searchModeInput = {
     mode: z.enum(['fts', 'semantic', 'hybrid']).optional().describe('Search mode. Defaults to the Brainlink config value.')
 };
-const resolveVault = async (vault) => {
+const resolveExecutionContext = async (input) => {
     const config = await loadBrainlinkConfig();
-    return assertVaultAllowed(vault ?? config.vault, config.allowedVaults);
+    const vault = await assertVaultAllowed(input.vault ?? config.vault, config.allowedVaults);
+    const agent = input.agent ?? config.defaultAgent;
+    return {
+        vault,
+        config,
+        agent
+    };
 };
 const jsonResult = (value) => ({
     content: [
@@ -57,8 +67,8 @@ export const addNoteInputSchema = {
     content: z
         .string()
         .min(1)
-        .describe('Durable Markdown memory. Include explicit [[wiki links]] and #tags when the memory should be connected.'),
-    agent: z.string().min(1).optional().default('shared').describe('Agent memory namespace. Defaults to shared.'),
+        .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().describe('Agent memory namespace.'),
     allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.')
 };
 export const indexInputSchema = {
@@ -80,26 +90,36 @@ export const orphansInputSchema = {
     ...vaultInput,
     ...agentInput
 };
+export const statsInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const syncInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    contextQuery: z.string().min(1).optional().describe('Optional context smoke query. Omit to skip context probe.'),
+    mode: z.enum(['fts', 'semantic', 'hybrid']).optional().describe('Search mode for the optional context probe. Defaults to config value.'),
+    contextLimit: positiveInteger(12).describe('Context smoke result limit when contextQuery is provided.'),
+    contextTokens: positiveInteger(2000).describe('Context smoke token target when contextQuery is provided.')
+};
 export const contextTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const config = await loadBrainlinkConfig();
-    const mode = sanitizeSearchMode(input.mode, config.defaultSearchMode);
-    const contextPackage = await buildContextPackage(vault, input.query, input.limit, input.tokens, input.agent, mode);
+    const context = await resolveExecutionContext(input);
+    const mode = sanitizeSearchMode(input.mode, context.config.defaultSearchMode);
+    const contextPackage = await buildContextPackage(context.vault, input.query, input.limit, input.tokens, context.agent, mode);
     return jsonResult({
-        vault,
-        agent: input.agent,
+        vault: context.vault,
+        agent: context.agent,
         mode,
         ...contextPackage
     });
 };
 export const searchTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const config = await loadBrainlinkConfig();
-    const mode = sanitizeSearchMode(input.mode, config.defaultSearchMode);
-    const results = await searchKnowledge(vault, input.query, input.limit, input.agent, mode);
+    const context = await resolveExecutionContext(input);
+    const mode = sanitizeSearchMode(input.mode, context.config.defaultSearchMode);
+    const results = await searchKnowledge(context.vault, input.query, input.limit, context.agent, mode);
     return jsonResult({
-        vault,
-        agent: input.agent,
+        vault: context.vault,
+        agent: context.agent,
         query: input.query,
         limit: input.limit,
         mode,
@@ -107,60 +127,98 @@ export const searchTool = async (input) => {
     });
 };
 export const addNoteTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const path = await addNote(vault, input.title, input.content, input.agent, {
+    const context = await resolveExecutionContext(input);
+    const path = await addNote(context.vault, input.title, input.content, context.agent, {
         allowSensitive: input.allowSensitive
     });
-    const index = await indexVault(vault);
+    const index = await indexVault(context.vault);
     return jsonResult({
-        vault,
+        vault: context.vault,
         title: input.title,
-        agent: input.agent,
+        agent: context.agent,
         path,
         index
     });
 };
 export const indexTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const result = await indexVault(vault);
+    const context = await resolveExecutionContext(input);
+    const result = await indexVault(context.vault);
     return jsonResult({
-        vault,
+        vault: context.vault,
         ...result
     });
 };
 export const validateTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const validation = await validateVault(vault, input.agent);
+    const context = await resolveExecutionContext(input);
+    const validation = await validateVault(context.vault, context.agent);
     return jsonResult({
-        vault,
-        agent: input.agent,
+        vault: context.vault,
+        agent: context.agent,
         ...validation
     });
 };
 export const graphTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const graph = await getGraph(vault, input.agent);
+    const context = await resolveExecutionContext(input);
+    const graph = await getGraph(context.vault, context.agent);
     return jsonResult({
-        vault,
-        agent: input.agent,
+        vault: context.vault,
+        agent: context.agent,
         ...graph
     });
 };
 export const brokenLinksTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const brokenLinks = await getBrokenLinksReport(vault, input.agent);
+    const context = await resolveExecutionContext(input);
+    const brokenLinks = await getBrokenLinksReport(context.vault, context.agent);
     return jsonResult({
-        vault,
-        agent: input.agent,
+        vault: context.vault,
+        agent: context.agent,
         brokenLinks
     });
 };
 export const orphansTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const orphans = await getOrphansReport(vault, input.agent);
+    const context = await resolveExecutionContext(input);
+    const orphans = await getOrphansReport(context.vault, context.agent);
     return jsonResult({
-        vault,
-        agent: input.agent,
+        vault: context.vault,
+        agent: context.agent,
         orphans
     });
 };
+export const statsTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const stats = await getStats(context.vault, context.agent);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        stats
+    });
+};
+export const syncTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const index = await indexVault(context.vault);
+    const stats = await getStats(context.vault, context.agent);
+    const validation = await validateVault(context.vault, context.agent);
+    const brokenLinks = await getBrokenLinksReport(context.vault, context.agent);
+    const orphans = await getOrphansReport(context.vault, context.agent);
+    const response = {
+        vault: context.vault,
+        agent: context.agent,
+        index,
+        stats,
+        validation,
+        brokenLinks,
+        orphans
+    };
+    if (!input.contextQuery) {
+        return jsonResult(response);
+    }
+    const mode = sanitizeSearchMode(input.mode, context.config.defaultSearchMode);
+    const contextPackage = await buildContextPackage(context.vault, input.contextQuery, input.contextLimit, input.contextTokens, context.agent, mode);
+    return jsonResult({
+        ...response,
+        context: {
+            mode,
+            ...contextPackage
+        }
+    });
+};

package/docs/AGENT_USAGE.md

@@ -41,6 +41,8 @@ $HOME/.brainlink/vault
 
 Use `--vault <path>` for a one-off custom vault, or set `vault` in `brainlink.config.json` / `.brainlink.json` for a workspace-level custom default. Set `BRAINLINK_HOME` when the whole Brainlink home directory should live somewhere else.
 
+You can also set `defaultAgent` in `brainlink.config.json` / `.brainlink.json` (for example `"defaultAgent": "coding-agent"`). When set, CLI commands and MCP calls reuse it when `--agent`/`agent` is not passed.
+
 ## Agent Namespaces
 
 Each agent writes into a dedicated namespace under `agents/<agent-id>/`:
@@ -133,6 +135,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 +147,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.
@@ -196,6 +208,54 @@ If the context is empty or weak:
 3. Inspect links and backlinks.
 4. Only then answer from general reasoning.
 
+## Optimized Agent Workflow (1 to 7)
+
+Use this exact loop for higher signal and lower noise:
+
+1. Read memory before decisions:
+   - `blink context "<task>" --agent "$BLINK_AGENT" --json`
+   - Add `--mode hybrid` for mixed retrieval.
+2. Keep vault structure deterministic:
+   - Keep shared knowledge in `agents/shared`.
+   - Keep private work-in-progress in your own agent namespace.
+3. Write durable notes only, with explicit links and tags:
+   - include at least one `[[...]]` link
+   - include `#tags` for retrieval
+4. Store only stable decisions and update an existing note when possible.
+5. Use cache-conscious read/refresh cycle:
+   - prefer targeted queries over broad dumps.
+   - avoid re-indexing unless note set changed.
+6. Run guardrails regularly:
+   - `npm run brainlink:sync -- --vault ./vault --agent "$BLINK_AGENT"`.
+   - the sync flow runs `index`, `stats`, `validate`, `broken-links`, `orphans` and a quick context probe.
+7. Before responding:
+   - cite sources from context output
+   - keep output anchored in retrieved references.
+
+Templates are available in `docs/templates` for quick note creation.
+
+Recommended template:
+
+```bash
+cp docs/templates/agent-note-template.md /tmp/agent-note.md
+```
+
+### MCP Usage for the Optimized Flow
+
+When using MCP, use this compact sequence for the same memory discipline:
+
+1. Bootstrap context:
+   - `brainlink_context` with `agent`, `query`, `mode: hybrid`, `limit`.
+2. Capture durable decisions:
+   - `brainlink_add_note` with explicit `[[wiki links]]` and `#tags`.
+3. Run maintenance before handoff or before the next step:
+   - `brainlink_sync` with `agent`, `contextQuery`, `mode: hybrid`.
+4. Diagnose graph issues only when needed:
+   - `brainlink_validate`, `brainlink_broken_links`, `brainlink_orphans`.
+5. Inspect relationships:
+   - `brainlink_graph`.
+6. Use `brainlink_stats` for a quick health snapshot.
+
 ## Examples For Common Coding Agents
 
 These examples assume the agent can run shell commands in the user workspace.
@@ -464,6 +524,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"
 ```
@@ -552,4 +614,5 @@ Weak retrieval usually means:
 - Local embeddings are deterministic and provider-free; remote embedding providers are not implemented yet.
 - MCP integration is available through the `brainlink-mcp` stdio server.
 - HTTP API is local and unauthenticated.
-- Watch mode depends on platform filesystem watcher behavior.
+- Bucket vaults support S3-compatible `s3://bucket/prefix` URIs and use a local cache for SQLite indexes.
+- Watch mode depends on platform filesystem watcher behavior and is only supported for local filesystem vaults.

package/docs/ARCHITECTURE.md

@@ -105,13 +105,15 @@ Application code depends on domain rules and infrastructure interfaces.
 The infrastructure layer handles side effects:
 
 - reading Markdown files from disk
+- mirroring S3-compatible bucket Markdown into a local cache
 - writing Markdown notes
 - creating `.brainlink`
 - writing and querying SQLite
 - running FTS, semantic and hybrid retrieval
 - narrowing semantic candidates through SQLite embedding buckets before cosine scoring
 
-SQLite is an index, not the canonical storage model.
+SQLite is an index, not the canonical storage model. For bucket vaults, Markdown
+objects in the bucket remain canonical and SQLite is still local derived data.
 
 ## Indexing Flow
 
@@ -216,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.
@@ -240,6 +259,7 @@ Relevant content
 Permanent:
 
 - Markdown files
+- S3-compatible Markdown objects when the vault is `s3://bucket/prefix`
 - optional Git history around the vault
 
 Canonical agent memory lives under:
@@ -251,6 +271,7 @@ vault/agents/<agent-id>/**/*.md
 Rebuildable:
 
 - `.brainlink/brainlink.db`
+- `$BRAINLINK_HOME/bucket-cache`
 - FTS records
 - local embedding vectors
 - local embedding bucket index

package/docs/RELEASE.md

@@ -32,7 +32,7 @@ blink context "release smoke" --vault ./tmp-vault --mode hybrid --json
 blink server --vault ./tmp-vault --host 127.0.0.1 --port 4321
 ```
 
-9. Verify the server refuses accidental public binds:
+9. Verify the server refuses public binds:
 
 ```bash
 blink server --vault ./tmp-vault --host 0.0.0.0

package/docs/templates/agent-namespace-bootstrap.md

@@ -0,0 +1,27 @@
+# Namespace Bootstrap for New Agent
+
+# <agent-id> Agent Notes
+
+## Purpose
+
+- Scope: 
+- Owner: 
+- Active project contexts:
+
+## Core Notes
+
+- [[Architecture]]
+- [[Coding Conventions]]
+- [[Runbook]]
+- [[Decision Log]]
+- [[Open Questions]]
+
+## Process
+
+1. Before task: context "<task>" --agent <agent-id> --json
+2. During task: document durable findings with explicit [[wiki links]]
+3. After task: add note + index + validation run
+
+## Tags
+
+#agent #<agent-id> #process

package/docs/templates/agent-note-template.md

@@ -0,0 +1,31 @@
+# Agent Note Template
+
+# <Title>
+
+## Context
+
+- What was decided or discovered.
+- Why this happened.
+- Expected impact or expected behavior.
+
+## References
+
+- [[Parent concept]]
+- [[Related decision]]
+
+## Notes
+
+#decision #<domain> #agent
+
+---
+
+## Changelog
+
+- YYYY-MM-DD: created
+
+## Durability checklist
+
+- The note has a clear title.
+- It links to at least one existing note (unless this is a root concept).
+- It has at least one `#tag`.
+- The content is stable knowledge, not one-off chat or session noise.