@andespindola/brainlink 1.0.3 → 1.0.4

package/README.md

@@ -534,9 +534,14 @@ Available tools:
 - `brainlink_context`: read indexed context for a task or question; pass `strategy: "rag"` for fresh retrieval assembly, `strategy: "cag"` for persisted context packs or `strategy: "auto"` for CAG hits with RAG fallback.
 - `brainlink_context_packs`: list or clear persisted CAG context packs.
 - `brainlink_search`: search indexed notes.
+- `brainlink_explain`: explain why indexed notes matched a query.
 - `brainlink_dedupe`: detect duplicate candidates using exact hash + semantic similarity scores.
 - `brainlink_resolve_duplicate`: resolve duplicate pairs (`merge`, `link`, `ignore`) with connectivity-safe fallback edges.
 - `brainlink_add_note`: write durable Markdown memory and reindex.
+- `brainlink_remember`: capture durable memory with inferred title, tags and Context Links; supports dry-run.
+- `brainlink_inbox_add`: capture a quick untriaged memory item.
+- `brainlink_inbox_list`: list untriaged inbox memory items.
+- `brainlink_inbox_process`: suggest titles, tags and links for inbox items.
 - `brainlink_delete_note`: delete a durable Markdown note by title or path after explicit confirmation and reindex.
 - `brainlink_add_file`: ingest a local file as a note and reindex.
 - `brainlink_canonicalize_context_links`: ensure existing notes link to inferred context hubs.
@@ -544,14 +549,20 @@ Available tools:
 - `brainlink_volatile_clear`: clear temporary memory for the current vault/agent namespace.
 - `brainlink_index`: rebuild the vault index. Pass `full=true` for a complete source reindex.
 - `brainlink_stats`: read indexed vault statistics.
+- `brainlink_doctor_actions`: return vault checks plus prioritized executable next actions.
 - `brainlink_validate`: validate broken links and orphan notes.
 - `brainlink_sync`: run index, stats, validation, broken-link and orphan checks in one call.
 - `brainlink_graph`: read indexed graph nodes and weighted links.
 - `brainlink_graph_contexts`: list the visual graph contexts used by the local server.
 - `brainlink_broken_links`: list unresolved wiki links.
+- `brainlink_suggest_links`: suggest Context Links for content or fixes for unresolved wiki links.
+- `brainlink_repair_links`: repair unresolved wiki links by retargeting safe matches or creating placeholder target notes.
 - `brainlink_orphans`: list disconnected notes.
+- `brainlink_session_close`: write or preview a session handoff note.
+- `brainlink_project_init`: seed project memory from local project docs.
 
 For the most automatic workflow, start MCP sessions with `brainlink_bootstrap` (optionally with `query`) and then continue with `brainlink_context`/`brainlink_add_note`.
+MCP is kept in parity with practical Brainlink CLI workflows when a feature is safe and meaningful for tool clients.
 By default, Brainlink enforces context-first for MCP reads (`enforceContextFirst=true`): non-context read tools return preflight until `brainlink_context` is called for the vault/agent session.
 By default, MCP startup already runs bootstrap on the configured default vault/agent (`autoBootstrapOnStartup=true`), so sessions begin warm.
 By default, Brainlink enforces bootstrap and auto-runs it for read tools when session state is missing or stale (`autoBootstrapOnRead=true`).
@@ -701,6 +712,27 @@ blink quickstart --vault ./team-vault --mcp-only --json
 Runs index + doctor + stats + validation, refreshes bootstrap session readiness, optionally returns context for a query, and (by default) upgrades local agent integration for plug-and-play MCP usage.
 When `--mode`, `--limit` or `--tokens` are omitted, quickstart uses agent profile defaults when available.
 
+### Practical Memory Workflows
+
+```bash
+blink remember --content "Keep Markdown as the source of truth. #architecture"
+blink remember --content-file ./handoff.md --dry-run
+blink inbox add --content "Quick note to triage later"
+blink inbox list
+blink inbox process --json
+blink session-close --content "Validated release flow"
+blink daily --dry-run
+blink suggest-links --content "Architecture and release flow"
+blink suggest-links --broken
+blink repair-links
+blink search "architecture" --explain
+blink explain "architecture"
+blink doctor --actionable
+blink project init --path .
+```
+
+`remember` infers a title, tags and Context Links before writing a durable note. `inbox` captures quick untriaged memory and later suggests titles, tags and links. `session-close`/`daily` writes a handoff note with vault health and git status. `suggest-links` proposes Context Links or likely fixes for unresolved wiki links. `repair-links` retargets high-confidence broken links and creates `#triage` placeholder notes for unresolved targets that cannot be safely retargeted. `doctor --actionable` returns prioritized commands instead of only checks. `project init` seeds memory from project docs such as `AGENTS.md`, `README.md` and architecture docs.
+
 ### `config`
 
 ```bash

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

@@ -628,6 +628,40 @@ li small {
   grid-column: span 2;
 }
 
+.content-actions {
+  grid-column: span 2;
+}
+
+.node-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.node-actions button {
+  width: auto;
+  min-height: 34px;
+  padding: 0 10px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--panel-strong);
+  color: var(--text);
+  cursor: pointer;
+}
+
+.node-actions button:hover,
+.node-actions button:focus {
+  border-color: var(--accent);
+  color: var(--accent);
+}
+
+#contentActionStatus {
+  min-height: 16px;
+  margin: 0;
+  color: var(--muted);
+  font-size: 12px;
+}
+
 .content-dialog .note-content {
   max-height: none;
   min-height: 0;

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

@@ -107,6 +107,15 @@ export const createClientHtml = () => `<!doctype html>
                   <h3>Backlinks</h3>
                   <ul id="contentIncoming"></ul>
                 </section>
+                <section class="content-meta-section content-actions">
+                  <h3>Actions</h3>
+                  <div class="node-actions">
+                    <button id="copyWikiLink" type="button">Copy wiki link</button>
+                    <button id="suggestNodeLinks" type="button">Suggest links</button>
+                  </div>
+                  <p id="contentActionStatus"></p>
+                  <ul id="contentLinkSuggestions"></ul>
+                </section>
               </div>
               <pre id="contentBody" class="note-content"></pre>
             </article>

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

@@ -33,7 +33,11 @@ const elements = {
   contentOutgoing: byId('contentOutgoing'),
   contentIncoming: byId('contentIncoming'),
   contentBody: byId('contentBody'),
-  contentClose: byId('contentClose')
+  contentClose: byId('contentClose'),
+  copyWikiLink: byId('copyWikiLink'),
+  suggestNodeLinks: byId('suggestNodeLinks'),
+  contentActionStatus: byId('contentActionStatus'),
+  contentLinkSuggestions: byId('contentLinkSuggestions')
 }
 
 const state = {
@@ -926,6 +930,59 @@ const closeContentDialog = () => {
   elements.contentDialog.hidden = true
 }
 
+const selectedNode = () => {
+  if (!state.selectedNodeId) {
+    return null
+  }
+
+  const packed = nodeByIdFromChunk().get(state.selectedNodeId)
+  if (!packed) {
+    return null
+  }
+
+  return {
+    id: packed[0],
+    title: packed[1],
+    path: packed[4] || ''
+  }
+}
+
+const copySelectedWikiLink = async () => {
+  const node = selectedNode()
+  if (!node) {
+    elements.contentActionStatus.textContent = 'Select a note first.'
+    return
+  }
+
+  const value = '[[' + node.title + ']]'
+  try {
+    await navigator.clipboard.writeText(value)
+    elements.contentActionStatus.textContent = 'Copied ' + value
+  } catch {
+    elements.contentActionStatus.textContent = value
+  }
+}
+
+const loadSelectedLinkSuggestions = async () => {
+  const content = elements.contentBody.textContent || ''
+  if (!content.trim()) {
+    elements.contentActionStatus.textContent = 'Selected note has no content.'
+    return
+  }
+
+  elements.contentActionStatus.textContent = 'Loading suggestions...'
+  const response = await fetch('/api/suggest-links?limit=5&content=' + encodeURIComponent(content.slice(0, 2000)) + scopeQuery('&'))
+  if (!response.ok) {
+    throw new Error('Failed to load link suggestions')
+  }
+  const payload = await response.json()
+  const suggestions = Array.isArray(payload.suggestions) ? payload.suggestions : []
+  elements.contentLinkSuggestions.innerHTML = suggestions.length > 0
+    ? suggestions.map((item) => '<li><button type="button" data-title="' + escapeHtml(item.title) + '">[[' + escapeHtml(item.title) + ']]</button></li>').join('')
+    : '<li>No strong suggestions</li>'
+  elements.contentActionStatus.textContent = suggestions.length > 0 ? 'Suggested Context Links' : 'No strong suggestions found.'
+}
+
 const loadNodeDetails = async (nodeId) => {
   if (!nodeId) {
     return
@@ -965,6 +1022,8 @@ const loadNodeDetails = async (nodeId) => {
   elements.contentOutgoing.innerHTML = list(related.outgoing)
   elements.contentIncoming.innerHTML = list(related.incoming)
   elements.contentBody.textContent = typeof node.content === 'string' ? node.content : ''
+  elements.contentActionStatus.textContent = ''
+  elements.contentLinkSuggestions.innerHTML = ''
 
   openContentDialog()
 }
@@ -1518,6 +1577,31 @@ const setupControls = () => {
     closeContentDialog()
   })
 
+  elements.copyWikiLink.addEventListener('click', () => {
+    copySelectedWikiLink().catch((error) => {
+      elements.contentActionStatus.textContent = error instanceof Error ? error.message : String(error)
+    })
+  })
+
+  elements.suggestNodeLinks.addEventListener('click', () => {
+    loadSelectedLinkSuggestions().catch((error) => {
+      elements.contentActionStatus.textContent = error instanceof Error ? error.message : String(error)
+    })
+  })
+
+  elements.contentLinkSuggestions.addEventListener('click', (event) => {
+    const button = event.target.closest('button[data-title]')
+    if (!button) {
+      return
+    }
+    const value = '[[' + button.dataset.title + ']]'
+    navigator.clipboard.writeText(value).then(() => {
+      elements.contentActionStatus.textContent = 'Copied ' + value
+    }).catch(() => {
+      elements.contentActionStatus.textContent = value
+    })
+  })
+
   elements.contentDialog.addEventListener('click', (event) => {
     if (event.target === elements.contentDialog) {
       closeContentDialog()

package/dist/application/inbox.js

@@ -0,0 +1,54 @@
+import { relative } from 'node:path';
+import { addNoteWithMetadata } from './add-note.js';
+import { buildRememberSuggestion } from './memory-suggestions.js';
+import { indexVault } from './index-vault.js';
+import { ensureVault, readMarkdownFiles } from '../infrastructure/file-system-vault.js';
+const compactPreview = (content) => content
+    .replace(/^---[\s\S]*?\n---\n?/, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 180);
+const extractTitle = (content, fallback) => content.match(/^#\s+(.+)$/m)?.[1]?.trim() || fallback;
+export const addInboxItem = async (input) => {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const result = await addNoteWithMetadata(input.vaultPath, `Inbox ${timestamp}`, `${input.content.trim()}\n\n#inbox #triage`, input.agentId, {
+        autoContextLinks: false
+    });
+    const index = input.autoIndex === false ? null : await indexVault(input.vaultPath);
+    return {
+        item: result,
+        index
+    };
+};
+export const listInboxItems = async (vaultPath, limit = 20) => {
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const files = await readMarkdownFiles(absoluteVaultPath);
+    return files
+        .filter((file) => /(^|\s)#inbox\b/.test(file.content))
+        .sort((left, right) => right.updatedAt.getTime() - left.updatedAt.getTime())
+        .slice(0, Math.max(0, limit))
+        .map((file) => ({
+        title: extractTitle(file.content, 'Inbox item'),
+        path: relative(absoluteVaultPath, file.absolutePath),
+        updatedAt: file.updatedAt.toISOString(),
+        preview: compactPreview(file.content)
+    }));
+};
+export const processInboxItems = async (input) => {
+    const items = await listInboxItems(input.vaultPath, input.limit ?? 10);
+    const suggestions = await Promise.all(items.map(async (item) => {
+        const suggestion = await buildRememberSuggestion({
+            vaultPath: input.vaultPath,
+            content: item.preview,
+            agentId: input.agentId,
+            linkLimit: 5
+        });
+        return {
+            ...item,
+            suggestedTitle: suggestion.title,
+            suggestedTags: suggestion.tags,
+            suggestedLinks: suggestion.links.map((link) => link.title)
+        };
+    }));
+    return suggestions;
+};

package/dist/application/memory-suggestions.js

@@ -0,0 +1,220 @@
+import { readFile } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import { ensureVault } from '../infrastructure/file-system-vault.js';
+import { searchKnowledge } from './search-knowledge.js';
+import { getGraphSummary } from './get-graph-summary.js';
+import { getBrokenLinksReport } from './analyze-vault.js';
+const stopwords = new Set([
+    'about',
+    'after',
+    'agent',
+    'agents',
+    'antes',
+    'brainlink',
+    'com',
+    'como',
+    'das',
+    'dos',
+    'for',
+    'from',
+    'para',
+    'por',
+    'que',
+    'the',
+    'this',
+    'uma',
+    'with'
+]);
+const wordPattern = /[\p{L}\p{N}_-]+/gu;
+const tagPattern = /(^|\s)#([A-Za-z0-9][A-Za-z0-9_-]*)/g;
+const unique = (values) => Array.from(new Set(values));
+const normalizeText = (value) => value
+    .normalize('NFKD')
+    .replace(/\p{Diacritic}/gu, '')
+    .toLowerCase();
+const words = (value) => normalizeText(value)
+    .match(wordPattern)
+    ?.filter((word) => word.length > 2 && !stopwords.has(word)) ?? [];
+const titleCase = (value) => value
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((word) => `${word.slice(0, 1).toUpperCase()}${word.slice(1)}`)
+    .join(' ');
+const stripMarkdownNoise = (value) => value
+    .replace(/^---[\s\S]*?\n---\n?/, '')
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/[#>*_\-[\]()`]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+export const inferMemoryTitle = (content, fallback = 'Memory Note') => {
+    const heading = content.match(/^#{1,6}\s+(.+)$/m)?.[1]?.trim();
+    if (heading)
+        return heading.replace(/\s+#\w[\w-]*/g, '').trim();
+    const firstSentence = stripMarkdownNoise(content).split(/[.!?\n]/)[0]?.trim();
+    if (!firstSentence)
+        return fallback;
+    return titleCase(firstSentence.split(/\s+/).slice(0, 8).join(' '));
+};
+export const inferMemoryTags = (content, extraTags = []) => {
+    const explicit = Array.from(content.matchAll(tagPattern), (match) => match[2]);
+    const weighted = words(content).reduce((state, word) => {
+        state.set(word, (state.get(word) ?? 0) + 1);
+        return state;
+    }, new Map());
+    const inferred = Array.from(weighted.entries())
+        .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+        .map(([word]) => word.replace(/[^a-z0-9_-]/g, '-'))
+        .filter((word) => word.length >= 3)
+        .slice(0, 4);
+    return unique([...extraTags, ...explicit, ...inferred])
+        .map((tag) => tag.replace(/^#/, '').trim())
+        .filter(Boolean)
+        .slice(0, 8);
+};
+const scoreTitleAgainstText = (title, content) => {
+    const textWords = new Set(words(content));
+    const titleWords = words(title);
+    if (titleWords.length === 0)
+        return 0;
+    const hits = titleWords.filter((word) => textWords.has(word)).length;
+    return Number((hits / titleWords.length).toFixed(4));
+};
+const editDistance = (left, right) => {
+    const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    const current = Array.from({ length: right.length + 1 }, () => 0);
+    for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+        current[0] = leftIndex;
+        for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+            const cost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+            current[rightIndex] = Math.min(previous[rightIndex] + 1, current[rightIndex - 1] + 1, previous[rightIndex - 1] + cost);
+        }
+        for (let index = 0; index < previous.length; index += 1) {
+            previous[index] = current[index];
+        }
+    }
+    return previous[right.length] ?? 0;
+};
+const titleSimilarity = (left, right) => {
+    const normalizedLeft = normalizeText(left).replace(/\s+/g, ' ').trim();
+    const normalizedRight = normalizeText(right).replace(/\s+/g, ' ').trim();
+    if (!normalizedLeft || !normalizedRight)
+        return 0;
+    if (normalizedLeft === normalizedRight)
+        return 1;
+    const distance = editDistance(normalizedLeft, normalizedRight);
+    const maxLength = Math.max(normalizedLeft.length, normalizedRight.length);
+    return Number(Math.max(0, 1 - distance / maxLength).toFixed(4));
+};
+export const suggestContextLinks = async (vaultPath, content, agentId, limit) => {
+    await ensureVault(vaultPath);
+    const graph = await getGraphSummary(vaultPath, agentId);
+    const byTitle = new Map();
+    for (const node of graph.nodes) {
+        const score = scoreTitleAgainstText(node.title, content);
+        if (score > 0) {
+            byTitle.set(node.title.toLowerCase(), {
+                title: node.title,
+                path: node.path,
+                score,
+                reason: 'title words appear in the new memory'
+            });
+        }
+    }
+    const query = stripMarkdownNoise(content).slice(0, 500);
+    const searchResults = query.length > 0
+        ? await searchKnowledge(vaultPath, query, Math.max(limit * 2, 6), agentId, 'hybrid')
+        : [];
+    for (const result of searchResults) {
+        const key = result.title.toLowerCase();
+        const current = byTitle.get(key);
+        const score = Number(Math.min(1, Math.max(result.score / 20, result.semanticScore)).toFixed(4));
+        if (!current || score > current.score) {
+            byTitle.set(key, {
+                title: result.title,
+                path: result.path,
+                score,
+                reason: result.textScore > 0 ? 'search matched title, tags or content' : 'semantic search found related content'
+            });
+        }
+    }
+    return Array.from(byTitle.values())
+        .sort((left, right) => right.score - left.score || left.title.localeCompare(right.title))
+        .slice(0, Math.max(0, limit));
+};
+export const buildRememberSuggestion = async (input) => {
+    const title = input.title?.trim() || inferMemoryTitle(input.content);
+    const tags = inferMemoryTags(input.content, input.tags ?? []);
+    const suggestedLinks = await suggestContextLinks(input.vaultPath, input.content, input.agentId, input.linkLimit ?? 5);
+    const explicitLinks = (input.links ?? []).map((link) => ({
+        title: link,
+        path: '',
+        score: 1,
+        reason: 'provided explicitly'
+    }));
+    const links = unique([...explicitLinks, ...suggestedLinks].map((link) => link.title))
+        .map((linkTitle) => explicitLinks.find((link) => link.title === linkTitle) ?? suggestedLinks.find((link) => link.title === linkTitle))
+        .filter((link) => Boolean(link));
+    const tagLine = tags.length > 0 ? `\n\n${tags.map((tag) => `#${tag}`).join(' ')}` : '';
+    const linkSection = links.length > 0
+        ? `\n\n## Context Links\n\n${links.map((link) => `- [[${link.title}]]`).join('\n')}`
+        : '';
+    return {
+        title,
+        tags,
+        links,
+        content: `${input.content.trim()}${tagLine}${linkSection}`.trim()
+    };
+};
+export const suggestBrokenLinkFixes = async (vaultPath, agentId, limit) => {
+    const [brokenLinks, graph] = await Promise.all([
+        getBrokenLinksReport(vaultPath, agentId),
+        getGraphSummary(vaultPath, agentId)
+    ]);
+    return brokenLinks.map((link) => ({
+        ...link,
+        candidates: graph.nodes
+            .map((node) => ({
+            title: node.title,
+            path: node.path,
+            score: Math.max(scoreTitleAgainstText(link.toTitle, `${node.title} ${node.path}`), titleSimilarity(link.toTitle, node.title)),
+            reason: 'similar title/path'
+        }))
+            .filter((candidate) => candidate.score > 0)
+            .sort((left, right) => right.score - left.score || left.title.localeCompare(right.title))
+            .slice(0, Math.max(0, limit))
+    }));
+};
+export const explainSearchResults = async (vaultPath, query, limit, agentId, mode) => {
+    const queryWords = new Set(words(query));
+    const results = await searchKnowledge(vaultPath, query, limit, agentId, mode);
+    return results.map((result) => {
+        const titleWords = words(result.title).filter((word) => queryWords.has(word));
+        const tagWords = result.tags.filter((tag) => queryWords.has(normalizeText(tag)));
+        const contentWords = words(result.content).filter((word) => queryWords.has(word));
+        const reasons = [
+            ...(titleWords.length > 0 ? [`title matched: ${unique(titleWords).join(', ')}`] : []),
+            ...(tagWords.length > 0 ? [`tags matched: ${unique(tagWords).join(', ')}`] : []),
+            ...(contentWords.length > 0 ? [`content matched: ${unique(contentWords).slice(0, 8).join(', ')}`] : []),
+            ...(result.semanticScore > 0 ? [`semantic score: ${result.semanticScore.toFixed(3)}`] : []),
+            `text score: ${result.textScore.toFixed(3)}`,
+            `final score: ${result.score.toFixed(3)}`
+        ];
+        return {
+            ...result,
+            reasons
+        };
+    });
+};
+export const readMemoryContentInput = async (input) => {
+    if (input.content != null && input.content.trim().length > 0) {
+        return input.content;
+    }
+    if (input.contentFile != null && input.contentFile.trim().length > 0) {
+        return readFile(input.contentFile, 'utf8');
+    }
+    throw new Error('Use --content or --content-file to provide content.');
+};
+export const inferTitleFromFilePath = (filePath) => basename(filePath, extname(filePath))
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();

package/dist/application/operational-workflows.js

@@ -0,0 +1,153 @@
+import { execFile } from 'node:child_process';
+import { access, readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { promisify } from 'node:util';
+import { addNoteWithMetadata } from './add-note.js';
+import { doctorVault, getStats, validateVault } from './analyze-vault.js';
+import { indexVault } from './index-vault.js';
+import { buildRememberSuggestion } from './memory-suggestions.js';
+import { ensureVault } from '../infrastructure/file-system-vault.js';
+const execFileAsync = promisify(execFile);
+const readIfExists = async (path) => {
+    try {
+        await access(path);
+        return readFile(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+const tryGitStatus = async (cwd) => {
+    try {
+        const { stdout } = await execFileAsync('git', ['status', '--short'], { cwd });
+        return stdout.trim();
+    }
+    catch {
+        return '';
+    }
+};
+export const buildActionableDoctor = async (vaultPath) => {
+    const [doctor, validation] = await Promise.all([
+        doctorVault(vaultPath),
+        validateVault(vaultPath)
+    ]);
+    const actions = [
+        ...(doctor.recommendations ?? []).map((recommendation) => ({
+            severity: 'warning',
+            command: recommendation.startsWith('Vault is empty') ? recommendation.replace(/^Vault is empty\. Add your first note: /, '') : recommendation,
+            reason: 'doctor recommendation'
+        })),
+        ...(validation.brokenLinks.length > 0
+            ? [{
+                    severity: 'warning',
+                    command: `blink repair-links --vault "${vaultPath}"`,
+                    reason: `${validation.brokenLinks.length} unresolved wiki links can be safely repaired or materialized as placeholder targets`
+                }]
+            : []),
+        ...(validation.orphans.length > 0
+            ? [{
+                    severity: 'info',
+                    command: `blink suggest-links --vault "${vaultPath}"`,
+                    reason: `${validation.orphans.length} notes have no incoming or outgoing links`
+                }]
+            : []),
+        {
+            severity: doctor.ok ? 'info' : 'critical',
+            command: `blink index --vault "${vaultPath}"`,
+            reason: 'keep derived index synchronized with Markdown source'
+        }
+    ];
+    return {
+        doctor,
+        validation,
+        actions
+    };
+};
+export const closeSession = async (input) => {
+    const [stats, validation, gitStatus] = await Promise.all([
+        getStats(input.vaultPath, input.agentId),
+        validateVault(input.vaultPath, input.agentId),
+        tryGitStatus(input.cwd)
+    ]);
+    const date = new Date().toISOString().slice(0, 10);
+    const title = `Session Close ${basename(input.cwd)} ${date}`;
+    const content = [
+        input.content?.trim() ? `## Notes\n\n${input.content.trim()}` : null,
+        '## Vault State',
+        `- Documents: ${stats.documentCount}`,
+        `- Links: ${stats.linkCount}`,
+        `- Broken links: ${stats.brokenLinkCount}`,
+        `- Orphans: ${stats.orphanCount}`,
+        gitStatus ? `\n## Git Status\n\n\`\`\`txt\n${gitStatus}\n\`\`\`` : null,
+        validation.brokenLinks.length > 0
+            ? `\n## Follow Up\n\n- Review unresolved links with \`blink suggest-links --broken\`.`
+            : null,
+        '\n#session #handoff'
+    ].filter((part) => Boolean(part)).join('\n');
+    const suggestion = await buildRememberSuggestion({
+        vaultPath: input.vaultPath,
+        content,
+        agentId: input.agentId,
+        title,
+        tags: ['session', 'handoff'],
+        linkLimit: 5
+    });
+    if (input.write === false) {
+        return {
+            title,
+            content: suggestion.content,
+            writtenPath: null,
+            index: null
+        };
+    }
+    const note = await addNoteWithMetadata(input.vaultPath, title, suggestion.content, input.agentId, {
+        autoContextLinks: false
+    });
+    const index = input.autoIndex === false ? null : await indexVault(input.vaultPath);
+    return {
+        title,
+        content: suggestion.content,
+        writtenPath: note.path,
+        index
+    };
+};
+export const initializeProjectMemory = async (input) => {
+    const vault = await ensureVault(input.vaultPath);
+    const candidates = ['AGENTS.md', 'README.md', 'docs/ARCHITECTURE.md', 'docs/QUICKSTART.md'];
+    const contents = await Promise.all(candidates.map(async (relativePath) => ({
+        relativePath,
+        content: await readIfExists(join(input.projectPath, relativePath))
+    })));
+    const available = contents.filter((item) => item.content !== null);
+    const fallback = available.length > 0
+        ? []
+        : [{
+                relativePath: 'Project Overview',
+                content: `Project path: ${input.projectPath}\n\n#project #memory`
+            }];
+    const notes = await Promise.all([...available, ...fallback].map(async (item) => {
+        const title = `Project ${basename(input.projectPath)} ${item.relativePath.replace(/\.md$/i, '').replace(/[\\/]/g, ' ')}`;
+        const suggestion = await buildRememberSuggestion({
+            vaultPath: input.vaultPath,
+            content: `${item.content.trim()}\n\n#project #memory`,
+            agentId: input.agentId,
+            title,
+            tags: ['project', 'memory'],
+            linkLimit: 5
+        });
+        const note = await addNoteWithMetadata(input.vaultPath, title, suggestion.content, input.agentId, {
+            autoContextLinks: false
+        });
+        return {
+            title,
+            path: note.path
+        };
+    }));
+    const index = await indexVault(input.vaultPath);
+    return {
+        projectPath: input.projectPath,
+        vault,
+        notes,
+        index
+    };
+};